推荐定义标准响应结构并封装错误处理函数，统一返回格式：Code表示业务状态码，Msg为提示信息，Data为可选数据；成功用writeSuccess返回Code=0，错误用writeError返回预定义错误码，HTTP状态码默认200，必要时配合401/403等状态码。
在 Golang 的 HTTP 接口开发中，合理返回错误信息是构建清晰、可维护 API 的关键。直接使用 http.Error 或裸写 JSON 字符串容易导致响应格式不统一，不利于前端处理。推荐的做法是定义标准的响应结构，统一成功和错误的输出格式。
定义标准响应结构
一个通用的 API 响应通常包含状态码、消息和数据体。例如：
type Response struct {
Code int `json:"code"`
Msg string `json:"msg"`
Data interface{} `json:"data,omitempty"`
}
其中 Code 表示业务状态码（非 HTTP 状态码），Msg 是提示信息，Data 为可选的返回数据。通过 omitempty 标签，当无数据时自动省略该字段。
封装错误响应函数
为了简化错误返回，可以封装公共函数：
立即学习“go语言免费学习笔记（深入）”；
func writeError(w http.ResponseWriter, code int, msg string) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK) // 保持 200，由 body 中的 code 区分
json.NewEncoder(w).Encode(Response{
Code: code,
Msg: msg,
})
}
func writeSuccess(w http.ResponseWriter, data interface{}) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(Response{
Code: 0,
Msg: "success",
Data: data,
})
}
这样无论成功或失败都使用 HTTP 200，真正的状态由 body 中的 Code 判断，适合前后端分离场景。
处理不同类型的错误
实际开发中可能遇到参数校验失败、资源未找到、权限不足等错误。建议预定义常见错误码：
const (
ErrCodeInvalidParams = 4001
ErrCodeNotFound = 4041
ErrCodeUnauthorized = 4011
)
在接口中根据逻辑调用对应错误返回：
if userID <= 0 {
writeError(w, ErrCodeInvalidParams, "用户ID无效")
return
}
也可以结合中间件统一捕获 panic 并返回 系统内部错误，避免服务崩溃暴露细节。
与 HTTP 状态码配合使用
虽然业务错误可通过 body 返回，但某些情况仍建议使用正确的 HTTP 状态码，如认证失败返回 401，禁止访问返回 403。此时可调整 writeError 的 WriteHeader 参数，让网关或代理层能正确识别。
基本上就这些。统一响应结构能让前端更稳定解析，也便于日志记录和监控报警。关键是尽早约定格式，并在整个项目中贯彻执行。
