错误处理与请求追踪

错误不是一个统一的“500”。输入不合法、没有权限、资源不存在、依赖超时和程序异常需要不同处理。稳定的错误模型能让客户端做正确分支，也能让服务端更快定位。

先按责任划分失败

失败类型	例子	应如何响应
输入问题	缺少必填字段、格式错误	指出可修正字段
身份与权限	未登录、越权操作	明确认证或权限状态
资源状态	不存在、版本冲突	告知资源现状或刷新方式
依赖故障	数据库、第三方服务超时	记录上下文，提供重试语义
程序异常	未预料分支、代码缺陷	避免泄露细节，关联请求标识

服务端内部堆栈和密钥不能直接返回给客户端。对外给出可操作的信息，对内记录排查所需的上下文。

使用稳定的错误体

{
  "code": "VALIDATION_ERROR",
  "message": "请检查提交内容",
  "fields": {
    "title": "标题不能为空"
  },
  "requestId": "req_abc123"
}

code 给程序判断，message 给用户阅读，fields 支持表单定位，requestId 让支持人员和日志系统能指向同一次请求。字段缺失时应保持兼容，不要让客户端必须猜测。

请求标识贯穿调用链

入口处生成或接收请求标识，并传到日志、下游调用和错误响应中。一次页面失败时，开发人员可以从标识找到所有相关记录，而不是在海量日志中按时间猜测。

请求 req_abc123
  → API 日志：解析参数
  → 服务日志：创建订单
  → 数据库日志：事务回滚
  → 响应：requestId=req_abc123

处理失败不等于无限重试

重试应有次数、退避与总时限；写入操作还要有幂等键或去重策略。无法自动恢复的失败应进入清晰的人工处理或补偿流程。

• 记录发生了什么、影响谁、是否可重试。
• 对预期业务错误降低日志噪音，对异常错误保留足够上下文。
• 定期回顾高频错误，把重复人工处理变成产品提示或代码约束。