Go项目统一管理错误码的核心是构建结构化常量体系，集中定义、分组命名、配套消息模板与AppError封装，并映射HTTP状态码，辅以文档生成和CI校验保障一致性。
Go项目中统一管理错误码，核心是把错误码从散落在各处的字符串或数字，变成可查、可维护、可扩展的结构化常量体系，并配合有意义的错误包装和上下文传递。关键不在于“定义多少个码”，而在于“怎么让码真正被用起来、不冲突、不重复、不难查”。
错误码用常量而非硬编码
避免在代码里直接写"ERR_USER_NOT_FOUND"或1001，全部收归到一个集中文件（如pkg/error/code.go）中定义为具名常量：
- 用iota自增生成整型码，语义清晰又防重复
- 配套定义对应的消息模板（非固定文案，支持格式化），方便日志和API返回
- 按业务域分组（如UserErrXXX、OrderErrXXX），加注释说明使用场景
错误值 = 错误码 + 原始错误 + 上下文
单纯返回错误码不够，Go强调错误链（error wrapping）。推荐封装一个AppError结构体或函数：
- 包含Code（对应上面的常量）、Message（带占位符的模板）、Cause（原始error，如sql.ErrNoRows）
- 实现Error()方法，输出含码+消息+cause链的可读字符串
- 提供Wrap(code, format, args...)辅助函数，一行完成码注入+上下文补充
HTTP API层做错误码到状态码的映射
错误码是业务概念，HTTP状态码是传输协议概念，二者不能混用。需建立明确映射规则：
- 例如：所有UserErrXXX默认映射为400 Bad Request；权限类码（如AuthErrForbidden）映射为403 Forbidden；系统级失败（如SysErrDBDown）映射为500 Internal Server Error
- 在统一的HTTP中间件或响应构造器中完成转换，避免每个handler手动判断
- 响应体结构统一包含code（业务码）、message（前端友好提示）、trace_id（便于查日志）
配套工具提升可用性
光有设计不够，得让人愿意用、不容易错：
- 生成错误码文档：用go:generate扫描常量，自动输出Markdown或JSON格式的码表（含码值、名称、说明、HTTP状态）
- CI阶段校验：禁止新增错误码时漏写注释，或出现重复iota值
- 日志打点时自动提取AppError.Code，聚合看板可按码统计错误率
基本上就这些。不复杂但容易忽略的是“一致性”——只要团队约定好从哪导入码、怎么包装错误、谁负责更新文档，就能让错误码真正成为协作语言，而不是又一个没人维护的常量文件。
