name: typescript-dev description: TypeScript 开发最佳实践、代码质量工具和文档模板。在处理 .ts、.tsx 文件或 TypeScript 项目时激活。 allowed-tools: [‘Read’, ‘Glob’, ‘Grep’, ‘Bash’]

TypeScript 开发专家

此技能支持 TypeScript 项目开发。

🎯 核心规则

包管理

必需：使用 pnpm 作为包管理器
不要使用 npm 或 yarn

类型安全

tsconfig.json：必须设置 strict: true
空值处理：利用可选链 ?. 和空值合并 ??
导入：使用 ES 模块，避免 require()
禁止使用 ANY：在生产代码中不要使用 any 类型

最佳实践

类型推断：在类型明显时让 TypeScript 推断
泛型：用于可复用组件
联合类型：对于字符串字面量，优先使用联合类型而非枚举
实用工具类型：利用内置类型（Partial, Pick, Omit）

文档

必需：使用 TSDoc 格式编写文档注释
仅限公共 API：为导出的函数、类和接口编写文档
自解释代码：优先使用清晰的命名而非过多的注释
必要时才写文档：仅当代码意图无法从签名中明显看出时才添加 TSDoc

🛠️ 代码质量工具

开发工作流

# 格式化代码
pnpm run format

# 运行代码检查
pnpm run lint

# 类型检查
pnpm tsc --noEmit

# 运行测试并生成覆盖率报告
pnpm test -- --coverage

🎯 质量检查清单

在代码审查时检查以下内容：

[ ] 公共 API 具有 TSDoc 注释（当意图无法从签名中清晰看出时）
[ ] 未使用 any 类型
[ ] 正确的错误处理
[ ] 测试覆盖率高于 80%
[ ] 正确利用了类型推断
[ ] 使用了实用工具类型
[ ] 使用了可选链 (?.) 和空值合并 (??)
[ ] 使用了 ES 模块（避免 require()）

🚀 常用模式

错误处理

// 良好：清晰的错误类型
class ValidationError extends Error {
  constructor(message: string, public field: string) {
    super(message);
    this.name = 'ValidationError';
  }
}

// 良好：Result 类型模式
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

异步/等待

// 良好：包含错误处理
async function fetchUserData(id: string): Promise<Result<UserData>> {
  try {
    const response = await fetch(`/api/users/${id}`);
    const data = await response.json();
    return { success: true, data };
  } catch (error) {
    return { success: false, error: error as Error };
  }
}

类型守卫

// 良好：自定义类型守卫
function isUserProfile(value: unknown): value is UserProfile {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'username' in value
  );
}

💡 性能提示

避免不必要的重新渲染 (React)
- 对开销大的组件使用 React.memo
- 适当使用 useMemo / useCallback
懒加载
- 使用动态导入进行代码分割
- 对组件使用 React.lazy()

仅类型导入

import type { UserProfile } from './types';

🔍 应避免的常见反模式

❌ 不要：

// 使用 any 类型
function process(data: any) { }

// 隐式 any
function getValue(obj, key) { }

// 过多的类型断言
const user = data as User;

✅ 应该：

// 正确的类型定义
function process(data: UserData) { }

// 显式类型
function getValue<T>(obj: T, key: keyof T) { }

// 使用类型守卫
if (isUser(data)) {
  // 此处 data 是 User 类型
}