4. 容错响应设计原则：优雅降级、明确错误码、用户可理解的消息、不泄露内部细节
当异步导出任务因参数校验失败而无法继续时，API 的容错响应直接决定了调用方的恢复效率与用户体验。本章围绕四个核心原则展开：优雅降级、明确错误码、用户可理解的消息、不泄露内部细节。这四个原则共同构成一套既安全又实用的容错响应体系。
4.1 原则一：优雅降级（Graceful Degradation）
优雅降级要求系统在参数校验失败时，不直接返回 500 或崩溃，而是以可控的方式返回部分功能或明确的失败指引。对于异步导出任务，降级策略包括：
- 拒绝执行但保留上下文：返回错误响应时，保留请求 ID、任务类型等非敏感上下文，方便调用方关联日志。
- 提供可操作的替代方案：例如提示调用方修正参数后重试，或提供更小数据范围的导出选项。
- 避免级联失败：参数校验失败后，不触发后续的资源锁定、数据查询或文件生成流程。
设计要点：降级不是隐藏错误，而是让错误的影响范围最小化，同时为调用方保留恢复路径。
4.2 原则二：明确错误码（Explicit Error Code）
错误码是调用方程序化处理错误的核心依据。容错响应必须使用结构化的、可枚举的错误码，而非仅依赖 HTTP 状态码。推荐采用 业务域 + 错误类型 + 具体编号 的分层编码方式。
| 错误码示例 | 含义 | 适用场景 |
|---|---|---|
EXPORT_PARAM_INVALID_DATE_RANGE |
日期范围参数不合法 | 开始日期晚于结束日期 |
EXPORT_PARAM_MISSING_REQUIRED |
缺少必填参数 | 未提供导出格式字段 |
EXPORT_PARAM_FORMAT_UNSUPPORTED |
不支持的导出格式 | 传入 xlsx 但系统仅支持 csv |
EXPORT_PARAM_VALUE_OUT_OF_RANGE |
参数值超出允许范围 | 分页大小超过 1000 条限制 |
最佳实践：错误码应保持稳定，不随版本迭代随意变更。调用方可以基于错误码编写重试、告警或降级逻辑。
4.3 原则三：用户可理解的消息（User-Understandable Message）
错误消息需要同时面向两类读者：开发人员（调试用）和业务用户（操作指引用）。容错响应中的消息应包含：
- 问题描述：用自然语言说明哪个参数出了什么问题。
- 期望值或范围：明确告知合法值是什么。
- 修正建议：给出具体的修改方向。
{
"code": "EXPORT_PARAM_INVALID_DATE_RANGE",
"message": "导出日期范围不合法：开始日期 2025-01-01 不能晚于结束日期 2024-12-31。请确保开始日期 ≤ 结束日期。",
"field": "date_range.start_date",
"suggestion": "将开始日期调整为 2024-12-31 或更早的日期"
}
避坑提示：避免使用“参数错误”“系统异常”等模糊描述。消息中不要包含数据库字段名、堆栈信息或内部变量名。
4.4 原则四：不泄露内部细节（No Internal Detail Leakage）
容错响应是系统的对外接口，必须严格过滤内部实现细节。以下信息禁止出现在响应体中：
- 数据库表名、字段名、SQL 片段
- 文件系统路径、服务器 IP、端口号
- 框架版本、中间件名称、依赖库信息
- 堆栈跟踪（stack trace）或调试日志
- 内部错误码（如 Java 异常类名）
安全做法是将内部错误映射为对外公开的错误码，同时将详细日志记录在服务端，通过请求 ID 关联。
4.5 四原则协同架构
下图展示了四个原则在异步导出参数校验容错响应中的协同关系：
4.6 原则冲突时的优先级
在实际设计中，四个原则可能产生冲突。例如“用户可理解的消息”与“不泄露内部细节”之间需要平衡。建议按以下优先级处理：
- 不泄露内部细节（安全第一）—— 任何可能暴露系统内部的信息都必须过滤。
- 明确错误码（程序化处理基础）—— 确保调用方可以自动化响应。
- 用户可理解的消息（人机交互友好）—— 在安全前提下提供清晰指引。
- 优雅降级（整体体验兜底）—— 当无法提供完整信息时，至少保证系统稳定。
案例：当参数校验发现日期格式错误时，响应应包含错误码
EXPORT_PARAM_INVALID_DATE_FORMAT 和消息“日期格式应为 yyyy-MM-dd”，而不应包含“DateTimeParseException at line 47”等内部异常信息。
4.7 容错响应完整性检查清单
| 检查项 | 通过标准 | 违反示例 |
|---|---|---|
| 是否包含结构化错误码 | 错误码可枚举、可文档化 | 仅返回 HTTP 400 |
| 消息是否对用户友好 | 指出问题参数、合法范围、修正建议 | “参数校验失败” |
| 是否泄露内部信息 | 无堆栈、无路径、无库名 | “NullPointerException in ExportServiceImpl” |
| 是否支持降级 | 返回请求 ID，不触发后续流程 | 直接返回 500 且无上下文 |
遵循以上四个原则，可以构建出既安全又易用的异步导出参数校验容错响应体系，有效降低调用方的集成成本与运维压力。