dev-playbooks-cn 1.0.0

package/skills/devbooks-coder/references//344/275/216/351/243/216/351/231/251/346/224/271/345/212/250/346/212/200/346/234/257.md

@@ -0,0 +1,275 @@
+# 低风险改动技术速查表
+
+> 来源：《修改代码的艺术》(Working Effectively with Legacy Code) - Michael Feathers
+> 适用角色：Coder（实现负责人）
+
+---
+
+## 适用场景
+
+当 Coder 需要在遗留代码中添加功能或修复 bug，但面临以下约束时：
+- 时间压力大，无法大规模重构
+- 测试覆盖不足，改动风险高
+- 需要保证"行为保持"
+
+---
+
+## 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **行为保持** | 任何改动必须保证原有功能不变 |
+| **最小侵入** | 尽量不修改原有代码，而是在外围添加/包装 |
+| **可测试优先** | 新代码必须可测试，即使旧代码不可测试 |
+| **依靠编译器** | 改签名后让编译器报错来发现所有调用点 |
+
+---
+
+## 一、Sprout Method（萌生方法）
+
+### 定义
+在需要添加新功能时，不修改原有方法，而是**新建一个方法**，然后在原方法中调用它。
+
+### 适用场景
+- 需要在某个方法中间添加逻辑
+- 原方法过长或难以测试
+- 新逻辑相对独立
+
+### 操作步骤
+1. 识别需要添加代码的位置
+2. 将新代码提取为独立方法
+3. 为新方法编写测试
+4. 在原位置调用新方法
+
+### 示例
+
+```python
+# 原代码（难以测试）
+class OrderProcessor:
+    def process(self, order):
+        # 100行遗留代码...
+        total = self._calculate_total(order)
+        # 需要在这里添加折扣计算逻辑
+        self._save_order(order, total)
+        # 50行遗留代码...
+
+# Sprout Method 重构后
+class OrderProcessor:
+    def process(self, order):
+        # 100行遗留代码...（不动）
+        total = self._calculate_total(order)
+        discounted_total = self._apply_discount(order, total)  # 新增调用
+        self._save_order(order, discounted_total)  # 修改参数
+        # 50行遗留代码...（不动）
+
+    def _apply_discount(self, order, total):  # 新方法，可独立测试
+        if order.customer.is_vip:
+            return total * 0.9
+        return total
+```
+
+### 优点
+- 新代码 100% 可测试
+- 对原代码改动最小（仅添加一行调用）
+- 风险隔离：新逻辑的 bug 不会影响原有逻辑
+
+---
+
+## 二、Sprout Class（萌生类）
+
+### 定义
+当新功能需要多个方法或状态时，**新建一个类**来承载，然后在原代码中实例化并使用它。
+
+### 适用场景
+- 新功能复杂，需要多个方法
+- 新功能需要维护状态
+- 原类已经过大（>500 行）
+
+### 操作步骤
+1. 创建新类，实现新功能
+2. 为新类编写完整测试
+3. 在原代码中创建新类实例
+4. 调用新类方法
+
+### 示例
+
+```python
+# 新建独立类（完全可测试）
+class DiscountCalculator:
+    def __init__(self, discount_rules: list[DiscountRule]):
+        self._rules = discount_rules
+
+    def calculate(self, order, original_total):
+        discount = 0
+        for rule in self._rules:
+            discount += rule.apply(order, original_total)
+        return original_total - discount
+
+# 在原代码中使用
+class OrderProcessor:
+    def __init__(self):
+        self._discount_calc = DiscountCalculator(self._load_rules())
+
+    def process(self, order):
+        # 遗留代码...
+        total = self._calculate_total(order)
+        discounted = self._discount_calc.calculate(order, total)  # 使用新类
+        self._save_order(order, discounted)
+```
+
+### 优点
+- 新类完全独立，可单独测试
+- 职责清晰，避免原类膨胀
+- 未来可扩展（如添加更多折扣规则）
+
+---
+
+## 三、Wrap Method（包装方法）
+
+### 定义
+不修改原方法实现，而是**创建一个新方法包装原方法**，在包装方法中添加前置/后置逻辑。
+
+### 适用场景
+- 需要在方法执行前后添加逻辑（如日志、验证、缓存）
+- 原方法签名不变，对调用方透明
+- 遵循开闭原则
+
+### 操作步骤
+1. 将原方法重命名（如 `pay` → `_pay_impl`）
+2. 创建同名新方法
+3. 在新方法中调用原方法，添加前后逻辑
+
+### 示例
+
+```python
+# 原代码
+class PaymentService:
+    def pay(self, order, amount):
+        # 支付逻辑...
+        return result
+
+# Wrap Method 重构后
+class PaymentService:
+    def pay(self, order, amount):  # 外部调用不变
+        self._log_payment_start(order, amount)  # 前置逻辑
+        result = self._pay_impl(order, amount)  # 原逻辑
+        self._log_payment_end(order, result)    # 后置逻辑
+        return result
+
+    def _pay_impl(self, order, amount):  # 原方法重命名
+        # 原支付逻辑（完全不变）
+        return result
+```
+
+### 优点
+- 原逻辑完全不变
+- 调用方无感知
+- 前后置逻辑可独立测试
+
+---
+
+## 四、Wrap Class（包装类/装饰器）
+
+### 定义
+创建一个新类，**包装原类**，在调用原类方法前后添加逻辑（装饰器模式）。
+
+### 适用场景
+- 原类无法修改（如第三方库）
+- 需要为整个类添加横切关注点（日志、缓存、权限）
+- 想保持原类不变
+
+### 操作步骤
+1. 创建包装类，持有原类实例
+2. 实现相同接口
+3. 在方法中添加逻辑后委托给原类
+
+### 示例
+
+```python
+# 原类（可能是第三方库，无法修改）
+class LegacyPaymentGateway:
+    def process(self, payment):
+        # 复杂的遗留逻辑...
+        return result
+
+# Wrap Class
+class AuditedPaymentGateway:
+    def __init__(self, gateway: LegacyPaymentGateway, audit_log: AuditLog):
+        self._gateway = gateway
+        self._audit = audit_log
+
+    def process(self, payment):  # 相同接口
+        self._audit.log_start(payment)
+        try:
+            result = self._gateway.process(payment)  # 委托原类
+            self._audit.log_success(payment, result)
+            return result
+        except Exception as e:
+            self._audit.log_failure(payment, e)
+            raise
+```
+
+### 优点
+- 原类完全不变
+- 可组合多个包装（如：缓存 + 日志 + 重试）
+- 符合开闭原则
+
+---
+
+## 五、决策流程图
+
+```
+需要添加/修改功能
+      │
+      ▼
+┌─────────────────────────┐
+│ 新功能是否独立成块？      │
+└───────────┬─────────────┘
+       ┌────┴────┐
+       ▼         ▼
+      是        否
+       │         │
+       ▼         ▼
+ ┌──────────┐  ┌──────────────────┐
+ │ 需要状态？ │  │ 在方法前后添加？   │
+ └────┬─────┘  └────────┬─────────┘
+   ┌──┴──┐          ┌───┴───┐
+   ▼     ▼          ▼       ▼
+  是    否         是      否
+   │     │          │       │
+   ▼     ▼          ▼       ▼
+Sprout  Sprout    Wrap    在方法中间
+Class   Method   Method   添加
+                  或       │
+                 Wrap      ▼
+                 Class   Sprout
+                         Method
+```
+
+---
+
+## 六、与 Test Owner 的协作
+
+| Coder 行为 | 需要 Test Owner 配合 |
+|-----------|---------------------|
+| 使用 Sprout Method/Class | Test Owner 为新方法/类编写测试 |
+| 使用 Wrap Method/Class | Test Owner 验证包装后行为不变 |
+| 需要解依赖才能测试 | 参考《解依赖技术速查表》 |
+| 改动影响多个调用方 | 参考 Impact Analysis 的 Pinch Point |
+
+---
+
+## 七、禁止行为
+
+- **禁止**：直接修改遗留代码的核心逻辑（除非有充分测试覆盖）
+- **禁止**：为了"顺手重构"而改动不相关代码
+- **禁止**：删除看似无用的代码（可能有隐藏依赖）
+- **禁止**：修改 `tests/**` 目录（需交还 Test Owner）
+
+---
+
+## 参考资料
+
+- 《修改代码的艺术》第 6-8 章
+- 《解依赖技术速查表》
+- dev-playbooks `devbooks-coder/SKILL.md`

package/skills/devbooks-coder/references//346/227/245/345/277/227/350/247/204/350/214/203.md

@@ -0,0 +1,329 @@
+# 日志规范
+
+借鉴 VS Code 的日志实践，本文档定义了应用程序日志的标准规范。
+
+---
+
+## 1) 日志级别
+
+### 级别定义
+
+| 级别 | 用途 | 示例 |
+|------|------|------|
+| `ERROR` | 需要立即关注的错误 | 数据库连接失败、外部 API 错误 |
+| `WARN` | 潜在问题，但不影响主流程 | 配置缺失使用默认值、重试成功 |
+| `INFO` | 关键业务流程节点 | 用户登录、订单创建、服务启动 |
+| `DEBUG` | 开发调试信息 | 函数入参、中间状态 |
+| `TRACE` | 详细追踪信息 | 每行数据处理、循环迭代 |
+
+### 级别选择指南
+
+```typescript
+// ERROR：系统无法正常工作
+logger.error('Database connection failed', { error, retries: 3 });
+
+// WARN：可恢复的问题
+logger.warn('Cache miss, falling back to database', { key });
+
+// INFO：业务里程碑
+logger.info('User registered', { userId, email });
+
+// DEBUG：开发时有用的信息
+logger.debug('Processing request', { params, headers });
+
+// TRACE：非常详细的追踪
+logger.trace('Row processed', { rowIndex, data });
+```
+
+---
+
+## 2) 日志格式
+
+### 结构化日志
+
+```typescript
+// 推荐：结构化日志
+logger.info('Order created', {
+  orderId: '12345',
+  userId: 'user-789',
+  amount: 99.99,
+  currency: 'USD',
+  items: 3
+});
+
+// 输出 JSON（便于解析）
+{
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "level": "INFO",
+  "message": "Order created",
+  "orderId": "12345",
+  "userId": "user-789",
+  "amount": 99.99,
+  "currency": "USD",
+  "items": 3,
+  "service": "order-service",
+  "traceId": "abc-123-xyz"
+}
+```
+
+### 必须包含的字段
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `timestamp` | ISO 8601 格式时间戳 | `2024-01-15T10:30:00.000Z` |
+| `level` | 日志级别 | `INFO`, `ERROR` |
+| `message` | 人类可读的消息 | `User logged in` |
+| `service` | 服务名称 | `user-service` |
+| `traceId` | 请求追踪 ID | `abc-123-xyz` |
+
+### 可选字段
+
+| 字段 | 说明 | 何时使用 |
+|------|------|---------|
+| `userId` | 用户标识 | 有用户上下文时 |
+| `requestId` | 请求 ID | HTTP 请求处理 |
+| `duration` | 耗时（毫秒） | 性能相关日志 |
+| `error` | 错误详情 | ERROR 级别日志 |
+
+---
+
+## 3) 日志内容规范
+
+### 消息格式
+
+```typescript
+// 推荐：动词开头，描述发生了什么
+logger.info('User logged in', { userId });
+logger.info('Order created', { orderId });
+logger.info('Payment processed', { paymentId, amount });
+
+// 避免：模糊的消息
+logger.info('Done');  // ❌ 什么 done？
+logger.info('Error');  // ❌ 什么 error？
+logger.info('Processing...');  // ❌ 处理什么？
+```
+
+### 上下文数据
+
+```typescript
+// 推荐：包含足够的上下文
+logger.error('Failed to process payment', {
+  orderId: '12345',
+  paymentMethod: 'credit_card',
+  error: {
+    code: 'DECLINED',
+    message: 'Card declined by issuer'
+  },
+  retryCount: 2
+});
+
+// 避免：缺少上下文
+logger.error('Payment failed');  // ❌ 哪个订单？什么原因？
+```
+
+### 敏感数据处理
+
+```typescript
+// 禁止：记录敏感数据
+logger.info('User login', {
+  email: 'user@example.com',
+  password: '123456'  // ❌ 绝对禁止！
+});
+
+// 正确：脱敏处理
+logger.info('User login', {
+  email: maskEmail('user@example.com'),  // u***@example.com
+  passwordProvided: true
+});
+
+// 脱敏工具函数
+function maskEmail(email: string): string {
+  const [local, domain] = email.split('@');
+  return `${local[0]}***@${domain}`;
+}
+
+function maskCreditCard(card: string): string {
+  return `****-****-****-${card.slice(-4)}`;
+}
+```
+
+**禁止记录的数据**：
+
+| 类型 | 示例 |
+|------|------|
+| 密码 | password, secret, token |
+| 凭证 | API key, access token |
+| 个人信息 | 身份证号、银行卡号 |
+| 敏感业务数据 | 完整信用卡号、CVV |
+
+---
+
+## 4) 错误日志规范
+
+### 错误信息结构
+
+```typescript
+logger.error('Operation failed', {
+  operation: 'createOrder',
+  error: {
+    name: error.name,
+    message: error.message,
+    code: error.code,
+    stack: error.stack  // 仅在非生产环境
+  },
+  context: {
+    userId: '12345',
+    input: sanitize(input)  // 脱敏后的输入
+  },
+  recovery: 'Will retry in 5 seconds'
+});
+```
+
+### 错误分类
+
+```typescript
+// 可恢复错误（WARN）
+logger.warn('Temporary failure, retrying', {
+  operation: 'fetchData',
+  attempt: 2,
+  maxAttempts: 3
+});
+
+// 不可恢复错误（ERROR）
+logger.error('Critical failure', {
+  operation: 'saveData',
+  error: error.message,
+  action: 'Manual intervention required'
+});
+```
+
+---
+
+## 5) 性能日志
+
+### 耗时记录
+
+```typescript
+// 记录操作耗时
+const start = performance.now();
+await processOrder(order);
+const duration = performance.now() - start;
+
+logger.info('Order processed', {
+  orderId: order.id,
+  duration: Math.round(duration),  // 毫秒
+  durationUnit: 'ms'
+});
+
+// 超时警告
+if (duration > 1000) {
+  logger.warn('Slow operation detected', {
+    operation: 'processOrder',
+    duration,
+    threshold: 1000
+  });
+}
+```
+
+### 批量操作
+
+```typescript
+logger.info('Batch processing completed', {
+  operation: 'importUsers',
+  total: 1000,
+  success: 985,
+  failed: 15,
+  duration: 5230,
+  avgPerItem: 5.23
+});
+```
+
+---
+
+## 6) 日志配置
+
+### 环境配置
+
+| 环境 | 默认级别 | 输出格式 | 堆栈跟踪 |
+|------|---------|---------|---------|
+| Development | DEBUG | 人类可读 | 完整 |
+| Staging | INFO | JSON | 仅 ERROR |
+| Production | INFO | JSON | 仅 ERROR |
+
+### 配置示例
+
+```typescript
+// logger.config.ts
+interface LoggerConfig {
+  level: 'error' | 'warn' | 'info' | 'debug' | 'trace';
+  format: 'json' | 'pretty';
+  includeStack: boolean;
+  service: string;
+}
+
+const config: LoggerConfig = {
+  level: process.env.LOG_LEVEL || 'info',
+  format: process.env.NODE_ENV === 'production' ? 'json' : 'pretty',
+  includeStack: process.env.NODE_ENV !== 'production',
+  service: process.env.SERVICE_NAME || 'app'
+};
+```
+
+---
+
+## 7) 日志库推荐
+
+### Node.js
+
+```typescript
+// 推荐：pino（高性能）
+import pino from 'pino';
+
+const logger = pino({
+  level: 'info',
+  formatters: {
+    level: (label) => ({ level: label.toUpperCase() })
+  },
+  timestamp: () => `,"timestamp":"${new Date().toISOString()}"`
+});
+
+// 或：winston（功能丰富）
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.Console()
+  ]
+});
+```
+
+### 浏览器
+
+```typescript
+// 简单封装
+const logger = {
+  error: (msg: string, data?: object) =>
+    console.error(JSON.stringify({ level: 'ERROR', message: msg, ...data })),
+  warn: (msg: string, data?: object) =>
+    console.warn(JSON.stringify({ level: 'WARN', message: msg, ...data })),
+  info: (msg: string, data?: object) =>
+    console.info(JSON.stringify({ level: 'INFO', message: msg, ...data })),
+  debug: (msg: string, data?: object) =>
+    console.debug(JSON.stringify({ level: 'DEBUG', message: msg, ...data }))
+};
+```
+
+---
+
+## 8) 检查清单
+
+编写日志时确认：
+
+- [ ] 级别是否正确？（ERROR/WARN/INFO/DEBUG）
+- [ ] 消息是否清晰？（动词开头，描述事件）
+- [ ] 上下文是否充分？（能定位问题）
+- [ ] 敏感数据是否脱敏？
+- [ ] 错误日志是否包含堆栈？
+- [ ] 性能日志是否包含耗时？