17370845950

业务错误码不推荐用int，应定义自定义类型ErrorCode并封装AppError结构体，通过构造函数统一创建、绑定上下文，HTTP状态码映射应在transport层独立处理，全局错误码需按模块命名、集中管理、CI校验。

错误码该不该用 int 类型定义

Go 官方生态（如 net/http、os）普遍用 int 表示系统级错误码，但业务错误码**不推荐直接用 int 常量**。原因很实际：类型丢失导致易误用、无法携带上下文、IDE 无法跳转到定义、难以批量校验重复值。

• 用 int 定义：const ErrUserNotFound = 404 → 调用时可能被当成任意整数传入，编译器不报错
• 更安全的做法是定义自定义类型：

  type ErrorCode int
  
  const (
  	ErrUserNotFound ErrorCode = 1001
  	ErrInvalidToken ErrorCode = 1002
  )

• 配合 String() 方法还能让日志输出可读名：func (e ErrorCode) String() string { ... }

如何让错误码和 error 实例绑定

单纯定义常量没用，关键是要让每个错误码能生成带上下文的 error。别写 errors.New("user not found") 这种无结构的字符串错误。

• 用结构体封装错误码 + 消息 + 可选字段：

  type AppError struct {
  	Code    ErrorCode
  	Message string
  	TraceID string
  }
  
  func (e *AppError) Error() string { return e.Message }
  func (e *AppError) StatusCode() int { return int(e.Code) }
  

• 提供构造函数，强制走统一出口：NewUserNotFoundError("user id: 123") 内部自动填 Code: ErrUserNotFound
• 避免在 handler 层手动 new &AppError{...} —— 构造逻辑收口后，后续加 trace、metrics、i18n 才可控

错误码和 HTTP 状态码怎么映射才不混乱

业务错误码（如 1001）和 HTTP 状态码（如 404）是两层概念，硬性一一对应会出问题。比如 ErrRateLimited 应该返回 429，但 ErrInternalFailure 在调试环境可能返回 500，上线后却要返回 503。

• 不要在错误码常量里塞 HTTP 状态码：const ErrUserNotFound = 404 是典型反模式
• 用独立映射表或方法做转换：

  func (e ErrorCode) HTTPStatus() int {
  	switch e {
  	case ErrUserNotFound:
  		
  return 404
  	case ErrRateLimited:
  		return 429
  	default:
  		return 500
  	}
  }

• 映射逻辑放在 transport 层（如 HTTP handler），而不是 domain 层 —— 错误码本身应与协议无关

全局错误码表怎么维护才不易冲突

多人协作时，最怕两个模块都定义了 ErrInvalidParam = 1000。靠文档约定或人工 review 不可靠。

• 按模块划分命名空间：user.ErrInvalidEmail、order.ErrInsufficientStock，类型也分包定义
• 所有错误码常量集中在一个 errors/code.go 文件，禁止分散定义；用注释标注用途和责任人：

  // ErrInvalidEmail user module, used in email validation
  // @owner: auth-team
  const ErrInvalidEmail ErrorCode = 2001
  

• CI 加一道检查：用 go list -f '{{.ImportPath}}' ./... | xargs -I{} go tool vet -shadow {} 配合自定义脚本扫重复值

错误码不是写完就扔的常量，它会随着接口演进、多端适配、监控告警不断被读取和解释。真正麻烦的不是定义，而是当某天发现 ErrTimeout 在三个服务里含义不同、HTTP 状态码被前端硬编码、日志里只看到数字看不到上下文——那些地方，往往没在定义时就设计好边界。