如何在 Go语言微服务中统一规范 RESTful API 的错误码输出-Golang-PHP中文网

go微服务统一错误码输出需分层设计：错误类型须分层（如usernotfounderror）、http状态码语义化（400/401/404等严格对应场景）、响应结构固定为{"code":404,"message":"user not found","request_id":"xxx"}，中间件统一拦截apperror接口并转换，禁止service层直接使用http常量，确保协议语义不被破坏。

如何在 go语言微服务中统一规范 restful api 的错误码输出

Go 微服务里统一错误码输出，不是加个中间件就能解决的事——关键在于错误类型是否分层、HTTP 状态码是否语义化、响应结构是否可预测。不按这套逻辑做，c.JSON(200, map[string]interface{}{"code": 500, "msg": "xxx"}) 这类写法会反复出现，前端永远要手动解析 code 字段，重试、监控、告警全得绕开 HTTP 协议语义。

错误不能只靠 fmt.Errorf 包裹后直接返回

service 层抛出 fmt.Errorf("failed to create user: %w", dbErr)，handler 层再 c.JSON(500, ...)，看似简单，实则破坏了错误分类能力。原始错误类型丢失，无法区分是数据库超时（应重试）、参数校验失败（应改请求）、还是权限不足（应跳转登录）。

业务逻辑中用自定义错误类型替代 fmt.Errorf，比如 UserNotFoundError、InsufficientBalanceError
所有 error 必须实现一个公共接口，如 type AppError interface { StatusCode() int; Error() string }
禁止在 service 层调用 http.* 相关常量（如 http.StatusNotFound），状态码映射只发生在 API 层或中间件

中间件必须拦截 error 并转换为标准响应

别在每个 handler 里写 if err != nil { c.JSON(...); return }。这种写法重复、遗漏率高，且无法统一日志格式和 traceID 注入。

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本官方下载，版本号 1.26.0，适合旧项目维护、兼容性测试和指定版本开发环境搭建。

下载

注册全局错误中间件：r.Use(errorHandlerMiddleware)
中间件内用类型断言判断 error 是否实现了 AppError，再调用其 StatusCode() 方法获取状态码
非 AppError 的 panic 或未预期 error，统一 fallback 到 http.StatusInternalServerError，但响应体不暴露堆栈（生产环境禁用 err.Error() 直出）
响应结构固定为：{"code": 404, "message": "user not found", "request_id": "xxx"}，其中 code 字段值 = HTTP 状态码，不另设业务码字段

HTTP 状态码必须严格对应语义，不混用

把所有错误都塞进 500 或全用 200 + 自定义 code，等于放弃 HTTP 协议的契约能力。fetch 的 response.ok、axios 的 error.response.status、网关的自动重试策略，全都依赖这个字段。

http.StatusBadRequest (400)：仅用于客户端输入错误，如 JSON 解析失败、字段缺失、类型不符（c.ShouldBindJSON() 报错）
http.StatusUnauthorized (401)：认证失败（token 过期、签名无效），不含业务含义
http.StatusForbidden (403)：认证通过但无权限（RBAC 拒绝），与 401 严格区分
http.StatusNotFound (404)：资源不存在（路由匹配成功但 DB 查无此 ID），不是“接口不存在”
http.StatusConflict (409)：业务冲突（如创建重复用户名），不是“数据已存在”的模糊表达