writing-typescript

TypeScript 开发（2025）

核心原则

• 严格类型检查：启用所有严格检查
• 解析，而非验证：在边界处转换不可信数据
• 组合优于继承：使用小而专注的函数
• 显式优于隐式：不使用 any，优先使用 unknown

工具链

bun          # Runtime + package manager (fast)
vite         # Frontend bundling
vitest       # Testing
eslint       # Linting
prettier     # Formatting

快速模式

类型守卫

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

可辨识联合类型

type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

function processResult<T>(result: Result<T>): T {
  if (result.ok) return result.value;
  throw result.error;
}

工具类型

type UserUpdate = Partial<User>;
type UserSummary = Pick<User, "id" | "name">;
type UserWithoutPassword = Omit<User, "password">;
type ReadonlyUser = Readonly<User>;

tsconfig.json 要点

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "isolatedModules": true
  }
}

参考资料

• PATTERNS.md - 代码模式与风格
• REACT.md - React 组件模式
• TESTING.md - 使用 vitest 进行测试

命令

bun install              # Install deps
bun run build            # Build
bun test                 # Test
bun run lint             # Lint
bun run format           # Format

---

易错点

• 在 verbatimModuleSyntax 下对命名导出使用 import type：仅导入类型的值会触发错误。解决方法：import { type Foo } from "mod"（内联标记）。
• 对对象使用 as const：同时设为只读并缩窄为字面量类型 — 这不同于 as Foo（断言类型）或 satisfies Foo（验证但不扩大类型）。
• satisfies 验证但不扩大类型；as 会扩大类型 — 在本应使用 satisfies 的地方使用 as，会在不知不觉中丢失字面量类型。
• Array<T>.includes(x) 要求 x 的类型为 T — 无法从联合类型中进行收窄；标准解决方法是使用类型谓词辅助函数。
• strictNullChecks: false 会使 ALL 类型的 T 都表示 T | null | undefined — 部分迁移会留下对可空性的错误描述。
• tsconfig.json 的 extends 不会递归合并 compilerOptions.paths — 子级路径会替换父级路径，而不是与其合并。