typescript

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript

Specification

规范

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

<prerequisite> This skill extends the JavaScript preference skill. You MUST load `javascript` first for naming, module style, async patterns, and general JavaScript conventions. </prerequisite>

Types encode intent. Let the compiler prove the rest.

You MUST use TypeScript 7.0 as the baseline. You MUST carry TypeScript 6.0 migration guidance forward: 7.0 is expected to match 6.0 checking and command-line behavior, adopt the 6.0 defaults, and hard-error on constructs and flags deprecated in 6.0.

文中的

MUST

、

MUST NOT

、

REQUIRED

、

SHALL

、

SHALL NOT

、

SHOULD

、

SHOULD NOT

、

RECOMMENDED

、

MAY

和

OPTIONAL

术语按 RFC 2119 中的定义解释。

<prerequisite> 本技能扩展自JavaScript规范技能。你必须先加载`javascript`技能，以遵循命名规范、模块风格、异步模式及通用JavaScript约定。 </prerequisite>

类型承载意图，其余交由编译器验证。

你必须以TypeScript 7.0为基准版本。你必须延续TypeScript 6.0的迁移指导原则：7.0版本需匹配6.0的检查逻辑与命令行行为，沿用6.0的默认配置，并对6.0中已废弃的语法结构和编译标记触发硬错误。

References

参考资料

Topic	Reference	Load when
Configuration and TS 6-to-7 migration	`references/configuration.md`	Updating tsconfig, module resolution, compiler directives, native tooling
Generics and type-level programming	`references/generics.md`	Designing reusable generic APIs, utility types, mapped/conditional/template literal types
Narrowing and type guards	`references/narrowing.md`	Modeling variants, validating unknown values, writing exhaustive code
Patterns and declarations	`references/patterns.md`	Choosing interfaces/types/enums/classes/brands/overloads/callback signatures

主题	参考文档	适用场景
配置与TS 6到7迁移	`references/configuration.md`	更新tsconfig、模块解析、编译器指令、原生工具链
泛型与类型级编程	`references/generics.md`	设计可复用的泛型API、工具类型、映射/条件/模板字面量类型
类型收窄与类型守卫	`references/narrowing.md`	建模变体、验证未知值、编写穷尽式代码
模式与声明	`references/patterns.md`	选择接口/类型别名/枚举/类/品牌类型/重载/回调签名

Baseline

基准原则

You MUST treat TypeScript 7.0 as stable project direction. The native Go compiler and language service are the expected direction for type checking, editor tooling, and performance-sensitive validation.
You MUST use 6.0 as the compatibility bridge: code that passes 6.0 with stable type ordering and without deprecated flags SHOULD be ready for 7.0.
You SHOULD prefer explicit, domain-shaped types over clever type-level machinery. Stay at the simplest type complexity tier that proves the behavior.
You MUST match the project's established conventions first. If a project contradicts this skill, follow the project locally and flag the divergence once.

你必须将TypeScript 7.0视为项目的稳定技术方向。原生Go编译器与语言服务是类型检查、编辑器工具链及性能敏感型验证的首选方案。
你必须以6.0版本作为兼容性过渡桥梁：通过6.0版本检查、具备稳定类型排序且未使用废弃标记的代码，应可直接适配7.0版本。
相较于复杂的类型级实现，你应优先选择明确的、贴合业务域的类型。采用能验证行为的最简类型复杂度层级即可。
你必须优先遵循项目已确立的规范。若项目规范与本技能冲突，先遵循本地项目规范，并一次性标记差异点。

Type Safety

类型安全

Strict mode is REQUIRED. TS 7.0 defaults to strict checking; keep
```
strict: true
```
explicit in shared configs when clarity helps.
You MUST use
unknown
for untrusted values. Narrow API, JSON, user input, and caught values before use. Temporary
```
any
```
is acceptable only for migrations or mocks, with a short comment explaining why.
You SHOULD avoid non-null assertions. Narrow instead. If
```
!
```
is truly needed, explain the invariant near the assertion.
You SHOULD prefer annotations and
satisfies
over assertions. Use
```
satisfies
```
to validate literals without widening; use annotations where intentional widening or public API shape matters. Use
```
as
```
only when you know more than the compiler.
You MUST use
import type
and
export type
for type-only imports and re-exports.
You MUST NOT suppress type errors casually. Prefer fixing the type. Use
```
@ts-expect-error
```
only for deliberate invalid examples or tests, with a comment. Do not use
```
@ts-ignore
```
or
```
@ts-nocheck
```
in production code.

必须启用严格模式。 TS 7.0默认开启严格检查；若需提升清晰度，在共享配置中显式设置
```
strict: true
```
必须对不可信值使用
unknown
类型。在使用API返回值、JSON数据、用户输入及捕获的错误值前，先进行类型收窄。仅在迁移或模拟场景下可临时使用
```
any
```
，并需添加简短注释说明原因。
应避免非空断言。 优先使用类型收窄。若确实需要使用
```
!
```
，需在断言附近注释说明不变条件。
相较于类型断言，应优先使用类型注解和
satisfies
。使用
```
satisfies
```
验证字面量类型而不进行类型拓宽；在需要刻意拓宽类型或定义公共API形态时使用类型注解。仅当你比编译器掌握更多信息时，才使用
```
as
```
进行断言。
必须使用
import type
和
export type
用于仅类型导入与重导出。
不得随意抑制类型错误。 优先修复类型问题。仅在编写故意无效的示例或测试时使用
```
@ts-expect-error
```
，并添加注释。生产代码中禁止使用
```
@ts-ignore
```
或
```
@ts-nocheck
```
。

Modeling

类型建模

You SHOULD use discriminated unions for variants. Use a
```
kind
```
,
```
type
```
, or similarly stable literal discriminator and exhaustive handling.
You SHOULD use interfaces for object shapes and type aliases for everything else. Use
```
type
```
for unions, intersections, tuples, function types, mapped types, and conditional types.
You SHOULD use literal unions or
as const
maps for simple constants. Use string enums only when a real runtime object or namespace is useful. Avoid implicit numeric enums and mixed enum members.
Branded types for nominal safety. Use them for domain IDs, validated strings, and units that MUST NOT be mixed.
Keep nullability at use sites. Prefer
```
function find(): User | null
```
over spreading
```
MaybeUser
```
aliases through the codebase.
Use
Record<K, V>
for dictionary-shaped data. Prefer specific key unions when possible.

应使用区分联合类型建模变体。 使用
```
kind
```
、
```
type
```
或类似的稳定字面量作为区分符，并实现穷尽式处理。
对象形态优先使用接口，其他场景优先使用类型别名。 使用
```
type
```
定义联合类型、交叉类型、元组、函数类型、映射类型及条件类型。
简单常量优先使用字面量联合类型或
as const
映射。仅当需要真实运行时对象或命名空间时，才使用字符串枚举。避免隐式数字枚举和混合类型枚举成员。
使用品牌类型实现名义类型安全。 将其用于业务域ID、已验证字符串及不可混用的单位类型。
在使用站点处理可空性。 优先选择
```
function find(): User | null
```
，而非在整个代码库中传播
```
MaybeUser
```
这类别名。
使用
Record<K, V>
定义字典形态数据。若可能，优先使用具体的键联合类型。

Generics

泛型

You SHOULD let inference work. Do not specify type arguments when the compiler can infer them.
You SHOULD constrain generics with
```
extends
```
when the implementation requires structure.
You SHOULD avoid return-type-only generics; callers SHOULD NOT have to guess type arguments.
You SHOULD use built-in utility types (
```
Partial
```
,
```
Pick
```
,
```
Omit
```
,
```
Record
```
,
```
ReturnType
```
,
```
Parameters
```
,
```
Awaited
```
,
```
NoInfer
```
) instead of hand-rolled equivalents.
You SHOULD use
```
NoInfer<T>
```
when one parameter MUST be checked against another parameter's inferred type without driving the inference itself.
Reserve conditional, mapped, template literal, and recursive types for library/framework code or places where they remove more complexity than they add.

应让编译器自动推断类型。当编译器可自行推断时，无需显式指定类型参数。
当实现需要特定结构时，应使用
```
extends
```
约束泛型。
应避免仅用于返回值的泛型；调用者不应需要猜测类型参数。
应使用内置工具类型（
```
Partial
```
、
```
Pick
```
、
```
Omit
```
、
```
Record
```
、
```
ReturnType
```
、
```
Parameters
```
、
```
Awaited
```
、
```
NoInfer
```
）而非手动实现等效类型。
当一个参数必须与另一个参数的推断类型进行校验，但又不希望驱动推断过程时，应使用
```
NoInfer<T>
```
。
仅在库/框架代码中，或能减少整体复杂度的场景下，使用条件类型、映射类型、模板字面量类型及递归类型。

Configuration

配置

TS 7.0 defaults MUST be treated as normative:
```
strict
```
is on,
```
module
```
defaults toward
```
esnext
```
, and
```
target
```
defaults toward the stable ECMAScript version immediately before
```
esnext
```
.
You SHOULD prefer modern configuration:
- Bundled apps:
```
module: "preserve"
```
  ,
```
moduleResolution: "bundler"
```
  ,
```
noEmit: true
```
  .
- Direct Node output:
```
module: "nodenext"
```
  , with package
```
type
```
  and emitted file extensions handled deliberately.
- Use
```
verbatimModuleSyntax
```
  ,
```
isolatedModules
```
  ,
```
moduleDetection: "force"
```
  , and explicit
```
types
```
  .
You MUST NOT depend on TS 6.0-deprecated paths in new work: legacy ES5 targeting, classic/node10-style resolution,
```
baseUrl
```
as a lookup root,
```
import ... asserts
```
,
```
outFile
```
, or AMD/UMD/SystemJS module targets.
You SHOULD use
```
stableTypeOrdering
```
while validating 6.0-to-7.0 migrations when type-display or declaration-order stability matters.

TS 7.0的默认配置必须视为标准：
```
strict
```
默认开启，
```
module
```
默认趋向
```
esnext
```
，
```
target
```
默认趋向
```
esnext
```
之前的稳定ECMAScript版本。
应优先使用现代配置：
- 打包应用：
```
module: "preserve"
```
  ，
```
moduleResolution: "bundler"
```
  ，
```
noEmit: true
```
  。
- 直接输出Node代码：
```
module: "nodenext"
```
  ，需明确处理package的
```
type
```
  字段及输出文件扩展名。
- 使用
```
verbatimModuleSyntax
```
  、
```
isolatedModules
```
  、
```
moduleDetection: "force"
```
  及显式
```
types
```
  配置。
新代码中不得依赖TS 6.0已废弃的配置路径：遗留ES5目标版本、classic/node10风格解析、将
```
baseUrl
```
作为查找根、
```
import ... asserts
```
、
```
outFile
```
，或AMD/UMD/SystemJS模块目标。
当类型显示或声明顺序稳定性很重要时，在验证6.0到7.0的迁移过程中应使用
```
stableTypeOrdering
```
。

Application

实践应用

When writing TypeScript:

You MUST apply these conventions without narrating each one.
You MUST keep exported functions, public methods, and package boundaries explicitly typed.
You SHOULD keep local implementation types inferred when inference is clear.
You MUST use runtime validation at trust boundaries; types do not validate data at runtime.

When reviewing TypeScript:

You MUST lead with concrete bugs, unsoundness, or migration risks.
You SHOULD show the smallest correction inline.
You MUST separate style preferences from type-safety issues.

编写TypeScript代码时：

必须直接应用这些规范，无需逐一说明。
必须为导出函数、公共方法及包边界显式添加类型注解。
当类型推断清晰时，应让本地实现类型自动推断。
必须在信任边界处进行运行时验证；类型无法在运行时验证数据。

评审TypeScript代码时：

必须先关注具体的bug、类型不安全问题或迁移风险。
应展示最小化的内联修正方案。
必须将风格偏好与类型安全问题区分开。