TypeScript 全指南：从入门到精通

let name: string = "TypeScript";
let version: number = 6.0;
let isOpenSource: boolean = true;

interface User {
  name: string;
  age: number;
  greet(): string;
}
 
const user: User = {
  name: "Alice",
  age: 30,
  greet() {
    return `Hello, I'm ${this.name}`;
  },
};

let id: string | number;
 
id = "abc-123"; // OK
id = 42; // OK

function identity<T>(value: T): T {
  return value;
}
 
const result1 = identity<string>("hello"); // 类型是 string
const result2 = identity<number>(42); // 类型是 number

function processValue(value: string | number) {
  if (typeof value === "string") {
    // 在这个分支里，TypeScript 知道 value 是 string
    console.log(value.toUpperCase());
  } else {
    // 在这个分支里，TypeScript 知道 value 是 number
    console.log(value.toFixed(2));
  }
}

// TypeScript 自动推断 x 的类型为 number
let x = 10;
 
// 自动推断返回值类型为 string
function greet(name: string) {
  return `Hello, ${name}`;
}

// 原始类型
let str: string = "hello";
let num: number = 42;
let bool: boolean = true;
let n: null = null;
let u: undefined = undefined;
let sym: symbol = Symbol("id");
let big: bigint = 100n;
 
// 特殊类型
let notSure: unknown = "maybe a string";
notSure = 42; // OK，unknown 可以接收任何值
 
let nothing: void = undefined; // 常用于函数没有返回值的场景
let impossible: never; // 永远不会有值的类型
 
// 数组
let numbers: number[] = [1, 2, 3];
let strings: Array<string> = ["a", "b", "c"];
 
// 元组——固定长度和类型的数组
let tuple: [string, number] = ["age", 25];

interface Person {
  name: string;
  age: number;
  email?: string; // 可选属性
  readonly id: number; // 只读属性
}
 
const person: Person = {
  name: "Bob",
  age: 25,
  id: 1,
};
 
// person.id = 2; // 错误：id 是只读的
 
// 接口可以扩展
interface Employee extends Person {
  department: string;
  salary: number;
}

// 基础用法
type ID = string | number;
type Point = { x: number; y: number };
 
// 与 interface 的区别：type 可以表示联合类型
type Status = "active" | "inactive" | "suspended";
 
// 也可以表示函数类型
type Callback = (data: string) => void;
 
// 交叉类型
type Named = { name: string };
type Aged = { age: number };
type NamedAndAged = Named & Aged;
 
const user: NamedAndAged = { name: "Charlie", age: 28 };

// 联合类型：A 或 B
type Result = Success | Error;
 
interface Success {
  status: "success";
  data: string;
}
 
interface Error {
  status: "error";
  message: string;
}
 
function handleResult(result: Result) {
  if (result.status === "success") {
    console.log(result.data); // TypeScript 知道这里是 Success
  } else {
    console.log(result.message); // TypeScript 知道这里是 Error
  }
}
 
// 交叉类型：A 且 B
type Admin = User & { permissions: string[] };
 
interface User {
  name: string;
  email: string;
}
 
const admin: Admin = {
  name: "Diana",
  email: "diana@example.com",
  permissions: ["read", "write", "delete"],
};

// 参数类型和返回值类型
function add(a: number, b: number): number {
  return a + b;
}
 
// 可选参数和默认值
function greet(name: string, greeting?: string): string {
  return `${greeting || "Hello"}, ${name}`;
}
 
// 剩余参数
function sum(...numbers: number[]): number {
  return numbers.reduce((acc, n) => acc + n, 0);
}
 
// 函数重载
function formatDate(value: string): string;
function formatDate(value: number): string;
function formatDate(value: string | number): string {
  if (typeof value === "number") {
    return new Date(value).toLocaleDateString();
  }
  return new Date(value).toLocaleDateString();
}

// 数字枚举
enum Direction {
  Up = 0,
  Down = 1,
  Left = 2,
  Right = 3,
}
 
// 字符串枚举
enum HttpStatusCode {
  OK = "200",
  NotFound = "404",
  InternalError = "500",
}
 
let status: HttpStatusCode = HttpStatusCode.OK;

// 字符串字面量
type Theme = "light" | "dark" | "system";
let theme: Theme = "dark";
 
// 数字字面量
type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6;
let roll: DiceRoll = 3;
 
// 布尔字面量
type Truthy = true;

// as 语法
const canvas = document.getElementById("main") as HTMLCanvasElement;
canvas.getContext("2d");
 
// 尖括号语法（JSX 文件中不可用）
// const input = <HTMLInputElement>document.getElementById("input");
 
// 非空断言
const element = document.querySelector(".box")!;
element.classList.add("active");

// 泛型函数
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}
 
first([1, 2, 3]); // 返回 number | undefined
first(["a", "b"]); // 返回 string | undefined
 
// 泛型约束（extends）
interface HasLength {
  length: number;
}
 
function logLength<T extends HasLength>(value: T): T {
  console.log(value.length);
  return value;
}
 
logLength("hello"); // OK，string 有 length
logLength([1, 2, 3]); // OK，数组有 length
// logLength(123);      // 错误，number 没有 length
 
// 多个泛型参数
function merge<K extends string, V>(key: K, value: V): Record<K, V> {
  return { [key]: value } as Record<K, V>;
}
 
// 泛型默认值
interface PaginatedResponse<T = unknown> {
  data: T[];
  total: number;
  page: number;
}
 
// 使用默认类型
const res: PaginatedResponse = { data: [], total: 0, page: 1 };

// 基础映射类型
type Readonly<T> = {
  readonly [P in keyof T]: T[P];
};
 
type Optional<T> = {
  [P in keyof T]?: T[P];
};
 
interface Todo {
  title: string;
  description: string;
  completed: boolean;
}
 
type ReadonlyTodo = Readonly<Todo>;
// 等价于 { readonly title: string; readonly description: string; readonly completed: boolean }
 
// 映射类型 + 重新映射键（TypeScript 4.1+）
type Getters<T> = {
  [P in keyof T as `get${Capitalize<string & P>}`]: () => T[P];
};
 
type TodoGetters = Getters<Todo>;
// { getTitle: () => string; getDescription: () => string; getCompleted: () => boolean }

// 基础形式：SomeType extends OtherType ? TrueType : FalseType
type IsString<T> = T extends string ? "yes" : "no";
 
type A = IsString<string>; // "yes"
type B = IsString<number>; // "no"
 
// infer 关键字：在条件类型中推断类型
type Flatten<T> = T extends Array<infer Item> ? Item : T;
 
type F1 = Flatten<string[]>; // string
type F2 = Flatten<number>; // number
 
// 提取函数返回值类型
type GetReturnType<T> = T extends (...args: never[]) => infer R ? R : never;
 
type R1 = GetReturnType<() => string>; // string
type R2 = GetReturnType<(x: number) => boolean>; // boolean
 
// 分布式条件类型
type ToArray<T> = T extends any ? T[] : never;
type Result = ToArray<string | number>; // string[] | number[]
 
// 避免分布式行为：用 [T] 包裹
type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;
type Result2 = ToArrayNonDist<string | number>; // (string | number)[]

// typeof：获取变量的类型
const config = {
  port: 3000,
  host: "localhost",
  debug: true,
};
 
type Config = typeof config;
// { port: number; host: string; debug: boolean }
 
// keyof：获取类型的所有属性名组成的联合类型
type ConfigKeys = keyof Config; // "port" | "host" | "debug"
 
// 索引访问类型：Type['key']
type PortType = Config["port"]; // number
 
// ReturnType：获取函数返回值类型
function createuser(name: string) {
  return { name, createdAt: new Date() };
}
 
type User = ReturnType<typeof createUser>;
// { name: string; createdAt: Date }
 
// Parameters：获取函数参数类型组成的元组
type CreateUserParams = Parameters<typeof createUser>;
// [name: string]

// typeof 守卫
function double(value: string | number): string | number {
  if (typeof value === "string") {
    return value.repeat(2); // value: string
  }
  return value * 2; // value: number
}
 
// instanceof 守卫
function formatDate(value: string | Date): string {
  if (value instanceof Date) {
    return value.toISOString(); // value: Date
  }
  return new Date(value).toISOString(); // value: string
}
 
// in 操作符守卫
interface Fish {
  swim(): void;
}
interface Bird {
  fly(): void;
}
 
function move(animal: Fish | Bird) {
  if ("swim" in animal) {
    animal.swim(); // animal: Fish
  } else {
    animal.fly(); // animal: Bird
  }
}
 
// 自定义类型守卫（type predicates）
function isString(value: unknown): value is string {
  return typeof value === "string";
}
 
function process(input: unknown) {
  if (isString(input)) {
    console.log(input.toUpperCase()); // input: string
  }
}
 
// 可辨识联合（Discriminated Unions）
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; x: number }
  | { kind: "triangle"; x: number; y: number };
 
function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.x ** 2;
    case "triangle":
      return (shape.x * shape.y) / 2;
  }
}

// 编写声明文件 example.d.ts
declare module "my-lib" {
  interface MyLibOptions {
    timeout?: number;
    retries?: number;
  }
 
  function init(options: MyLibOptions): void;
  function getData(id: string): Promise<string>;
 
  export { init, getData, MyLibOptions };
}
 
// 使用
import { init, getData } from "my-lib";
 
init({ timeout: 5000 });
const data = await getData("abc");

// ES 模块（推荐方式）
// math.ts
export function add(a: number, b: number): number {
  return a + b;
}
export const PI = 3.14159;
 
// app.ts
import { add, PI } from "./math";
 
// 命名空间（旧式方式，新项目不推荐）
namespace Validation {
  export interface StringValidator {
    isValid(s: string): boolean;
  }
 
  export class EmailValidator implements StringValidator {
    isValid(s: string): boolean {
      return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
    }
  }
}
 
const validator = new Validation.EmailValidator();

// 方法装饰器
function logged(originalMethod: any, context: ClassMethodDecoratorContext) {
  const methodName = String(context.name);
  function replacementMethod(this: any, ...args: any[]) {
    console.log(`LOG: Entering method '${methodName}'.`);
    const result = originalMethod.call(this, ...args);
    console.log(`LOG: Exiting method '${methodName}'.`);
    return result;
  }
  return replacementMethod;
}
 
class Calculator {
  @logged
  add(a: number, b: number): number {
    return a + b;
  }
}

// 深层 Partial
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};
 
// 深层 Readonly
type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};
 
// 提取 Promise 内部的类型
type UnwrapPromise<T> = T extends Promise<infer U> ? UnwrapPromise<U> : T;
 
type Result = UnwrapPromise<Promise<Promise<string>>>; // string
 
// 将对象的键从 snake_case 转为 camelCase
type SnakeToCamel<S extends string> = S extends `${infer Head}_${infer Tail}`
  ? `${Head}${Capitalize<SnakeToCamel<Tail>>}`
  : S;
 
type CamelCase = SnakeToCamel<"user_name_id">; // "userNameId"
 
// 递归类型：路径取值
type PathValue<T, P extends string> = P extends `${infer Key}.${infer Rest}`
  ? Key extends keyof T
    ? PathValue<T[Key], Rest>
    : never
  : P extends keyof T
    ? T[P]
    : never;
 
interface Data {
  user: {
    profile: {
      name: string;
    };
  };
}
 
type Name = PathValue<Data, "user.profile.name">; // string

{
  "compilerOptions": {
    // 语言与环境
    "target": "ES2022", // 编译目标
    "lib": ["ES2022", "DOM"], // 类型定义库
    "module": "ESNext", // 模块系统
    "moduleResolution": "bundler", // 模块解析策略
 
    // 严格模式（推荐全部开启）
    "strict": true, // 启用所有严格检查
    "noUncheckedIndexedAccess": true, // 数组/对象索引返回 T | undefined
    "noImplicitOverride": true, // 覆盖方法必须加 override
    "exactOptionalPropertyTypes": true, // 精确的可选属性类型
 
    // 输出控制
    "declaration": true, // 生成 .d.ts 文件
    "declarationMap": true, // 生成声明映射
    "sourceMap": true, // 生成 source map
 
    // 互操作性
    "esModuleInterop": true, // 允许默认导入 CommonJS 模块
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true, // 允许导入 JSON
    "isolatedModules": true, // 确保每个文件可以独立编译
 
    // 其他
    "skipLibCheck": true, // 跳过 .d.ts 文件的类型检查
    "forceConsistentCasingInFileNames": true,
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"],
}

interface Point1 {
  x: number;
  y: number;
}
interface Point2 {
  x: number;
  y: number;
}
 
const p1: Point1 = { x: 1, y: 2 };
const p2: Point2 = p1; // OK，结构兼容

// 避免过深的类型递归（TypeScript 有递归深度限制）
// 不好的做法
type BadDeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? BadDeepPartial<T[K]> : T[K];
};
 
// 对于特别深的嵌套，考虑使用具体层级
type Partial3<T> = Partial<{
  [K in keyof T]: T[K] extends object
    ? Partial<{
        [K2 in keyof T[K]]: T[K][K2] extends object ? Partial<T[K][K2]> : T[K][K2];
      }>
    : T[K];
}>;
 
// 使用 interface 代替交叉类型来提升性能
// 交叉类型会创建新的中间类型，interface 只是声明式的
// 不好的做法
type A = { a: string } & { b: number } & { c: boolean };
// 好的做法
interface B {
  a: string;
  b: number;
  c: boolean;
}
 
// 项目引用（Project References）加速大型项目编译
// tsconfig.json
// {
//   "references": [
//     { "path": "./packages/core" },
//     { "path": "./packages/utils" }
//   ]
// }