typescript-standards

何时加载

在任务涉及以下内容时加载此技能：

• 创建或重构函数、方法、类、模块
• 类型选择：接口、类型、枚举、泛型、工具类型
• 领域建模、边界、共享契约
• API 设计、层间模块边界
• 设计原则：SOLID、KISS、YAGNI、LIFT、SoC
• 有实际依据的设计模式（GoF）

组合使用

此技能与框架技能互为补充：

• 与 angular-standards 一同加载时：将 TypeScript 规则应用于 Angular 资源的 .ts 文件
• 框架技能优先处理生态系统特定的组织方式（Angular DI、signals 等）
• 此技能优先处理通用语言和设计规则（类型、边界、模块）
• 根据 angular-standards 的“组合使用”部分触发加载此技能——对于 angular-standards 已涵盖的组件任务，请勿单独自动触发

不要在以下情况加载

• 仅涉及 HTML 模板或 SCSS/CSS 的任务
• 构建／部署／基础设施任务
• 提交（使用 git-commit）
• CI/CD 配置

---

TypeScript 规范

使用时机

• 在项目中创建或重构 TypeScript 文件。
• 定义接口、类型、共享契约和模块边界。
• 对领域、结果、错误、集合和公共 API 建模。
• 做出与特定框架无关的设计和架构决策。

目标

• 保持类型强健、可预测且易于阅读。
• 保持简单、内聚，并促进代码健康演进。
• 将详细规则集中在本地参考资料中，以避免重复并明确优先级。
• 务实地应用设计原则，避免过度设计。

LIFT 原则

在创建任何新类型、辅助工具、模块、类、适配器、工厂、端口或抽象之前，应用 LIFT 原则：

• 定位（Locate）：查找现有契约、类型、辅助工具、模式、模块和参考资料。
• 识别（Identify）：确定已有内容中哪些可以解决部分问题，以及哪些地方存在实际或潜在的重复。
• 寻找（Find）：在引入新内容之前，找到最小且内聚的复用、扩展或组合位置。
• 力求 DRY（Try to be DRY）：消除实际重复，同时避免创建过早抽象、过度通用的层或不透明结构。

与其他技能的集成

• 此技能横跨多个领域，属于语言层级：Angular 和 Vue 等框架应继续规定框架特定的架构。
• typescript-standards 定义 TypeScript 中的建模、契约、模块设计、边界验证和务实设计。
• 如果发生冲突，框架技能优先处理生态系统特定的组织方式；typescript-standards 优先处理通用语言和设计规则。

主要规则

• 引入新类型、模块、类、辅助工具、适配器、工厂或模式之前，先应用 LIFT。
• 绝不使用 any；类型不确定时，使用 unknown。
• 导入时始终使用路径别名。严格禁止深层相对导入（../../ 或更深）。
  • 应用内部跨模块导入使用 @<app-name>/<feature>/*（例如，@vendas/services/some.service）。
  • 共享库导入使用 @lib/<lib-name>（例如，@lib/data-access、@lib/ui、@lib/utils、@lib/pipes）。
  • 有子路径别名时，使用 @lib/<lib-name>/<sub-path>（例如，@lib/data-access/config、@lib/data-access/enums）。
  • 仅在同一功能文件夹内允许相对导入（./ 或 ../），最多 1 层。
• 接口名称必须以 I 开头。
• 不要在非专用接口文件中创建接口。
• 每个接口都必须有一个对应的生成器，并使用 faker.js。
• 接口生成器必须放在专用文件中，并遵循项目采用的文件夹层级。
• 每次执行时，生成器必须创建或接收一个随机种子，并由此派生所有契约数据。
• 不要在非专用枚举文件中创建枚举。
• 每个文件只保留一个枚举。
• 每个枚举都必须在同一文件中包含一个用于映射其值标签的结构。
• 优先使用函数和模块，而不是类。
• 优先使用组合，而不是继承。
• 默认遵循 KISS、YAGNI 和 SoC。
• 将 SOLID 视为务实的启发原则，而非教条式清单。
• 将对象体操视为可选的设计约束，而非规则。
• 只有在确实面临变更、重复或解耦压力时，才使用 GoF 模式。
• 对象键足够时，优先使用 Record 而不是 Map。
• 只有确实需要其专用 API 或对不可序列化键的支持时，才使用 Map。
• 除非类型之间紧密相关，否则每个文件只放一个契约。
• 引入新类型前，检查领域中是否已存在等效契约。
• 数据从系统外部进入时，验证运行时边界。
• 使用单引号和分号。

流程

1. 创建新类型、模块或抽象之前，先应用 LIFT。
2. 确定此次变更真正需要的契约、类型和边界。
3. 如果存在接口，也要规划在正确项目层级中的对应生成器。
4. 创建新类型之前，先复用现有类型。
5. 使用限制最严格、最清晰、最简单的选项建模。
6. 如果存在不确定性，使用 unknown 并进行显式收窄。
7. 根据对状态、身份、生命周期或多态性的实际需求，选择函数、模块、对象或类。
8. 如果考虑使用 GoF 模式，先检查简单组合是否能解决问题。
9. 使用 KISS、YAGNI、SoC 和领域可读性检查结果。

质量检查清单

• 引入新结构前已应用 LIFT。
• 未引入 any。
• 无深层相对导入（../../ 或更深）——所有跨模块导入均使用路径别名。
• 接口名称遵循 I 前缀规则。
• 接口位于专用文件中。
• 接口具有对应的生成器。
• 接口生成器使用 faker.js。
• 接口生成器遵循项目的文件夹层级。
• 接口生成器每次执行时使用单个随机种子。
• 枚举位于专用文件中。
• 每个文件只有一个枚举。
• 每个枚举都在同一文件中包含标签映射结构。
• 优先选择满足需求的最简单方案。
• 没有投机性抽象。
• 适用时优先使用 Record。
• 只有在有充分技术理由时才使用 Map。
• 必要时对外部边界进行了适当验证。
• 文件使用单引号和分号。
• 没有不必要地增加类型、类或模式。

注意事项

• 此技能默认不要求采用面向对象设计；在 TypeScript 中，函数、模块和组合通常是最佳起点。
• SOLID、GoF 和 Object Calisthenics 的目的在于改进设计和可维护性，而不是为额外的复杂性辩护。
• 当框架技能定义了特定结构时，请遵循该框架，并在语言和设计层面应用此技能。

类型决策

在定义接口、类型、枚举、泛型或建模领域契约时参考。

• 接口与类型：references/types-interface-vs-type.md
• 接口生成器：references/types-interface-generators.md
• 枚举：references/types-enums.md
• 领域建模：references/types-domain-modeling.md
• 泛型：references/types-generics.md
• 工具类型：references/types-utility-types.md
• 联合类型与类层次结构：references/types-unions-vs-class-hierarchies.md
• 类型收窄与 unknown：references/types-narrowing-and-unknown.md
• 只读与不可变性：references/types-readonly-and-immutability.md
• Record 与 Map：references/types-record-vs-map.md
• 错误与结果结构：references/types-errors-and-result-shapes.md
• 运行时验证：references/types-runtime-validation.md

架构与模块设计

在设计函数、类、模块、边界或 API 表面时参考。

• 函数与类：references/architecture-functions-vs-classes.md
• 模块与边界：references/architecture-modules-and-boundaries.md
• DI 与组合：references/architecture-dependency-injection-and-composition.md
• 副作用与端口：references/architecture-side-effects-and-ports.md
• API 设计：references/architecture-api-design.md
• 文件组织：references/architecture-file-organization.md

设计原则

在做出影响可维护性的结构或设计决策时参考。

• LIFT：references/principles-lift.md
• SOLID：references/principles-solid.md
• KISS 与 YAGNI：references/principles-kiss-yagni.md
• 关注点分离：references/principles-separation-of-concerns.md
• Object Calisthenics：references/principles-object-calisthenics.md

设计模式

仅在确实需要应对变更、重复或解耦时参考。

• 模式概览：references/patterns-overview.md
• 创建型：references/patterns-creational.md
• 结构型：references/patterns-structural.md
• 行为型：references/patterns-behavioral.md
• 何时不使用模式：references/patterns-when-not-to-use.md

务实设计

在评估重复、抽象权衡或重构时机时参考。

• 重复与抽象：references/pragmatic-duplication-vs-abstraction.md
• 重构时机：references/pragmatic-refactoring-triggers.md