---
tags: [后端, Go, Gin, 错误处理, API设计]
create time: 2026-04-28 00:15
---

# 业务错误码：JSON Body vs 响应头

## 概述

讨论 API 返回业务错误码时，应该放在 JSON body 还是自定义 HTTP 响应头（如 `X-Biz-Code`），以及何时需要两者兼有。

## 正文

### 方案对比

| | JSON Body（`code` 字段） | 响应头（`X-Biz-Code`） |
|---|---|---|
| **优点** | 解析简单，所有语言/框架天然支持 | 中间件/网关不经解析 body 就能识别错误类型 |
| **缺点** | 客户端必须先解析 body 才知道发生了什么 | 不是所有代理层都透传自定义头；某些 SDK 默认不暴露 headers |

```go
// 方案 A：仅 JSON body
c.JSON(http.StatusBadRequest, gin.H{
    "code":    40001,
    "message": "参数校验失败",
})

// 方案 B：同时写入 header + body
c.Header("X-Biz-Code", strconv.Itoa(40001))
c.JSON(http.StatusBadRequest, gin.H{
    "code":    40001,
    "message": "参数校验失败",
})
```

### 面向前端（同团队）

JSON body 就够了。前端代码是你写的，统一走 body 的 `code` 字段即可，加 header 反而增加复杂度。

```typescript
// 前端统一拦截器处理
axios.interceptors.response.use(null, (err) => {
    const bizCode = err.response?.data?.code;
    if (bizCode === 40001) showToast("请检查输入");
    if (bizCode === 40101) navigateTo("/login");
    return Promise.reject(err);
});
```

### 面向第三方开发者 —— 推荐双通道

原因有三：

1. **网关 / 反向代理决策**——WAF、API Gateway 或熔断器通常只能看 HTTP 状态码和 header，无法解析 JSON body。`X-Biz-Code` 能让网关直接拦截特定错误（比如 `40001` 直接限流，而不打到你的服务）。

2. **SDK 封装友好**——第三方集成 SDK 后，可根据 header 快速区分重试策略：瞬时错误自动重试，确定错误直接抛出，无需先解 body。

3. **调试效率**——运维通过日志打印 `$http_x_biz_code` 就能一眼看到业务错误分布，不用额外解析请求体。

### Gin 中的统一实现

```go
func handleBizError(c *gin.Context, httpCode, bizCode int, msg string) {
    c.Header("X-Biz-Code", strconv.Itoa(bizCode)) // ← header
    c.JSON(httpCode, gin.H{                        // ← body
        "code":    bizCode,
        "message": msg,
    })
}
```

成本极小——多一行 `c.Header()` 而已，但对两边的使用者（前端 + 第三方）都照顾到了。

## 关联笔记

- [[GIN/6-error-handling]] — 错误处理机制总览
- [[GIN/6-error-handling/q-c-error-nil-panic]] — c.Error(nil) 是否会导致 panic