简介
Go 代码里最常见的错误处理大概是这样：
result, err := doSomething()
if err != nil {
return err
}
这几行代码不难，真正容易出问题的是后面的选择：
应该新建错误，还是包装原错误？
应该使用 ==，还是 errors.Is？
什么时候需要自定义错误类型？
错误应该在哪一层记录日志？
多个清理操作同时失败，应该返回哪一个错误？
普通错误、panic 和 recover 到底怎么分工？
Go 没有把错误处理藏进异常机制，而是把错误当成普通值显式传递。
这套设计看起来重复，却带来一个直接好处：函数签名会明确说明操作可能失败，调用方也能在失败发生的位置决定返回、重试、降级还是终止。
一句话概括：
error 不只是错误文本，它还是可以分类、包装、传递和组合的值。
error 到底是什么
error 是 Go 内置的接口类型，定义非常简单：
type error interface {
Error() string
}
任何类型只要实现了 Error() string，就实现了 error 接口。
package main
import "fmt"
type ValidationError struct {
Field string
Message string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("字段 %s：%s", e.Field, e.Message)
}
func validateName(name string) error {
if name == "" {
return &ValidationError{Field: "name", Message: "不能为空"}
}
return nil
}
func main() {
err := validateName("")
fmt.Println(err)
}
输出：
字段 name：不能为空
ValidationError 没有声明实现某个接口。Go 使用隐式接口实现，只要方法集合满足要求，就可以作为 error 返回。
nil 表示操作成功
函数通常把 error 放在最后一个返回值：
func divide(a, b int) (int, error) {
if b == 0 {
return 0, errors.New("除数不能为 0")
}
return a / b, nil
}
约定很明确：
err == nil：操作成功，其他返回值可以使用err != nil：操作失败，先处理错误
完整示例：
package main
import (
"errors"
"fmt"
)
func divide(a, b int) (int, error) {
if b == 0 {
return 0, errors.New("除数不能为 0")
}
return a / b, nil
}
func main() {
result, err := divide(12, 3)
if err != nil {
fmt.Println("计算失败：", err)
return
}
fmt.Println("计算结果：", result)
}
输出：
计算结果： 4
错误分支尽早返回，可以减少嵌套：
data, err := loadData()
if err != nil {
return err
}
result, err := parseData(data)
if err != nil {
return err
}
return saveResult(result)
正常流程保持在左侧，错误处理紧跟在可能失败的调用后面，这就是 Go 项目里常见的写法。
创建错误的三种常见方式
errors.New：固定错误文本
errors.New 适合创建不需要动态参数的简单错误：
err := errors.New("用户名不能为空")
完整示例：
package main
import (
"errors"
"fmt"
)
func checkAge(age int) error {
if age < 0 {
return errors.New("年龄不能小于 0")
}
return nil
}
func main() {
if err := checkAge(-1); err != nil {
fmt.Println(err)
}
}
fmt.Errorf：带动态信息
错误信息需要带上文件名、用户 ID 或参数值时，使用 fmt.Errorf：
return fmt.Errorf("用户 %d 不存在", userID)
这里仅仅是格式化文本，还没有形成错误链。
package main
import "fmt"
func findUser(id int64) error {
return fmt.Errorf("用户 %d 不存在", id)
}
func main() {
fmt.Println(findUser(1001))
}
输出：
用户 1001 不存在
自定义错误：携带结构化信息
如果调用方需要读取错误码、字段名、重试时间等信息，应定义错误类型，而不是解析错误字符串。
type RateLimitError struct {
RetryAfter time.Duration
}
func (e *RateLimitError) Error() string {
return fmt.Sprintf("请求过于频繁，%s 后重试", e.RetryAfter)
}
错误文本适合阅读，结构化字段适合程序判断。
错误文本不是错误身份
下面两个错误的文本相同，但不是同一个错误值：
first := errors.New("not found")
second := errors.New("not found")
fmt.Println(first == second)
输出：
false
因此，不能在判断时临时创建一个同文本错误：
if errors.Is(err, errors.New("not found")) {
// 通常匹配不到
}
需要稳定识别的错误，应复用同一个变量：
var ErrNotFound = errors.New("not found")
这种包级错误值通常称为哨兵错误。
哨兵错误：表示稳定的错误类别
哨兵错误适合表达调用方需要识别的固定状态：
var (
ErrNotFound = errors.New("not found")
ErrConflict = errors.New("conflict")
ErrPermission = errors.New("permission denied")
)
完整示例：
package main
import (
"errors"
"fmt"
)
var ErrUserNotFound = errors.New("user not found")
func findUser(id int64) error {
if id != 1001 {
return ErrUserNotFound
}
return nil
}
func main() {
err := findUser(2002)
if errors.Is(err, ErrUserNotFound) {
fmt.Println("返回 404")
return
}
if err != nil {
fmt.Println("返回 500")
}
}
导出的哨兵错误会成为包的公开契约。调用方一旦依赖 ErrUserNotFound，后续修改时就要继续维护这个语义。
只想返回一段说明，不希望调用方依赖错误类别时，普通错误文本通常已经够用。
为什么要包装错误
底层函数返回的错误往往缺少业务上下文。
例如：
file does not exist
只看这句话，不知道读取了哪个文件，也不知道发生在哪个业务流程。
可以使用 %w 包装原错误：
return fmt.Errorf("读取配置 %q: %w", filename, err)
包装后同时保留两部分信息：
外层上下文：读取配置 "app.json"
底层原因：file does not exist
完整示例：
package main
import (
"errors"
"fmt"
"os"
)
func readConfig(filename string) ([]byte, error) {
data, err := os.ReadFile(filename)
if err != nil {
return nil, fmt.Errorf("读取配置 %q: %w", filename, err)
}
return data, nil
}
func main() {
_, err := readConfig("missing.json")
if err == nil {
return
}
fmt.Println(err)
if errors.Is(err, os.ErrNotExist) {
fmt.Println("配置文件不存在，加载默认配置")
}
}
输出类似：
读取配置 "missing.json": open missing.json: no such file or directory
配置文件不存在，加载默认配置
%w 和 %v 的差别非常重要：
fmt.Errorf("读取配置失败: %v", err) // 只拼接文本
fmt.Errorf("读取配置失败: %w", err) // 包装错误，保留错误链
两者打印出来可能很像，但只有 %w 能让 errors.Is、errors.As 继续识别底层错误。
错误链是怎么形成的
使用 %w 包装后，外层错误会提供：
Unwrap() error
可以把单链错误理解成：
HTTP 层错误
↓ Unwrap
Service 层错误
↓ Unwrap
Repository 层错误
↓ Unwrap
ErrNotFound
示例：
package main
import (
"errors"
"fmt"
)
var ErrRecordNotFound = errors.New("record not found")
func queryUser(id int64) error {
return fmt.Errorf("查询 user_id=%d: %w", id, ErrRecordNotFound)
}
func loadProfile(id int64) error {
if err := queryUser(id); err != nil {
return fmt.Errorf("加载用户资料: %w", err)
}
return nil
}
func main() {
err := loadProfile(1001)
fmt.Println(err)
fmt.Println(errors.Is(err, ErrRecordNotFound))
fmt.Println(errors.Unwrap(err))
}
输出：
加载用户资料: 查询 user_id=1001: record not found
true
查询 user_id=1001: record not found
errors.Unwrap 只拆一层。业务判断通常不需要手动循环解包，直接使用 errors.Is 或 errors.As 即可。
errors.Is：判断错误值和错误类别
直接使用 == 只能比较当前错误值：
err == ErrNotFound
错误被包装后，外层错误不再等于哨兵错误：
wrapped := fmt.Errorf("查询失败: %w", ErrNotFound)
fmt.Println(wrapped == ErrNotFound) // false
fmt.Println(errors.Is(wrapped, ErrNotFound)) // true
errors.Is 会沿错误树向下检查：
- 当前错误是否等于目标错误
- 当前错误是否实现自定义的
Is(error) bool - 当前错误能否通过
Unwrap继续展开
因此，只要错误可能被包装，就优先使用：
if errors.Is(err, ErrNotFound) {
// 按未找到处理
}
不要比较错误文本：
if err.Error() == "record not found" {
// 文本稍有变化就失效
}
错误文本用于展示和日志，errors.Is 用于程序分支。
errors.As：提取错误链中的具体类型
哨兵错误适合表达固定类别，自定义错误类型适合携带额外字段。
package main
import (
"errors"
"fmt"
)
type ValidationError struct {
Field string
Value any
Message string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("字段 %s 的值 %v 不合法：%s", e.Field, e.Value, e.Message)
}
func validateAge(age int) error {
if age < 0 || age > 150 {
return &ValidationError{
Field: "age",
Value: age,
Message: "必须在 0 到 150 之间",
}
}
return nil
}
func register(age int) error {
if err := validateAge(age); err != nil {
return fmt.Errorf("注册校验失败: %w", err)
}
return nil
}
func main() {
err := register(200)
var validationErr *ValidationError
if errors.As(err, &validationErr) {
fmt.Printf("field=%s, value=%v, message=%s\n",
validationErr.Field,
validationErr.Value,
validationErr.Message,
)
}
}
输出：
field=age, value=200, message=必须在 0 到 150 之间
直接类型断言只检查最外层动态类型：
validationErr, ok := err.(*ValidationError)
如果错误已经被 %w 包装，通常会断言失败。
errors.As 会遍历错误链，更适合提取可能被包装的自定义错误。
目标变量的写法要与错误类型一致：
var target *ValidationError
if errors.As(err, &target) {
// target 的类型是 *ValidationError
}
自定义错误同时保留底层原因
自定义错误不仅可以保存业务字段，也可以实现 Unwrap 保留底层错误：
package main
import (
"errors"
"fmt"
)
var ErrInsufficientBalance = errors.New("insufficient balance")
type PaymentError struct {
OrderID int64
Code string
Err error
}
func (e *PaymentError) Error() string {
return fmt.Sprintf("订单 %d 支付失败，code=%s: %v", e.OrderID, e.Code, e.Err)
}
func (e *PaymentError) Unwrap() error {
return e.Err
}
func pay(orderID int64) error {
return &PaymentError{
OrderID: orderID,
Code: "BALANCE_NOT_ENOUGH",
Err: ErrInsufficientBalance,
}
}
func main() {
err := pay(9001)
if errors.Is(err, ErrInsufficientBalance) {
fmt.Println("提示余额不足")
}
var paymentErr *PaymentError
if errors.As(err, &paymentErr) {
fmt.Printf("order_id=%d, code=%s\n", paymentErr.OrderID, paymentErr.Code)
}
}
输出：
提示余额不足
order_id=9001, code=BALANCE_NOT_ENOUGH
这时同一个错误同时支持两种判断：
errors.Is判断底层错误类别errors.As读取外层结构化信息
errors.Join：合并多个错误
有些操作可能同时产生多个错误。
例如关闭多个资源、批量校验多个字段、并行执行多个任务。只返回最后一个错误，会把前面的错误丢掉。
Go 1.20 增加了 errors.Join：
joined := errors.Join(firstErr, secondErr)
它有几个特点：
- 忽略传入的
nil - 所有参数都是
nil时返回nil - 错误文本通常按换行连接
errors.Is和errors.As可以遍历每个分支
批量校验示例：
package main
import (
"errors"
"fmt"
"strings"
)
var (
ErrNameRequired = errors.New("name is required")
ErrPasswordTooShort = errors.New("password is too short")
ErrEmailInvalid = errors.New("email is invalid")
)
type RegisterRequest struct {
Name string
Email string
Password string
}
func validate(request RegisterRequest) error {
var errs []error
if strings.TrimSpace(request.Name) == "" {
errs = append(errs, ErrNameRequired)
}
if !strings.Contains(request.Email, "@") {
errs = append(errs, ErrEmailInvalid)
}
if len(request.Password) < 8 {
errs = append(errs, ErrPasswordTooShort)
}
return errors.Join(errs...)
}
func main() {
err := validate(RegisterRequest{
Name: "",
Email: "invalid-email",
Password: "123",
})
if err == nil {
fmt.Println("校验通过")
return
}
fmt.Println(err)
fmt.Println("邮箱错误：", errors.Is(err, ErrEmailInvalid))
fmt.Println("密码错误：", errors.Is(err, ErrPasswordTooShort))
}
输出：
name is required
email is invalid
password is too short
邮箱错误： true
密码错误： true
errors.Join 形成的是错误树，不再只是单链。
它实现的是：
Unwrap() []error
而 errors.Unwrap 只处理 Unwrap() error，不会返回 errors.Join 的子错误。判断合并错误时，应直接使用 errors.Is 和 errors.As。
一个 fmt.Errorf 可以包装多个错误
现代 Go 允许一个 fmt.Errorf 格式串包含多个 %w：
err := fmt.Errorf("保存失败，写入错误: %w，关闭错误: %w", writeErr, closeErr)
这同样会形成多分支错误树，errors.Is 和 errors.As 可以检查其中任意分支。
如果只是把多个独立错误汇总起来，errors.Join 通常更直接。
如果还需要在一条错误文本中说明每个错误对应的操作，多个 %w 更有表达力。
实战一：读取并解析配置
下面的 demo 串起文件读取、JSON 解析、错误包装和错误分类。
package main
import (
"encoding/json"
"errors"
"fmt"
"os"
)
type Config struct {
Address string `json:"address"`
Port int `json:"port"`
}
func loadConfig(filename string) (Config, error) {
data, err := os.ReadFile(filename)
if err != nil {
return Config{}, fmt.Errorf("读取配置文件 %q: %w", filename, err)
}
var config Config
if err := json.Unmarshal(data, &config); err != nil {
return Config{}, fmt.Errorf("解析配置文件 %q: %w", filename, err)
}
if config.Address == "" {
return Config{}, errors.New("配置 address 不能为空")
}
if config.Port <= 0 || config.Port > 65535 {
return Config{}, fmt.Errorf("配置 port 超出范围: %d", config.Port)
}
return config, nil
}
func main() {
config, err := loadConfig("app.json")
if err != nil {
switch {
case errors.Is(err, os.ErrNotExist):
fmt.Println("配置文件不存在")
case errors.Is(err, os.ErrPermission):
fmt.Println("没有读取配置文件的权限")
default:
var syntaxErr *json.SyntaxError
if errors.As(err, &syntaxErr) {
fmt.Printf("JSON 第 %d 字节附近存在语法错误\n", syntaxErr.Offset)
return
}
fmt.Println("加载配置失败：", err)
}
return
}
fmt.Printf("配置加载成功：%s:%d\n", config.Address, config.Port)
}
这个例子体现了分层处理方式：
底层负责返回具体原因。
中间层使用 %w 增加操作上下文。
边界层使用 Is 或 As 决定最终动作。
实战二：统一 HTTP 错误响应
业务层不应该到处拼 HTTP JSON，也不应该把数据库错误原文直接返回给客户端。
可以定义应用错误，在 HTTP 边界统一映射：
package main
import (
"encoding/json"
"errors"
"fmt"
"net/http"
"net/http/httptest"
)
var ErrUserNotFound = errors.New("user not found")
type AppError struct {
Status int
Code string
Message string
Err error
}
func (e *AppError) Error() string {
return fmt.Sprintf("%s: %v", e.Code, e.Err)
}
func (e *AppError) Unwrap() error {
return e.Err
}
func getUser(id string) error {
if id == "" {
return &AppError{
Status: http.StatusBadRequest,
Code: "INVALID_ARGUMENT",
Message: "id 不能为空",
Err: errors.New("empty user id"),
}
}
return fmt.Errorf("查询用户 id=%s: %w", id, ErrUserNotFound)
}
func writeError(w http.ResponseWriter, err error) {
status := http.StatusInternalServerError
code := "INTERNAL_ERROR"
message := "服务暂时不可用"
var appErr *AppError
switch {
case errors.As(err, &appErr):
status = appErr.Status
code = appErr.Code
message = appErr.Message
case errors.Is(err, ErrUserNotFound):
status = http.StatusNotFound
code = "USER_NOT_FOUND"
message = "用户不存在"
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(map[string]string{
"code": code,
"message": message,
})
}
func handler(w http.ResponseWriter, r *http.Request) {
if err := getUser(r.URL.Query().Get("id")); err != nil {
writeError(w, err)
return
}
w.WriteHeader(http.StatusNoContent)
}
func main() {
request := httptest.NewRequest(http.MethodGet, "/user?id=1001", nil)
recorder := httptest.NewRecorder()
handler(recorder, request)
fmt.Println("status:", recorder.Code)
fmt.Print("body: ", recorder.Body.String())
}
输出：
status: 404
body: {"code":"USER_NOT_FOUND","message":"用户不存在"}
这里把两类信息分开了：
- 内部错误链：用于日志和排查
- 对外错误码与消息：用于稳定 API 契约
数据库地址、SQL、文件路径和调用栈等内部信息不应该直接暴露给客户端。
实战三：只重试可恢复错误
重试不能只看“发生了错误”。参数错误、权限错误等永久性错误，重复执行不会变好。
可以定义带重试信息的错误类型：
package main
import (
"errors"
"fmt"
"time"
)
type TemporaryError struct {
After time.Duration
Err error
}
func (e *TemporaryError) Error() string {
return fmt.Sprintf("临时错误，%s 后可重试: %v", e.After, e.Err)
}
func (e *TemporaryError) Unwrap() error {
return e.Err
}
func retry(maxAttempts int, operation func() error) error {
var lastErr error
for attempt := 1; attempt <= maxAttempts; attempt++ {
err := operation()
if err == nil {
return nil
}
lastErr = err
var temporaryErr *TemporaryError
if !errors.As(err, &temporaryErr) {
return err
}
fmt.Printf("第 %d 次执行失败：%v\n", attempt, err)
if attempt < maxAttempts {
time.Sleep(temporaryErr.After)
}
}
return fmt.Errorf("重试 %d 次后仍然失败: %w", maxAttempts, lastErr)
}
func main() {
attempts := 0
err := retry(3, func() error {
attempts++
if attempts < 3 {
return &TemporaryError{
After: time.Millisecond,
Err: errors.New("远端服务超时"),
}
}
return nil
})
fmt.Println("最终错误：", err)
fmt.Println("执行次数：", attempts)
}
输出：
第 1 次执行失败：临时错误，1ms 后可重试: 远端服务超时
第 2 次执行失败：临时错误，1ms 后可重试: 远端服务超时
最终错误： <nil>
执行次数： 3
真实项目还应考虑指数退避、随机抖动、上下文取消、请求幂等性和最大总耗时。
实战四：保留关闭资源时的错误
很多代码会这样写：
defer file.Close()
读取文件时通常可以接受，但写文件、刷新缓冲区或提交数据时，关闭阶段也可能失败。完全忽略 Close 错误，可能把写入不完整误判成成功。
可以使用命名返回值和 errors.Join 合并主流程错误与关闭错误：
package main
import (
"errors"
"fmt"
)
type Writer struct {
writeErr error
closeErr error
}
func (w *Writer) Write([]byte) error {
return w.writeErr
}
func (w *Writer) Close() error {
return w.closeErr
}
func save(writer *Writer, data []byte) (err error) {
defer func() {
err = errors.Join(err, writer.Close())
}()
if writeErr := writer.Write(data); writeErr != nil {
return fmt.Errorf("写入数据: %w", writeErr)
}
return nil
}
func main() {
writeErr := errors.New("磁盘空间不足")
closeErr := errors.New("刷新缓冲区失败")
err := save(&Writer{writeErr: writeErr, closeErr: closeErr}, []byte("data"))
fmt.Println(err)
fmt.Println("包含写入错误：", errors.Is(err, writeErr))
fmt.Println("包含关闭错误：", errors.Is(err, closeErr))
}
输出：
写入数据: 磁盘空间不足
刷新缓冲区失败
包含写入错误： true
包含关闭错误： true
是否必须处理 Close 错误取决于资源语义。只读文件和内存缓冲区的风险不同，持久化写入、压缩流和网络连接更值得关注关闭阶段的结果。
typed nil：看起来是 nil，返回后却不为 nil
error 是接口，接口值由动态类型和动态值组成。
下面的函数有隐藏问题：
type QueryError struct{}
func (*QueryError) Error() string {
return "query failed"
}
func bad() error {
var err *QueryError
return err
}
err 指针虽然是 nil，返回到 error 接口后，接口中仍然保存了动态类型 *QueryError，所以接口本身不等于 nil。
完整示例：
package main
import "fmt"
type QueryError struct{}
func (*QueryError) Error() string {
return "query failed"
}
func bad() error {
var err *QueryError
return err
}
func good() error {
return nil
}
func main() {
fmt.Println("bad() == nil：", bad() == nil)
fmt.Println("good() == nil：", good() == nil)
}
输出：
bad() == nil： false
good() == nil： true
没有错误时应直接返回字面量 nil，不要把 nil 具体指针装进 error 接口。
应该包装，还是直接返回
不是每一层都必须包装。
包装适合补充有价值的上下文：
return fmt.Errorf("读取订单 %d: %w", orderID, err)
直接返回适合当前函数没有新增信息的情况：
return repository.Save(order)
无意义的层层包装会产生噪声：
handler failed: service failed: use case failed: repository failed: query failed
更实用的判断标准是：
当前层能否补充操作名、关键标识或业务阶段？
能补充有效上下文就包装，不能就直接返回。
还有一个重要边界：包装底层错误等于允许调用方通过 errors.Is 或 errors.As 观察它。
公开包如果不希望暴露底层实现细节，可以转换成包自己的错误契约，而不是直接 %w 暴露数据库驱动错误。
错误应该在哪里记录日志
常见问题是每一层都记录一次：
Repository 记录一次
Service 记录一次
Handler 再记录一次
同一个故障最终产生三条甚至更多重复日志。
更清楚的分工是：
底层：返回错误，必要时增加上下文。
中间层：分类、转换或继续包装。
系统边界：记录一次完整日志，并决定响应、退出或重试。
HTTP 服务通常在中间件或 Handler 边界记录；命令行程序通常在 main 附近记录；后台任务通常在任务执行器边界记录。
如果中间层已经真正处理了错误，例如降级成功、忽略了某个可接受错误，记录一条有业务意义的日志也合理。
错误文本怎么写
Go 标准库和常见项目通常使用小写开头、不加句号的错误文本：
errors.New("user not found")
fmt.Errorf("read config %q: %w", filename, err)
原因是错误经常会被继续包装：
start server: load config: read config "app.json": file does not exist
每一层都写完整句子和句号，组合后会显得断裂。
中文项目不受大小写影响，但仍适合保持短语风格，并包含必要上下文：
fmt.Errorf("查询订单 order_id=%d: %w", orderID, err)
不要把密码、令牌、完整身份证号等敏感数据写进错误文本，因为错误很可能进入日志和监控系统。
error 和 panic 的边界
error 用于调用方可以预期并处理的失败：
- 参数不合法
- 文件不存在
- 用户不存在
- 余额不足
- 请求超时
- 数据库暂时不可用
panic 更适合程序内部不变量被破坏，或者初始化阶段已经无法继续运行：
- 必需的静态模板无法加载
- 程序内部状态违反不变量
- 数组越界和 nil 指针等编程错误
普通业务失败不应该使用 panic：
if balance < amount {
return ErrInsufficientBalance
}
而不是：
if balance < amount {
panic("余额不足")
}
recover 不是通用错误处理
recover 只能在同一个 goroutine 的延迟函数中捕获 panic。
func runSafely(task func()) (err error) {
defer func() {
if value := recover(); value != nil {
err = fmt.Errorf("任务发生 panic: %v", value)
}
}()
task()
return nil
}
它适合放在进程边界或任务边界，例如 HTTP 中间件、消息消费者和任务执行器，防止单个任务的 panic 直接拖垮整个服务。
recover 之后不能假装什么都没发生。通常还需要记录堆栈、终止当前请求或任务，并确保共享状态没有处于半完成状态。
不要用 panic 加 recover 模拟 try-catch。可预期失败继续使用 error。
常见错误
忽略 error
不推荐：
data, _ := os.ReadFile("config.json")
如果确实允许忽略，应写清楚原因，例如尽力而为的清理操作。普通业务流程直接丢弃错误，很容易把根因变成后续的空值、脏数据或 panic。
使用 %v 破坏错误链
return fmt.Errorf("保存用户失败: %v", err)
文本还在，但错误身份丢失。
需要保留底层原因时使用：
return fmt.Errorf("保存用户失败: %w", err)
使用 == 判断包装错误
if err == ErrNotFound {
// 包装后匹配不到
}
更稳妥的写法：
if errors.Is(err, ErrNotFound) {
// 可以沿错误链匹配
}
比较 err.Error()
if err.Error() == "user not found" {
}
错误文本一旦增加 ID、操作名或本地化内容，判断就会失效。稳定分类应使用哨兵错误、错误类型或明确错误码。
返回 nil 具体指针
func load() error {
var err *LoadError
return err
}
返回后的接口不等于 nil。成功分支直接 return nil。
到处记录同一个错误
错误每向上传一层就记录一次，会造成重复告警和日志噪声。通常在真正处理错误的边界记录一次即可。
把内部错误直接返回给客户端
下面的做法可能泄露 SQL、路径和内部结构：
http.Error(w, err.Error(), http.StatusInternalServerError)
对外返回稳定的错误码和安全消息，内部日志保留完整错误链。
工程实践建议
先定义错误契约
包的调用方需要区分哪些失败，应在设计 API 时明确：
var ErrNotFound = errors.New("not found")
或者：
type ValidationError struct {
Field string
}
不需要调用方识别的内部细节，不必全部导出。
增加能定位问题的上下文
好的错误信息通常包含：
- 做了什么操作
- 操作对象的非敏感标识
- 底层原因
例如：
return fmt.Errorf("更新订单 order_id=%d 状态为 %s: %w", orderID, status, err)
用 Is 分类，用 As 取字段
if errors.Is(err, ErrNotFound) {
// 判断稳定错误类别
}
var validationErr *ValidationError
if errors.As(err, &validationErr) {
// 读取字段名等结构化信息
}
在边界完成错误翻译
数据库错误不应该一路原样变成 HTTP 响应。
常见转换关系：
| 内部错误 | HTTP 状态 | 对外错误码 |
|---|---|---|
| 参数校验失败 | 400 | INVALID_ARGUMENT |
| 资源不存在 | 404 | NOT_FOUND |
| 数据冲突 | 409 | CONFLICT |
| 权限不足 | 403 | PERMISSION_DENIED |
| 未知系统错误 | 500 | INTERNAL_ERROR |
同样的业务错误也可以在 gRPC、消息任务或命令行边界翻译成各自的协议结果。
测试错误语义，不要锁死完整文本
脆弱测试：
if err.Error() != "load user: user not found" {
// 文案调整就失败
}
更稳定的测试：
if !errors.Is(err, ErrUserNotFound) {
// 错误类别不符合预期
}
自定义错误可以结合 errors.As 检查关键字段。只有错误文本本身就是公开契约时，才需要完整字符串比较。
常见问题
errors.New 和 fmt.Errorf 怎么选
固定文本使用 errors.New：
errors.New("invalid state")
需要插入变量使用 fmt.Errorf：
fmt.Errorf("invalid state %q", state)
需要保留底层错误链时使用 %w：
fmt.Errorf("update state: %w", err)
errors.Is 会比较错误文本吗
不会。
errors.Is 主要根据错误值身份、错误链和自定义 Is 方法判断。两个文本相同的 errors.New 错误通常不会匹配。
errors.As 和类型断言有什么区别
类型断言只看当前接口值的动态类型：
target, ok := err.(*ValidationError)
errors.As 会沿错误树查找：
var target *ValidationError
ok := errors.As(err, &target)
错误可能被包装时使用 errors.As。
errors.Unwrap 能拆开 errors.Join 吗
不能。
errors.Unwrap 只调用 Unwrap() error，而 errors.Join 返回的错误实现 Unwrap() []error。合并错误应使用 errors.Is、errors.As，或者在确实需要遍历时断言 interface{ Unwrap() []error }。
错误包装层数越多越好吗
不是。
包装的价值在于补充上下文和保留原因。没有新增信息的包装只会让文本重复。包边界、业务阶段和外部系统调用通常是比较有价值的包装位置。
自定义错误应该使用值还是指针
两种方式都可以，但需要保持一致。
复杂错误通常使用指针接收者：
func (e *ValidationError) Error() string
这样只有 *ValidationError 实现 error，errors.As 的目标也应写成：
var target *ValidationError
errors.As(err, &target)
不要一部分代码返回值，一部分代码返回指针，否则匹配逻辑容易混乱。
总结
Go error 的核心可以压缩成几句话：
error 是只有 Error() string 方法的内置接口。
nil 表示成功，非 nil 表示失败。
errors.New 创建固定错误，fmt.Errorf 创建动态错误。
fmt.Errorf 配合 %w 可以增加上下文并保留错误链。
errors.Is 用于判断错误值和错误类别。
errors.As 用于提取错误链中的具体错误类型。
errors.Join 用于保留多个并列错误。
错误文本用于阅读，错误值、类型和错误码用于程序判断。
可预期失败返回 error，内部不变量破坏才考虑 panic。
日志通常在系统边界记录一次。
日常选择可以按下面这张表判断：
| 场景 | 常见写法 |
|---|---|
| 固定错误文本 | errors.New("...") |
| 动态错误文本 | fmt.Errorf("id=%d", id) |
| 包装底层错误 | fmt.Errorf("操作失败: %w", err) |
| 判断哨兵错误 | errors.Is(err, ErrNotFound) |
| 提取自定义错误 | errors.As(err, &target) |
| 合并多个错误 | errors.Join(errs...) |
| 普通业务失败 | 返回 error |
| 内部不变量被破坏 | 视边界决定是否 panic |
| HTTP 或任务边界 | 记录日志并翻译错误 |
if err != nil 只是错误处理的入口。真正稳定的错误体系，需要保留原因、补充上下文、提供可判断的错误语义，并在合适的边界完成日志记录和协议转换。
