答案：Go API 错误处理应统一响应格式、使用自定义错误类型区分业务错误、通过中间件捕获 panic，并在校验失败时返回字段级错误信息，确保一致性与可维护性。
在 Go 语言开发 API 接口时，良好的错误处理机制是保障系统健壮性和可维护性的关键。合理的错误设计能让调用方清晰理解问题所在，同时便于日志追踪和监控报警。以下是常见的 Golang API 错误处理规范与实用示例。
统一错误响应格式
API 返回的错误信息应结构一致，方便前端或客户端解析。建议使用 JSON 格式返回错误，并包含状态码、错误消息和可选的详细信息。
定义统一的响应结构：
type ErrorResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Detail string `json:"detail,omitempty"`
}
func writeError(w http.ResponseWriter, code int, message, detail string) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(code)
json.NewEncoder(w).Encode(ErrorResponse{
Code: code,
Message: message,
Detail: detail,
})
}
使用自定义错误类型区分业务错误
Go 的 error 是接口类型，可通过实现自定义错误增强语义。在 API 层，区分系统错误和业务错误有助于精准响应。
立即学习“go语言免费学习笔记（深入）”；
例如定义业务错误类型：
type AppError struct {
Code int
Message string
Err error
}
func (e *AppError) Error() string {
return e.Message
}
// 预定义常见错误
var (
ErrUserNotFound = &AppError{Code: 404, Message: "用户不存在"}
ErrInvalidInput = &AppError{Code: 400, Message: "请求参数无效"}
)
在处理函数中判断错误类型并返回对应 HTTP 状态：
func getUserHandler(w http.ResponseWriter, r *http.Request) {
userID := r.URL.Query().Get("id")
if userID == "" {
writeError(w, 400, "缺少用户ID", "query param 'id' is required")
return
}
user, err := userService.Get(userID)
if err != nil {
if errors.Is(err, ErrUserNotFound) {
writeError(w, 404, err.Error(), "")
return
}
// 其他错误视为服务器内部错误
log.Printf("获取用户失败: %v", err)
writeError(w, 500, "服务器内部错误", "")
return
}
json.NewEncoder(w).Encode(user)
}
中间件集中处理 panic 和未知错误
为避免因未捕获的 panic 导致服务崩溃，建议使用中间件统一恢复并返回 500 响应。
func RecoverMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
log.Printf("panic: %v\n%s", err, debug.Stack())
writeError(w, 500, "服务器内部错误", "panic occurred")
}
}()
next.ServeHTTP(w, r)
})
}
将中间件应用于路由：
mux := http.NewServeMux()
mux.HandleFunc("/user", getUserHandler)
log.Fatal(http.ListenAndServe(":8080", RecoverMiddleware(mux)))
验证错误返回具体字段信息
对于表单或 JSON 输入校验失败，应返回具体出错字段，帮助调用方快速定位问题。
扩展 ErrorResponse 支持字段级错误：
type FieldError struct {
Field string `json:"field"`
Reason string `json:"reason"`
}
type ValidationErrorResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Errors []FieldError `json:"errors,omitempty"`
}
校验示例：
func createUserHandler(w http.ResponseWriter, r *http.Request) {
var input struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
writeError(w, 400, "请求体解析失败", err.Error())
return
}
var fieldErrors []FieldError
if input.Name == "" {
fieldErrors = append(fieldErrors, FieldError{Field: "name", Reason: "不能为空"})
}
if !strings.Contains(input.Email, "@") {
fieldErrors = append(fieldErrors, FieldError{Field: "email", Reason: "邮箱格式无效"})
}
if len(fieldErrors) > 0 {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(400)
json.NewEncoder(w).Encode(ValidationErrorResponse{
Code: 400,
Message: "输入验证失败",
Errors: fieldErrors,
})
return
}
// 处理创建逻辑...
}
基本上就这些。通过统一格式、自定义错误、中间件防护和字段级反馈，可以让 Go 编写的 API 错误处理更清晰可靠。关键是保持一致性，让所有错误路径都遵循相同模式。 
