SuperAPI AI 工具集

ts-code-style-conventions

编程与开发

查看项目

更新于 10-22 16:18

技能介绍

用途

这是一套与框架无关的个人 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)。纯映射器不做单元测试,需从测试运行器配置中排除。资料未提供收费、价格、平台或效果等信息。