5.16 异常与统一响应

概述

所有响应（成功、业务失败、校验失败、未认证、panic）都经 Response 中间件输出统一 JSON 信封，绝不出现 HTML 错误页。错误分三类：apperr 业务错误、普通 error、panic。

信封结构

{ "code": 0, "ok": true, "msg": "操作成功", "data": {} }

字段	说明
code	0 成功；非 0 为业务/系统错误码
ok	布尔捷径（前端可只看它）
msg	提示信息（前端默认 toast 文案）
data	数据；无数据为 null

错误的三个来源

apperr 错误（consts 哨兵 / apperr.Newf）
   → 按其携带的 code/msg 原样输出（如 401/403/404/422 业务码）

普通 error（含 binding 校验失败、gorm 错误）
   → 映射为通用失败码，msg 取错误文本

panic
   → Response 中间件内 recovery 捕获 → 500 信封 + 错误栈日志
   → 最外层 gin.CustomRecovery 兜底（防御静态资源等业务链之外的 panic）

拦截点前移的错误

部分错误在到达 handler 前就被中间件终结并直接写信封：401（JWT）、403（Authz）、限流拒绝、演示拒绝、租户拒绝。这类请求不产生操作日志，metrics 有分类计数。

无路由与静态兜底

NoRoute → JSON 404 信封（"接口不存在: METHOD /path"）
CustomRecovery → JSON 500 信封（业务链外兜底）

前端行为

• 拦截器解包：ok=true 直接返回 data
• ok=false / HTTP 错误 → toast msg，特定 code（401）触发刷新或跳登录
• 不在业务代码里重复判断 HTTP 状态（信封即事实）

业务错误码规范

• 定义在 internal/consts/biz_err.go，哨兵形式全局共享
• 新增错误码：编号段规划 + 中文 msg + 语义化命名（CodeRecordNotFound / CodeRecordExists）
• 详见 8.2 错误码对照表

下一步

→ 5.17 链路追踪与指标