基于Gin框架的微服务统一错误码规范-Golang-PHP中文网

gin微服务统一错误码的核心是http状态码与业务码解耦，需集中定义五位语义化错误码、通过apperror结构体分离code/msg/traceid，并由中间件动态映射http状态码；禁用默认recovery，自定义errorhandler统一处理c.errors，确保错误可查、可导出、不可硬编码。

基于gin框架的微服务统一错误码规范

Gin 微服务里统一错误码，核心不是写一堆 Success/Fail 函数，而是把 HTTP 状态码和业务状态码彻底解耦，并让错误码定义可查、可导出、不可硬编码。

错误码必须集中定义且带语义，不能散落在 handler 里

常见错误现象：不同 handler 返回 1001、ERR_USER_NOT_FOUND、"user not exist" 三种写法，前端无法做 switch 判断，日志也搜不到统一标识。

实操建议：

Gin框架 1.9.0

Gin框架 1.9.0版本源码包下载，版本号 1.9.0，适合需要 sonic JSON 支持、路由修复和内容协商改进的 Go Web 开发场景。

下载

新建 pkg/errcode/errcode.go，所有业务错误码用 const 定义，注释说明场景，例如：const UserNotFound = 10001 // 用户模块-查询失败-用户不存在
配套实现 Text(code int) string 方法，避免字符串硬编码；调用 errcode.Text(errcode.UserNotFound) 拿提示语
禁止在 handler 里直接写 c.JSON(404, gin.H{"code": 10001}) —— 必须通过工厂函数生成，如 errcode.NewNotFound(errcode.UserNotFound)
五位数字分层编码更易维护：前两位表示模块（10=用户，20=订单），后三位表示错误类型（001=未找到，002=参数非法）

AppError 结构体必须分离 HTTPStatus 和业务 Code

响应体里混着 status: 404 和 code: 10001 不是风格问题，是契约问题。网关靠 status 做重试，前端靠 code 做 toast 或跳转，两者语义不同、用途不同、变更频率也不同。

实操建议：

AppError 字段只保留 Code int（业务码）、Msg string（用户提示）、TraceID string（链路追踪），不存 HTTPStatus
HTTP 状态码由中间件根据错误类型动态映射，例如 errcode.UserNotFound → http.StatusNotFound，映射关系走 map[int]int 静态表，初始化加载一次
未显式映射的 Code 默认 fallback 到 http.StatusInternalServerError，避免返回 200 + 错误体这种反直觉响应
响应结构体 JSON key 统一为 code、msg、data，不要出现 message、error、result 等变体

CustomRecovery 必须替换默认 gin.Recovery()，且注册顺序最前

默认 gin.Recovery() 返回 HTML 页面、不带 code 字段、不透传 trace_id，和你定义的业务错误格式完全割裂。更麻烦的是，它和自定义错误中间件共存时容易触发 http: multiple response.WriteHeader calls panic。

实操建议：

禁用默认 recovery：router.Use(CustomRecovery())，且必须放在所有其他中间件之前
CustomRecovery() 里 defer 后必须 return，否则 c.Next() 继续执行，可能二次写响应头
panic 捕获后直接调用 c.AbortWithStatusJSON(http.StatusInternalServerError, response.Error(5000, "系统异常"))，别用 c.Error() —— 它只是存错，不输出
日志记录必须用 log.Printf("PANIC: %+v", err) 或 logger.Errorw("PANIC", "err", err)，不用 fmt.Printf，否则丢堆栈

ErrorHandler 中间件必须检查 c.Errors 而非 err != nil

c.Error() 是信号机制，不是响应动作。它把错误推入 c.Errors 队列，但不会中断流程、也不会自动渲染 —— 你得在请求生命周期末尾主动读取并转换。

实操建议：

在 CustomRecovery() 之后注册 ErrorHandler()，结构为：c.Next(); if len(c.Errors) > 0 { ... }
判断错误类型必须用 errors.Is(err.Err, ErrInvalidParam)，别用 err.Error() == "xxx" 字符串匹配
业务 error 工厂函数（如 ErrInvalidParam）要实现 Unwrap() error，支持链式错误追踪
确保只在一处出口调用 c.AbortWithStatusJSON()，重复调用会 panic；不要在 handler 里手动 c.JSON() 处理业务错误