SuperAPI AI 工具集

typescript-expert

编程与开发

查看项目

更新于 10-16 09:50

技能介绍

用途:以「运行时简单、编译期精确」为目标编写、重构或审查 TypeScript 代码。先在本地仓库约定与官方 TypeScript 指引之间取优先级,优先遵循仓库约定。

主要能力与工作流:先读取最近的 tsconfig.json、package.json 及相关源码,再选择类型;先建模运行时契约(输入、输出、失败模式、所有权边界、公开 API 形态);用类型让非法状态难以表示,但实现保持可读的 JavaScript;在边界处校验未知外部数据,不假装未校验数据已符合内部类型。涉及测试改动时,交给 write-tests 技能处理运行器、夹具、断言、依赖和校验约定。

验证:完成前运行最小必要命令——包级改动用该包的 typecheck/test;更大范围用 pnpm run typecheck:changed 与 pnpm run test:changed;条件允许时运行 pnpm run lint。

类型设计:局部变量和回调参数上下文明显时依赖推断;导出函数、公开方法、重载实现、递归函数及返回类型属于契约一部分的函数,加显式返回类型;必须检查后再用的值用 unknown,避免 any;用 string、number、boolean、symbol、object 等原始类型,不用装箱类型;新公开对象形状和选项对象优先用 interface,联合、元组、映射类型、条件类型及非对象别名用 type;行为取决于模式、状态、kind 或变体时用可辨识联合,并在增改变体时做穷尽检查;对象字面量需符合更宽类型同时保留窄推断时用 satisfies;应保持窄且只读的字面量表、判别值和元组用 as const。

避免类型漏洞:不要用 any、as SomeType、!、@ts-ignore 或 @ts-expect-error 来修错误,先改类型模型、加控制流收窄、校验未知输入或改 API 形态;断言只在 TypeScript 无法表达的真实证明处使用,并尽量贴近该证明;重复的运行时检查优先用可复用的类型守卫或断言函数;避免 value as unknown as Target 这类双重断言,无法避免时隔离在边界并记录不变式。

null、可选与索引值:保持 strictNullChecks 纪律,使用前处理 null 和 undefined;当 ''、0、false、空数组是有效值时,优先用 value !== undefined、value !== null 或 value != null 而非宽泛真值判断;property?: T 表示属性可缺席,若键总存在但值可缺失则写 property: T | undefined;索引数组、元组、map、record 或 URL/search 参数时先考虑缺失值;非空断言 ! 仅在附近不变式可证明时局部使用。

函数与 API:每个接受形态的实现和返回类型相同时,优先联合参数而非重载;真正不同的调用签名才用重载,最具体的在前、最通用的在后;回调返回值被忽略时用 () => void;避免 Function,写出可调用形状如 (request: Request) => Response | Promise<Response>;会产生多种行为模式的布尔标志参数优先改为具名选项对象或可辨识联合。

泛型:仅当类型参数关联至少两个位置(输入到输出、键到对象、项到集合、回调到值)时引入;尽量少用,移除不影响结果类型的参数;只为实现实际使用的能力加约束(如 extends { length: number } 或 extends keyof source);调用方优先推断类型实参。

边界与断言:把 JSON、请求体、header、环境值、动态路由参数、文件系统数据、第三方响应等不可信输入先解析收窄,再转为内部类型;断言贴近运行时证明,证明可复用时优先小的类型守卫或断言函数;除非测试或上游兼容需要,不用 @ts-ignore 或 @ts-expect-error 消音,且要写明具体原因。

适用场景:在仓库中编写、重构、审查 TypeScript 代码,设计公开 API 与包结构,处理边界数据与类型收窄。

限制:本技能内容来自公开资料,具体收费、价格、平台或效果暂未提供。