如何为Go API返回结构化错误_Go API错误结构设计指南-Golang-PHP中文网

如何为Go API返回结构化错误_Go API错误结构设计指南

P粉602998670

发布： 2025-12-19 20:11:32

原创

638人浏览过

Go API结构化错误的核心是统一JSON格式，含Status、Code、Message、Detail（debug模式）、RequestID字段；需分层封装、避免裸error透出，集成HTTP处理器并设正确状态码，支持i18n与错误码文档化。

如何为go api返回结构化错误_go api错误结构设计指南

Go API 返回结构化错误的核心是：统一错误格式、区分错误类型、保留原始上下文、便于前端解析。不建议直接返回 error 字符串或裸 panic，而应设计可序列化、含状态码、错误码、用户提示和调试信息的 JSON 错误响应。

定义标准错误结构体

一个实用的错误结构需包含 HTTP 状态码、业务错误码、用户友好的消息、机器可读的错误 ID（可选）、以及开发用的详细原因（仅 debug 模式暴露）：

Status：对应 HTTP 状态码（如 400、401、404、500）
Code：自定义业务错误码（如 "USER_NOT_FOUND"、"INVALID_EMAIL"），字符串更易维护和国际化
Message：面向终端用户的简明提示（如 "用户不存在"）
Detail：可选字段，仅在 debug=true 时返回（如具体校验失败字段、SQL 错误原文）
RequestID：关联日志追踪，方便后端排查

示例结构：

type APIError struct {
    Status    int    `json:"status"`
    Code      string `json:"code"`
    Message   string `json:"message"`
    Detail    string `json:"detail,omitempty"`
    RequestID string `json:"request_id,omitempty"`
}

func (e *APIError) Error() string { return e.Message }

登录后复制

分层封装错误，避免裸 error 透出

不要让数据库错误、JSON 解析错误等底层 error 直接返回给客户端。应在 handler 层统一拦截并转换：

使用中间件或 defer 捕获 panic，并转为 500 类错误
对已知业务错误（如用户未登录、权限不足）主动构造 *APIError
对未知错误（如第三方服务超时、DB 连接失败）统一降级为 500 + 通用码（如 "INTERNAL_ERROR"），不暴露敏感细节
可借助 errors.Is / errors.As 判断错误类型，再做映射（例如识别 pgx.ErrNoRows → 404 + "USER_NOT_FOUND"）

与 HTTP 处理器集成（以 net/http 为例）

在 handler 中返回错误时，不直接写 http.Error，而是统一调用一个响应函数：

稿定抠图

AI自动消除图片背景

查看详情

成功时：writeJSON(w, http.StatusOK, data)
失败时：writeError(w, err) —— 内部判断是否为 *APIError，否则包装为 500
确保 Content-Type 设为 application/json; charset=utf-8
设置合适的 HTTP 状态码（别让所有错误都返回 200 + {“error”:…}）

这样前端可通过 HTTP 状态码快速区分网络/服务异常 vs 业务异常。

可选增强：支持 i18n 与错误码文档化

若需多语言支持，Message 不宜硬编码，可改为 key（如 "user.not_found"），由前端或网关根据 Accept-Language 渲染；同时维护一份公开的错误码表（Markdown 或 OpenAPI x-error-codes 扩展），标注每个 Code 对应的场景、HTTP 状态、是否可重试等，提升协作效率。

基本上就这些。结构化错误不是堆砌字段，而是让错误成为 API 的一部分契约 —— 前端能预期、后端好定位、运维可追踪。

以上就是如何为Go API返回结构化错误_Go API错误结构设计指南的详细内容，更多请关注php中文网其它相关文章！