用途:为 Go Web 应用提供一套生产级编码规范,通过五条不可协商的规则约束每个 handler、service 与代码行。
主要能力:
- 零全局状态:所有 handler 必须是持有依赖(db、logger、HTTP 客户端、缓存)的 struct 方法,禁止包级可变状态;允许包级常量、纯函数、哨兵错误与 validator 实例。
- 显式错误处理:每个错误都要检查并用 fmt.Errorf("doing X: %w", err) 包装,json.NewEncoder(w).Encode 的错误也要处理;可用 AppError 结构统一映射 HTTP 错误。
- 校验优先:在边界用 go-playground/validator 校验所有传入 JSON,校验失败返回 400/422,内部数据视为可信,不重复校验。
- 可测试性:每个 handler 配套 _test.go,使用 httptest.NewRequest 与 httptest.NewRecorder 通过 HTTP 层测试,采用表驱动测试并覆盖错误路径。
- 文档:每个导出符号都要有以其名称开头的 Go doc 注释,并说明重要错误返回。
使用方式:按依赖、边界、错误、测试、文档五个硬性关卡依次落地;新增 HTTP handler 时逐项通过后再进入下一步。参考资料 references/validation.md 覆盖自定义校验器、嵌套结构体与跨字段校验;references/testing-handlers.md 覆盖中间件测试、集成测试、文件上传与流式响应测试。
适用场景:Go 后端 API 开发、代码评审与自检清单。
限制:资料未提供安装命令、收费或平台信息;规则为规范性约定,具体项目需自行适配。