如何在Golang中自定义HTTP错误码_HTTP错误码设计建议

应避免直接用 http.Error 返回自定义状态码，因其仅支持预设常量（如404、500），无法传入422、409等语义化码；正确做法是手动调用 WriteHeader + Write，并注意顺序与 Content-Type 设置。

如何在Golang中自定义HTTP错误码_HTTP错误码设计建议第1张

为什么要避免直接用 `http.Error` 返回自定义状态码

http.Error 内部固定使用 http.StatusInternalServerError（500）或 http.StatusNotFound（404）等预设码，无法传入任意整数状态码。想返回 422 Unprocessable Entity 或 409 Conflict 时，它直接失效。

它只接受 http.StatusOK 等常量，不接受 422 这样的字面量
底层调用的是 ResponseWriter.WriteHeader(statusCode) + Write([]byte)，但封装层把状态码“锁死”了
实际开发中，API 设计常需语义化错误码（如表单校验失败用 422，资源冲突用 409），硬套 400 或 500 会丢失意图

正确写法：手动调用 `WriteHeader` + `Write`

Go 的 http.ResponseWriter 接口允许任意状态码，只要在 Write 前调用 WriteHeader 即可。这是最轻量、最可控的方式。

func handleUserCreate(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        w.WriteHeader(http.StatusMethodNotAllowed)
        w.Write([]byte(`{"error": "method not allowed"}`))
        return
    }

    // 校验失败 → 422
    if !isValidUser(r) {
        w.WriteHeader(422)
        w.Header().Set("Content-Type", "application/json")
        w.Write([]byte(`{"error": "invalid user data"}`))
        return
    }

    // 成功 → 201
    w.WriteHeader(http.StatusCreated)
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"id": 123}`))
}

必须先调用 WriteHeader，再调用 Write；顺序反了会导致状态码被忽略（默认 200）
WriteHeader 不会自动设置 Content-Type，需手动 w.Header().Set(...)
若多次调用 WriteHeader，只有第一次生效；后续调用会被静默丢弃

封装一个可复用的错误响应函数

重复写 WriteHeader + Header().Set + Write 很容易漏掉 Content-Type 或写错顺序。建议封装成工具函数，但注意别过度设计。

func writeJSONError(w http.ResponseWriter, status int, msg string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(map[string]string{"error": msg})
}

// 使用示例
func handler(w http.ResponseWriter, r *http.Request) {
    if r.URL.Path == "/admin" && !isAdmin(r) {
        writeJSONError(w, 403, "forbidden")
        return
    }
}

把 Header().Set 放在 WriteHeader 前或后都行（Go 的 Header 修改在 WriteHeader 前后都有效）
用 json.Encoder 替代 json.Marshal + Write，避免中间分配字节切片
不要在这个函数里 panic 或 recover —— HTTP handler 本身不该吞错误，该让上层中间件处理

哪些状态码适合 API 场景，哪些要慎用

HTTP 状态码不是越多越好。选错码会让前端难以区分客户端错误和服务器错误，也影响网关、CDN、监控的行为。

立即学习“go语言免费学习笔记（深入）”；

优先用语义明确的标准码：400（通用客户端错误）、401（未认证）、403（已认证但无权限）、404（资源不存在）、409（并发修改冲突）、422（数据格式合法但语义无效）
避免滥用 5xx：比如数据库唯一约束失败，本质是客户端提交了重复数据，应返回 409 而非 500
不要自定义 6xx/7xx 码：HTTP/1.1 只定义到 5xx，非标准码可能被代理、负载均衡器截断或重写
422 比 400 更合适做表单校验失败响应——它明确表示“请求体语法正确，但语义不通过”，前端可据此保留输入并高亮字段