Go / 系统课时
设计统一错误响应
设计统一错误响应
统一错误响应要解决两个问题:客户端如何稳定识别失败类型,以及服务端如何在提供足够修正信息的同时隐藏内部实现细节。本节会固定 JSON 契约,并用一个完整 Go 示例统一映射校验失败、未找到、冲突和内部故障。
学习目标
- 设计包含稳定错误码、消息和可选细节的统一 JSON 结构
- 将常见业务失败映射到合适的 HTTP 状态码
- 区分可公开的错误信息与只应进入服务端日志的内部信息
先固定错误响应契约
客户端应稳定依赖机器可判断的 code,而不是解析自然语言消息。message 用于展示或记录,details 只承载客户端能够据此修正请求的结构化信息。HTTP 状态码表达错误大类,JSON 错误码进一步表达业务语义。
| 场景 | HTTP 状态码 | 示例错误码 |
|---|---|---|
| 输入校验失败 | 400 | INVALID_ARGUMENT |
| 资源未找到 | 404 | NOT_FOUND |
| 状态或唯一性冲突 | 409 | CONFLICT |
| 未分类内部故障 | 500 | INTERNAL |
同一种业务失败应保持稳定映射。若同一个“资源不存在”有时返回 404、有时返回 500,客户端就无法可靠决定是否提示用户、刷新数据或重试。
集中完成错误映射
下面把业务错误先转换成“HTTP 状态码 + 统一响应体”,再序列化为 JSON。这样具体路由只需要产生业务错误,不必在每个处理函数里重复决定错误码、消息和公开细节。
package main
import (
"encoding/json"
"errors"
"fmt"
"net/http"
)
type ErrorDetails struct {
Field string `json:"field"`
Reason string `json:"reason"`
}
type ErrorBody struct {
Code string `json:"code"`
Message string `json:"message"`
Details *ErrorDetails `json:"details,omitempty"`
}
type ErrorResponse struct {
Error ErrorBody `json:"error"`
}
var (
errNotFound = errors.New("item not found")
errConflict = errors.New("item already exists")
)
type ValidationError struct {
Field string
Reason string
}
func (e *ValidationError) Error() string {
return e.Field + ": " + e.Reason
}
func renderError(err error) (int, ErrorResponse) {
var validationErr *ValidationError
switch {
case errors.As(err, &validationErr):
return http.StatusBadRequest, ErrorResponse{Error: ErrorBody{
Code: "INVALID_ARGUMENT",
Message: "请求参数不合法",
Details: &ErrorDetails{Field: validationErr.Field, Reason: validationErr.Reason},
}}
case errors.Is(err, errNotFound):
return http.StatusNotFound, ErrorResponse{Error: ErrorBody{
Code: "NOT_FOUND", Message: "资源不存在",
}}
case errors.Is(err, errConflict):
return http.StatusConflict, ErrorResponse{Error: ErrorBody{
Code: "CONFLICT", Message: "资源状态冲突",
}}
default:
// 未知故障只返回固定公共信息,原始 err 应由服务端日志记录。
return http.StatusInternalServerError, ErrorResponse{Error: ErrorBody{
Code: "INTERNAL", Message: "服务暂时不可用",
}}
}
}
func main() {
cases := []error{
&ValidationError{Field: "name", Reason: "不能为空"},
errNotFound,
errConflict,
errors.New("database connection refused at db.internal:5432"),
}
for _, err := range cases {
status, response := renderError(err)
body, marshalErr := json.Marshal(response)
if marshalErr != nil {
panic(marshalErr)
}
fmt.Printf("%d %s\n", status, body)
}
}预期输出:
400 {"error":{"code":"INVALID_ARGUMENT","message":"请求参数不合法","details":{"field":"name","reason":"不能为空"}}}
404 {"error":{"code":"NOT_FOUND","message":"资源不存在"}}
409 {"error":{"code":"CONFLICT","message":"资源状态冲突"}}
500 {"error":{"code":"INTERNAL","message":"服务暂时不可用"}}示例最后一个错误包含内部主机名和端口,但这些内容没有进入响应体。真实 HTTP 服务只需把 renderError 返回的状态码和响应对象交给统一的响应写入层,同时把原始错误写入受控日志或观测系统。
错误码和消息承担不同职责
code 应保持稳定,供客户端执行分支逻辑,例如看到 CONFLICT 后刷新资源状态;message 是面向人的简洁描述,可以调整措辞,但客户端不应靠匹配这段文字判断错误类型。
details 只在确有结构化修正信息时出现。例如字段校验失败可以返回字段名和失败原因;资源不存在通常不需要额外细节。这样可以避免为了统一格式而制造大量空字段。
内部故障只暴露公共信息
数据库错误、SQL 文本、内部主机名、文件路径、堆栈以及第三方服务响应正文都属于服务内部信息。它们可以进入受权限控制的日志,但不应直接成为公开 API 的 message 或 details。
对于无法分类的故障,稳定返回 500 Internal Server Error、INTERNAL 和通用消息即可。统一错误响应真正需要统一的是状态码语义、机器错误码和信息公开边界,而不是简单让所有失败“长得一样”。