typescript

TypeScript 指南

使用现代工具进行 TypeScript 开发的标准和最佳实践。编写或修改 TypeScript 代码时，请遵循这些指南。

设计原则

始终贯彻 DRY、KISS 和 SOLID 原则。适合时优先采用函数式方法；对于有状态的行为，使用类。组合优于继承。每个模块都应只有一个职责。使用依赖注入来管理类的依赖项。

代码风格

• 命名：变量、函数和类的名称应描述明确且简洁
• 文档：为公共 API、复杂逻辑以及不明显的设计决策编写 JSDoc 注释
• 类型注解：明确指定类型，以减少推断时间；除非必要，否则避免使用 any
• 导入：避免使用集中导出文件，以防止循环依赖；优先直接导入

类型安全

• 严格 TypeScript：启用严格模式并使用恰当的类型定义。适用时，使用 Zod 模式等类型安全模式进行验证，并使用类型安全的 DOM 辅助函数。
• 避免 any：类型确实未知时，使用 unknown 代替 any。适当地缩小类型范围。
• 类型推断：明确指定类型，以减少推断时间并提升清晰度

类型模式

• 联合类型：对于可能属于多种类型之一的值，使用联合类型
• 可辨识联合：使用可辨识联合实现类型安全的状态机
• 泛型约束：使用泛型约束确保类型安全
• 工具类型：充分利用 TypeScript 工具类型（Pick、Omit、Partial 等）

架构

模块组织

• 每个模块专注于一项职责，并具有清晰的边界
• 提取可复用函数以避免重复
• 设计时考虑在不同场景中的复用
• 将类型与其使用位置放在一起，或置于专用类型文件中
• 在适当的模块边界定义类型

依赖管理

• 使用依赖注入以便于测试
• 组合优于继承
• 保持依赖最少且职责明确

测试

结构

• 测试目录结构与 src/ 保持一致
• 测试文件：*.test.ts 或 *.spec.ts
• 使用描述性测试名称
• 修改代码时，务必检查是否有适当的单元测试

质量

• 使用 AAA（Arrange、Act、Assert）模式
• 测试应实用、易读、简洁且易于维护
• 测试边界情况和错误条件
• 为关键路径保持测试覆盖率

工具

• Vitest：使用 Vitest 进行单元测试和集成测试（优先于 Jest）
• 使用 @vitest/coverage-v8 进行覆盖率测试
• 需要时使用 jsdom 进行 DOM 测试
• 适当地模拟外部依赖项
• Playwright：使用 Playwright 进行端到端（E2E）测试

代码格式化与 lint

Prettier

• 使用 Prettier 统一代码格式
• 配置：printWidth: 120、singleQuote: true、jsxSingleQuote: true
• 运行 pnpm format 格式化代码
• 运行 pnpm format:check 检查格式

ESLint

• 使用带有 TypeScript 插件的 ESLint
• 使用 @typescript-eslint/parser 和 @typescript-eslint/eslint-plugin
• 运行 pnpm lint 检查 lint
• 运行 pnpm lint:fix 自动修复问题

框架建议

对于客户端交互较少的项目

• Astro：内容型网站、博客和文档的绝佳选择
  • 默认仅使用少量 JavaScript
  • 需要时可通过服务端岛屿进行静态生成
  • 性能和 SEO 表现出色
  • 以 TypeScript 为先，开发体验出色

对于客户端交互较多的项目

• 使用搭配 TypeScript 的 React、Svelte 或 SolidJS
• 根据团队偏好和项目需求选择

构建工具

• Vite：开发和生产环境的首选构建工具（除非另有要求）
• 基于现代 Rust 的工具：优先选择 Rolldown 或其他更底层语言的工具
  • 除非明确要求，否则避免使用 Webpack 和其他较旧的、基于 JavaScript 的打包工具

包管理

• pnpm：首选包管理器（比 npm/yarn 更快、更高效）
• 在 package.json 中使用 packageManager 字段
• 在单体仓库中使用 pnpm workspaces

实现

实现 TypeScript 代码时：

• 提交前确保代码通过类型检查
• 将相关更改与测试归为原子提交
• 检查现有工作流模式（先写规范、TDD 等）并遵循

参考

有关使用 pnpm 的单体仓库特定模式，请参阅 references/pnpm-monorepo.md。