first commit

2025-10-24 20:23:16 +08:00
commit 58dd30f0e3
12 changed files with 3296 additions and 0 deletions
--- a/typescript-spec.md
+++ b/typescript-spec.md
@@ -0,0 +1,526 @@
+# 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 的类型系统与语言特性，降低维护成本并提升交付质量。