TypeScript 类型系统

// 原始类型
let name: string = "Alice";
let age: number = 30;
let active: boolean = true;
let nothing: null = null;
let undef: undefined = undefined;
 
// BigInt / Symbol（很少用，知道存在即可）
let big: bigint = 100n;
let sym: symbol = Symbol("id");

// ❌ 多余的注解
let name: string = "Alice";
 
// ✅ 让 TS 推断
let name = "Alice"; // TS 推断为 string

// 数组：所有元素同类型
let nums: number[] = [1, 2, 3];
let nums2: Array<number> = [1, 2, 3]; // 等价
 
// 只读数组
let frozen: readonly number[] = [1, 2, 3];
 
// 元组：固定长度 + 每个位置固定类型
let pair: [string, number] = ["Alice", 30];
let triple: [string, number, boolean] = ["Bob", 25, true];
 
// 可选元组元素（?）
let coord: [number, number, number?] = [10, 20]; // z 可选
 
// 剩余元素
let strings: [string, ...string[]] = ["first", "second", "third"];

// 内联对象类型
let user: { name: string; age: number } = {
  name: "Alice",
  age: 30,
};
 
// 提取为 type 别名
type User = {
  name: string;
  age: number;
};
 
let user: User = { name: "Alice", age: 30 };
 
// 用 interface（与 type 几乎等价，§4.6 详解差异）
interface User {
  name: string;
  age: number;
}
 
// 可选属性（?）
type Config = {
  host: string;
  port?: number; // 可选
};
 
// 只读属性
type Point = {
  readonly x: number;
  readonly y: number;
};

// 基础注解
function greet(name: string): string {
  return `Hello, ${name}`;
}
 
// 箭头函数
const greet = (name: string): string => `Hello, ${name}`;
 
// 函数类型表达式
type Greeter = (name: string) => string;
const greet: Greeter = (name) => `Hello, ${name}`;
 
// 可选参数
function log(message: string, level?: string) {
  // level 是 string | undefined
}
 
// 默认参数（推断为 string）
function log(message: string, level = "info") {
  // level 是 string
}
 
// 剩余参数
function sum(...nums: number[]): number {
  return nums.reduce((a, b) => a + b, 0);
}
 
// 函数重载
function format(value: string): string;
function format(value: number): string;
function format(value: string | number): string {
  return String(value);
}

// 字符串字面量
let direction: "left" | "right" = "left";
direction = "up"; // ❌ Error: '"up"' is not assignable to type '"left" | "right"'
 
// 数字字面量
let dice: 1 | 2 | 3 | 4 | 5 | 6 = 1;
 
// 布尔字面量（少见）
let flag: true = true;

// ❌ 旧写法：用 enum
enum Direction {
  Left = "left",
  Right = "right",
}
 
function move(dir: Direction) {
  /* ... */
}
move(Direction.Left);
 
// ✅ 现代写法：字面量联合
type Direction = "left" | "right";
 
function move(dir: Direction) {
  /* ... */
}
move("left"); // 直接传字符串

type Point = { x: number; y: number };
type Coord = { x: number; y: number };
 
const p: Point = { x: 1, y: 2 };
const c: Coord = p; // ✅ 完全合法——两个类型形状相同
 
// 即使是匿名对象类型也行
const fn = (point: { x: number; y: number }) => point.x + point.y;
fn(p); // ✅ 合法
fn({ x: 5, y: 10 }); // ✅ 合法（字面量也匹配）

type User = { name: string; age: number };
 
// ✅ 正常：通过中间变量
const data = { name: "Alice", age: 30, role: "admin" };
const user: User = data; // 没问题
 
// ❌ 反例：直接传字面量
const user: User = { name: "Alice", age: 30, role: "admin" };
// Error: 'role' does not exist in type 'User'

// 1. 先存到变量
const data = { name: "Alice", age: 30, role: "admin" };
const user: User = data;
 
// 2. 类型断言
const user = { name: "Alice", age: 30, role: "admin" } as User;
 
// 3. 索引签名（接受任意附加属性）
type UserExtended = User & { [key: string]: unknown };

type Animal = { name: string };
type Dog = { name: string; breed: string };
 
// 函数参数：父类型函数能赋给子类型函数（逆变）
type AnimalHandler = (a: Animal) => void;
type DogHandler = (d: Dog) => void;
 
const handleAnimal: AnimalHandler = (a) => console.log(a.name);
const handleDog: DogHandler = handleAnimal; // ✅ 合法——AnimalHandler 接受 Animal，肯定也接受 Dog
 
const handleAnimalFromDog: AnimalHandler = handleDog; // ❌ 通常不合法（严格模式下）
// DogHandler 期望 Dog，传 Animal 会缺 breed

// 不需要显式 implements
interface Quacker {
  quack(): void;
}
 
class Duck {
  quack() {
    console.log("quack!");
  }
}
 
class Person {
  quack() {
    console.log("I am pretending to be a duck");
  }
}
 
function makeQuack(x: Quacker) {
  x.quack();
}
 
makeQuack(new Duck()); // ✅
makeQuack(new Person()); // ✅ —— 形状匹配，TS 不在意是不是 Duck

const greeting = "hello";
// 推断为字面量类型 'hello'
 
let greeting = "hello";
// 推断为 string（因为可以重新赋值）

function format(x: string | number): string {
  if (typeof x === "string") {
    // 这里 x 是 string
    return x.toUpperCase();
  } else {
    // 这里 x 是 number
    return x.toFixed(2);
  }
}

class Dog {
  bark() {
    console.log("woof");
  }
}
 
class Cat {
  meow() {
    console.log("meow");
  }
}
 
function makeSound(animal: Dog | Cat) {
  if (animal instanceof Dog) {
    animal.bark(); // 这里 animal 是 Dog
  } else {
    animal.meow(); // 这里 animal 是 Cat
  }
}

type Bird = { fly: () => void };
type Fish = { swim: () => void };
 
function move(animal: Bird | Fish) {
  if ("fly" in animal) {
    animal.fly(); // 这里 animal 是 Bird
  } else {
    animal.swim(); // 这里 animal 是 Fish
  }
}

type User = { id: number; name: string };
 
function isUser(x: unknown): x is User {
  return (
    typeof x === "object" &&
    x !== null &&
    "id" in x &&
    typeof (x as User).id === "number" &&
    "name" in x &&
    typeof (x as User).name === "string"
  );
}
 
const data: unknown = JSON.parse(input);
 
if (isUser(data)) {
  data.name; // 这里 data 是 User
}

type Result =
  | { status: "success"; data: User }
  | { status: "error"; error: string }
  | { status: "loading" };
 
function handle(result: Result) {
  switch (result.status) {
    case "success":
      console.log(result.data); // 这里 result 是 success 分支
      break;
    case "error":
      console.log(result.error); // 这里 result 是 error 分支
      break;
    case "loading":
      console.log("loading...");
      break;
  }
}

type Action =
  | { type: "INCREMENT"; payload: number }
  | { type: "DECREMENT"; payload: number }
  | { type: "RESET" };
 
function reducer(state: number, action: Action) {
  switch (action.type) {
    case "INCREMENT":
      return state + action.payload;
    case "DECREMENT":
      return state - action.payload;
    case "RESET":
      return 0; // RESET 没 payload，TS 不会让你访问
  }
}

function reducer(state: number, action: Action) {
  switch (action.type) {
    case "INCREMENT":
      return state + action.payload;
    case "DECREMENT":
      return state - action.payload;
    case "RESET":
      return 0;
    default:
      // 如果 switch 没穷尽所有情况，这里 action 不是 never
      // TS 会报错
      const exhaustive: never = action;
      return state;
  }
}
 
// 加新 action 但忘了处理时：
type Action =
  | { type: "INCREMENT"; payload: number }
  | { type: "DECREMENT"; payload: number }
  | { type: "RESET" }
  | { type: "MULTIPLY"; payload: number }; // 新加的
 
// reducer 里 default 分支会报错：
// Type '{ type: "MULTIPLY"; payload: number; }' is not assignable to type 'never'

let x: any = JSON.parse(input);
x.foo.bar; // ✅ 编译通过——但运行时可能崩溃
 
let y: unknown = JSON.parse(input);
y.foo.bar; // ❌ 编译错误——必须先收窄
 
if (typeof y === "object" && y !== null && "foo" in y) {
  // 现在可以安全访问
}

function throwError(message: string): never {
  throw new Error(message);
}
 
function fail(): never {
  while (true) {
    // 无限循环
  }
}

type Status = "active" | "inactive" | "pending";
type ID = string | number;
 
function format(id: ID): string {
  // id 可以是 string 或 number
  return String(id);
}

type StringOrNumber = string | number;
 
const x: StringOrNumber = "hello"; // ✅
const y: StringOrNumber = 42; // ✅
const z: StringOrNumber = true; // ❌

type Animal = { name: string; age: number };
type Vehicle = { name: string; wheels: number };
 
type AnimalOrVehicle = Animal | Vehicle;
 
function show(x: AnimalOrVehicle) {
  console.log(x.name); // ✅ 两个都有
  console.log(x.age); // ❌ Vehicle 没有
  console.log(x.wheels); // ❌ Animal 没有
}

type Animal = { name: string; age: number };
type Pet = { owner: string };
 
type PetAnimal = Animal & Pet;
// { name: string; age: number; owner: string }
 
const dog: PetAnimal = {
  name: "Rex",
  age: 5,
  owner: "Alice",
};

type A = { x: number };
type B = { y: number };
type C = { z: number };
 
type ABC = A & B & C;
// { x: number; y: number; z: number }

type Cat = { meow: () => void; purr: () => void };
type Dog = { bark: () => void; wagTail: () => void };
 
// 联合：可能是 Cat 也可能是 Dog，只能调用两者都有的方法（这里没有，所以啥都不能调）
type Pet = Cat | Dog;
const p: Pet = ...;
p.meow(); // ❌
 
// 交叉：既是 Cat 又是 Dog（一只能 meow 又能 bark 的怪兽）
type CatDog = Cat & Dog;
const cd: CatDog = ...;
cd.meow();    // ✅
cd.bark();    // ✅
cd.purr();    // ✅
cd.wagTail(); // ✅

type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };
 
function useUser(id: string) {
  const [state, setState] = useState<AsyncState<User>>({ status: 'idle' });
 
  // ...
 
  return state;
}
 
// 使用方
const state = useUser('123');
 
if (state.status === 'loading') return <Loading />;
if (state.status === 'error') return <Error error={state.error} />;
if (state.status === 'success') return <UserCard user={state.data} />;
return null; // idle

// 泛型函数
function identity<T>(value: T): T {
  return value;
}
 
identity<string>("hello"); // 显式传 T = string
identity("hello"); // 让 TS 推断 T = 'hello'
identity(42); // T = 42

// ❌ 反例：用 any，类型信息丢失
function identity(value: any): any {
  return value;
}
 
const x = identity("hello"); // x 是 any
x.foo; // ✅ 编译通过（但运行时崩溃）
 
// ✅ 正例：用泛型，类型保留
function identity<T>(value: T): T {
  return value;
}
 
const y = identity("hello"); // y 是 'hello'
y.foo; // ❌ 编译错误

function len<T>(value: T) {
  return value.length; // ❌ T 可能没 length
}

function len<T extends { length: number }>(value: T): number {
  return value.length;
}
 
len("hello"); // ✅ string 有 length
len([1, 2, 3]); // ✅ 数组有 length
len({ length: 10 }); // ✅ 对象有 length
len(42); // ❌ number 没有 length

function createState<T = string>(initial: T): T {
  return initial;
}
 
createState("hello"); // T 推断为 string
createState<number>(42); // T 显式为 number
createState(); // ❌ initial 是必传

// 泛型类
class Box<T> {
  constructor(public value: T) {}
 
  get(): T {
    return this.value;
  }
}
 
const box = new Box<number>(42);
box.get(); // number
 
// 泛型接口
interface Repository<T> {
  findById(id: string): Promise<T>;
  save(entity: T): Promise<void>;
}
 
class UserRepo implements Repository<User> {
  async findById(id: string): Promise<User> {
    /* ... */
  }
  async save(entity: User): Promise<void> {
    /* ... */
  }
}

function pair<A, B>(a: A, b: B): [A, B] {
  return [a, b];
}
 
pair("hello", 42); // [string, number]
 
// 实际场景：Map 的 key/value
function makeMap<K, V>(entries: [K, V][]): Map<K, V> {
  return new Map(entries);
}

// ✅ 合理：保留 input 和 output 的关系
function pluck<T, K extends keyof T>(obj: T, keys: K[]): T[K][] {
  return keys.map((k) => obj[k]);
}
 
const user = { name: "Alice", age: 30 };
pluck(user, ["name"]); // string[]
pluck(user, ["age"]); // number[]

// ❌ 滥用：泛型只用一次，没保留任何关系
function log<T>(value: T): void {
  console.log(value);
}
 
// 直接写就行：
function log(value: unknown): void {
  console.log(value);
}

type Keys<T> = keyof T;
 
type UserKeys = Keys<{ name: string; age: number }>;
// 'name' | 'age'

function get<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
 
const user = { name: "Alice", age: 30 };
get(user, "name"); // string
get(user, "age"); // number
get(user, "xxx"); // ❌ Error

function create<T>(constructor: new () => T): T {
  return new constructor();
}
 
class User {
  name = "default";
}
 
const u = create(User); // u is User

type User = { name: string; age: number; email: string };
 
type PartialUser = Partial<User>;
// { name?: string; age?: number; email?: string }
 
// 实战：更新对象时，只传需要改的字段
function updateUser(id: string, updates: Partial<User>) {
  // ...
}
 
updateUser("123", { name: "Bob" }); // ✅

type Config = { host?: string; port?: number };
 
type StrictConfig = Required<Config>;
// { host: string; port: number }

type User = { name: string; age: number };
 
type ReadonlyUser = Readonly<User>;
 
const u: ReadonlyUser = { name: "Alice", age: 30 };
u.name = "Bob"; // ❌ Cannot assign to 'name'

type User = { id: string; name: string; age: number; email: string };
 
type PublicUser = Pick<User, "id" | "name">;
// { id: string; name: string }

type User = { id: string; name: string; age: number; password: string };
 
type SafeUser = Omit<User, "password">;
// { id: string; name: string; age: number }

// 键是字符串字面量，值统一类型
type Roles = Record<"admin" | "user" | "guest", string[]>;
// { admin: string[]; user: string[]; guest: string[] }
 
const permissions: Roles = {
  admin: ["read", "write", "delete"],
  user: ["read", "write"],
  guest: ["read"],
};
 
// 任意字符串键
type CacheMap = Record<string, unknown>;

type A = Awaited<Promise<string>>; // string
type B = Awaited<Promise<Promise<number>>>; // number（递归解包）
 
// 实战：从异步函数推导返回值
async function fetchUser() {
  return { name: "Alice", age: 30 };
}
 
type User = Awaited<ReturnType<typeof fetchUser>>;
// { name: string; age: number }

function add(a: number, b: number): number {
  return a + b;
}
 
type AddReturn = ReturnType<typeof add>; // number
type AddParams = Parameters<typeof add>; // [number, number]

type LowerCase = Lowercase<"HELLO">; // 'hello'
type UpperCase = Uppercase<"hello">; // 'HELLO'
type Capitalize = Capitalize<"hello">; // 'Hello'
type Uncap = Uncapitalize<"Hello">; // 'hello'

type StringOrNull = string | null | undefined;
type Strict = NonNullable<StringOrNull>; // string

// ❌ 旧写法 1：用 as → 类型变窄到指定类型
const config = {
  host: "localhost",
  port: 3000,
} as { host: string; port: number };
 
config.host; // string（不是 'localhost' 字面量）
 
// ❌ 旧写法 2：注解 → 一样变窄
const config: { host: string; port: number } = {
  host: "localhost",
  port: 3000,
};
 
config.host; // string（不是 'localhost'）
 
// ✅ 新写法：satisfies → 验证 + 保留精确类型
const config = {
  host: "localhost",
  port: 3000,
} satisfies { host: string; port: number };
 
config.host; // 'localhost'（保留字面量类型！）
config.port; // 3000

type User = {
  profile: {
    name: string;
    address: { city: string };
  };
};
 
type PartialUser = Partial<User>;
// 只有顶层 profile 变可选；嵌套的 name / city 仍是必填
 
// 想要深度可选需要自己写：
type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};
 
type Result = DeepPartial<User>;
// { profile?: { name?: string; address?: { city?: string } } }

type IsString<T> = T extends string ? true : false;
 
type A = IsString<"hello">; // true
type B = IsString<42>; // false

// 提取数组元素类型
type ArrayElement<T> = T extends (infer U)[] ? U : never;
 
type A = ArrayElement<number[]>; // number
type B = ArrayElement<string[]>; // string
type C = ArrayElement<string>; // never

type ToArray<T> = T extends any ? T[] : never;
 
type A = ToArray<string | number>;
// 等价于 ToArray<string> | ToArray<number>
// 结果：string[] | number[]

// 把所有属性变可选（这就是 Partial 的实现）
type Partial<T> = {
  [K in keyof T]?: T[K];
};
 
// 把所有属性变只读
type Readonly<T> = {
  readonly [K in keyof T]: T[K];
};
 
// 把所有值变成 string
type Stringify<T> = {
  [K in keyof T]: string;
};
 
type Result = Stringify<{ name: number; age: number }>;
// { name: string; age: string }

// + 添加修饰符（默认）
type Readonly<T> = { +readonly [K in keyof T]: T[K] };
 
// - 移除修饰符
type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type Required<T> = { [K in keyof T]-?: T[K] };

type Greeting = `Hello, ${string}`;
 
const g1: Greeting = "Hello, Alice"; // ✅
const g2: Greeting = "Hi, Alice"; // ❌
 
// 联合 → 笛卡尔积
type Direction = "top" | "bottom" | "left" | "right";
type Position = `${Direction}-${number}`;
// 'top-${number}' | 'bottom-${number}' | ...

type CSSColor = `#${string}` | `rgb(${number}, ${number}, ${number})`;
 
const c1: CSSColor = "#fff"; // ✅
const c2: CSSColor = "rgb(255, 0, 0)"; // ✅
const c3: CSSColor = "red"; // ❌

// 提取函数返回值（这就是 ReturnType 的实现）
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
 
type A = ReturnType<() => string>; // string
type B = ReturnType<(x: number) => User>; // User
 
// 提取数组元素
type ArrayElement<T> = T extends (infer U)[] ? U : never;
 
// 提取 Promise 的解包值
type Awaited<T> = T extends Promise<infer V> ? V : T;
 
// 多个 infer
type FirstAndLast<T> = T extends [infer F, ...any[], infer L] ? [F, L] : never;
type Result = FirstAndLast<[1, 2, 3, 4]>; // [1, 4]

// ❌ AI 生成
function processData(data: any) {
  return data.items.map((item: any) => item.value);
  // 一切类型信息都丢了
}
 
// ✅ 你应改为
function processData<T extends { items: { value: unknown }[] }>(data: T) {
  return data.items.map((item) => item.value);
}

// ❌ AI 生成
const user = JSON.parse(input) as User;
user.name; // 编译过，但 input 可能不是 User 形状 → 运行时崩
 
// ✅ 你应改为：用类型守卫验证
function isUser(x: unknown): x is User {
  // 实际验证逻辑
}
 
const data = JSON.parse(input);
if (isUser(data)) {
  data.name; // 安全
}
 
// ✅ 或用 Zod 等运行时验证库
const user = userSchema.parse(JSON.parse(input));

// ❌ AI 生成：泛型只用一次，毫无意义
function log<T>(value: T): void {
  console.log(value);
}
 
// ✅ 改成
function log(value: unknown): void {
  console.log(value);
}

// ❌ 反例
const data: any = await fetch("/api").then((r) => r.json());
data.users.map((u) => u.name); // u 是 any
 
// ✅ 正例
const data: unknown = await fetch("/api").then((r) => r.json());
 
// 用类型守卫或 Zod 验证后再用
if (isApiResponse(data)) {
  data.users.map((u) => u.name); // u 类型推断正确
}

function reducer(state: State, action: Action) {
  switch (action.type) {
    case "INC":
      return state + 1;
    case "DEC":
      return state - 1;
    default:
      const _exhaustive: never = action; // 加了新 case 就编译错
      return state;
  }
}

type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};

type DogHandler = (d: Dog) => void;
type AnimalHandler = (a: Animal) => void;
 
const handleAnimal: AnimalHandler = (a) => console.log(a.name);
 
const handleDog: DogHandler = handleAnimal; // ✅ 正确：宽函数能接受窄类型
 
// 反过来不行
const handleAnimal2: AnimalHandler = handleDog; // ❌ DogHandler 期望 Dog，传 Animal 不安全

// ❌ 旧写法（生成运行时代码）
enum Direction {
  Left = "left",
  Right = "right",
}
 
// ✅ 新写法（纯类型，零运行时开销）
const Direction = {
  Left: "left",
  Right: "right",
} as const;
type Direction = (typeof Direction)[keyof typeof Direction]; // 'left' | 'right'
 
// 或者直接字面量联合
type Direction = "left" | "right";

// ❌ 反例：会被打包器视为运行时依赖
import { User } from "./types";
 
// ✅ 正例：明确告知"只是类型"
import type { User } from "./types";