✨ feat(typescript): add standards docs and sync rewrite coverage

2026-02-24 17:30:43 +08:00
parent 872c1afc24
commit 1f46203299
12 changed files with 360 additions and 12 deletions
@@ -0,0 +1,35 @@
+# TypeScript 代码风格
+
+本 Playbook 的 TypeScript 代码风格以 Google TypeScript Style Guide 为基线：
+
+- Google TypeScript Style Guide: https://google.github.io/styleguide/tsguide.html
+- TypeScript 官方手册: https://www.typescriptlang.org/docs/handbook/
+
+## 项目约定
+
+- 行宽：100（与 Prettier 配置保持一致）
+- 缩进：2 空格
+- 引号：单引号（Prettier `singleQuote: true`）
+- 分号：不加（Prettier `semi: false`）；如仓库已有配置则以仓库为准
+- 尾随逗号：`all`（ES5+）
+
+## 类型约定
+
+- 禁止 `any`；需要宽泛类型时用 `unknown` 并做类型收窄
+- 优先使用 `interface` 描述对象结构；`type` 用于联合/交叉/工具类型
+- 函数返回类型：公共 API 必须显式标注；内部实现可依赖推断
+- 泛型参数名：单字母（`T`、`K`、`V`）或描述性名称（`TItem`）
+
+## 模块约定
+
+- 使用 ES Module（`import`/`export`）；禁止 `require()`（除 `.cjs` 文件）
+- 每文件一个主要导出；避免桶文件（`index.ts` re-export 过多）
+- 路径别名：以 `tsconfig.json` 的 `paths` 为准
+
+## 异步约定
+
+- 优先 `async/await`；避免裸 `.then()/.catch()` 链
+- `async` 函数必须处理错误（`try/catch` 或调用方捕获）
+- 不得忽略 Promise（使用 `void` 操作符显式标记有意忽略）
+
+当既有代码与本约定冲突时，优先保持局部一致性，逐步迁移。
@@ -0,0 +1,88 @@
+# TypeScript 配置清单
+
+本文件汇总 TypeScript 项目常用配置文件说明。
+
+## 1) `tsconfig.json`
+
+关键编译选项：
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
+```
+
+- `strict: true`：启用全部严格检查（必须）
+- `noUncheckedIndexedAccess`：数组/对象索引访问返回 `T | undefined`（推荐）
+- `skipLibCheck`：跳过 `.d.ts` 检查，加快编译
+
+## 2) `.prettierrc`
+
+```json
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 100,
+  "trailingComma": "all",
+  "tabWidth": 2
+}
+```
+
+## 3) `eslint.config.js`（Flat Config）
+
+```js
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: { projectService: true },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+    },
+  },
+)
+```
+
+## 4) `.editorconfig`
+
+```ini
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{ts,tsx,js,jsx,json}]
+indent_style = space
+indent_size = 2
+max_line_length = 100
+```
+
+## 5) `.vscode/settings.json`
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.rulers": [100],
+  "typescript.tsdk": "node_modules/typescript/lib"
+}
+```
@@ -0,0 +1,41 @@
+# TypeScript 命名规范
+
+## 文件与目录
+
+- 文件名：`kebab-case.ts` / `kebab-case.tsx`
+- 测试文件：`kebab-case.test.ts` / `kebab-case.spec.ts`
+- 类型声明文件：`kebab-case.d.ts`
+- 目录名：`kebab-case/`
+
+## 标识符
+
+| 类别              | 风格                       | 示例                           |
+| ----------------- | -------------------------- | ------------------------------ |
+| 类（Class）       | `PascalCase`               | `UserService`                  |
+| 接口（Interface） | `PascalCase`               | `UserProfile`（不加 `I` 前缀） |
+| 类型别名（Type）  | `PascalCase`               | `ApiResponse<T>`               |
+| 枚举（Enum）      | `PascalCase`               | `HttpStatus`                   |
+| 枚举成员          | `UPPER_WITH_UNDER`         | `NOT_FOUND`                    |
+| 函数/方法         | `camelCase`                | `getUserById`                  |
+| 变量/参数         | `camelCase`                | `userId`                       |
+| 常量（模块级）    | `UPPER_WITH_UNDER`         | `MAX_RETRY_COUNT`              |
+| 私有成员          | `_camelCase`               | `_cache`                       |
+| 泛型参数          | 单字母或 `T` 前缀          | `T`、`TItem`、`K`、`V`         |
+| React 组件        | `PascalCase`               | `UserCard`                     |
+| React Hook        | `camelCase`，以 `use` 开头 | `useUserData`                  |
+
+## 布尔值命名
+
+布尔变量/属性以 `is`、`has`、`can`、`should` 开头：
+
+```ts
+const isLoading = true
+const hasPermission = false
+```
+
+## 避免
+
+- 单字母变量（循环索引 `i`/`j` 除外）
+- 缩写（`usr`、`btn`）；优先完整单词
+- 匈牙利命名法（`strName`、`nCount`）
+- 接口名加 `I` 前缀（`IUserService`）
@@ -0,0 +1,47 @@
+# TypeScript 工具链
+
+本 Playbook 推荐以下工具保证代码一致性与质量：
+
+- `typescript`：编译器（`tsc`）
+- `prettier`：格式化
+- `eslint`：风格检查与静态分析（配合 `@typescript-eslint`）
+- `vitest` / `jest`：测试（按项目选择）
+- `tsx` / `ts-node`：直接运行 `.ts` 文件（开发/脚本场景）
+
+## 常用命令（示例）
+
+安装工具（按项目实际包管理器调整）：
+
+```bash
+pnpm add -D typescript prettier eslint typescript-eslint
+```
+
+类型检查：
+
+```bash
+tsc --noEmit
+```
+
+格式化：
+
+```bash
+prettier --write .
+```
+
+Lint 检查：
+
+```bash
+eslint .
+```
+
+运行测试：
+
+```bash
+vitest run
+# 或
+jest --ci
+```
+
+## 包管理器
+
+优先使用仓库已有的包管理器（`pnpm` / `npm` / `yarn`）；未经沟通不切换。