6. 代码质量: 重构 / code review / 复杂度治理 / DDD 落地

TL;DR

代码质量决定的是"软件 5 年后还能不能改"。这一章把"好代码"从玄学变成可操作的方法：重构是有纪律的语义等价变换，code review 是质量门禁而非走过场，复杂度治理让代码不被技术债压垮，DDD 让复杂业务领域保持清晰。

读完应能：

1. 用"坏味道清单"发现代码问题，用安全的重构手法（保持行为不变）改进。
2. 知道 code review 该看什么、怎么给反馈、怎么不让人难受。
3. 用量化手段（圈复杂度等）治理复杂度，而不是靠感觉。
4. 理解 DDD 的核心战术（实体/值对象/聚合/领域服务）何时用。

一、什么是"好代码"

1.1 质量的本质：可修改性

代码质量 = 改它需要多少成本 + 多少风险。好代码 = 低成本、低风险地满足新需求。

不是"优雅""花哨"，而是：

• 可读：5 分钟后/5 个月后/别人能看懂。
• 可测：能写测试（依赖注入、边界清晰）。
• 可改：加功能不破坏其他部分（低耦合）。
• 可维护：出问题能快速定位。

1.2 四个质量维度

二、代码坏味道清单（先发现）

2.1 命名与结构

• 魔法数字/字符串：if (x > 86400) → 提取常量 ONE_DAY_SECONDS。
• 烂命名：d、temp、data2 → 用意图命名。
• 长函数：> 30-50 行 → 拆成有名字的小函数。
• 重复代码（DRY 违规）：两处相似逻辑 → 提取。
• 长参数列表：> 4 个参数 → 参数对象。

2.2 结构与耦合

• 上帝对象：一个类做所有事 → 拆分职责。
• 深耦合：A 知道 B 的内部细节 → 减少暴露。
• 散弹式修改：改一个需求要动 10 个文件 → 关注点没聚合。
• 过度耦合到具体实现：依赖接口而非具体类。

2.3 行为问题

• 注释撒谎：注释和代码不符 → 改注释或改代码。
• 死代码：没被调用 → 删。
• 隐藏依赖：函数依赖全局状态但签名看不出 → 参数显式传。
• 副作用隐藏在 getter 里：getName() 居然改状态 → 命名撒谎。

三、重构：有纪律的改进

3.1 重构的定义

重构 = 不改变外部行为，只改进内部结构，每一步都有测试兜底。

"我顺手改了一下"不算重构——重构必须每一步都能跑测试验证行为没变。

3.2 经典手法

3.3 重构的安全流程

1. 先补/跑测试（建立安全网）
2. 一次只做一个微重构（小步）
3. 每步跑测试（确认行为没变）
4. 全部绿 → 继续下一步；红 → 回退

3.4 示例：Extract Function

# ❌ 一个函数做三件事（校验、计算、格式化）
def process_order(order):
    # 校验
    if order.status != "pending":
        raise ValueError("invalid status")
    if order.total <= 0:
        raise ValueError("invalid total")
    # 计算
    total = order.total
    discount = 0.1 if total > 1000 else 0
    final = total * (1 - discount)
    # 格式化
    return f"ORDER-{order.id}-{final:.2f}"

# ✅ 拆成三个有名字的函数
def _validate_order(order): ...
def _calculate_total(order): ...
def _format_result(order_id, total): ...

def process_order(order):
    _validate_order(order)
    final = _calculate_total(order)
    return _format_result(order.id, final)

四、Code Review：质量门禁

4.1 看什么

Review 不是"找茬"，是理解 + 把关：

4.2 反馈的原则

• 对代码不对人：说"这个函数有问题"不说"你写错了"。
• 解释为什么：不只说"这里不对"，说"这里可能在 X 场景下崩，因为 Y"。
• 区分阻塞 vs 建议：明确"必须改"和"可以讨论"。
• 给方向不给答案：问"这里是不是该提取个函数？"优于直接贴代码。
• 关注重要的事：安全/正确性/性能 > 命名/格式（格式交给 linter）。

4.3 Review 的规模

• PR 太大（> 400 行）→ Review 质量急剧下降，应拆小。
• 每 PR 建议 200-400 行改动，一次审 < 60 分钟。
• Review 速度重要：拖 3 天的 review 比没有 review 更糟（阻塞交付）。目标 < 24h 反馈。

4.4 自动化的边界

交给工具: 格式 / lint / 类型 / 常见 bug（gosec/semgrep/staticcheck）
留给人:   设计 / 语义 / 权衡 / 业务正确性 / 一致性

五、复杂度治理

5.1 圈复杂度（Cyclomatic Complexity）

定义：代码中独立路径的数量 = 1 + 分支数(if/for/case/&&/||)。

def f(x):
    if x > 0: return "pos"    # +1
    elif x < 0: return "neg"  # +1
    return "zero"             # 基础 1
# 圈复杂度 = 3

治理标准：

• ≤ 10：正常
• 11-20：需要解释，考虑拆分

• 20：必须重构（几乎不可测）

工具：radon（Python）、gocyclo（Go）、SonarQube（通用）。

5.2 其他复杂度信号

5.3 复杂度的平衡

复杂度治理不是"越简单越好"——过度抽象（掉进简化主义）也是复杂度。平衡点：

• 代码是要读懂的（可读性优先），不是要"最短/最聪明"。
• 一个 5 行的 if 分支，比一个需要跳 3 个文件的抽象类更简单。
• "三法则"（Rule of Three）：代码用到第三次才提取抽象。前两次复制粘贴是合理的。

六、DDD（领域驱动设计）落地

6.1 DDD 解决什么

复杂业务领域（电商、金融、医疗）里，代码和业务语言脱节 → 沟通成本高、实现和需求漂移。DDD 让代码说业务的语言。

6.2 战略设计（宏观）

• 限界上下文（Bounded Context）：把业务切成独立领域（订单、库存、支付各一个上下文），各自有语言和模型。
• 上下文映射：上下文间的关系（防腐层 ACL、共享内核等）。
• 通用语言（Ubiquitous Language）：领域术语在代码里和业务里用同一个词。

6.3 战术设计（微观）

6.4 何时该用 DDD

七、落地：工程实践清单

[ ] 代码有测试（单元覆盖关键逻辑）
[ ] 命名表达意图（无魔法数/烂名/死代码）
[ ] 函数短小、单一职责
[ ] 圈复杂度可控（< 15 主要函数）
[ ] 无上帝对象、无深耦合
[ ] 重复代码已提取（Rule of Three）
[ ] code review 是门禁不是走过场
[ ] PR 小步（< 400 行）、Review 快（< 24h）
[ ] 重构与功能开发分开 commit
[ ] 复杂领域有清晰模型（DDD 或分层）

八、结束 + 速查表

下一篇: 7. 可观测性实操: metrics/logs/traces 打点 / OpenTelemetry / SLO.