golang

Go 错误处理实战：别怕 if err != nil，它是在保护你

错误处理是 Go 风格的核心部分很多初学者看到 Go 代码里反复出现，第一反应是啰嗦。和异常机制相比，它确实更显眼。可是显眼正是 Go 的设计选择：失败路径应该被看见，调用者应该明确决定如何处理失败，而不是让错误从深层调用栈里悄悄冒出来。

Leeting Yan 2020-02-18 8 分钟阅读 3968 字

错误处理是 Go 风格的核心部分

很多初学者看到 Go 代码里反复出现 if err != nil，第一反应是啰嗦。和异常机制相比，它确实更显眼。可是显眼正是 Go 的设计选择：失败路径应该被看见，调用者应该明确决定如何处理失败，而不是让错误从深层调用栈里悄悄冒出来。

真实后端系统里，失败是常态。文件可能不存在，数据库可能超时，用户输入可能非法，第三方接口可能返回 500，网络可能抖动。把这些情况当作正常控制流的一部分，代码会更可靠。

Go 的错误处理不是只会写 return err。你还需要知道什么时候包装错误，什么时候定义哨兵错误，什么时候使用自定义错误类型，日志应该在哪一层打，HTTP 接口应该如何把内部错误转换成用户能理解的响应。

error 是一个接口

Go 的错误类型是内置接口：

type error interface {
	Error() string
}

任何类型只要实现 Error() string，就是一个错误。最常见的创建方式是：

err := errors.New("user not found")

或者格式化：

err := fmt.Errorf("user %d not found", userID)

函数通常把错误作为最后一个返回值：

func findUser(id int64) (User, error) {
	if id <= 0 {
		return User{}, fmt.Errorf("invalid user id: %d", id)
	}
	return User{ID: id, Name: "小林"}, nil
}

调用方处理：

user, err := findUser(1)
if err != nil {
	fmt.Println("find user failed:", err)
	return
}
fmt.Println(user.Name)

成功时错误为 nil，失败时结果值通常返回零值。这个模式非常稳定。

不要忽略错误

有时你会看到这样的代码：

user, _ := findUser(1)
fmt.Println(user.Name)

_ 会忽略错误。除非你非常确定错误不重要，否则不要这样写。被忽略的错误最终会变成更难查的问题。

更好的写法：

user, err := findUser(1)
if err != nil {
	return fmt.Errorf("find user: %w", err)
}

如果确实要忽略，也应该让意图明显。例如关闭响应体时，有些场景可以记录日志但不影响主流程：

if err := resp.Body.Close(); err != nil {
	log.Printf("close response body: %v", err)
}

错误处理的基本原则是：要么处理，要么返回，要么明确记录。不要假装它不存在。

错误包装：保留上下文

底层错误通常信息不够。比如文件读取失败只告诉你 no such file or directory，但调用者需要知道是在读哪个配置。

func loadConfig(path string) ([]byte, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("read config %s: %w", path, err)
	}
	return data, nil
}

%w 表示包装错误。它不仅把上下文拼进错误消息，还保留原始错误，方便上层使用 errors.Is 或 errors.As 判断。

调用：

data, err := loadConfig("config.json")
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(string(data))

输出可能是：

read config config.json: open config.json: no such file or directory

这比单独返回 err 更容易排查。包装错误时，上下文要具体，不要写空泛的 failed。好的错误消息应该回答“正在做什么时失败”。

errors.Is 判断错误类型

有些错误需要被上层识别。比如用户不存在和数据库连接失败，处理方式不同。可以定义哨兵错误：

var ErrUserNotFound = errors.New("user not found")

使用：

func findUser(id int64) (User, error) {
	if id == 404 {
		return User{}, ErrUserNotFound
	}
	return User{ID: id, Name: "小林"}, nil
}

判断：

user, err := findUser(404)
if err != nil {
	if errors.Is(err, ErrUserNotFound) {
		fmt.Println("show empty page")
		return
	}
	return err
}

如果中间层包装了错误：

return User{}, fmt.Errorf("query user %d: %w", id, ErrUserNotFound)

errors.Is 仍然能判断出来。这就是 %w 的价值。

不要用字符串比较错误：

if err.Error() == "user not found" {
}

错误消息是给人看的，不适合作为程序判断依据。

自定义错误类型

当错误需要携带结构化信息时，可以定义类型：

type ValidationError struct {
	Field   string
	Message string
}

func (e ValidationError) Error() string {
	return fmt.Sprintf("%s: %s", e.Field, e.Message)
}

使用：

func validateEmail(email string) error {
	if email == "" {
		return ValidationError{Field: "email", Message: "is required"}
	}
	if !strings.Contains(email, "@") {
		return ValidationError{Field: "email", Message: "is invalid"}
	}
	return nil
}

上层提取：

err := validateEmail("bad")
var validationErr ValidationError
if errors.As(err, &validationErr) {
	fmt.Println(validationErr.Field, validationErr.Message)
}

errors.As 用来从错误链里找某种类型。自定义错误适合需要字段名、错误码、重试标记、HTTP 状态码等结构化信息的场景。

但不要所有错误都自定义类型。普通上下文错误用 fmt.Errorf 足够。自定义错误应当服务于程序判断，而不是为了显得复杂。

日志应该打在边界

一个常见坏习惯是每层都打日志：

func repoFindUser(id int64) (User, error) {
	err := query()
	if err != nil {
		log.Println("query failed:", err)
		return User{}, err
	}
	return user, nil
}

func serviceGetUser(id int64) (User, error) {
	user, err := repoFindUser(id)
	if err != nil {
		log.Println("repo failed:", err)
		return User{}, err
	}
	return user, nil
}

这样一个错误可能被打印多次，日志噪声很大。更推荐的方式是：底层包装上下文，上层边界统一记录。

func repoFindUser(id int64) (User, error) {
	if err := query(); err != nil {
		return User{}, fmt.Errorf("query user %d: %w", id, err)
	}
	return user, nil
}

HTTP handler、CLI main、后台任务入口这些地方是边界，适合记录最终错误：

user, err := service.GetUser(r.Context(), id)
if err != nil {
	log.Printf("get user: %v", err)
	http.Error(w, "internal error", http.StatusInternalServerError)
	return
}

这样日志既有完整上下文，又不会重复。

HTTP 场景下的错误转换

内部错误不能原样暴露给用户。比如数据库错误不应该直接返回给前端。可以写一个简单转换函数：

func writeError(w http.ResponseWriter, err error) {
	switch {
	case errors.Is(err, ErrUserNotFound):
		http.Error(w, "user not found", http.StatusNotFound)
	default:
		log.Printf("unexpected error: %v", err)
		http.Error(w, "internal server error", http.StatusInternalServerError)
	}
}

Handler 使用：

func getUserHandler(w http.ResponseWriter, r *http.Request) {
	user, err := findUser(404)
	if err != nil {
		writeError(w, err)
		return
	}

	if err := json.NewEncoder(w).Encode(user); err != nil {
		log.Printf("encode user: %v", err)
	}
}

真实项目里可能有统一响应格式：

type ErrorResponse struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

然后根据错误类型映射成业务错误码。重点是边界清楚：内部错误用于排查，外部响应用于用户理解。两者不应该混在一起。

小结

Go 的错误处理看起来重复，但它让失败路径清晰可见。普通函数返回 (value, error)，调用者用 if err != nil 处理；底层错误要加上下文，用 %w 包装；需要程序判断时，用 errors.Is、errors.As，不要比较错误字符串；日志尽量在边界统一记录，底层负责返回有信息量的错误。

写 Go 时，不要害怕错误处理占几行代码。真正危险的不是 if err != nil 太多，而是失败被隐藏、被忽略、被错误地转换。一个后端系统能否稳定运行，很大程度取决于错误路径是否清楚。

当你开始认真处理错误，Go 代码会显得更踏实。它不让你把异常藏起来，而是要求你在每个关键点做决定。这种显式，正是 Go 工程风格的重要部分。

常见问题与解答

if err != nil 太啰嗦怎么办？

Go 的错误处理确实显式且重复，但这是设计选择。处理每个错误让失败路径清晰可见。作为补偿，Go 没有异常堆栈展开，控制流更直接。

errors.Is 和 errors.As 什么时候用？

errors.Is：判断错误链中是否有某个特定错误值（如 sql.ErrNoRows）
errors.As：判断错误链中是否有某个错误类型，并提取它（如提取自定义错误类型）

panic 什么时候用？

程序如果遇到不可恢复的状态（如配置缺失、数据库连接失败在启动时），可以用 log.Fatal 或 panic。业务请求处理中不要 panic，应该返回 error。

错误包装链

func serviceLayer() error {
    if err := dbQuery(); err != nil {
        return fmt.Errorf("service failed: %w", err)
    }
    return nil
}

func handler() {
    if err := serviceLayer(); err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            http.NotFound(w, r)
            return
        }
        log.Printf("handler error: %v", err)
        http.Error(w, "internal error", 500)
    }
}

哨兵错误

var (
    ErrNotFound    = errors.New("not found")
    ErrInvalidInput = errors.New("invalid input")
    ErrUnauthorized = errors.New("unauthorized")
)

业务层定义这些哨兵错误，handler 层判断返回对应 HTTP 状态码。

错误代码映射

func HTTPStatusFromError(err error) int {
    switch {
    case errors.Is(err, ErrNotFound):
        return http.StatusNotFound
    case errors.Is(err, ErrInvalidInput):
        return http.StatusBadRequest
    case errors.Is(err, ErrUnauthorized):
        return http.StatusUnauthorized
    default:
        return http.StatusInternalServerError
    }
}

实践练习

完成以下练习以巩固所学知识：

阅读 Go 官方文档相关章节
编写一个完整的示例程序
为示例程序编写单元测试
使用 go test 和 go benchmark 验证实现
尝试优化内存分配和运行时间

真实项目用例

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

代码审查清单

函数是否处理了所有 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 相关面试，以下概念是高频考点：

goroutine 和线程的区别
channel 的缓冲和非缓冲用法
defer 的执行顺序和与返回值的关系
map 的并发不安全性和解决方案
interface 的隐式实现和类型断言
slice 的底层数组和 append 机制
GC 的基本原理和调优参数
context 的使用场景和超时控制
error 的包装和 errors.Is/errors.As
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 泄漏。

常见坑与避坑指南

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

延伸阅读与实践建议

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

把文中所有示例代码在自己的机器上跑一遍
给示例代码补充错误分支的测试用例
尝试基于本文内容构建一个小型完整项目
在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
订阅 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 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页