从零开始掌握 Skill 规范：新手开发者的完整避坑指南

共计 1735 个字符，预计需要花费 5 分钟才能阅读完成。

为什么我们需要 Skill 规范？

去年我们团队曾经历过一次严重的线上事故：由于开发者随意命名接口（如 getData1()、getData2()），导致前端调用时混淆了数据来源，最终引发订单金额计算错误。更糟糕的是，没有类型定义的返回结果让问题直到生产环境才暴露——这就是不规范编码的代价。

Skill 规范 vs 传统编码的核心差异

三个典型场景的规范实现

场景 1：函数定义与类型安全

/**
 * 获取用户待支付订单（带防御性校验）* @param userId - 用户 ID（必须大于 0）* @throws {BusinessError} 当用户不存在时抛出业务异常
 */
async function fetchPendingOrders(userId: number): Promise<Order[]> {if (userId <= 0) throw new Error('Invalid user ID');

  const orders = await orderRepository.findByUser(userId);
  return orders.filter(o => o.status === 'PENDING');
}

场景 2：分层错误处理

// 业务异常（可预期情况）class BusinessError extends Error {constructor(public code: string, message: string) {super(message);
  }
}

// 系统异常（意外错误）function handlePayment() {
  try {processPayment();
  } catch (err) {if (err instanceof BusinessError) {alertUser(err.message); // 给用户友好提示
    } else {logToSentry(err); // 系统级监控
      throw new Error('支付服务暂不可用');
    }
  }
}

场景 3：API 设计（SOLID 原则）

// 接口隔离原则（Interface Segregation Principle）interface OrderFetcher {fetchOrders(): Promise<Order[]>;}

interface OrderUpdater {updateOrder(order: Order): void;
}

// 高内聚低耦合的实现
class OrderService implements OrderFetcher, OrderUpdater {// 实现省略...}

生产环境实战指南

自动化校验工具

.eslintrc.js 关键配置示例：

module.exports = {
  rules: {
    '@typescript-eslint/explicit-function-return-type': 'error',
    'consistent-return': ['error', { treatUndefinedAsUnspecified: true}],
    'no-magic-numbers': ['warn', { ignore: [0, 1] }]
  }
};

代码审查 Checklist

• [] 所有导出方法是否有 TSDoc 注释？
• [] 是否存在超过 200 行的模块文件？
• [] 错误处理是否区分业务异常和系统异常？

改造旧项目策略

1. 先为新增代码强制规范
2. 用 eslint --fix 自动修复基础问题
3. 逐步拆分上帝类（God Class）

课后实践任务

1. 重构以下代码（原始版本）：

   function proc(data) {
     // 处理逻辑...
     return result;
   }

2. 配置 ESLint + Prettier 自动化检查
3. 在团队分享会上演示你的改造思路

循环依赖破解技巧

当模块 A 依赖 B，同时 B 又依赖 A 时：

1. 提炼公共逻辑到新模块 C
2. 使用依赖注入（Dependency Injection）
3. 合并高耦合模块（最后手段）

规范编码就像系安全带——初期可能觉得束缚，但当项目复杂度提升时，它会成为你最可靠的安全网。现在就开始培养好习惯吧！