# TypeScript/JavaScript 代码风格

本 Playbook 的 TypeScript/JavaScript 代码风格以 Google TypeScript Style Guide 为基线：

- Google TypeScript Style Guide: <https://google.github.io/styleguide/tsguide.html>
- TypeScript 官方手册: <https://www.typescriptlang.org/docs/handbook/>

## 项目约定

- 适用范围：业务代码默认使用 `.ts/.tsx`；`.js/.mjs/.cjs` 仅用于脚本、工具链或配置
- 行宽：100（与 Prettier 配置保持一致）
- 缩进：2 空格
- 引号：单引号（Prettier `singleQuote: true`）
- 分号：不加（Prettier `semi: false`）；如仓库已有配置则以仓库为准
- 尾随逗号：`all`（ES5+）

## 类型约定

- TypeScript 禁止 `any`；需要宽泛类型时用 `unknown` 并做类型收窄
- 优先使用 `interface` 描述对象结构；`type` 用于联合/交叉/工具类型
- 函数返回类型：公共 API 必须显式标注；内部实现可依赖推断
- 泛型参数名：单字母（`T`、`K`、`V`）或描述性名称（`TItem`）
- JavaScript 文件建议启用 `// @ts-check` 与 JSDoc 进行静态检查

## 模块约定

- 使用 ES Module（`import`/`export`）；禁止 `require()`（除 `.cjs` 文件）
- 每文件一个主要导出；避免桶文件（`index.ts`/`index.js` re-export 过多）
- 路径别名：以 `tsconfig.json` 的 `paths` 为准

## 异步约定

- 优先 `async/await`；避免裸 `.then()/.catch()` 链
- `async` 函数必须处理错误（`try/catch` 或调用方捕获）
- 不得忽略 Promise（使用 `void` 操作符显式标记有意忽略）

当既有代码与本约定冲突时，优先保持局部一致性，逐步迁移。
