Back to Details

typescript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Const Types Pattern (REQUIRED)

常量类型模式（强制要求）

typescript
// ✅ ALWAYS: Create const object first, then extract type
const STATUS = {
  ACTIVE: "active",
  INACTIVE: "inactive",
  PENDING: "pending",
} as const;

type Status = (typeof STATUS)[keyof typeof STATUS];

// ❌ NEVER: Direct union types
type Status = "active" | "inactive" | "pending";
Why? Single source of truth, runtime values, autocomplete, easier refactoring.
typescript
// ✅ 始终遵循：先创建常量对象，再提取类型
const STATUS = {
  ACTIVE: "active",
  INACTIVE: "inactive",
  PENDING: "pending",
} as const;

type Status = (typeof STATUS)[keyof typeof STATUS];

// ❌ 禁止：直接使用联合类型
type Status = "active" | "inactive" | "pending";
原因？ 单一数据源、支持运行时值、自动补全、更易重构。

Flat Interfaces (REQUIRED)

扁平化接口（强制要求）

typescript
// ✅ ALWAYS: One level depth, nested objects → dedicated interface
interface UserAddress {
  street: string;
  city: string;
}

interface User {
  id: string;
  name: string;
  address: UserAddress;  // Reference, not inline
}

interface Admin extends User {
  permissions: string[];
}

// ❌ NEVER: Inline nested objects
interface User {
  address: { street: string; city: string };  // NO!
}
typescript
// ✅ 始终遵循：保持一级深度，嵌套对象需定义独立接口
interface UserAddress {
  street: string;
  city: string;
}

interface User {
  id: string;
  name: string;
  address: UserAddress;  // 引用独立接口，而非内联定义
}

interface Admin extends User {
  permissions: string[];
}

// ❌ 禁止：内联嵌套对象
interface User {
  address: { street: string; city: string };  // 不允许！
}

Never Use 
any

禁止使用
any
类型

typescript
// ✅ Use unknown for truly unknown types
function parse(input: unknown): User {
  if (isUser(input)) return input;
  throw new Error("Invalid input");
}

// ✅ Use generics for flexible types
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

// ❌ NEVER
function parse(input: any): any { }
typescript
// ✅ 对于真正未知的类型，使用unknown
function parse(input: unknown): User {
  if (isUser(input)) return input;
  throw new Error("Invalid input");
}

// ✅ 使用泛型实现灵活类型
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

// ❌ 禁止使用
function parse(input: any): any { }

Utility Types

工具类型

typescript
Pick<User, "id" | "name">     // Select fields
Omit<User, "id">              // Exclude fields
Partial<User>                 // All optional
Required<User>                // All required
Readonly<User>                // All readonly
Record<string, User>          // Object type
Extract<Union, "a" | "b">     // Extract from union
Exclude<Union, "a">           // Exclude from union
NonNullable<T | null>         // Remove null/undefined
ReturnType<typeof fn>         // Function return type
Parameters<typeof fn>         // Function params tuple
typescript
Pick<User, "id" | "name">     // 选择指定字段
Omit<User, "id">              // 排除指定字段
Partial<User>                 // 所有字段设为可选
Required<User>                // 所有字段设为必填
Readonly<User>                // 所有字段设为只读
Record<string, User>          // 对象类型定义
Extract<Union, "a" | "b">     // 从联合类型中提取指定类型
Exclude<Union, "a">           // 从联合类型中排除指定类型
NonNullable<T | null>         // 移除null/undefined类型
ReturnType<typeof fn>         // 获取函数返回类型
Parameters<typeof fn>         // 获取函数参数元组

Type Guards

类型守卫

typescript
function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value
  );
}
typescript
function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value
  );
}

Import Types

类型导入

typescript
import type { User } from "./types";
import { createUser, type Config } from "./utils";
typescript
import type { User } from "./types";
import { createUser, type Config } from "./utils";