mcpField
T
typescript-best-practices

typescript-best-practices

github.com/ghosttypes开发835 次安装5 周前更新
代码仓库

关于 typescript-best-practices

面向希望保持代码一致性与类型安全的 TypeScript 开发者，提供开发规范。内容涵盖严格配置、运行时校验、错误处理及导入导出约定，并按主题提供参考文件。

主要功能

  1. 01严格的 TypeScript 配置
  2. 02为公共 API 显式声明类型
  3. 03使用判别联合与 Result 类型
  4. 04运行时类型守卫与断言
  5. 05导入导出约定
  6. 06按主题划分的参考文件

适用场景

  1. 01设置严格的 tsconfig.json 选项
  2. 02描述连接状态与操作结果
  3. 03在运行时校验未知数据
  4. 04整理导入并避免循环依赖

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ghosttypes/ff-5mp-api-ts --skill typescript-best-practices

安装后在 Claude Code 中输入/typescript-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
error-handling.md
generics.md
import-export.md
interfaces-types.md
tsconfig.md
type-guards-assertions.md
unions-discriminated.md
utility-types.md

详细介绍

TypeScript 最佳实践

快速入门

始终启用严格模式，并为公共 API 使用显式类型。优先使用仅类型导入（import type）和命名导出，而不是默认导出。使用可辨识联合进行状态管理，并使用类型守卫进行运行时验证。

类型安全基础

严格模式配置

在 tsconfig.json 中启用所有严格标志：

{
  "strict": true,
  "noImplicitAny": true,
  "noImplicitReturns": true,
  "strictNullChecks": true,
  "strictFunctionTypes": true
}
空值安全
// Explicit null handling
export function findById<T>(items: Map<string, T>, id: string): T | null {
  return items.get(id) ?? null;
}

// Optional chaining and nullish coalescing
export function getName(item?: Item): string {
  return item?.name ?? 'Unknown';
}
显式返回类型

为公共 API 使用显式返回类型：

// Good
export function validateConfig(data: unknown): ValidatedConfig | null {
  const result = ConfigSchema.safeParse(data);
  return result.success ? result.data : null;
}

// Bad - implicit return type
export function validateConfig(data) {
  return data;
}

核心模式

用于状态的可辨识联合
export type ConnectionState =
  | { status: 'disconnected' }
  | { status: 'connecting'; progress: number }
  | { status: 'connected'; connectionId: string }
  | { status: 'error'; message: string };

// TypeScript knows which properties are available in each branch
用于错误处理的 Result 类型
export type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

const result = await connectToService(options);
if (result.success) {
  console.log('Connected:', result.data.id);
} else {
  console.error('Failed:', result.error.message);
}
只读属性

对不可变数据使用 readonly：

export interface Config {
  readonly enableFeature: boolean;
  readonly port: number;
}

类型守卫与断言

// Type guard
export function isUserData(data: unknown): data is UserData {
  return typeof data === 'object' && data !== null && 'name' in data;
}

// Assertion function
export function assertIsDefined<T>(value: T): asserts value is NonNullable<T> {
  if (value === undefined || value === null) throw new Error('Value is undefined or null');
}

导入/导出约定

// Type-only imports (preferred)
import type { Config } from '../types/config';

// Named exports (avoid default exports)
export class DataService {}
export const getService = () => DataService.getInstance();

// Grouped imports
import { External } from 'external';           // External deps
import { internalUtil } from './utils';         // Internal utils
import type { MyType } from './types';          // Types

何时使用参考文件

参考文件加载时机
tsconfig.md设置 TypeScript 配置
interfaces-types.md定义接口、泛型类型、扩展外部类型
unions-discriminated.md使用可辨识联合、Result 类型和穷尽性检查
type-guards-assertions.md运行时验证、品牌类型、断言函数
utility-types.md使用内置工具类型、const 断言和模板字面量类型
error-handling.md实现结构化错误、错误工厂和重试逻辑
generics.md构建泛型服务、仓库、工厂和事件发射器
import-export.md组织导入/导出、避免循环依赖

应避免的常见反模式

  1. 使用 any —— 改用 unknown 并配合类型守卫
  2. 默认导出 —— 更难重构和进行摇树优化
  3. 公共 API 使用隐式返回类型
  4. 不可变数据使用非只读接口
  5. 嵌套可选属性（{ a?: { b?: string } }）—— 改用可辨识联合

评论

支持 Markdown