Repository navigation
14 comprehensive checklist
omeyang edited this page Sep 16, 2026
·
1 revision
本文档整合所有代码质量标准的检查清单，用于代码提交前自查和 Code Review。
提交前必须执行以下检查：
golangci-lint run ./... # 静态分析
gocyclo -over 10 internal/ # 复杂度
go test ./... -cover # 测试覆盖率必须全部通过，否则禁止提交。
- 必须追求"优秀"而非"能跑"
- 应该质疑不合理的现有代码
- 必须考虑长期可维护性
- 应该从业务角度抽象，避免技术绑架
- 禁止以"原来就这样"为由拒绝改进
- 正确性：测试覆盖率不低于 90%（核心业务不低于 95%）
- 可维护性：函数不超过 70 行，复杂度不超过 10
- 健壮性：错误处理完善
- 性能：P99 不超过 100ms
- 可观测性：日志、监控完善
- 禁止过度设计（抽象需 2 种及以上实现）
- 不应该过度追求性能（牺牲可读性）
- 禁止过度 Mock（业务逻辑不 Mock）
- 应该遵循 TDD 流程（红 -> 绿 -> 重构）
- 应该测试先于实现编写
- 必须每个测试验证一个明确的行为
- 核心业务逻辑不低于 95%
- API 层不低于 90%
- 整体代码不低于 90%
- 边界条件必须有覆盖
- 应该 Mock 外部依赖（数据库、HTTP、消息队列）
- 禁止 Mock 核心业务逻辑
- 禁止 Mock 简单结构体
- 应该验证 Mock 调用次数
- 接口必须小而专注（单一职责）
- 应该优先使用单方法接口
- 接口命名禁止包含包名
- 接口应该按职责拆分
- 必须有 2 种及以上实现时才抽象
- 禁止为了抽象而抽象
- 必须遵循 YAGNI 原则
- 同一函数抽象层次必须一致
- 禁止抽象泄漏
- 接口禁止暴露实现细节
- 所有错误必须处理（禁止用
_忽略） - 必须使用
%w包装错误 - 错误应该携带足够上下文
- 必须使用
errors.Is和errors.As判断错误
- 必须检查 nil
- 必须检查空字符串
- 必须检查空切片
- 必须检查数值边界
- 必须检查索引越界
- API 层必须验证参数
- Service 层应该验证业务规则
- 禁止信任外部输入
- 必须保护共享状态
- 必须使用
-race检测数据竞争 - 必须安全使用 channel
- 必须防止 SQL/NoSQL 注入
- 必须防止命令注入
- 禁止在日志中记录敏感信息
- 应该使用加密存储密码
- 函数能用一句话（无"并且"）描述功能
- 函数体内操作处于同一抽象层次
- 函数不超过 70 行，应该不超过 40 行
- 嵌套深度不超过 3 层
- 参数不超过 3 个（不含
ctx），超过用结构体 - 参数顺序：
ctx→ 主输入 → 选项 - 无裸布尔参数
- 无输出参数（out parameter）
- 返回值不超过 3 个，
error在最后
- 命令函数和查询函数分离（CQS）
- 纯计算逻辑无副作用
- 使用 Guard Clause 提前返回
- 副作用集中在函数末尾
- 所有导出的标识符都有明确的外部使用者
- 没有"以防万一"的导出
- 有约束的字段不导出
- 有约束的类型提供了构造函数
- 构造函数校验了参数合法性
- DTO/配置结构体可以导出字段
- 导出函数/方法不超过 15 个
- 导出类型不超过 5 个
- 使用
internal/隐藏实现包 - 没有导出的全局可变状态
- 新增功能不应该修改现有代码
- 应该使用策略模式替代 if-else
- 必须依赖接口而非实现
- 禁止使用全局变量
- 禁止硬编码依赖
- 应该使用依赖注入
- 单包 Fan-out 不超过 5
- 无控制耦合（不传递控制标志）
- 模块职责必须单一
- 模块内功能必须高度相关
- 禁止有 "工具类"、"通用类"
- 应该按功能分包，而非技术分包
- 包内聚度通过删除法/命名法验证
- 系统边界做了输入验证和协议转换
- 系统边界不包含业务逻辑
- 不同层使用不同数据模型（必要时）
- 分层验证（API 格式 → Service 业务 → Model 数据）
- 外部系统通过防腐层隔离
- 依赖方向必须清晰（上层依赖下层）
- 禁止循环依赖
- 核心业务禁止依赖基础设施细节
- 接口定义在使用方，而非实现方
- 依赖必须可注入
- 函数职责必须单一
- 禁止使用全局状态
- 时间应该可控（注入 TimeProvider）
- 关键路径必须有日志（入口、出口、错误）
- 必须使用结构化日志
- 应该暴露监控指标（/metrics）
- 应该支持分布式追踪
- 命名必须见名知义
- 函数应该不超过 70 行
- 参数应该不超过 3 个
- 嵌套应该不超过 3 层
- 代码风格必须一致
- 必须避免 N+1 查询
- 应该避免重复计算
- 应该避免不必要的内存分配
- 数据库查询应该有索引
- 应该批量操作替代逐个操作
- 热点数据应该有缓存
- 缓存必须有过期时间
- 应该避免缓存雪崩
- 应该使用 Goroutine 池限制并发
- Goroutine 必须有生命周期管理
- 禁止 Goroutine 泄漏
-
golangci-lint run ./...必须无错误 - 禁止有未处理的错误
- 禁止有未使用的变量/函数
- 禁止有安全问题
- 圈复杂度必须不超过 10（核心业务）
- 函数长度应该不超过 70 行
- 单文件长度必须不超过 800 行
- 单元测试覆盖率必须不低于 90%
- 所有测试必须通过
- 禁止有 flaky 测试
-
govulncheck ./...必须无漏洞 - 禁止有硬编码密码
- 输入验证必须完善
# 格式化
gofmt -w .
goimports -w .
# 静态分析
golangci-lint run ./...
# 复杂度
gocyclo -over 10 internal/
# 测试
go test ./... -v
go test ./... -cover
go test ./... -race
# 性能测试
go test -bench=. -benchmem ./...
# 安全检查
govulncheck ./...# 自动格式化
gofmt -w .
# 自动修复 lint 问题
golangci-lint run --fix ./...
# 自动添加/删除 import
goimports -w .- 功能符合需求
- 边界条件处理正确
- 错误处理完善
- 有单元测试覆盖
- 接口设计合理
- 抽象层次一致
- 没有过度设计
- 耦合度低，内聚度高
- 代码清晰易读
- 命名见名知义
- 没有魔法数字
- golangci-lint 通过
- 测试覆盖率达标
- 输入验证完善
- 无注入风险
- 敏感数据加密
- 无硬编码密码/密钥
- 无明显性能问题
- 数据库查询有索引
- 批量操作优化
- 无内存泄漏
- 关键操作有日志
- 日志携带足够上下文
- 有监控指标
- 代码已自测通过
- 单元测试覆盖率不低于 90%
-
golangci-lint run ./...无错误 -
gocyclo -over 10无输出 - 提交信息清晰
- 关联 Issue/任务单号
- 性能测试通过
- 安全扫描通过
- 文档已更新
- 自己先 Review 一遍代码
- 禁止提交未格式化的代码
- 禁止提交有 lint 错误的代码
- 禁止提交未测试的代码
- 禁止提交复杂度过高的代码
- 禁止跳过 CI/CD 检查
- Go Code Review Comments：https://go.dev/wiki/CodeReviewComments
- Effective Go：https://go.dev/doc/effective_go
- golangci-lint：https://golangci-lint.run/
- Uber Go Style Guide：https://github.com/uber-go/guide
本页由 Maat 仓库的 scripts/sync-wiki.sh 自动生成，请勿直接编辑。