接口返回与异常

普通 JSON 接口使用统一响应 R<T>：

{
  "code": 0,
  "message": "成功",
  "data": {},
  "traceId": "request-trace-id"
}

业务码

code	含义	前端行为
0	成功	使用 data
1	通用业务失败	展示 message
401	未认证或登录失效	清理会话并跳转登录
403	已认证但权限不足	保留登录状态并提示无权限

认证和鉴权异常还应使用匹配的 HTTP 状态。特别是权限不足不能伪装成 code = 0，否则前端会把失败结果当成功处理。

返回用法

return R.ok(data);
return R.ok();
return R.fail("业务提示");

可预期业务错误使用统一业务异常，由全局异常处理转换为结构化响应。不要在各 Controller 重复捕获同一种异常。

Trace ID

每个请求会生成请求标识并写入 MDC。统一响应中的 traceId 与应用日志前缀中的 reqId 对应，可用于关联：

• Controller 接口日志。
• Service 业务日志。
• P6Spy SQL 日志。
• 全局异常栈。

下载和预览使用 ResponseEntity 返回文件流，不走普通 JSON 响应；请求标识仍会进入服务端日志，但不会包裹进文件内容。

错误信息原则

• 参数错误明确指出字段或约束。
• 权限错误使用 403，不泄露内部资源明细。
• 登录错误避免区分“账号不存在”和“密码错误”，降低账号枚举风险。
• 第三方存储或短信错误对用户保持可理解，对服务端保留必要异常链。
• 生产环境不向客户端返回 SQL、文件绝对路径、堆栈和密钥信息。

前端处理

Axios 拦截器统一添加 Bearer Token、处理网络错误、超时和 401。业务层只处理当前功能需要的成功数据或局部错误，不应在每个页面再次实现登录失效流程。