TypeScript 实战与类型设计

// ❌ 入门：类型注解
type User = {
  id: string;
  name: string;
  loading: boolean;
  data: any; // ← any 起手
  error: any; // ← 又一个 any
};
 
// 使用方
function show(user: User) {
  if (user.loading) return "loading";
  if (user.error) return user.error;
  return user.data.name; // ← user.data 是 any，TS 帮不上忙
}

// ✅ 资深：类型设计
type UserState =
  | { status: "loading" }
  | { status: "error"; error: Error }
  | { status: "success"; user: { id: string; name: string } };
 
function show(state: UserState) {
  switch (state.status) {
    case "loading":
      return "loading";
    case "error":
      return state.error.message;
    case "success":
      return state.user.name; // ← 类型完全推断出来
  }
}

// 两者都能描述对象
type UserType = {
  name: string;
  age: number;
};
 
interface UserInterface {
  name: string;
  age: number;
}

// 1. 联合类型
type Status = "active" | "inactive";
 
// 2. 元组
type Pair = [string, number];
 
// 3. 字面量类型别名
type Direction = "up" | "down" | "left" | "right";
 
// 4. 计算属性 / 映射类型
type Readonly<T> = { readonly [K in keyof T]: T[K] };
 
// 5. 条件类型
type IsString<T> = T extends string ? true : false;

// 1. 声明合并（同名 interface 自动合并）
interface Window {
  customProperty: string;
}
interface Window {
  anotherProperty: number;
}
// 现在 Window 同时有 customProperty 和 anotherProperty
 
// 用途：扩展第三方库的全局类型
declare global {
  interface Window {
    myAppConfig: { theme: string };
  }
}
 
// type 不能这么做
type Window = { ... }; // ❌ 重复声明会报错

// 99% 的场景用 type
type User = {
  id: string;
  name: string;
};
 
type Status = "active" | "inactive";
 
// 仅当需要声明合并时用 interface
declare global {
  interface Window {
    config: AppConfig;
  }
}

// 对象描述用 interface
interface User {
  id: string;
  name: string;
}
 
// 联合 / 字面量 / 元组用 type
type Status = "active" | "inactive";
type Pair = [string, number];

// 你写的
enum Direction {
  Left = "left",
  Right = "right",
}
 
// TypeScript 编译为（有运行时代码）
var Direction;
(function (Direction) {
  Direction["Left"] = "left";
  Direction["Right"] = "right";
})(Direction || (Direction = {}));

enum Status {
  Pending, // 0
  Active, // 1
  Closed, // 2
}
 
function process(s: Status) {
  // ...
}
 
process(Status.Pending); // ✅
process(0); // ✅ 也合法！数字 enum 可以传任意 number
process(99); // ❌ 但传 99 也编译过——只在运行时才报错

// ✅ 替代 enum Direction { Left = 'left', Right = 'right' }
type Direction = "left" | "right";
 
function move(dir: Direction) {
  // ...
}
 
move("left"); // ✅
move("up"); // ❌ Type '"up"' is not assignable to type 'Direction'

// ✅ 替代有"运行时对象"需求的 enum
const Direction = {
  Left: "left",
  Right: "right",
} as const;
 
type Direction = (typeof Direction)[keyof typeof Direction];
// 'left' | 'right'
 
function move(dir: Direction) {
  // ...
}
 
move(Direction.Left); // ✅
move("left"); // ✅
move("up"); // ❌

const enum Direction {
  Left = "left",
  Right = "right",
}
 
// 编译后内联（零运行时）
move(Direction.Left); // 编译为 move('left')

反例：什么都可能 → 运行时检查
  ↓
正例：用类型限制可能 → 编译期保证

// ❌ 反例：所有字段都可空——业务约束消失
type UserState = {
  loading: boolean;
  error: string | null;
  data: User | null;
};
 
// 使用方
function show(state: UserState) {
  if (state.loading) {
    // 这里 error 和 data 还可能不是 null 吗？
    // TS 不知道，你也不知道
  }
}

// ✅ 正例：状态之间互斥
type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: User }
  | { status: 'error'; error: Error };
 
// 使用方
function show(state: UserState) {
  switch (state.status) {
    case 'idle':
      return null; // 不能访问 data / error
    case 'loading':
      return <Spinner />;
    case 'success':
      return <UserCard user={state.data} />; // ✅ 类型推断知道有 data
    case 'error':
      return <ErrorMsg error={state.error} />; // ✅ 类型推断知道有 error
  }
}

// ❌ 反例
type FormState = {
  values: Record<string, unknown>;
  errors: Record<string, string>;
  isSubmitting: boolean;
  isSubmitted: boolean;
  submitError: string | null;
};
 
// "isSubmitting + isSubmitted 同时为 true 应该不可能"——但类型不强制

// ✅ 正例
type FormState =
  | { phase: "editing"; values: Record<string, unknown>; errors: Record<string, string> }
  | { phase: "submitting"; values: Record<string, unknown> }
  | { phase: "success"; result: unknown }
  | { phase: "error"; values: Record<string, unknown>; submitError: string };

// ❌ 反例：把 success / error 都塞进同一个对象
type ApiResponse<T> = {
  ok: boolean;
  data?: T;
  error?: string;
};
 
// 使用方
async function fetchUser(): Promise<ApiResponse<User>> {
  // ...
}
 
const res = await fetchUser();
if (res.ok) {
  res.data?.name; // 还要 ?.！TS 不知道 ok=true 时 data 一定有
}

// ✅ 正例：用可辨识联合
type ApiResponse<T> = { ok: true; data: T } | { ok: false; error: string };
 
const res = await fetchUser();
if (res.ok) {
  res.data.name; // ✅ TS 知道 data 一定存在，不需要 ?.
} else {
  res.error; // ✅ TS 知道有 error
}

// ❌ 反例
type ButtonProps = {
  type: "button" | "link";
  href?: string;
  onClick?: () => void;
};
 
// 类型上"link 没 href 也合法"，"button 有 href 也合法"——业务约束丢失

// ✅ 正例
type ButtonProps = { type: "button"; onClick: () => void } | { type: "link"; href: string };
 
// 现在：
// type='button' 必须有 onClick
// type='link' 必须有 href
// 互不交叉

// ❌ 反例：假装它就是 User
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  const data = await res.json(); // any
  return data as User; // ❌ 谎报类型
}
 
// 使用方
const user = await fetchUser("123");
user.name.toUpperCase(); // 编译过——但如果后端返回的 name 是 null，运行时崩溃

import { z } from "zod";
 
// 1. 定义 schema
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  age: z.number().min(0).max(150),
  email: z.string().email().optional(),
});
 
// 2. 自动推导出 TS 类型
type User = z.infer<typeof UserSchema>;
// { id: string; name: string; age: number; email?: string }
 
// 3. 运行时验证
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  const data = await res.json();
 
  // parse 失败时抛错，成功时返回类型确定的对象
  return UserSchema.parse(data);
}
 
// 使用方
const user = await fetchUser("123");
user.name.toUpperCase(); // ✅ 真正安全——schema 已经验证过

const SignupSchema = z.object({
  email: z.string().email("请输入有效邮箱"),
  password: z.string().min(8, "密码至少 8 位"),
  age: z.number().min(13, "需要 13 岁以上").max(150),
  agree: z.literal(true, { errorMap: () => ({ message: "必须同意条款" }) }),
});
 
type SignupForm = z.infer<typeof SignupSchema>;
 
function handleSubmit(formData: unknown) {
  const result = SignupSchema.safeParse(formData);
 
  if (!result.success) {
    // result.error.issues 包含每个字段的错误
    return showErrors(result.error.issues);
  }
 
  // result.data 是类型安全的 SignupForm
  return submitToServer(result.data);
}

// ❌ 反例
const config = JSON.parse(localStorage.getItem("config") || "{}") as AppConfig;
// any → as → 假类型
 
// ✅ 正例
const ConfigSchema = z.object({
  theme: z.enum(["light", "dark"]),
  fontSize: z.number().min(10).max(30),
});
 
const raw = localStorage.getItem("config");
const config = raw ? ConfigSchema.parse(JSON.parse(raw)) : defaultConfig;

// ❌ 反例
const port = parseInt(process.env.PORT!); // 漏配置时 NaN
const apiKey = process.env.API_KEY!; // 漏配置时 undefined → 'undefined'
 
// ✅ 正例
const EnvSchema = z.object({
  PORT: z.coerce.number().min(1).max(65535),
  API_KEY: z.string().min(1),
  NODE_ENV: z.enum(["development", "production", "test"]),
});
 
export const env = EnvSchema.parse(process.env);
// 启动时如果环境变量缺失或类型错——立即抛错
// 之后访问 env.PORT / env.API_KEY 都是类型安全的

import * as v from "valibot";
 
const UserSchema = v.object({
  id: v.string(),
  name: v.string(),
});
 
type User = v.InferOutput<typeof UserSchema>;
const user = v.parse(UserSchema, data);

type UserId = string;
type ProductId = string;
 
function getUser(id: UserId) {
  /* ... */
}
function getProduct(id: ProductId) {
  /* ... */
}
 
const userId: UserId = "u_123";
const productId: ProductId = "p_456";
 
getUser(productId); // ❌ 应该报错，但 TS 不报——都是 string
getProduct(userId); // ❌ 同样不报

type Brand<T, B> = T & { readonly __brand: B };
 
type UserId = Brand<string, "UserId">;
type ProductId = Brand<string, "ProductId">;
 
// 工厂函数：把普通 string 提升为带 brand 的类型
function asUserId(id: string): UserId {
  return id as UserId;
}
 
function asProductId(id: string): ProductId {
  return id as ProductId;
}
 
const userId = asUserId("u_123");
const productId = asProductId("p_456");
 
function getUser(id: UserId) {
  /* ... */
}
function getProduct(id: ProductId) {
  /* ... */
}
 
getUser(userId); // ✅
getUser(productId); // ❌ Argument of type 'ProductId' is not assignable to parameter of type 'UserId'
getUser("u_123"); // ❌ 普通字符串也不行——必须经过 asUserId

import { z } from "zod";
 
const UserIdSchema = z.string().brand<"UserId">();
const ProductIdSchema = z.string().brand<"ProductId">();
 
type UserId = z.infer<typeof UserIdSchema>;
type ProductId = z.infer<typeof ProductIdSchema>;
 
const userId = UserIdSchema.parse("u_123"); // 同时验证 + 加 brand
const productId = ProductIdSchema.parse("p_456");

type SafeHtml = Brand<string, "SafeHtml">;
type RawHtml = string;
 
// 净化函数把 raw 提升为 safe
function sanitize(raw: RawHtml): SafeHtml {
  // 用 DOMPurify 等净化
  const clean = DOMPurify.sanitize(raw);
  return clean as SafeHtml;
}
 
// 渲染函数只接受已净化的
function renderHtml(html: SafeHtml) {
  document.body.innerHTML = html; // 安全
}
 
renderHtml(sanitize(userInput)); // ✅
renderHtml(userInput); // ❌ 类型错，强制走 sanitize

src/
├─ users/
│  ├─ User.tsx
│  ├─ User.types.ts      ← 与组件同目录
│  ├─ useUserData.ts
│  └─ ...
├─ products/
│  └─ ...

src/
├─ types/
│  ├─ user.ts
│  ├─ product.ts
│  └─ index.ts           ← 桶文件
├─ users/
└─ products/

// ❌ 普通 import
import { User } from "./types";
function fn(u: User) {
  /* ... */
}
 
// 编译后 import 仍在 bundle 里——但实际只用作类型，浪费 bundle

// ✅ import type
import type { User } from "./types";
function fn(u: User) {
  /* ... */
}
 
// 编译时被擦除——零运行时开销

// 一行同时导入类型和值
import { type User, fetchUser } from "./users";

// tsconfig.json
{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

// types/user.ts
 
// ✅ 导出类型
export type User = {
  id: string;
  name: string;
};
 
// ✅ 导出 schema（既是值也是类型）
import { z } from 'zod';
export const UserSchema = z.object({ ... });
export type User = z.infer<typeof UserSchema>;
 
// ❌ 不要导出"内部辅助类型"
type _Internal = { ... }; // 私有，不导出

// ❌ AI 生成
type State = {
  loading: boolean;
  error: string | null;
  data: User | null;
};
 
// ✅ 你应改为可辨识联合
type State =
  | { status: "loading" }
  | { status: "error"; error: string }
  | { status: "success"; data: User };

// ❌ AI 生成
async function fetchUser(): Promise<User> {
  const res = await fetch("/api/user");
  return res.json(); // any → 假装是 User
}
 
// ✅ 你应改为
async function fetchUser(): Promise<User> {
  const res = await fetch("/api/user");
  return UserSchema.parse(await res.json());
}

// ❌ AI 训练数据里很多老代码用 enum
enum Status {
  Pending,
  Active,
}
 
// ✅ 你应改为
type Status = "pending" | "active";
// 或
const Status = { Pending: "pending", Active: "active" } as const;

// ❌ 反例
const data: any = JSON.parse(input);
data.foo.bar; // 编译过但可能崩
 
// ✅ 正例
const data: unknown = JSON.parse(input);
const validated = MySchema.parse(data); // 真正验证

// ❌ 反例
const config: { theme: string } = { theme: "dark" };
config.theme; // string，不是 'dark'
 
// ✅ 正例
const config = { theme: "dark" } satisfies { theme: string };
config.theme; // 'dark'

const ResponseSchema = z.object({
  users: z.array(UserSchema),
});
 
const res = ResponseSchema.parse(await response.json());
// 后端字段变了 → parse 时立即报错（带详细信息）
// 而不是某个用户访问时神秘崩

type UserId = Brand<string, "UserId">;
type ProductId = Brand<string, "ProductId">;
 
getUser(productId); // ❌ 现在编译错

// ❌ 反例
enum Direction {
  Left,
  Right,
}
 
// ✅ 正例
type Direction = "left" | "right";

// ❌ 反例
import { User } from "./types";
 
// ✅ 正例
import type { User } from "./types";

function handle(state: State) {
  switch (state.status) {
    case 'loading': return ...;
    case 'success': return ...;
    case 'error': return ...;
    default:
      const _exhaustive: never = state;
      return _exhaustive;
  }
}

// 1. 先想清楚业务约束 → 写成类型
type CheckoutState =
  | { phase: "cart"; items: CartItem[] }
  | { phase: "shipping"; items: CartItem[]; address: Address }
  | { phase: "payment"; items: CartItem[]; address: Address; method: PaymentMethod }
  | { phase: "success"; orderId: OrderId };
 
// 2. 实现自然约束在类型里——payment 阶段必有 address，cart 阶段必无 orderId
function transition(state: CheckoutState, event: Event): CheckoutState {
  // ...
}