应避免直接用 http.Error 返回自定义状态码，因其仅支持预设常量（如404、500），无法传入422、409等语义化码；正确做法是手动调用 WriteHeader + Write，并注意顺序与 Content-Type 设置。
为什么要避免直接用 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更合适做表单校验失败响应——它明确表示“请求体语法正确，但语义不通过”，前端可据此保留输入并高亮字段
真正难的不是怎么写状态码，而是团队对每个码的业务含义达成一致，并在文档、SDK、前端错误处理中统一消费。否则，写得再规范也没用。
