Go 的错误处理很直接：函数返回 error，调用方检查它。但项目变大后，如果所有错误都只是 fmt.Errorf("bad request")，HTTP 层就很难判断该返回 400、404 还是 500；日志里也很难分清用户错误和系统错误。结构化错误的目标不是复杂化，而是让错误携带稳定语义。
本文用一个任务 API 举例，讲 sentinel error、自定义错误类型、错误包装，以及如何把业务错误映射成 HTTP 响应。
sentinel error 适合稳定状态
最简单的方式是定义包级错误：
var ErrTaskNotFound = errors.New("task not found")
var ErrPermissionDenied = errors.New("permission denied")
仓储层：
func (s *Store) GetTask(ctx context.Context, id int64) (Task, error) {
var task Task
err := s.db.QueryRowContext(ctx, `SELECT id, title FROM tasks WHERE id = ?`, id).
Scan(&task.ID, &task.Title)
if errors.Is(err, sql.ErrNoRows) {
return Task{}, ErrTaskNotFound
}
if err != nil {
return Task{}, fmt.Errorf("query task %d: %w", id, err)
}
return task, nil
}
Handler：
task, err := store.GetTask(r.Context(), id)
if errors.Is(err, ErrTaskNotFound) {
writeError(w, http.StatusNotFound, "task_not_found", "任务不存在")
return
}
errors.Is 可以穿透包装。即使仓储层后来写成 fmt.Errorf("load task: %w", ErrTaskNotFound)，HTTP 层仍然能识别。
自定义错误类型适合携带字段
如果错误需要字段，比如参数名、错误码、用户可见消息，可以定义类型：
type AppError struct {
Code string
Message string
Err error
}
func (e *AppError) Error() string {
if e.Err == nil {
return e.Code + ": " + e.Message
}
return e.Code + ": " + e.Message + ": " + e.Err.Error()
}
func (e *AppError) Unwrap() error {
return e.Err
}
构造：
func NewValidationError(message string) *AppError {
return &AppError{
Code: "invalid_request",
Message: message,
}
}
校验：
func validateTitle(title string) error {
if strings.TrimSpace(title) == "" {
return NewValidationError("标题不能为空")
}
return nil
}
HTTP 层用 errors.As 提取：
var appErr *AppError
if errors.As(err, &appErr) {
writeError(w, http.StatusBadRequest, appErr.Code, appErr.Message)
return
}
errors.As 用于判断错误链中是否有某个类型。它比字符串匹配可靠得多。
不要把内部错误文案直接返回
系统错误需要记录详细日志，但响应给用户的文案要稳定、安全：
if err != nil {
log.Printf("create task failed: %v", err)
writeError(w, http.StatusInternalServerError, "internal_error", "服务暂时不可用")
return
}
数据库连接失败、SQL 语句、外部服务地址、堆栈信息都不该直接出现在响应里。用户需要知道能不能重试、输入哪里错了；开发者需要在日志里看到具体原因。这两个目标不要混在一起。
错误码要稳定
响应结构可以这样：
type ErrorResponse struct {
Error struct {
Code string `json:"code"`
Message string `json:"message"`
} `json:"error"`
}
错误码比如：
invalid_request
task_not_found
permission_denied
internal_error
文案可以随着产品语言调整，错误码不应该频繁变化。前端、客户端 SDK、监控告警可能都依赖错误码。不要用中文文案当逻辑判断依据。
统一映射函数
可以把错误到 HTTP 的映射集中起来：
func writeAppError(w http.ResponseWriter, err error) {
if errors.Is(err, ErrTaskNotFound) {
writeError(w, http.StatusNotFound, "task_not_found", "任务不存在")
return
}
if errors.Is(err, ErrPermissionDenied) {
writeError(w, http.StatusForbidden, "permission_denied", "没有权限")
return
}
var appErr *AppError
if errors.As(err, &appErr) {
writeError(w, http.StatusBadRequest, appErr.Code, appErr.Message)
return
}
log.Printf("unexpected error: %v", err)
writeError(w, http.StatusInternalServerError, "internal_error", "服务暂时不可用")
}
这样每个 handler 不用重复写一堆 if。项目变大后，可以把映射规则放在 HTTP 层，业务层只返回业务错误。不要让业务层直接返回 HTTP 状态码，除非你的业务层就是 HTTP 专用。
包装错误时保留原因
调用外部服务失败：
resp, err := client.Do(req)
if err != nil {
return fmt.Errorf("call billing service: %w", err)
}
defer resp.Body.Close()
使用 %w 而不是 %v，可以保留错误链。上层如果需要识别 context.DeadlineExceeded，就能用 errors.Is：
if errors.Is(err, context.DeadlineExceeded) {
// 超时处理
}
不是每个错误都要包装很多层，但跨边界时加一点上下文很有用。日志里看到 call billing service: context deadline exceeded，比单独一个 context deadline exceeded 更容易定位。
小结
Go 的结构化错误可以从简单规则开始：稳定状态用 sentinel error，需要字段时用自定义错误类型，跨层传递时用 %w 包装，HTTP 层集中映射成状态码和错误响应。判断错误用 errors.Is 和 errors.As，不要匹配字符串。
错误设计的目标是让调用方做正确决策。用户错误、权限错误、资源不存在和系统错误应该能被清楚区分。这样 API 更稳定，日志也更容易排查。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。