dev-playbooks-cn 1.0.0

package/skills/devbooks-code-review/references//345/235/217/345/221/263/351/201/223/351/200/237/346/237/245/350/241/250.md

@@ -0,0 +1,495 @@
+# 8 种核心坏味道速查表
+
+> 来源：《重构：改善既有代码的设计》辩论修订版
+> 从原书 22 种坏味道精简为 8 种高频高影响的核心坏味道
+
+---
+
+## 速查索引
+
+| # | 坏味道 | 一句话描述 | 严重性 |
+|---|--------|------------|--------|
+| 1 | Duplicated Code | 相同代码出现多处 | 阻塞 |
+| 2 | Long Method | 函数太长难以理解 | 阻塞 |
+| 3 | Large Class | 类承担太多职责 | 警告 |
+| 4 | Long Parameter List | 参数太多难以调用 | 阻塞 |
+| 5 | Divergent Change | 一个类因多种原因变化 | 警告 |
+| 6 | Shotgun Surgery | 一个变更需改多个类 | 阻塞 |
+| 7 | Feature Envy | 函数过度依赖他类 | 警告 |
+| 8 | Primitive Obsession | 业务概念用原始类型 | 警告 |
+| 9 | **Module Cycle（循环依赖）** | A→B→A 导致无法独立测试 | **阻塞** |
+
+---
+
+## 1. Duplicated Code（重复代码）
+
+**识别信号**：
+- 相似度>80%的代码块出现≥2处
+- 复制粘贴后只改了变量名
+- 兄弟子类中有相同代码
+
+**为什么是问题**：
+- 修改时容易漏改，导致行为不一致
+- 增加代码量，降低可读性
+- 违反 DRY 原则
+
+**重构手法**：
+1. **同一类内重复** → Extract Method
+2. **兄弟子类间重复** → Extract Method → Pull Up Method
+3. **无关类间重复** → Extract Class（提取公共类）
+
+**代码示例**：
+```python
+# 坏味道：重复的验证逻辑
+def create_user(email):
+    if not email or '@' not in email:
+        raise ValueError("Invalid email")
+    # ...
+
+def update_email(email):
+    if not email or '@' not in email:  # 重复！
+        raise ValueError("Invalid email")
+    # ...
+
+# 重构后：提取方法
+def validate_email(email):
+    if not email or '@' not in email:
+        raise ValueError("Invalid email")
+
+def create_user(email):
+    validate_email(email)
+    # ...
+```
+
+---
+
+## 2. Long Method（过长函数）
+
+**识别信号**：
+- **P95<50行**（超标触发讨论）
+- 需要滚动才能看完整个函数
+- 函数内有大段注释解释"这部分做什么"
+- 圈复杂度>10
+
+**为什么是问题**：
+- 难以理解函数整体逻辑
+- 难以测试（需要覆盖太多分支）
+- 难以复用部分逻辑
+
+**重构手法**：
+1. **注释是信号** → Extract Method（函数名来自注释）
+2. **临时变量过多** → Replace Temp with Query
+3. **条件分支复杂** → Decompose Conditional
+
+**代码示例**：
+```python
+# 坏味道：过长函数
+def process_order(order):
+    # 验证订单
+    if not order.items:
+        raise ValueError("Empty order")
+    if order.total < 0:
+        raise ValueError("Invalid total")
+
+    # 计算折扣
+    discount = 0
+    if order.customer.is_vip:
+        discount = order.total * 0.1
+    elif order.total > 1000:
+        discount = order.total * 0.05
+
+    # 更新库存
+    for item in order.items:
+        stock = get_stock(item.product_id)
+        stock.quantity -= item.quantity
+        save_stock(stock)
+
+    # ... 还有50行
+
+# 重构后：提取方法
+def process_order(order):
+    validate_order(order)
+    discount = calculate_discount(order)
+    update_inventory(order)
+    # ...
+```
+
+---
+
+## 3. Large Class（过大的类）
+
+**识别信号**：
+- **P95<500行**
+- 实例变量>10个
+- 方法>20个
+- 有多组字段名前缀相同（如 `billing_xxx`, `shipping_xxx`）
+
+**为什么是问题**：
+- 违反单一职责原则
+- 难以测试（依赖太多）
+- 修改时影响范围不可控
+
+**重构手法**：
+1. **职责可分** → Extract Class
+2. **存在子类型** → Extract Subclass
+3. **只需部分接口** → Extract Interface
+
+---
+
+## 4. Long Parameter List（过长参数列）
+
+**识别信号**：
+- 参数数量>5
+- 参数顺序容易搞混
+- 多个函数有相同的参数组合
+
+**为什么是问题**：
+- 调用时容易传错参数
+- 函数签名难以记忆
+- 参数组合可能是隐藏的概念
+
+**重构手法**：
+1. **参数可从对象获取** → Preserve Whole Object
+2. **参数总是一起出现** → Introduce Parameter Object
+
+**代码示例**：
+```python
+# 坏味道：参数过多
+def create_address(street, city, state, zip_code, country, apt_number):
+    pass
+
+# 重构后：引入参数对象
+@dataclass
+class Address:
+    street: str
+    city: str
+    state: str
+    zip_code: str
+    country: str
+    apt_number: str = None
+
+def create_address(address: Address):
+    pass
+```
+
+---
+
+## 5. Divergent Change（发散式变化）
+
+**识别信号**：
+- 修改数据库时要改这个类
+- 修改 UI 时也要改这个类
+- 修改业务规则时还要改这个类
+- "每次改需求都要改这个文件"
+
+**为什么是问题**：
+- 类承担了多个变化轴的职责
+- 不同原因的修改互相影响
+- 难以单独测试某个维度
+
+**重构手法**：
+- Extract Class（按变化原因分离）
+
+**对比 Shotgun Surgery**：
+- Divergent Change：一个类响应多种变化
+- Shotgun Surgery：一种变化需要改多个类
+- 两者是**对偶问题**，解法相反
+
+---
+
+## 6. Shotgun Surgery（霰弹式修改）
+
+**识别信号**：
+- 一个需求需要修改≥3个类
+- "改一处要改好多地方"
+- 容易漏改导致 bug
+
+**为什么是问题**：
+- 修改容易遗漏
+- 散落的逻辑难以理解整体
+- 测试覆盖困难
+
+**重构手法**：
+1. **逻辑应集中** → Move Method / Move Field
+2. **过度分散** → Inline Class（先合并再重新拆分）
+
+---
+
+## 7. Feature Envy（依恋情结）
+
+**识别信号**：
+- 函数对其他类的调用 > 对自己类的调用
+- 函数大量使用另一个类的字段
+- "这个方法好像放错地方了"
+
+**为什么是问题**：
+- 违反"数据和操作应该在一起"原则
+- 增加类之间的耦合
+- 职责划分不清晰
+
+**重构手法**：
+- Move Method（移到数据所在的类）
+
+**例外情况**（不是 Feature Envy）：
+- Strategy 模式（策略类访问上下文）
+- Visitor 模式（访问者访问元素）
+- 需要在代码注释中标注"这是设计模式，不是 Feature Envy"
+
+---
+
+## 8. Primitive Obsession（基本类型偏执）
+
+**识别信号**：
+- 用 String 存电话号码、邮箱、货币
+- 用 int 存状态码、类型码
+- 业务规则散落在多处（如邮箱格式验证）
+
+**为什么是问题**：
+- 缺乏类型安全（String 可以传任何值）
+- 业务规则无法集中
+- 与 glossary.md 术语不对齐
+
+**重构手法**：
+- Replace Data Value with Object
+- Replace Type Code with Class/Subclass
+
+**适用范围**（辩论修订）：
+- **必须封装**：业务概念（Money、Email、UserId、PhoneNumber）
+- **可选封装**：技术类型（坐标、颜色、简单配置）
+
+**代码示例**：
+```python
+# 坏味道：原始类型存储业务概念
+def transfer(from_account: str, to_account: str, amount: float):
+    pass  # amount 可以是负数？什么货币？
+
+# 重构后：封装为值对象
+@dataclass(frozen=True)
+class Money:
+    amount: Decimal
+    currency: str
+
+    def __post_init__(self):
+        if self.amount < 0:
+            raise ValueError("Amount cannot be negative")
+
+def transfer(from_account: AccountId, to_account: AccountId, amount: Money):
+    pass
+```
+
+---
+
+## 已删除的坏味道（辩论后精简）
+
+以下概念经 Advocate/Skeptic/Judge 三方辩论后被删除：
+
+| 原坏味道 | 删除理由 |
+|----------|----------|
+| Parallel Inheritance Hierarchies | 现代代码极少使用深层继承 |
+| Lazy Class | 与 SRP 冲突，小类是好设计 |
+| Speculative Generality | 判断标准过于主观 |
+| Temporary Field | 发生率低 |
+| Message Chains | 函数式链式调用盛行 |
+| Middle Man | 分层架构中有防腐价值 |
+| Alternative Classes with Different Interfaces | 被术语一致性检查覆盖 |
+| Incomplete Library Class | 第三方库无法重构 |
+| Data Class | 现代架构(DDD)中 DTO 层允许贫血 |
+| Refused Bequest | 继承使用已大幅减少 |
+| Comments | "Why"型注释有价值 |
+
+---
+
+## 快速决策流程图
+
+```
+发现可疑代码
+    │
+    ├─ 重复？ ──────────────→ Extract Method
+    │
+    ├─ 函数>50行？ ─────────→ Extract Method + Decompose Conditional
+    │
+    ├─ 类>500行？ ──────────→ Extract Class
+    │
+    ├─ 参数>5个？ ──────────→ Introduce Parameter Object
+    │
+    ├─ 改一处要改多处？ ────→ Move Method/Field（集中逻辑）
+    │
+    ├─ 一个类响应多种变化？ → Extract Class（分离变化轴）
+    │
+    ├─ 函数总访问别的类？ ──→ Move Method
+    │
+    └─ 业务概念用String？ ──→ Replace Data Value with Object
+```
+
+---
+
+## 9. Module Cycle（循环依赖）
+
+> 来源：《架构整洁之道》辩论修订版 - 双方共识保留的核心规则
+
+**识别信号**：
+- 模块 A 依赖 B，B 又依赖 A（直接循环）
+- A→B→C→A 的间接循环
+- 无法单独编译/测试某个模块
+- "改一个模块，另一个必须同时改"
+
+**为什么是问题**：
+- 模块无法独立测试（必须同时 mock 多侧）
+- 无法独立部署/发布
+- 架构腐化的强信号
+- 重构成本指数级增长
+
+**检测工具**：
+```bash
+# JavaScript/TypeScript
+npx madge --circular src/
+
+# Java
+jdeps -R -summary target/classes | grep cycle
+
+# Go
+go mod graph | tsort 2>&1 | grep -i cycle
+
+# Python
+pydeps --show-cycles src/
+```
+
+**重构手法**：
+1. **依赖倒置** → 提取接口到独立模块，双方都依赖接口
+2. **回调/事件** → A 调用 B 时，B 通过回调/事件通知 A，而非直接依赖
+3. **提取公共模块** → 把 A/B 共同依赖的部分提取为 C
+
+**代码示例**：
+```python
+# 坏味道：循环依赖
+# order.py
+from payment import PaymentService  # Order → Payment
+
+# payment.py
+from order import Order  # Payment → Order（循环！）
+
+# 重构后：依赖倒置
+# interfaces.py（独立模块）
+class OrderInterface(ABC):
+    @abstractmethod
+    def get_total(self) -> Money: pass
+
+# order.py
+class Order(OrderInterface):  # 实现接口
+    pass
+
+# payment.py
+from interfaces import OrderInterface  # 只依赖接口
+class PaymentService:
+    def charge(self, order: OrderInterface): pass
+```
+
+**CI 集成建议**：
+```yaml
+# .github/workflows/ci.yml
+- name: Check circular dependencies
+  run: |
+    npx madge --circular src/ && echo "No cycles found" || exit 1
+```
+
+---
+
+## 参考资料
+
+- 《重构：改善既有代码的设计》(第2版) - Martin Fowler
+- 《架构整洁之道》- Robert C. Martin（第14章 组件耦合）
+- dev-playbooks 辩论修订版评估报告
+- devbooks-code-review 检查清单
+
+---
+
+## 10. VS Code 风格代码卫生检查
+
+> 借鉴 VS Code ESLint 自定义规则，作为代码评审的自动化检查项
+
+### 禁止提交的模式（阻塞级）
+
+| 模式 | 检测命令 | 原因 |
+|------|----------|------|
+| `test.only` / `describe.only` | `rg '\.only\s*\(' tests/` | 跳过其他测试 |
+| `console.log` / `console.debug` | `rg 'console\.(log\|debug)' src/` | 调试代码残留 |
+| `debugger` | `rg 'debugger' src/` | 断点残留 |
+| `@ts-ignore` | `rg '@ts-ignore' src/` | 隐藏类型错误 |
+| `as any` | `rg 'as any' src/` | 类型安全绕过 |
+| `TODO` 无 issue | `rg 'TODO(?!.*#\d+)' src/` | 无法追踪的待办 |
+
+### 资源管理检查（警告级）
+
+| 模式 | 检测方法 | 正确做法 |
+|------|----------|----------|
+| 非 readonly DisposableStore | `rg 'private\s+(?!readonly)\s*_?\w*[Dd]isposable'` | 使用 `readonly` |
+| dispose() 未调用 super | 人工检查 override dispose | 必须调用 `super.dispose()` |
+| setInterval 无清理 | 搜索 setInterval 无对应 clearInterval | 在 dispose 中清理 |
+| 事件监听无移除 | 搜索 addEventListener 无 removeEventListener | 使用 AbortController |
+
+### 分层约束检查
+
+```bash
+# 检查禁止的跨层依赖
+# base 层不能依赖 platform/editor/workbench
+rg "from ['\"](vs/(platform|editor|workbench))" src/vs/base/
+
+# platform 层不能依赖 editor/workbench
+rg "from ['\"](vs/(editor|workbench))" src/vs/platform/
+
+# common 层不能依赖 browser/node
+rg "from ['\"].*(browser|node)" src/**/common/
+```
+
+### 类型安全检查
+
+```typescript
+// 禁止：空对象断言
+const config = {} as Config;  // ❌
+
+// 禁止：非空断言
+const name = user!.name;  // ❌
+
+// 禁止：any 类型
+function process(data: any) { }  // ❌
+
+// 正确：使用 unknown 或具体类型
+function process(data: unknown) { }  // ✓
+```
+
+### 自动化检查脚本
+
+```bash
+#!/bin/bash
+# hygiene-check.sh
+
+set -e
+
+echo "=== 代码卫生检查 ==="
+
+# 1. 调试代码
+if rg -l 'console\.(log|debug)|debugger' src/ --type ts 2>/dev/null; then
+  echo "❌ 发现调试代码"
+  exit 1
+fi
+
+# 2. test.only
+if rg -l '\.only\s*\(' tests/ --type ts 2>/dev/null; then
+  echo "❌ 发现 test.only"
+  exit 1
+fi
+
+# 3. @ts-ignore
+count=$(rg -c '@ts-ignore' src/ --type ts 2>/dev/null | wc -l)
+if [ "$count" -gt 0 ]; then
+  echo "⚠️  发现 $count 处 @ts-ignore"
+fi
+
+# 4. any 类型
+count=$(rg -c ': any[^a-z]' src/ --type ts 2>/dev/null | wc -l)
+if [ "$count" -gt 0 ]; then
+  echo "⚠️  发现 $count 处 any 类型"
+fi
+
+echo "✅ 卫生检查通过"
+```