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。这样具体路由只需要产生业务错误,不必在每个处理函数里重复决定错误码、消息和公开细节。

go
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)
    }
}

预期输出:

text
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 和通用消息即可。统一错误响应真正需要统一的是状态码语义、机器错误码和信息公开边界,而不是简单让所有失败“长得一样”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计统一错误响应

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通