用途
这是一套与框架无关的个人 TypeScript 代码风格约定,适用于编写或审查 TypeScript 代码的场景,包括命名、类成员排序、方法签名,以及把一个模块拆分成多个文件。它可同样应用于 NestJS 服务、Angular 组件或普通库模块,并应叠加在任何具体技术栈技能(如 nestjs-personal-conventions、angular-personal-conventions)之下——它约束的是命名与结构,而非架构。
主要能力
命名
- 接口/类型名称不加 Interface 后缀(用 CreateUserRequest,而非 CreateUserRequestInterface)。
- 当名称其余部分已表达含义时,不使用填充词(Data、Info 等)(用 IncidentHistoryEntry,而非 IncidentHistoryEntryData)。Request/Response 不算填充词,它们表示方向(发送的内容 vs. 返回的内容),仍然有意义;实体名称本身不应被它们替代。
- 字段排序:在接口、类型以及 DTO/类字段声明中,必填字段在前,可选字段(field?: T)在后,没有例外。
- 非空断言(!)在所有地方都被禁止,唯一例外是框架校验的 DTO 字段这一处有文档记录的窄例外(见相关技术栈技能,如 nestjs-personal-conventions)——应改用显式守卫或收窄后的类型。
- 透传载荷参数命名为 payload,而非 request。当方法接收一个已组装好的对象并只是转发它(出站 HTTP 调用、事件发布)时,payload 读作“我正在发送的东西”,而 request 会与同一代码库中别处使用的入站请求含义冲突。
类结构
- 在任何框架的每个类中应用此成员顺序:输入 → 输出 → 按可见性排列的字段(public → protected → private)→ 构造函数 → 按可见性排列的方法(public → protected → private)。“输入”/“输出”指框架自身的输入/输出原语(例如 Angular 的 input()/output());没有该概念的类跳过这两个位置。为满足接口而存在的回调字段(事件处理器、生命周期钩子)按其实际可见性放在字段区,而不是因为它们是回调就固定在顶部。
- 方法体内逻辑块之间用空行分隔:用空行分隔守卫子句、数据准备、实际调用和结果处理。没有例外——读起来像一整段密集文字的方法,比同样逻辑但各阶段在视觉上分开的方法更难扫读。
- 3 个及以上参数 → 合并为一个具名对象并解构。一旦函数、方法或构造函数接收三个或更多参数,就把它们折叠为单个具名对象参数,而不是扁平的位置参数列表——公共和私有方法都一样。对象类型可内联声明,或放在附近的 *.types.ts 文件中。
// ❌ four positional params — call sites need the doc comment to be readable
function scheduleNotification(userId: number, channel: string, delayMs: number, retry: boolean) {}
// ✅ one destructured object — call sites are self-describing
function scheduleNotification({ userId, channel, delayMs, retry }: ScheduleNotificationParams) {}
避免 let 加后续重新赋值
优先使用从返回结果的箭头函数赋值的 const,而不是 let x; try { x = ...; } catch { ... }:
// ❌ mutable let, reassigned inside try/catch
let parsed;
try {
parsed = JSON.parse(raw);
} catch {
throw new Error('invalid JSON');
}
// ✅ const from a function that owns the try/catch
const parseJsonConfig = (raw: string): unknown => {
try {
return JSON.parse(raw);
} catch {
throw new Error('invalid JSON');
}
};
const parsed = parseJsonConfig(raw);
禁止魔法数字
把时长、TTL、间隔和重试次数表达为命名常量,或基于明显基准单位的算术(60 * 60 * 1000,或共享 const)——绝不用 900000 这样的不透明字面量。生产代码和测试代码都适用——测试自身的超时/延迟值和生产值一样需要名称。
拆分增长的模块
| 内容 | 放置位置 |
|---|---|
| 多于一个类型/接口 | *.types.ts |
| 常量 | *.constants.ts |
| 纯构建器/格式化函数(无副作用、无 DI) | *.helpers.ts——与 *.constants.ts 分开;即使在同一领域,const 和函数也不是同一种东西 |
| 纯行/载荷 → 领域类型映射器(逐字段重新赋值,除 ?? 默认值外无分支) | *.mapper.ts——与 *.helpers.ts 分开,后者用于真正的格式化/构建器逻辑 |
| 类型守卫(x is T 谓词) | 放在其收窄的类型旁边,同一个 *.types.ts 中——不放在 *.helpers.ts 或独立文件。守卫由它所保护的类型定义,而不是仅仅因为它是个函数 |
| 类/处理器本身 | 只放类及其导入——以上所有内容都放在别处 |
Barrels:index.ts 只导出公共 API——绝不重新导出内部类型。一个自身只包含若干类点号子文件夹的文件夹(一个 services/ 分组文件夹,内含 .service/、.resolver/ 等)拥有自己的聚合 index.ts,供外部消费者重新导出(from './services')。组内同级文件之间仍通过直接相对路径互相导入,而不是通过聚合 barrel——让同级导入经过它会有通过 barrel 本身产生导入循环的风险。
测试同置:任何带测试的单元都放在点号表示法的子文件夹中,并带本地 index.ts barrel——some-service/some-service.ts + some-service/some-service.spec.ts + some-service/index.ts。没有测试的普通常量/类型文件保持扁平。从测试运行器的发现/覆盖率配置中排除 .mapper.ts(例如 exclude: ['src/**/.mapper.ts']),而不是为它写 spec——纯映射器不做单元测试(见 testing-philosophy)。
常见错误
| 错误 | 修正 |
|---|---|
| CreateUserRequestInterface、UserData | 去掉 Interface 后缀和填充词:CreateUserRequest、User |
| 可选字段混在必填字段之前 | 必填在前,可选在后——重新排序 |
| 一个 4 个位置参数的函数 | 折叠为一个解构对象参数 |
| let x; try { x = ...} catch {...} | 提取为返回值的函数,从调用中赋值 const |
| TTL 用字面量 86400000 | 命名它,或写成 24 * 60 * 60 * 1000 |
| *.mapper.ts 函数带真正的分支/格式化逻辑 | 那是 helper,不是 mapper——移到 *.helpers.ts |
| 类型守卫放在 *.helpers.ts | 移到其收窄的类型旁边,即 *.types.ts |
使用方式
该技能以约定清单和正反示例的形式给出规则,供编写或审查 TypeScript 代码时参照。它不提供安装命令或运行步骤(资料未提供)。
适用场景
适用于任何框架下的 TypeScript 代码编写与审查,包括 NestJS 服务、Angular 组件和普通库模块。可叠加在具体技术栈技能之下使用。
限制
该约定只约束命名与结构,不涉及架构。非空断言有一个窄例外,需参考相关技术栈技能(如 nestjs-personal-conventions)。纯映射器不做单元测试,需从测试运行器配置中排除。资料未提供收费、价格、平台或效果等信息。