Go API结构化错误的核心是统一JSON格式，含Status、Code、Message、Detail（debug模式）、RequestID字段；需分层封装、避免裸error透出，集成HTTP处理器并设正确状态码，支持i18n与错误码文档化。
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，而是统一调用一个响应函数：
- 成功时：
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 的一部分契约 —— 前端能预期、后端好定位、运维可追踪。
