Back to Details

typescript-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TypeScript Patterns

TypeScript 模式

Master TypeScript in React and React Router v7 applications. Learn how to create type-safe loaders, actions, components, and leverage TypeScript's power for better DX.
在 React 和 React Router v7 应用中掌握 TypeScript，学习如何创建类型安全的加载器、动作、组件，利用 TypeScript 的能力获得更好的开发者体验（DX）。

Quick Reference

快速参考

Type-Safe Loader

类型安全的加载器

typescript
export async function loader({ params }: LoaderFunctionArgs) {
  const user = await fetchUser(params.userId);
  return { user };
}

// In component
const { user } = useLoaderData<typeof loader>();
typescript
export async function loader({ params }: LoaderFunctionArgs) {
  const user = await fetchUser(params.userId);
  return { user };
}

// 在组件中
const { user } = useLoaderData<typeof loader>();

Type-Safe Action

类型安全的动作

typescript
export async function action({ request }: ActionFunctionArgs) {
  const data = await request.formData();
  return { success: true };
}

// In component
const actionData = useActionData<typeof action>();
typescript
export async function action({ request }: ActionFunctionArgs) {
  const data = await request.formData();
  return { success: true };
}

// 在组件中
const actionData = useActionData<typeof action>();

Generic Component

泛型组件

typescript
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

function List<T>({ items, renderItem }: ListProps<T>) {
  return <ul>{items.map(renderItem)}</ul>;
}
typescript
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

function List<T>({ items, renderItem }: ListProps<T>) {
  return <ul>{items.map(renderItem)}</ul>;
}

When to Use This Skill

适用场景

  • Setting up TypeScript in React Router project
  • Creating type-safe routes
  • Building reusable generic components
  • Defining API response types
  • Improving IDE autocomplete and error detection
  • Refactoring JavaScript to TypeScript
  • 在 React Router 项目中配置 TypeScript
  • 创建类型安全的路由
  • 构建可复用的泛型组件
  • 定义 API 响应类型
  • 提升 IDE 自动补全和错误检测能力
  • 将 JavaScript 重构为 TypeScript

Core TypeScript for React Router

React Router 核心 TypeScript 用法

1. Loader Types

1. 加载器类型

typescript
import type { LoaderFunctionArgs } from "react-router";

// Define return type interface
interface LoaderData {
  user: User;
  posts: Post[];
}

export async function loader({ 
  params, 
  request 
}: LoaderFunctionArgs): Promise<LoaderData> {
  const user = await fetchUser(params.userId);
  const posts = await fetchPosts(params.userId);
  
  return { user, posts };
}

// Type-safe component
export default function Profile() {
  const { user, posts } = useLoaderData<typeof loader>();
  //    ^? { user: User; posts: Post[] }
  
  return (
    <div>
      <h1>{user.name}</h1>
      {posts.map(post => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  );
}
typescript
import type { LoaderFunctionArgs } from "react-router";

// 定义返回类型接口
interface LoaderData {
  user: User;
  posts: Post[];
}

export async function loader({ 
  params, 
  request 
}: LoaderFunctionArgs): Promise<LoaderData> {
  const user = await fetchUser(params.userId);
  const posts = await fetchPosts(params.userId);
  
  return { user, posts };
}

// 类型安全的组件
export default function Profile() {
  const { user, posts } = useLoaderData<typeof loader>();
  //    ^? { user: User; posts: Post[] }
  
  return (
    <div>
      <h1>{user.name}</h1>
      {posts.map(post => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  );
}

2. Action Types

2. 动作类型

typescript
import type { ActionFunctionArgs } from "react-router";

// Define action response types
type ActionSuccess = {
  success: true;
  user: User;
};

type ActionError = {
  success: false;
  errors: Record<string, string[]>;
};

type ActionData = ActionSuccess | ActionError;

export async function action({ 
  request 
}: ActionFunctionArgs): Promise<ActionData> {
  const formData = await request.formData();
  
  // Validation...
  if (hasErrors) {
    return {
      success: false,
      errors: { email: ["Invalid email"] }
    };
  }
  
  const user = await createUser(formData);
  return { success: true, user };
}

// Type-safe component
export default function CreateUser() {
  const actionData = useActionData<typeof action>();
  
  if (actionData?.success === false) {
    // TypeScript knows this is ActionError
    return <div>{actionData.errors.email}</div>;
  }
  
  if (actionData?.success === true) {
    // TypeScript knows this is ActionSuccess
    return <div>Created {actionData.user.name}</div>;
  }
  
  return <Form method="post">{/* ... */}</Form>;
}
typescript
import type { ActionFunctionArgs } from "react-router";

// 定义动作响应类型
type ActionSuccess = {
  success: true;
  user: User;
};

type ActionError = {
  success: false;
  errors: Record<string, string[]>;
};

type ActionData = ActionSuccess | ActionError;

export async function action({ 
  request 
}: ActionFunctionArgs): Promise<ActionData> {
  const formData = await request.formData();
  
  // 校验逻辑...
  if (hasErrors) {
    return {
      success: false,
      errors: { email: ["无效的邮箱地址"] }
    };
  }
  
  const user = await createUser(formData);
  return { success: true, user };
}

// 类型安全的组件
export default function CreateUser() {
  const actionData = useActionData<typeof action>();
  
  if (actionData?.success === false) {
    // TypeScript 会自动识别当前为 ActionError 类型
    return <div>{actionData.errors.email}</div>;
  }
  
  if (actionData?.success === true) {
    // TypeScript 会自动识别当前为 ActionSuccess 类型
    return <div>已创建 {actionData.user.name}</div>;
  }
  
  return <Form method="post">{/* ... */}</Form>;
}

3. Params Typing

3. 参数类型定义

typescript
import type { LoaderFunctionArgs, Params } from "react-router";

// Define expected params
interface RouteParams extends Params {
  userId: string;
  postId: string;
}

export async function loader({ params }: LoaderFunctionArgs) {
  // Type assertion for strict checking
  const { userId, postId } = params as RouteParams;
  
  return { userId, postId };
}

// Alternative: Runtime validation + type safety
import { z } from "zod";

const paramsSchema = z.object({
  userId: z.string(),
  postId: z.string(),
});

export async function loader({ params }: LoaderFunctionArgs) {
  const { userId, postId } = paramsSchema.parse(params);
  //    ^? { userId: string; postId: string }
  
  return { userId, postId };
}
typescript
import type { LoaderFunctionArgs, Params } from "react-router";

// 定义预期的参数
interface RouteParams extends Params {
  userId: string;
  postId: string;
}

export async function loader({ params }: LoaderFunctionArgs) {
  // 类型断言实现严格校验
  const { userId, postId } = params as RouteParams;
  
  return { userId, postId };
}

// 替代方案：运行时校验 + 类型安全
import { z } from "zod";

const paramsSchema = z.object({
  userId: z.string(),
  postId: z.string(),
});

export async function loader({ params }: LoaderFunctionArgs) {
  const { userId, postId } = paramsSchema.parse(params);
  //    ^? { userId: string; postId: string }
  
  return { userId, postId };
}

4. Zod Integration

4. Zod 集成

typescript
import { z } from "zod";

// Define schema
const createUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().positive(),
});

// Infer TypeScript type from schema
type CreateUserInput = z.infer<typeof createUserSchema>;
//   ^? { name: string; email: string; age: number }

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  
  const result = createUserSchema.safeParse({
    name: formData.get("name"),
    email: formData.get("email"),
    age: Number(formData.get("age")),
  });
  
  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors,
    };
  }
  
  // result.data is fully typed as CreateUserInput
  const user = await createUser(result.data);
  
  return { user };
}
typescript
import { z } from "zod";

// 定义校验 schema
const createUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().positive(),
});

// 从 schema 推导 TypeScript 类型
type CreateUserInput = z.infer<typeof createUserSchema>;
//   ^? { name: string; email: string; age: number }

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  
  const result = createUserSchema.safeParse({
    name: formData.get("name"),
    email: formData.get("email"),
    age: Number(formData.get("age")),
  });
  
  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors,
    };
  }
  
  // result.data 已经完全被推导为 CreateUserInput 类型
  const user = await createUser(result.data);
  
  return { user };
}

React Component Patterns

React 组件模式

1. Props Interface

1. Props 接口定义

typescript
// Define props clearly
interface ButtonProps {
  children: React.ReactNode;
  onClick: () => void;
  variant?: "primary" | "secondary";
  disabled?: boolean;
}

export function Button({ 
  children, 
  onClick, 
  variant = "primary",
  disabled = false 
}: ButtonProps) {
  return (
    <button 
      onClick={onClick} 
      disabled={disabled}
      className={`btn-${variant}`}
    >
      {children}
    </button>
  );
}
typescript
// 清晰定义 props
interface ButtonProps {
  children: React.ReactNode;
  onClick: () => void;
  variant?: "primary" | "secondary";
  disabled?: boolean;
}

export function Button({ 
  children, 
  onClick, 
  variant = "primary",
  disabled = false 
}: ButtonProps) {
  return (
    <button 
      onClick={onClick} 
      disabled={disabled}
      className={`btn-${variant}`}
    >
      {children}
    </button>
  );
}

2. Generic Components

2. 泛型组件

typescript
// Generic list component
interface ListProps<T> {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  keyExtractor: (item: T) => string | number;
}

export function List<T>({ 
  items, 
  renderItem, 
  keyExtractor 
}: ListProps<T>) {
  return (
    <ul>
      {items.map((item, index) => (
        <li key={keyExtractor(item)}>
          {renderItem(item, index)}
        </li>
      ))}
    </ul>
  );
}

// Usage with type inference
<List
  items={users}  // users: User[]
  renderItem={(user) => <span>{user.name}</span>}
  //          ^? user: User (inferred!)
  keyExtractor={(user) => user.id}
/>
typescript
// 泛型列表组件
interface ListProps<T> {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  keyExtractor: (item: T) => string | number;
}

export function List<T>({ 
  items, 
  renderItem, 
  keyExtractor 
}: ListProps<T>) {
  return (
    <ul>
      {items.map((item, index) => (
        <li key={keyExtractor(item)}>
          {renderItem(item, index)}
        </li>
      ))}
    </ul>
  );
}

// 支持类型推导的使用方式
<List
  items={users}  // users: User[]
  renderItem={(user) => <span>{user.name}</span>}
  //          ^? user: User (自动推导！)
  keyExtractor={(user) => user.id}
/>

3. Event Handlers

3. 事件处理器

typescript
interface FormProps {
  onSubmit: (data: FormData) => void;
}

export function Form({ onSubmit }: FormProps) {
  // Properly typed event handler
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    onSubmit(formData);
  };
  
  // Properly typed input handler
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    console.log(e.target.value);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <input onChange={handleChange} />
    </form>
  );
}
typescript
interface FormProps {
  onSubmit: (data: FormData) => void;
}

export function Form({ onSubmit }: FormProps) {
  // 类型正确的事件处理器
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    onSubmit(formData);
  };
  
  // 类型正确的输入框事件处理器
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    console.log(e.target.value);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <input onChange={handleChange} />
    </form>
  );
}

4. Forwarding Refs

4. Ref 转发

typescript
import { forwardRef } from "react";

interface InputProps {
  label: string;
  error?: string;
}

// Properly typed ref forwarding
export const Input = forwardRef<HTMLInputElement, InputProps>(
  ({ label, error }, ref) => {
    return (
      <div>
        <label>{label}</label>
        <input ref={ref} />
        {error && <span>{error}</span>}
      </div>
    );
  }
);

Input.displayName = "Input";
typescript
import { forwardRef } from "react";

interface InputProps {
  label: string;
  error?: string;
}

// 类型正确的 ref 转发
export const Input = forwardRef<HTMLInputElement, InputProps>(
  ({ label, error }, ref) => {
    return (
      <div>
        <label>{label}</label>
        <input ref={ref} />
        {error && <span>{error}</span>}
      </div>
    );
  }
);

Input.displayName = "Input";

5. Children Patterns

5. Children 模式

typescript
// Accept any valid React children
interface ContainerProps {
  children: React.ReactNode;
}

// Accept only specific component types
interface TabsProps {
  children: React.ReactElement<TabProps> | React.ReactElement<TabProps>[];
}

// Accept render prop
interface DataProviderProps<T> {
  data: T;
  children: (data: T) => React.ReactNode;
}

export function DataProvider<T>({ data, children }: DataProviderProps<T>) {
  return <>{children(data)}</>;
}
typescript
// 接受任意合法的 React children
interface ContainerProps {
  children: React.ReactNode;
}

// 仅接受特定类型的组件
interface TabsProps {
  children: React.ReactElement<TabProps> | React.ReactElement<TabProps>[];
}

// 接受 render prop
interface DataProviderProps<T> {
  data: T;
  children: (data: T) => React.ReactNode;
}

export function DataProvider<T>({ data, children }: DataProviderProps<T>) {
  return <>{children(data)}</>;
}

Advanced Patterns

进阶模式

1. Discriminated Unions

1. 可辨识联合类型

typescript
// Define mutually exclusive states
type LoadingState = 
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: User }
  | { status: "error"; error: string };

function UserProfile() {
  const [state, setState] = useState<LoadingState>({ 
    status: "idle" 
  });
  
  // TypeScript narrows type based on status
  switch (state.status) {
    case "idle":
      return <div>Click to load</div>;
      
    case "loading":
      return <div>Loading...</div>;
      
    case "success":
      // TypeScript knows state.data exists here
      return <div>{state.data.name}</div>;
      
    case "error":
      // TypeScript knows state.error exists here
      return <div>Error: {state.error}</div>;
  }
}
typescript
// 定义互斥的状态
type LoadingState = 
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: User }
  | { status: "error"; error: string };

function UserProfile() {
  const [state, setState] = useState<LoadingState>({ 
    status: "idle" 
  });
  
  // TypeScript 会根据 status 自动缩小类型范围
  switch (state.status) {
    case "idle":
      return <div>点击加载</div>;
      
    case "loading":
      return <div>加载中...</div>;
      
    case "success":
      // TypeScript 知道此处 state.data 一定存在
      return <div>{state.data.name}</div>;
      
    case "error":
      // TypeScript 知道此处 state.error 一定存在
      return <div>错误：{state.error}</div>;
  }
}

2. Type Guards

2. 类型守卫

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

// Usage
const data: unknown = await response.json();

if (isUser(data)) {
  // TypeScript knows data is User here
  console.log(data.name);
}
typescript
// 自定义类型守卫
function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value
  );
}

// 使用示例
const data: unknown = await response.json();

if (isUser(data)) {
  // TypeScript 知道此处 data 是 User 类型
  console.log(data.name);
}

3. Utility Types

3. 工具类型

typescript
// Pick specific properties
type UserPreview = Pick<User, "id" | "name" | "avatar">;

// Omit properties
type UserWithoutPassword = Omit<User, "password">;

// Make all properties optional
type PartialUser = Partial<User>;

// Make all properties required
type RequiredUser = Required<User>;

// Make all properties readonly
type ReadonlyUser = Readonly<User>;

// Extract keys of certain type
type StringKeys<T> = {
  [K in keyof T]: T[K] extends string ? K : never;
}[keyof T];

type UserStringFields = StringKeys<User>;
//   ^? "name" | "email" | "bio"
typescript
// 选取特定属性
type UserPreview = Pick<User, "id" | "name" | "avatar">;

// 排除特定属性
type UserWithoutPassword = Omit<User, "password">;

// 把所有属性设为可选
type PartialUser = Partial<User>;

// 把所有属性设为必填
type RequiredUser = Required<User>;

// 把所有属性设为只读
type ReadonlyUser = Readonly<User>;

// 提取特定类型的键
type StringKeys<T> = {
  [K in keyof T]: T[K] extends string ? K : never;
}[keyof T];

type UserStringFields = StringKeys<User>;
//   ^? "name" | "email" | "bio"

4. Mapped Types

4. 映射类型

typescript
// Create form state from model
type FormState<T> = {
  [K in keyof T]: {
    value: T[K];
    error?: string;
    touched: boolean;
  };
};

type UserFormState = FormState<User>;
// {
//   name: { value: string; error?: string; touched: boolean }
//   email: { value: string; error?: string; touched: boolean }
//   ...
// }
typescript
// 从模型创建表单状态
type FormState<T> = {
  [K in keyof T]: {
    value: T[K];
    error?: string;
    touched: boolean;
  };
};

type UserFormState = FormState<User>;
// {
//   name: { value: string; error?: string; touched: boolean }
//   email: { value: string; error?: string; touched: boolean }
//   ...
// }

5. Conditional Types

5. 条件类型

typescript
// Different return type based on input
type LoaderReturn<T extends boolean> = 
  T extends true 
    ? Promise<Response> 
    : Response;

function createLoader<T extends boolean>(
  async: T
): LoaderReturn<T> {
  // Implementation
  return null as any;
}

const syncLoader = createLoader(false);
//    ^? Response

const asyncLoader = createLoader(true);
//    ^? Promise<Response>
typescript
// 根据输入返回不同的类型
type LoaderReturn<T extends boolean> = 
  T extends true 
    ? Promise<Response> 
    : Response;

function createLoader<T extends boolean>(
  async: T
): LoaderReturn<T> {
  // 实现逻辑
  return null as any;
}

const syncLoader = createLoader(false);
//    ^? Response

const asyncLoader = createLoader(true);
//    ^? Promise<Response>

API Response Typing

API 响应类型定义

1. Domain Model Pattern

1. 领域模型模式

typescript
// API response type (snake_case)
interface UserAPI {
  user_id: string;
  full_name: string;
  email_address: string;
  created_at: string;
}

// Domain model (camelCase)
interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

// Transformation functions
export const User = {
  fromAPI(data: UserAPI): User {
    return {
      id: data.user_id,
      name: data.full_name,
      email: data.email_address,
      createdAt: new Date(data.created_at),
    };
  },
  
  toAPI(user: User): UserAPI {
    return {
      user_id: user.id,
      full_name: user.name,
      email_address: user.email,
      created_at: user.createdAt.toISOString(),
    };
  },
};

// Usage in loader
export async function loader() {
  const response = await fetch("/api/users");
  const data: UserAPI = await response.json();
  const user = User.fromAPI(data);
  
  return { user };
}
typescript
// API 响应类型（snake_case 命名）
interface UserAPI {
  user_id: string;
  full_name: string;
  email_address: string;
  created_at: string;
}

// 领域模型（camelCase 命名）
interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

// 转换函数
export const User = {
  fromAPI(data: UserAPI): User {
    return {
      id: data.user_id,
      name: data.full_name,
      email: data.email_address,
      createdAt: new Date(data.created_at),
    };
  },
  
  toAPI(user: User): UserAPI {
    return {
      user_id: user.id,
      full_name: user.name,
      email_address: user.email,
      created_at: user.createdAt.toISOString(),
    };
  },
};

// 在加载器中使用
export async function loader() {
  const response = await fetch("/api/users");
  const data: UserAPI = await response.json();
  const user = User.fromAPI(data);
  
  return { user };
}

2. Generic API Client

2. 泛型 API 客户端

typescript
// Generic fetch function with type safety
async function apiCall<T>(
  url: string, 
  options?: RequestInit
): Promise<T> {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  
  return response.json();
}

// Usage
const user = await apiCall<User>("/api/users/123");
//    ^? User

const posts = await apiCall<Post[]>("/api/posts");
//    ^? Post[]
typescript
// 类型安全的通用 fetch 函数
async function apiCall<T>(
  url: string, 
  options?: RequestInit
): Promise<T> {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    throw new Error(`API 错误：${response.status}`);
  }
  
  return response.json();
}

// 使用示例
const user = await apiCall<User>("/api/users/123");
//    ^? User

const posts = await apiCall<Post[]>("/api/posts");
//    ^? Post[]

Common Issues

常见问题

Issue 1: Type 'any' Errors

问题 1：类型 'any' 错误

Symptoms: TypeScript complains about implicit any Cause: Missing type annotations Solution: Add explicit types
typescript
// ❌ Implicit any
function processData(data) {
  return data.map(item => item.value);
}

// ✅ Explicit types
function processData(data: DataItem[]): number[] {
  return data.map(item => item.value);
}
症状：TypeScript 提示隐式 any 错误 原因：缺少类型注解 解决方案：添加显式类型
typescript
// ❌ 隐式 any
function processData(data) {
  return data.map(item => item.value);
}

// ✅ 显式类型
function processData(data: DataItem[]): number[] {
  return data.map(item => item.value);
}

Issue 2: Type Assertion Overuse

问题 2：类型断言滥用

Symptoms: Many 
as
casts in code Cause: Fighting TypeScript instead of fixing types Solution: Define proper types
typescript
// ❌ Too many assertions
const user = data as User;
const name = user.name as string;

// ✅ Proper typing
interface ApiResponse {
  data: User;
}

const response: ApiResponse = await fetch(...);
const user = response.data;
const name = user.name;
症状：代码中存在大量 
as
类型转换 原因：没有正确定义类型，强行绕过 TypeScript 校验 解决方案：定义合理的类型
typescript
// ❌ 过多的类型断言
const user = data as User;
const name = user.name as string;

// ✅ 合理的类型定义
interface ApiResponse {
  data: User;
}

const response: ApiResponse = await fetch(...);
const user = response.data;
const name = user.name;

Issue 3: Overly Complex Types

问题 3：类型过于复杂

Symptoms: Unreadable type definitions Cause: Trying to be too clever Solution: Simplify and document
typescript
// ❌ Too complex
type ComplexType<T, U extends keyof T> = {
  [K in U]: T[K] extends object ? Readonly<T[K]> : T[K]
};

// ✅ Simpler and clearer
type UserFields = Pick<User, "name" | "email">;
症状：类型定义难以阅读 原因：过度追求技巧性实现 解决方案：简化并添加注释
typescript
// ❌ 过于复杂
type ComplexType<T, U extends keyof T> = {
  [K in U]: T[K] extends object ? Readonly<T[K]> : T[K]
};

// ✅ 更简单清晰的实现
type UserFields = Pick<User, "name" | "email">;

Best Practices

最佳实践

  • Enable strict mode in tsconfig.json
  • Use 
    typeof loader
    for type inference
  • Define interfaces for all props
  • Use Zod for runtime validation + type inference
  • Create domain models with fromAPI/toAPI
  • Use discriminated unions for states
  • Avoid 
    any
    - use 
    unknown
    instead
  • Prefer interfaces over type aliases for objects
  • Use generic components for reusability
  • Document complex types with comments
  • 在 tsconfig.json 中开启严格模式
  • 使用 
    typeof loader
    实现类型推导
  • 为所有 props 定义接口
  • 使用 Zod 实现运行时校验 + 类型推导
  • 创建带 fromAPI/toAPI 方法的领域模型
  • 使用可辨识联合类型定义状态
  • 避免使用 
    any
    ，优先使用 
    unknown
  • 对象类型优先使用 interface 而非 type 别名
  • 使用泛型组件提升复用性
  • 为复杂类型添加注释说明

Anti-Patterns

反模式

Things to avoid:
  • ❌ Using 
    any
    everywhere
  • ❌ Type assertions without validation (
    as User
    )
  • ❌ Disabling TypeScript errors with 
    @ts-ignore
  • ❌ Not typing function parameters
  • ❌ Overly complex generic types
  • ❌ Duplicating types instead of reusing
  • ❌ Not using discriminated unions for state
  • ❌ Mixing runtime and type-only imports
需要避免的行为：
  • ❌ 随处使用 
    any
  • ❌ 没有校验就直接使用类型断言（
    as User
    ）
  • ❌ 使用 
    @ts-ignore
    禁用 TypeScript 错误
  • ❌ 不为函数参数定义类型
  • ❌ 定义过度复杂的泛型类型
  • ❌ 重复定义类型而不进行复用
  • ❌ 状态定义不使用可辨识联合类型
  • ❌ 混淆运行时导入和类型-only 导入

tsconfig.json Setup

tsconfig.json 配置

json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    
    // Strict type checking
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    
    // React
    "jsx": "react-jsx",
    "jsxImportSource": "react",
    
    // Module resolution
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    
    // Output
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}
json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    
    // 严格类型校验
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    
    // React 配置
    "jsx": "react-jsx",
    "jsxImportSource": "react",
    
    // 模块解析配置
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    
    // 输出配置
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

References

参考资料