typescript-core

TypeScript 核心模式

用于类型安全、运行时验证和优化配置的现代 TypeScript 开发模式。

快速入门

新建项目： 使用 2025 年 tsconfig → 启用 strict + noUncheckedIndexedAccess → 选择 Zod 进行验证

现有项目： 初始启用 strict: false → 用 unknown 修复 any → 添加 noUncheckedIndexedAccess

API 开发： 在边界处使用 Zod 模式 → 使用 z.infer<typeof Schema> 定义类型 → 使用 satisfies 定义路由

库开发： 启用 declaration: true → 使用 const 类型参数 → 查看 advanced-patterns-2025.md

快速参考

tsconfig.json 2025 基准配置

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true
  }
}

关键编译器选项

选项	用途	启用时机
noUncheckedIndexedAccess	对数组／对象访问强制进行空值检查	始终启用以确保安全
exactOptionalPropertyTypes	区分 undefined 与缺失属性	含可选字段的 API
verbatimModuleSyntax	强制显式导入仅用于类型的内容	ESM 项目
erasableSyntaxOnly	支持 Node.js 22+ 原生 TS	类型擦除环境

本地基准配置

针对仓库的 tsconfig 模式（CommonJS CLI、严格 NodeNext、Next.js 打包器），请参阅 references/configuration.md。

核心类型模式

Const 类型参数

通过泛型函数保留字面量类型：

function createConfig<const T extends Record<string, unknown>>(config: T): T {
  return config;
}

const config = createConfig({ 
  apiUrl: "https://api.example.com", 
  timeout: 5000 
});
// Type: { readonly apiUrl: "https://api.example.com"; readonly timeout: 5000 }

Satisfies 运算符

在保留字面量推断的同时验证类型：

type Route = { path: string; children?: Routes };
type Routes = Record<string, Route>;

const routes = {
  AUTH: { path: "/auth" },
  HOME: { path: "/" }
} satisfies Routes;

routes.AUTH.path;     // Type: "/auth" (literal preserved)
routes.NONEXISTENT;   // ❌ Type error

模板字面量类型

实现类型安全的字符串处理和路由提取：

type ExtractParams<T extends string> = 
  T extends `${string}:${infer Param}/${infer Rest}`
    ? Param | ExtractParams<Rest>
    : T extends `${string}:${infer Param}`
      ? Param
      : never;

type Params = ExtractParams<"/users/:id/posts/:postId">; // "id" | "postId"

带穷尽性检查的可辨识联合

type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

function handleResult<T>(result: Result<T>): T {
  if (result.success) return result.data;
  throw result.error;
}

// Exhaustiveness checking
type Action = 
  | { type: 'create'; payload: string }
  | { type: 'delete'; id: number };

function handle(action: Action) {
  switch (action.type) {
    case 'create': return action.payload;
    case 'delete': return action.id;
    default: {
      const _exhaustive: never = action;
      throw new Error(`Unhandled: ${_exhaustive}`);
    }
  }
}

运行时验证

TypeScript 类型在运行时会被擦除。处理外部数据（API、表单、配置文件）时，请使用验证库。

快速比较

库	包体积	速度	最适用于
Zod	~13.5kB	基准	全栈应用、tRPC 集成
TypeBox	~8kB	快 ~10 倍	OpenAPI、性能关键场景
Valibot	~1.4kB	快 ~2 倍	边缘函数、最小化包体积

基本模式（Zod）

import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "guest"]),
});

type User = z.infer<typeof UserSchema>;

// Validate external data
function parseUser(input: unknown): User {
  return UserSchema.parse(input);
}

→ 完整的 Zod、TypeBox 和 Valibot 模式请参阅 runtime-validation.md

决策支持

快速决策指南

需要在 type 和 interface 之间做选择？

• 公共 API／库类型 → interface
• 联合类型／映射类型 → type
• 简单的对象结构 → interface（默认）

需要泛型或联合类型？

• 输出类型取决于输入类型 → 泛型
• 固定的一组已知类型 → 联合类型
• 构建可复用的数据结构 → 泛型

要处理未知数据？

• 外部数据（API、用户输入）→ unknown（类型安全）
• 快速原型开发／迁移 → any（临时使用）

需要运行时验证？

• 使用 tRPC 的全栈 TypeScript → Zod
• OpenAPI／高性能场景 → TypeBox
• 边缘函数／最小化包体积 → Valibot

→ 全面的决策框架请参阅 decision-trees.md

故障排除

常见问题快速参考

类型上不存在该属性 → 定义合适的接口或使用可选属性

类型不可赋值 → 修复属性类型或使用运行时验证（Zod）

对象可能为 'undefined' → 使用可选链（?.）或类型守卫

找不到模块 → 检查文件扩展名（ESM 使用 .js）和模块解析方式

编译缓慢 → 启用 incremental，使用 skipLibCheck，考虑使用 esbuild/swc

→ 详细解决方案及示例请参阅 troubleshooting.md

导航

详细参考

• 📐 高级类型 - 条件类型、映射类型、infer 关键字、递归类型。构建复杂的类型工具或泛型库时加载。

• ⚙️ 配置 - 完整的 tsconfig.json 指南、项目引用、单体仓库模式。设置新项目或优化构建时加载。

• 🔒 运行时验证 - Zod、TypeBox、Valibot 的深入模式、错误处理、集成策略。实现 API 验证或表单处理时加载。

• ✨ 2025 年高级模式 - TypeScript 5.2+ 特性：using 关键字、稳定的装饰器、import type 行为、搭配泛型使用 satisfies。使用现代语言特性时加载。

• 🌳 决策树 - 关于 type 与 interface、泛型与联合类型、unknown 与 any、验证库选择、类型收窄策略及模块解析的清晰决策框架。做出 TypeScript 设计决策时加载。

• 🔧 故障排查 - 常见 TypeScript 错误及修复方法、类型推断问题、模块解析问题、tsconfig 配置错误、构建性能优化及类型兼容性错误。调试 TypeScript 问题时加载。

JavaScript / 运行时质量反模式

类型系统可以捕获类型错误，但有一类 JavaScript 缺陷发生在运行时/AST 层面，并会残留在生成的 JS 和纯 JS 文件中。请留意：

• 宽松相等（==/!=）——会导致强制类型转换错误和身份验证缺陷；请使用 ===/!==（仅在注释说明“null 或 undefined”时接受 == null）。
• 动态代码执行（eval、new Function(str)、字符串形式的 setTimeout）——存在注入风险且没有必要；请使用直接语法。
• 修改内置对象（Object/Array/Function.prototype）——会污染 for…in，破坏整个运行时；请改用扩展或自由函数。
• 变量遮蔽、用 var 代替 let/const、声明前使用函数——会降低可读性，并导致“错误变量”问题。
• switch 的 case 标签中使用逻辑或（case 1 || 2: 只会匹配 1）——请使用连续的 case 标签。
• 重复访问深层成员——将解析后的链缓存到局部变量中（尤其是 DOM）。
• 未加括号的 IIFE、反斜杠多行字符串、new Array()——可读性差且容易出错；请使用加括号的 IIFE、模板字面量和数组字面量。

参见 JS/TS 质量反模式，了解每种缺陷的合规/不合规示例、严重性、误报过滤规则及对应的 ESLint/SonarSource 规则。内容源自 CAST Highlight JavaScript 代码质量指标（https://doc.casthighlight.com/），并与 ESLint 核心规则和 SonarSource RSPEC 交叉比对。

危险信号

遇到以下情况时请停下来重新考虑：

• 对外部数据使用 any 而不是 unknown
• 未经运行时验证就使用 as 进行类型断言
• 为了方便而禁用严格模式
• 使用 @ts-ignore 却没有明确理由
• 未启用 noUncheckedIndexedAccess 时进行索引访问

与其他技能集成

• nextjs-core：类型安全的 Server Actions 和路由处理器
• nextjs-v16：异步 API 模式和 Cache Components 类型
• mcp-builder：MCP 工具输入的 Zod 模式

相关技能

使用 Core 时，以下技能可改进你的工作流：

• react：React 与 TypeScript：组件类型、hooks、泛型
• nextjs：Next.js 中的 TypeScript：Server Components、Server Actions 类型
• drizzle：使用 Drizzle ORM 执行类型安全的数据库查询
• prisma：Prisma 为数据库架构生成的 TypeScript 类型

[如果已部署在你的软件包中，可在这些技能中查阅完整文档]