Go 结构化错误入门：错误码、包装和 HTTP 映射

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 更容易定位。

HTTP 状态码映射表

映射集中管理能让所有 handler 的响应风格一致。不要让业务层直接返回 HTTP 状态码。

常见问题 FAQ

Q: 什么时候用 fmt.Errorf("... %w", err)，什么时候用自定义类型？
A: 跨层添加上下文包装用 %w；需要稳定错误码、前端展示文案或监控分类时用自定义类型。两者可以组合使用。

Q: %v 和 %w 有什么区别？
A: %v 只是把错误文本拼起来，errors.Is 无法穿透。%w 保留错误链，允许上层用 errors.Is 判断。跨层包装时优先 %w。

Q: sentinel error 命名惯例？
A: 公共包用 Err 前缀，如 var ErrNotFound = errors.New("not found")。包内私有错误小写开头。避免中文和动态文案。

常见陷阱

1. 暴露内部错误细节：数据库连接串、堆栈、文件路径不要返回给客户端。
2. errors.As 目标非指针：errors.As(err, &appErr) 必须是 **AppError 的指针，不然编译能通过但运行不提取。
3. 错误文案不稳定：不要把中文提示当业务判断依据。前端不应该解析 Message，应只依赖 Code。

对比表

小结

Go 的结构化错误可以从简单规则开始：稳定状态用 sentinel error，需要字段时用自定义错误类型，跨层传递时用 %w 包装，HTTP 层集中映射成状态码和错误响应。判断错误用 errors.Is 和 errors.As，不要匹配字符串。

错误设计的目标是让调用方做正确决策。用户错误、权限错误、资源不存在和系统错误应该能被清楚区分。保持错误码稳定、文案安全、映射集中，API 会更可靠，日志也更容易排查。新服务应该尽早建立错误规范，避免后期大规模重构。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

• 函数是否处理了所有 error 返回值
• 并发代码是否有明确的退出路径和 WaitGroup
• 用户输入是否经过校验和清洗
• 敏感配置是否通过环境变量或加密存储注入
• 测试是否覆盖了正常路径和至少一个错误路径
• 日志是否包含足够的上下文信息但不泄露敏感数据
• 接口设计是否符合最小接口原则

CI/CD 集成建议

• 每次提交前运行 go fmt ./...
• CI 中运行 go vet ./... 和 golangci-lint run
• 单元测试使用 go test -race ./... 检测数据竞争
• 关键路径的 benchmark 加入回归测试
• 使用 go mod verify 确保依赖完整性

性能调优检查点

• 使用 pprof 分析 CPU 和内存使用
• 关注 benchmark 的 allocs/op，减少高频路径的堆分配
• 检查数据库查询是否使用索引
• 确认外部 HTTP 调用有合理的超时设置
• 缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

1. goroutine 和线程的区别
2. channel 的缓冲和非缓冲用法
3. defer 的执行顺序和与返回值的关系
4. map 的并发不安全性和解决方案
5. interface 的隐式实现和类型断言
6. slice 的底层数组和 append 机制
7. GC 的基本原理和调优参数
8. context 的使用场景和超时控制
9. error 的包装和 errors.Is/errors.As
10. sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

1. 把文中所有示例代码在自己的机器上跑一遍
2. 给示例代码补充错误分支的测试用例
3. 尝试基于本文内容构建一个小型完整项目
4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
5. 订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

• Go 官方网站：https://go.dev/
• Go 标准库文档：https://pkg.go.dev/std
• Go by Example：https://gobyexample.com/
• Effective Go：https://go.dev/doc/effective_go
• Go 常见问题：https://go.dev/doc/faq
• Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

错误链和链式包装

多层架构中，错误需要逐层包装，每层添加自己的上下文：

// 仓储层
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 err != nil {
        return Task{}, fmt.Errorf("store query task %d: %w", id, err)
    }
    return task, nil
}

// 服务层
func (svc *Service) GetTask(ctx context.Context, id int64) (Task, error) {
    task, err := svc.store.GetTask(ctx, id)
    if err != nil {
        return Task{}, fmt.Errorf("service get task: %w", err)
    }
    return task, nil
}

// 处理层
func (h *Handler) GetTask(w http.ResponseWriter, r *http.Request) {
    task, err := h.service.GetTask(r.Context(), id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            writeError(w, http.StatusNotFound, "task_not_found", "任务不存在")
            return
        }
        // ...
    }
}

这种方法让每个层级都清楚自己的责任边界，也便于排查时判断问题出处。

错误 sentinel 的最佳实践

var (
    ErrNotFound       = errors.New("resource not found")
    ErrConflict       = errors.New("resource conflict")
    ErrPermissionDenied = errors.New("permission denied")
    ErrUnavailable    = errors.New("service unavailable")
)

Sentinel error 应该包裹在包级别，让调用方可以稳定引用。不要把动态文案塞进 sentinel error，也不要让每个模块都定义重复的 NotFound 错误。

测试错误类型

func TestAppErrorResponse(t *testing.T) {
    var appErr *AppError
    if !errors.As(someWrappedError, &appErr) {
        t.Fatal("expected AppError")
    }
    if appErr.Code != "invalid_request" {
        t.Fatalf("code = %q", appErr.Code)
    }
}

测试错误类型时，用 errors.As 而不是字符串匹配，能验证错误包装是否正确传递。

错误监控告警

func LogError(ctx context.Context, err error) {
    var appErr *AppError
    if errors.As(err, &appErr) {
        slog.ErrorContext(ctx, "app error",
            "code", appErr.Code,
            "error", appErr.Err,
        )
        metrics.ErrorsByCode.WithLabelValues(appErr.Code).Inc()
    }
}

按错误码分维度统计，可以帮助你发现哪种业务错误最常见，从而优化系统设计。

总结

错误不是程序的另一条输出流，而是系统设计的一部分。好的错误设计让调用方做正确决策，让用户看到有用信息，让运维收到准确告警。投入时间设计错误体系，会带来长期的收益。