# 5.16 异常与统一响应

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

## 信封结构

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

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

## 错误的三个来源

```text
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 有分类计数。

## 无路由与静态兜底

```text
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 错误码对照表](/zh/api-spec/error-code.html)

## 下一步

→ [5.17 链路追踪与指标](/zh/core/trace-metrics.html)