# TypeScript 编码最佳实践（参考 Clean Code TypeScript）

> 本规范以 [Clean Code TypeScript](https://github.com/labs42io/clean-code-typescript) 为基础，结合常见业务场景与团队协作经验，为 TypeScript 项目提供可执行的最佳实践。所有规则都配有简短示例，便于在代码生成、评审与重构中快速对照。

## 1. 变量与常量

- **语义化命名**：使用易读且准确的词汇描述变量含义，避免首字母缩写或无意义命名。  
  示例：
  ```ts
  const remainingTrialDays = totalTrialDays - usedTrialDays;
  ```
- **统一词汇表述**：同一概念使用一致命名，减少认知成本。  
  示例：
  ```ts
  type SubscriptionPlan = 'free' | 'pro';
  const currentPlan: SubscriptionPlan = 'pro';
  ```
- **可搜索名称**：对常量、配置使用具备辨识度的名称，方便全局检索。  
  示例：
  ```ts
  const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
  ```
- **解释性变量**：将复杂表达式抽取为具名变量，让意图自说明。  
  示例：
  ```ts
  const hasIncompleteProfile = !user.email || !user.phone;
  if (hasIncompleteProfile) {
    promptProfileCompletion();
  }
  ```
- **避免多余上下文**：变量名中不要重复所在模块的上下文信息。  
  示例：
  ```ts
  // 数据存于 billing 模块，无需前缀 billing
  const invoiceTotal = calcInvoiceTotal(items);
  ```
- **默认参数优于短路**：使用函数默认值替代 `||` 等短路写法，让可选参数更清晰。  
  示例：
  ```ts
  function sendReport(recipient: string, { retries = 3 }: { retries?: number } = {}) {
    /* ... */
  }
  ```

## 2. 函数设计

- **函数只做一件事**：将复杂操作拆分为独立函数，保持逻辑内聚。  
  示例：
  ```ts
  function createUser(dto: CreateUserInput) {
    validateUser(dto);
    const user = buildUser(dto);
    return saveUser(user);
  }
  ```
- **限制参数数量**：理想状态 ≤ 2 个参数；若超出，改用具名对象并定义类型。  
  示例：
  ```ts
  interface ScheduleOptions {
    triggerAt: Date;
    retryCount?: number;
  }
  function scheduleReminder(userId: string, options: ScheduleOptions) { /* ... */ }
  ```
- **描述性函数名**：函数名应说明行为与结果，避免依赖注释解释。  
  示例：
  ```ts
  function calculateLoyaltyDiscount(order: Order): number { /* ... */ }
  ```
- **避免标志参数**：用枚举或拆分函数替代布尔开关，消除逻辑分支迷雾。  
  示例：
  ```ts
  type ExportMode = 'draft' | 'final';
  function exportDocument(mode: ExportMode) { /* ... */ }
  ```
- **规避副作用**：默认生成纯函数，必要副作用通过返回值或专门模块处理。  
  示例：
  ```ts
  function formatDisplayName(user: User): string {
    return `${user.firstName} ${user.lastName}`;
  }
  ```
- **封装条件表达式**：复杂条件抽离成具名函数或变量，降低认知负担。  
  示例：
  ```ts
  function isVipEligible(order: Order) {
    return order.total > 200 && order.customerTier === 'gold';
  }
  if (isVipEligible(order)) {
    applyVipBenefits(order);
  }
  ```
- **提前返回与正向逻辑**：优先正向判断并提前返回，避免深层嵌套与否定条件。  
  示例：
  ```ts
  function ensureActive(user: User) {
    if (!user.isActive) {
      throw new Error('User is inactive');
    }
    return user;
  }
  ```
- **删除死代码**：及时移除无调用、无覆盖的函数或分支，保持代码整洁。  
  示例：
  ```ts
  // 检测到无引用后移除旧方法
  // function legacyPayment() { /* ... */ }
  ```

## 3. 对象与数据结构

- **使用访问器**：通过 getter/setter 提供受控访问，便于增加校验与日志。  
  示例：
  ```ts
  class Account {
    constructor(private _balance = 0) {}
    get balance(): number {
      return this._balance;
    }
    deposit(amount: number) {
      this._balance += amount;
    }
  }
  ```
- **隐藏实现细节**：使用 `private` 或 `#` 字段，阻止外部直接修改内部状态。  
  示例：
  ```ts
  class TokenStore {
    #tokens = new Map<string, string>();
    set(token: string, value: string) {
      this.#tokens.set(token, value);
    }
  }
  ```
- **偏好不可变数据**：使用 `Readonly<T>` 或解构复制，避免共享状态污染。  
  示例：
  ```ts
  const updatedOrder: Readonly<Order> = { ...order, status: 'shipped' };
  ```
- **类型守卫保障安全**：自定义类型守卫封装校验逻辑，提升复用与可读性。  
  示例：
  ```ts
  function isAppConfig(value: unknown): value is AppConfig {
    return typeof value === 'object' && value !== null && 'env' in value;
  }
  ```
- **利用字面量约束取值**：针对有限集合使用联合字面量或 `enum`，防止魔法字符串。  
  示例：
  ```ts
  type OrderStatus = 'pending' | 'paid' | 'failed';
  const status: OrderStatus = 'paid';
  ```

## 4. 类与面向对象

- **组合优先于继承**：通过组合与接口扩展行为，降低继承层级带来的窜扰。  
  示例：
  ```ts
  class UserNotifier {
    constructor(private readonly emailSender: EmailSender) {}
    notifyWelcome(user: User) {
      return this.emailSender.sendWelcome(user.email);
    }
  }
  ```
- **保持类职责单一**：类只关注一个领域概念，额外能力拆分为协作类。  
  示例：
  ```ts
  class PasswordHasher {
    hash(value: string): Promise<string> {
      return bcrypt.hash(value, 12);
    }
  }
  ```
- **接口驱动契约**：用接口定义外部依赖，便于替换实现与注入假对象测试。  
  示例：
  ```ts
  interface EmailSender {
    sendWelcome(email: string): Promise<void>;
  }
  class SmtpEmailSender implements EmailSender { /* ... */ }
  ```
- **方法链只在自然场景使用**：当返回 `this` 能提升易用性（如构建器）时才启用链式调用。  
  示例：
  ```ts
  class QueryBuilder {
    private filters: string[] = [];
    where(condition: string) {
      this.filters.push(condition);
      return this;
    }
    build() {
      return this.filters.join(' AND ');
    }
  }
  ```
- **访问修饰符显式化**：始终标识 `public`/`private`/`protected`，并优先使用 `readonly` 属性。  
  示例：
  ```ts
  class FeatureFlag {
    constructor(public readonly key: string, private readonly enabled: boolean) {}
    isEnabled() {
      return this.enabled;
    }
  }
  ```

## 5. SOLID 原则

- **单一职责（SRP）**：模块应聚焦唯一变更原因，降低耦合。  
  示例：
  ```ts
  class InvoicePrinter {
    constructor(private readonly formatter: InvoiceFormatter) {}
    print(invoice: Invoice) {
      return this.formatter.format(invoice);
    }
  }
  ```
- **开放-封闭（OCP）**：通过扩展实现新需求，而非修改已有代码。  
  示例：
  ```ts
  interface PricingStrategy {
    calculate(order: Order): number;
  }
  class VipPricingStrategy implements PricingStrategy { /* ... */ }
  ```
- **里氏替换（LSP）**：子类型必须兼容父类型契约，避免破坏预期。  
  示例：
  ```ts
  function printTotals(calculator: PricingStrategy, order: Order) {
    console.log(calculator.calculate(order));
  }
  ```
- **接口隔离（ISP）**：提供小而专注的接口，避免强迫消费者实现无关方法。  
  示例：
  ```ts
  interface ReadonlyRepository<T> {
    findById(id: string): Promise<T | null>;
    list(): Promise<T[]>;
  }
  ```
- **依赖反转（DIP）**：高层模块依赖抽象，低层实现通过注入传入。  
  示例：
  ```ts
  class PaymentService {
    constructor(private readonly gateway: PaymentGateway) {}
    pay(invoice: Invoice) {
      return this.gateway.charge(invoice);
    }
  }
  ```

## 6. 异步与并发

- **优先使用 async/await**：将 Promise 链写成同步流程，更易读并易于错误处理。  
  示例：
  ```ts
  export async function loadUser(id: string): Promise<User> {
    const response = await fetch(`/api/users/${id}`);
    return response.json();
  }
  ```
- **集中处理错误**：在靠近调用边界处统一捕获和记录，保留上下文。  
  示例：
  ```ts
  try {
    await processPayment(orderId);
  } catch (error) {
    logger.error('Payment failed', { orderId, error });
    throw new PaymentFailedError(orderId, error);
  }
  ```
- **并发任务显式管理**：使用 `Promise.allSettled` 或自定义控制，避免静默丢失异常。  
  示例：
  ```ts
  const results = await Promise.allSettled(tasks.map(executeTask));
  const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');
  ```
- **支持超时与取消**：利用 `AbortController` 或第三方库防止长时间挂起。  
  示例：
  ```ts
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 5000);
  await fetch(url, { signal: controller.signal });
  clearTimeout(timeoutId);
  ```
- **避免竞争条件**：在共享资源上使用锁、队列或幂等操作保障一致性。  
  示例：
  ```ts
  await lock.acquire('invoice:' + invoiceId, async () => {
    await issueInvoice(invoiceId);
  });
  ```

## 7. 错误处理

- **不忽略错误**：捕获后要记录、包装或重新抛出，切勿空 catch。  
  示例：
  ```ts
  try {
    await cache.save(key, value);
  } catch (error) {
    metrics.increment('cache.save.failure');
    throw error;
  }
  ```
- **抛得早，捕获得晚**：靠近错误发生点抛出，自上层统一处理。  
  示例：
  ```ts
  function ensureHasToken(token?: string): asserts token is string {
    if (!token) {
      throw new AuthError('Missing token');
    }
  }
  ```
- **提供上下文信息**：传递自定义错误类型或消息，方便排查。  
  示例：
  ```ts
  class PaymentFailedError extends Error {
    constructor(public readonly orderId: string, cause: unknown) {
      super(`Payment failed for order ${orderId}`);
      this.name = 'PaymentFailedError';
      this.cause = cause;
    }
  }
  ```
- **使用 `Result` 或 `Either` 模式（可选）**：在复杂流程中用显式返回承载错误，减少异常穿透。  
  示例：
  ```ts
  type Result<T> = { ok: true; value: T } | { ok: false; error: Error };
  ```

## 8. 格式化与一致性

- **自动化格式化**：采用 `prettier` 或团队约定，保持一致缩进与换行。  
  示例：
  ```json
  {
    "scripts": {
      "format": "prettier --write \"src/**/*.{ts,tsx}\""
    }
  }
  ```
- **启用严格 lint**：结合 `eslint` 与 `@typescript-eslint` 推行关键规则。  
  示例：
  ```json
  {
    "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"]
  }
  ```
- **避免深层嵌套**：通过提前返回或提取函数减少缩进层数。  
  示例：
  ```ts
  if (!user) {
    return null;
  }
  if (!user.isActive) {
    return null;
  }
  return user;
  ```
- **统一命名风格**：类型与类使用帕斯卡命名，函数与变量使用驼峰命名。  
  示例：
  ```ts
  class PaymentGateway {}
  function processPayment() { /* ... */ }
  ```
- **集中导出入口**：通过 `index.ts` 组织导出，控制模块暴露面。  
  示例：
  ```ts
  export { processPayment } from './processPayment';
  export type { PaymentRequest } from './types';
  ```

## 9. 注释与文档

- **注释意图而非实现**：仅在业务规则或约束难以通过代码表达时补充说明。  
  示例：
  ```ts
  // 使用结算日的下一工作日作为默认扣款日期
  const defaultChargeDate = getNextBusinessDay(settlementDate);
  ```
- **使用 JSDoc/TS Doc**：对外暴露的 API 写明输入、输出与异常。  
  示例：
  ```ts
  /**
   * 创建新的租户并返回租户 ID。
   * @throws TenantLimitExceededError 当达到租户上限时抛出。
   */
  export async function createTenant(input: CreateTenantInput): Promise<string> { /* ... */ }
  ```
- **不要注释掉代码**：移除暂时不用的逻辑，依赖版本控制追踪历史。  
  示例：
  ```ts
  // 删除旧实现，改由 git 历史追溯
  ```
- **链接示例或测试**：复杂模块在注释中指向参考用例或文档。  
  示例：
  ```ts
  // 更多用法见 tests/invoice/generateInvoice.test.ts
  generateInvoice(orderId);
  ```

## 10. 测试策略

- **安排-执行-断言 (AAA)**：测试结构清晰，便于阅读与维护。  
  示例：
  ```ts
  it('calculates total price', () => {
    const items = [{ price: 10 }, { price: 5 }]; // Arrange
    const result = totalPrice(items);            // Act
    expect(result).toBe(15);                     // Assert
  });
  ```
- **一个测试一个概念**：每个测试聚焦单一行为，失败时易于定位原因。  
  示例：
  ```ts
  it('throws when user is inactive', () => {
    expect(() => ensureActive({ isActive: false } as User)).toThrow();
  });
  ```
- **利用假对象隔离依赖**：通过实现接口的假对象或 mock 控制外部交互。  
  示例：
  ```ts
  class FakeEmailSender implements EmailSender {
    public sent: string[] = [];
    async sendWelcome(email: string) { this.sent.push(email); }
  }
  ```
- **覆盖边界条件**：针对 null、异常路径与类型缩小时的行为编写测试。  
  示例：
  ```ts
  it('returns empty list when no orders found', () => {
    expect(loadOrders([])).toEqual([]);
  });
  ```
- **类型驱动验证**：关键类型转换或守卫应有对应测试，确保类型假设成立。  
  示例：
  ```ts
  it('accepts valid config objects', () => {
    const config = { env: 'prod' };
    expect(isAppConfig(config)).toBe(true);
  });
```

## 11. 架构最佳实践

- **清晰分层**：按领域、应用、基础设施划分模块，控制依赖方向仅从外层指向内层。  
  示例：
  ```ts
  // application/useCases/createInvoice.ts
  import { Invoice } from '../domain/invoice';
  import type { InvoiceRepository } from '../domain/ports';
  ```
- **组合根集中依赖注入**：在应用入口集中装配依赖，避免在业务代码中到处 `new` 实现。  
  示例：
  ```ts
  export function createInvoiceService(): InvoiceService {
    const repository = new PrismaInvoiceRepository();
    return new InvoiceService(repository);
  }
  ```
- **领域对象显式建模**：使用类型与不可变对象表达核心概念，让业务规则留在领域层。  
  示例：
  ```ts
  type Invoice = Readonly<{
    id: string;
    amount: number;
    issuedAt: Date;
  }>;
  ```
- **边界 DTO 与映射**：在接口适配层定义 DTO，与领域对象之间通过映射转换，保持领域纯净。  
  示例：
  ```ts
  type InvoiceDto = { id: string; amount: number; issued_at: string };

  function toInvoice(dto: InvoiceDto): Invoice {
    return { id: dto.id, amount: dto.amount, issuedAt: new Date(dto.issued_at) };
  }
  ```
- **横切关注集中处理**：将日志、缓存、鉴权等横切逻辑通过中间件或装饰器统一管理。  
  示例：
  ```ts
  export function withCaching<TArgs extends unknown[], TResult>(
    fn: (...args: TArgs) => Promise<TResult>,
  ) {
    return async (...args: TArgs) => cache.remember(JSON.stringify(args), () => fn(...args));
  }
  ```
- **配置与环境隔离**：统一从配置模块读取环境变量，并提供类型安全的访问接口。  
  示例：
  ```ts
  export const config = {
    payment: {
      apiKey: process.env.PAYMENT_API_KEY ?? '',
      timeoutMs: Number(process.env.PAYMENT_TIMEOUT_MS ?? 5000),
    },
  } as const;
  ```

## 附录：AI 辅助生成代码提示

- **在提示中植入约束**：明确声明需使用 `strict` TypeScript、限制参数数量、禁止 `any`。  
  示例：
  ```txt
  请实现 strict TypeScript 的订单接口，禁止 any，函数不超过 3 个参数，并写出必要类型定义。
  ```
- **要求输出结构化**：提示 AI 同步生成类型、实现与测试用例。  
  示例：
  ```txt
  输出包含类型定义、主要函数实现，以及 Jest 测试示例。
  ```
- **生成后立即校验**：运行 `tsc --noEmit`、`eslint` 与测试脚本，验证生成代码质量。  
  示例：
  ```bash
  npx tsc --noEmit && npm run lint && npm test
  ```
- **迭代式对话**：先让 AI 生成数据结构与接口，再补实现与异常处理，最后检查测试通过。  
  示例：
  ```txt
  第一步：请先提供 API 接口类型定义。
  第二步：基于上一步补充实现与错误处理。
  ```

> 按照本规范执行，可以在保证代码整洁的前提下，充分利用 TypeScript 的类型系统与语言特性，降低维护成本并提升交付质量。