03 coding checklist

编码自检清单

本文档提供代码提交前、Code Review、重构等场景的快速检查清单。

---

代码提交前自查

命名检查

• 函数名见名知义（不看注释就知道干什么）
• 导出名不包含包名（避免 order.OrderQuery()）
• 没有使用 manager/service/handler/util
• 类型名准确描述用途
• 变量名符合 camelCase
• 缩写全大写（ID/IP/HTTP/URL）

设计检查

• 模块职责单一
• 依赖接口而非具体实现
• 遵循四层架构（API -> Service -> Model -> Infrastructure）
• 没有跨层调用
• 没有循环依赖

质量检查

• 函数不超过 70 行
• 参数不超过 3 个（超过使用 struct）
• 圈复杂度不超过 10
• 无重复代码（3 次及以上必须抽取）
• golangci-lint run 通过

测试检查

• 单元测试覆盖率不低于 90%（核心业务不低于 95%）
• 测试通过 go test ./...
• Mock 接口而非实现
• 测试数据不硬编码

错误处理

• 使用 fmt.Errorf("%w", err) 包装错误
• 错误携带足够上下文（ID、关键参数等）
• 对外 API 返回可读错误消息
• Error 级别记录堆栈

并发安全

• Goroutine 有生命周期管理（context/errgroup）
• 共享数据有锁保护（sync.Mutex/sync.Map）
• Channel 发送方负责关闭

文档检查

• 包注释包含用途说明
• 公开函数有文档注释
• 复杂逻辑有注释说明

---

Code Review 检查

功能检查

• 功能符合需求
• 边界条件处理正确
• 错误处理完善

设计检查

• 接口设计合理
• 没有过度设计
• 可扩展性好

质量检查

• 代码清晰易读
• 命名见名知义
• 没有魔法数字
• golangci-lint 通过
• 测试覆盖率达标

安全检查

• 输入验证完善
• 无 SQL/NoSQL 注入风险
• 敏感数据加密
• 无硬编码密码/密钥

性能检查

• 无明显性能问题
• 数据库查询有索引
• 批量操作优化
• 无内存泄漏

---

重构检查

兼容性

• 旧接口保持可用
• 上游无需修改代码
• 下游无需修改代码

测试验证

• 单元测试通过
• 集成测试通过
• 回归测试通过（对比新旧行为）
• 性能测试无退化

灰度发布

• 有灰度方案（流量切分/特性开关）
• 有监控指标（成功率/响应时间/错误率）
• 有回滚方案（配置/代码/流量）
• 有告警设置

---

常用检查命令

# 代码质量检查
golangci-lint run ./...

# 圈复杂度检查
gocyclo -over 10 internal/

# 运行测试
go test ./... -v

# 测试覆盖率
go test ./... -cover

# 性能测试
go test -bench=. -benchmem

# 依赖检查
go mod tidy
go mod verify

# 安全检查
govulncheck ./...

---

提交前最后确认

• 代码已自测通过
• 单元测试覆盖率达标
• golangci-lint 无告警
• 无高复杂度函数
• 提交信息清晰（[类型] 简要描述）
• 关联 Issue/任务单号