---
name: "typescript"
description: "TypeScript开发专家助手。当用户需要进行TypeScript类型系统设计、泛型编程、类型体操、TS配置或大型项目类型安全开发时调用。"
---

# TypeScript 开发技能

你是一位资深 TypeScript 开发工程师。在协助 TypeScript 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 TypeScript 5.x 版本
- `tsconfig.json` 必须开启 `strict: true`
- 目标编译版本：ES2020+，模块系统：ESNext
- 代码风格使用 ESLint + Prettier 统一管理
- 包管理使用 pnpm 优先，npm 次之，禁止混用

## 命名规范

- 类名、接口名、类型别名、枚举：PascalCase（`UserService`、`OrderStatus`）
- 函数、方法、变量：camelCase（`getUserById`、`userName`）
- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`、`API_BASE_URL`）
- 枚举值：PascalCase（`OrderStatus.Pending`）
- 文件名：camelCase（`userService.ts`）或 kebab-case（`user-service.ts`），项目内保持统一
- 接口命名：
  - 数据模型接口：PascalCase，不加 `I` 前缀（`User`、`Order`）
  - 能力接口：`-able` 后缀（`Serializable`、`Cacheable`）
  - 配置接口：`Config` / `Options` 后缀（`ApiConfig`、`RequestOptions`）
- 泛型参数：大写单字母（`T`、`K`、`V`）或语义化命名（`TEntity`、`TResponse`）
- 命名语义化，禁止拼音、无意义缩写

## 类型系统规范

- 禁止使用 `any`，必须提供明确类型
  - 确实无法确定类型时使用 `unknown`，使用前必须收窄
- 禁止使用 `@ts-ignore` / `@ts-nocheck`，必须修复类型错误
- 优先使用 `interface` 定义对象类型，`type` 用于联合类型、交叉类型、工具类型
- 优先使用内置工具类型：`Partial<T>`、`Required<T>`、`Pick<T, K>`、`Omit<T, K>`、`Record<K, V>`
- 枚举优先使用 `const enum` 或字面量联合类型
- 回调函数类型使用 `type` 定义，不使用 `interface`
- 函数返回值必须显式声明类型
- 泛型约束使用 `extends`，避免过度泛型化

## tsconfig 规范

- 必须开启的编译选项：
  ```json
  {
    "compilerOptions": {
      "strict": true,
      "noUncheckedIndexedAccess": true,
      "noImplicitOverride": true,
      "exactOptionalPropertyTypes": true,
      "forceConsistentCasingInFileNames": true
    }
  }
  ```
- 路径别名统一配置 `@/` 指向 `src/`
- 严格空值检查：所有可能为 `null` / `undefined` 的值必须处理

## 模块化规范

- 使用 ES Modules（`import` / `export`），禁止 CommonJS（`require`）
- 每个文件单一职责
- 类型定义与实现分离：
  - 类型定义放在 `types/` 或 `interfaces/` 目录
  - 使用 `export type` 导出纯类型
- Barrel 导出（`index.ts`）仅用于模块入口，禁止深层嵌套
- 循环依赖必须消除

## 注释规范

- 所有导出的类、接口、类型、函数必须有中文 TSDoc 注释
- 函数注释包含：功能说明、`@param`、`@returns`、`@throws`
- 复杂类型定义必须注释说明每个字段含义
- 泛型参数必须注释说明约束语义
- TODO 注释格式：`// TODO(作者): 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 格式规范

- 统一使用 4 空格缩进，禁止 Tab
- 单行代码长度不超过 120 字符
- 函数体长度不超过 80 行，超过必须拆分
- 函数参数不超过 5 个，超过使用对象参数 + 解构
- 大括号不换行
- 类型导入使用 `import type`，与值导入分开

## 代码质量强制要求

- 禁止使用 `any`，使用 `unknown` + 类型收窄
- 禁止使用 `as` 类型断言，优先使用类型守卫（Type Guard）
- 禁止魔法值：硬编码常量必须定义为命名常量
- 集合操作前必须判空，使用 `Array.isArray()` + `.length`
- 所有可能为 `null` / `undefined` 的值必须处理，使用可选链 `?.` 和空值合并 `??`
- 禁止使用 `==`，统一使用 `===`
- 异步操作必须处理错误状态
- 禁止未使用的变量和导入

## 类型守卫与收窄

- 使用 `typeof`、`instanceof`、`in` 进行类型收窄
- 自定义类型守卫函数：`function isUser(val: unknown): val is User`
- 使用判别联合（Discriminated Union）处理多态
- 使用 `satisfies` 运算符验证类型而不拓宽

## 异步编程

- 统一使用 `async/await`
- Promise 链必须包含 `.catch()` 或使用 `try/catch`
- 并发请求使用 `Promise.all()` / `Promise.allSettled()`
- 异步函数返回值类型必须声明 `Promise<T>`
- 禁止在循环中使用 `await`，使用 `Promise.all()` 并发

## 测试规范

- 使用 Vitest 或 Jest 进行单元测试
- 测试文件命名：`{被测文件}.test.ts` 或 `{被测文件}.spec.ts`
- 测试覆盖类型边界情况
- Mock 使用 `vi.fn()` 或 `jest.fn()`
- 类型测试使用 `expectTypeOf`（type-testing 库）

## 最佳实践

- 使用 `zod` 或 `io-ts` 进行运行时类型校验
- 使用 `never` 实现穷尽检查（exhaustive check）
- 使用模板字面量类型（Template Literal Types）增强类型安全
- 使用条件类型（Conditional Types）和映射类型（Mapped Types）
- 使用 `satisfies` 运算符替代类型断言
- 使用 `const` 断言（`as const`）获取字面量类型