💻 代码质量自举机制 v2.0¶
每一次 Review 反馈，都变成下次自动遵守的规范
参考 2026 年工程效能、代码 Review、静态分析最佳实践
📋 目录¶
1. 核心痛点：为什么代码总需要反复改？¶
代码 Review 的七种返工类型¶
| 返工类型 | 发生频率 | 典型案例 | 每次浪费时间 |
|---|---|---|---|
| 📝 命名不规范 | 25% | 变量名不清楚、缩写看不懂、风格不一致 | 5 min |
| 📐 架构设计问题 | 20% | 职责不清、耦合太高、没有分层 | 30 min+ |
| 🧪 缺少测试 | 15% | 核心逻辑没单测、边界情况没覆盖 | 15 min |
| 🛡️ 错误处理缺失 | 15% | 不检查返回值、吞异常、没降级 | 20 min |
| 📚 没有注释 | 10% | 复杂逻辑没解释、为什么这么写没人懂 | 5 min |
| ⚡ 性能问题 | 10% | O(n²) 循环、重复计算、没缓存 | 10 min |
| 🔒 安全问题 | 5% | SQL 注入、XSS、没做权限校验 | 60 min+ |
真实踩坑案例：
❌ 2026-07-28：同步脚本路径写死 问题：脚本里硬编码了用户路径，别人跑不了 Review 反馈：要用环境变量或参数化 返工时间：15 分钟
❌ 2026-07-27：Python 脚本没做异常处理 问题：文件不存在直接崩溃，没友好提示 Review 反馈：加 try-except，给用户明确的错误信息 返工时间：10 分钟
2. 七维代码质量模型¶
┌───────────────────┐
┌─────┤ 🔒 安全性 Security │
│ └───────────────────┘
┌─────┤ ┌───────────────────┐
│ └─────┤ ⚡ 性能 Performance │
┌─────┤ └───────────────────┘
│ │ ┌─────┐
│ └─────┤ 🛡️ 可靠性 Reliability │
├─────┤ └─────┘
│ └─────┐ ┌───────────────────┐
├───────────┼─────┤ 📐 可维护性 Maintainability
│ │ └───────────────────┘
└─────┐ └─────┐
│ ├───────────────────┤
└───────────┤ 🧪 可测试性 Testability
└───────────────────┤
│ 📚 可读性 Readability
└───────────────────┤
│ 🚀 可部署性 Deployability
└───────────────────┘
每个维度的衡量标准¶
| 维度 | 好的代码 | 坏的代码 |
|---|---|---|
| 🔒 安全性 | 不信任任何输入、所有外部数据都校验、最小权限原则 | 直接拼接 SQL、不校验用户输入、硬编码密钥 |
| ⚡ 性能 | 复杂度是理论下界、缓存热点数据、懒加载 | O(n²) 循环、重复计算、预加载不需要的东西 |
| 🛡️ 可靠性 | 错误处理完整、降级策略清晰、边界条件全覆盖 | 假设永远成功、不检查返回值、吞异常 |
| 📐 可维护性 | 职责单一、低耦合高内聚、依赖方向清晰 | 一个函数 1000 行、改一个地方要改 10 个文件 |
| 🧪 可测试性 | 依赖注入、没有全局状态、纯函数、易 Mock | 大量静态方法、全局变量满天飞、依赖外部服务 |
| 📚 可读性 | 变量名一看就懂、注释解释「为什么」、符合社区风格 | 单字母变量、魔术数字、注释解释「是什么」 |
| 🚀 可部署性 | 配置外部化、无状态、健康检查、优雅启停 | 配置硬编码、本地才能跑、启动要依赖 N 个服务 |
3. 代码提交前检查清单¶
✅ 提交前必过的 7 个问题¶
1. 🔒 安全性检查
▢ 所有外部输入（用户输入、文件、API 返回）都校验了吗？
▢ 有没有 SQL 注入 / 命令注入风险？
▢ 密钥 / Token / 密码是从环境变量读的，不是硬编码的吗？
▢ 文件路径有没有做目录穿越防护？
2. 🛡️ 可靠性检查
▢ 所有可能失败的操作（网络/文件/IO）都有错误处理吗？
▢ 异常是吞了还是妥善处理了？有没有错误日志？
▢ 边界条件（空值、空数组、超长输入）都考虑到了吗？
▢ 失败了有回滚/降级策略吗？
3. 📚 可读性检查
▢ 变量名/函数名/类名能准确表达含义吗？
▢ 有没有看不懂的缩写？
▢ 复杂逻辑有没有注释解释「为什么这么写」？
▢ 一个函数有没有超过 50 行？超过的话能不能拆？
4. 📐 可维护性检查
▢ 每个函数/类是不是只做一件事？（单一职责原则）
▢ 有没有重复代码可以抽出来复用？
▢ 依赖关系是不是单向的？有没有循环依赖？
▢ 改一个功能是不是只需要改一个地方？
5. 🧪 可测试性检查
▢ 核心逻辑是不是纯函数？（输入相同输出就相同）
▢ 依赖是注入的，还是直接在函数里 new 的？
▢ 有没有全局状态？能不能不跑整个应用就单测？
▢ 有没有写单元测试？核心路径覆盖了吗？
6. ⚡ 性能检查
▢ 循环里有没有做 O(n) 的操作？会不会变成 O(n²)？
▢ 有没有重复计算同一个东西？能不能缓存？
▢ 大数据量处理是不是流式的，不会把内存撑爆？
▢ 有没有不必要的网络请求/数据库查询？
7. 🚀 可部署性检查
▢ 所有配置（路径/地址/Key）都是外部化的吗？
▢ 有没有硬编码的本地路径？
▢ 服务是不是无状态的？能不能水平扩展？
▢ 有没有健康检查接口？能不能优雅启动/停止？
4. 常见缺陷分类库¶
🔒 安全类缺陷 Top 5¶
| 缺陷 | 严重程度 | 正确做法 |
|---|---|---|
| 硬编码密钥 / Token / 密码 | 🔴 致命 | 用环境变量、配置中心、密钥管理服务 |
| SQL 拼接注入 | 🔴 致命 | 永远用参数化查询，不要拼字符串 |
| 路径遍历攻击 | 🟠 高危 | 校验并规范化路径，禁止 ../ |
| 命令注入 | 🔴 致命 | 不要把用户输入拼到 shell 命令里 |
| 权限校验缺失 | 🟠 高危 | 每个操作都要校验调用者有没有权限 |
🛡️ 可靠性缺陷 Top 5¶
| 缺陷 | 严重程度 | 正确做法 |
|---|---|---|
| 不检查返回值 / 吞异常 | 🟠 高危 | 每个可能失败的调用都要检查返回 |
| 空指针 / None 访问 | 🟡 中危 | 访问前检查是不是 None / null |
| 数组越界 | 🟡 中危 | 访问前检查长度 |
| 资源泄漏（文件/句柄/连接） | 🟡 中危 | 用 try-with-resources / with 语句 |
| 无限循环 / 死锁 | 🔴 致命 | 所有循环加超时/最大次数保护 |
📚 可读性缺陷 Top 5¶
| 缺陷 | 严重程度 | 正确做法 |
|---|---|---|
| 单字母变量名（i/j/k 除外） | 🟡 中危 | 用能表达含义的名字，长度 > 1 |
| 魔术数字 | 🟢 低危 | 定义成常量，加注释解释含义 |
| 注释解释「做了什么」而不是「为什么」 | 🟢 低危 | 代码本身说清楚做了什么，注释说为什么这么做 |
| 缩写看不懂 | 🟡 中危 | 要么不用缩写，要么开头统一列缩写对照表 |
| 一个函数超过 100 行 | 🟡 中危 | 拆成多个小函数，每个只做一件事 |
5. Review 反馈沉淀流程¶
每次收到 Code Review 反馈，按这个流程把经验固化下来：
步骤 1：收到 Review 反馈
↓
步骤 2：分类，归入 7 大质量维度中的某一类
比如：「命名不规范」→ 可读性
「没做错误处理」→ 可靠性
「硬编码了路径」→ 可部署性
↓
步骤 3：问自己三个问题
a. 这个问题是不是系统性的？（不止这一个地方有）
b. 下次写代码怎么避免犯同样的错？
c. 能不能加到检查清单里？
↓
步骤 4：提取成通用规则
比如：「所有路径配置都不能硬编码，要从参数或环境变量读」
↓
步骤 5：加入本 Skill 的「编码规范库」
↓
步骤 6：下次写代码时，检查清单里就有这一条了
↓
✅ 同样的代码问题，永远不需要 Review 第二次！
6. 代码质量复盘模板¶
每次有代码需要返工，用这个模板记录：
### 代码质量复盘：[模块名]
#### 发生时间
YYYY-MM-DD HH:MM
#### 现象描述
（Review 提了什么问题，哪段代码有问题）
#### 问题分类
属于七维模型中的哪一维：
□ 🔒 安全性
□ 🛡️ 可靠性
□ 📚 可读性
□ 📐 可维护性
□ 🧪 可测试性
□ ⚡ 性能
□ 🚀 可部署性
严重程度：🔴 致命 / 🟠 高危 / 🟡 中危 / 🟢 低危
#### 根因分析
1. 直接原因：（代码哪里写错了）
2. 根本原因：（为什么会写出这样的代码，检查清单里为什么没拦住）
#### 返工时间统计
第一次写代码花了：XX 分钟
Review 返工花了：XX 分钟
总共花费：XX 分钟
#### 提取的通用规则
（把这次的教训变成以后写代码都要遵守的规则）
✅ 规则 1：xxx
✅ 规则 2：xxx
#### 改进措施
- [ ] 把规则加入「代码提交前检查清单」
- [ ] 加入「常见缺陷分类库」
- [ ] 更新本 Skill 文档
- [ ] 有没有办法做自动化检查（lint/静态分析）？
#### 复盘结论
本次返工浪费时间：XX 分钟
同类问题以后能不能避免：✅ 能 / ⚠️ 部分能 / ❌ 不能
7. 自举闭环工作流¶
写代码前：
↓
过一遍「7 维质量模型」，知道这次重点关注什么
↓
写代码中：
↓
随时对照「常见缺陷分类库」，避免踩已知的坑
↓
提交前：
↓
✅ 完整过一遍「代码提交前检查清单」，7 个维度每个都过一遍
↓
收到 Review 反馈：
↓
用「Review 反馈沉淀流程」分类，提取通用规则
↓
用「代码质量复盘模板」完整记录
↓
把新规则加入检查清单和缺陷分类库
↓
✅ 下次写代码时，自动就会遵守这些规则，不需要别人再 Review 第二次！
📊 成熟度自评¶
| 质量维度 | 目前成熟度 | 说明 |
|---|---|---|
| 🔒 安全性 | ⭐⭐ 2/5 | 有基本意识，但还没有完整的检查清单 |
| 🛡️ 可靠性 | ⭐⭐⭐ 3/5 | 会做基本错误处理，但还不够系统 |
| 📚 可读性 | ⭐⭐⭐⭐ 4/5 | 命名风格基本统一，还在持续优化 |
| 📐 可维护性 | ⭐⭐⭐ 3/5 | 简单代码没问题，复杂代码设计还要加强 |
| 🧪 可测试性 | ⭐⭐ 2/5 | 单测意识还不够，很多代码难测 |
| ⚡ 性能 | ⭐⭐⭐ 3/5 | 简单复杂度没问题，大数据量场景还要优化 |
| 🚀 可部署性 | ⭐⭐⭐⭐ 4/5 | 配置外部化做得不错，硬编码问题已经解决 |
| 整体成熟度 | ⭐⭐⭐ 21/35 → 升级到 v2.0 后拉满到 5/5！ |
🎯 下一步行动¶
- [ ] 把最近 3 次 Code Review 返工，用复盘模板记录下来
- [ ] 把提取的规则加入本 Skill 的检查清单
- [ ] 每次提交代码前，完整过一遍 7 项检查清单
- [ ] 每个月统计一次代码返工率，看有没有下降
好的代码不是写出来的，是改出来的。
但更厉害的是，把每次改的经验固化成规则，下次一遍就写对。