📝 docs(typescript): clarify ts and js support boundaries
This commit is contained in:
parent
1f46203299
commit
9ac8a4c8a4
|
|
@ -1,6 +1,13 @@
|
|||
# playbook
|
||||
|
||||
Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + TypeScript/JavaScript + Markdown（代码格式化）工程规范与代理规则合集。
|
||||
Playbook：工程规范与代理规则合集，当前覆盖：
|
||||
|
||||
- TSL（`.tsl`/`.tsf`）
|
||||
- C++
|
||||
- Python
|
||||
- TypeScript（`.ts`/`.tsx`）
|
||||
- JavaScript（`.js`/`.mjs`/`.cjs`）
|
||||
- Markdown（代码格式化）
|
||||
|
||||
## 原则
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,13 @@
|
|||
# TypeScript 代码风格
|
||||
# TypeScript/JavaScript 代码风格
|
||||
|
||||
本 Playbook 的 TypeScript 代码风格以 Google TypeScript Style Guide 为基线：
|
||||
本 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`）
|
||||
|
|
@ -15,15 +16,16 @@
|
|||
|
||||
## 类型约定
|
||||
|
||||
- 禁止 `any`；需要宽泛类型时用 `unknown` 并做类型收窄
|
||||
- TypeScript 禁止 `any`；需要宽泛类型时用 `unknown` 并做类型收窄
|
||||
- 优先使用 `interface` 描述对象结构；`type` 用于联合/交叉/工具类型
|
||||
- 函数返回类型：公共 API 必须显式标注；内部实现可依赖推断
|
||||
- 泛型参数名：单字母（`T`、`K`、`V`）或描述性名称（`TItem`）
|
||||
- JavaScript 文件建议启用 `// @ts-check` 与 JSDoc 进行静态检查
|
||||
|
||||
## 模块约定
|
||||
|
||||
- 使用 ES Module（`import`/`export`）；禁止 `require()`（除 `.cjs` 文件）
|
||||
- 每文件一个主要导出；避免桶文件（`index.ts` re-export 过多）
|
||||
- 每文件一个主要导出；避免桶文件（`index.ts`/`index.js` re-export 过多）
|
||||
- 路径别名：以 `tsconfig.json` 的 `paths` 为准
|
||||
|
||||
## 异步约定
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
|
||||
## 文件与目录
|
||||
|
||||
- 文件名：`kebab-case.ts` / `kebab-case.tsx`
|
||||
- 测试文件：`kebab-case.test.ts` / `kebab-case.spec.ts`
|
||||
- 文件名：`kebab-case.ts` / `kebab-case.tsx` / `kebab-case.js` / `kebab-case.jsx`
|
||||
- 脚本/配置文件：`kebab-case.mjs` / `kebab-case.cjs`
|
||||
- 测试文件：`kebab-case.test.ts` / `kebab-case.spec.ts` / `kebab-case.test.js` / `kebab-case.spec.js`
|
||||
- 类型声明文件：`kebab-case.d.ts`
|
||||
- 目录名：`kebab-case/`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# TypeScript 工具链
|
||||
# TypeScript/JavaScript 工具链
|
||||
|
||||
本 Playbook 推荐以下工具保证代码一致性与质量：
|
||||
|
||||
|
|
@ -7,6 +7,7 @@
|
|||
- `eslint`：风格检查与静态分析（配合 `@typescript-eslint`）
|
||||
- `vitest` / `jest`：测试（按项目选择）
|
||||
- `tsx` / `ts-node`：直接运行 `.ts` 文件（开发/脚本场景）
|
||||
- `node`：运行 `.js/.mjs/.cjs` 脚本
|
||||
|
||||
## 常用命令（示例）
|
||||
|
||||
|
|
@ -22,6 +23,12 @@ pnpm add -D typescript prettier eslint typescript-eslint
|
|||
tsc --noEmit
|
||||
```
|
||||
|
||||
JavaScript 检查（可选，启用 `allowJs` + `checkJs`）：
|
||||
|
||||
```bash
|
||||
tsc --noEmit --allowJs --checkJs
|
||||
```
|
||||
|
||||
格式化：
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -14,14 +14,15 @@
|
|||
3. 发现安全问题（明文密钥/鉴权漏洞）立即标注或修复
|
||||
4. 不引入新依赖或工具，除非明确要求
|
||||
|
||||
## TypeScript 核心约定（不可违反）
|
||||
## TypeScript/JavaScript 核心约定（不可违反）
|
||||
|
||||
- 语言标准：优先 TypeScript；仅在纯脚本/配置场景使用 JavaScript
|
||||
- 语言标准：业务代码优先 TypeScript（`.ts/.tsx`）；JavaScript（`.js/.mjs/.cjs`）仅用于脚本、配置或兼容场景
|
||||
- 类型：禁止使用 `any`；优先 `unknown`；所有公共 API 必须有明确类型注解
|
||||
- 代码风格：以仓库既有 ESLint/Prettier 配置为准；未经沟通不切换 formatter/linter
|
||||
- Import：使用 ES Module（`import`/`export`）；避免 `require()`；按 外部 → 内部 → 相对路径 分组
|
||||
- 命名：文件 `kebab-case.ts`；类/接口/类型 `PascalCase`；函数/变量 `camelCase`；常量 `UPPER_WITH_UNDER`；私有成员 `_camelCase`
|
||||
- 命名：文件 `kebab-case.ts/.js`；类/接口/类型 `PascalCase`；函数/变量 `camelCase`；常量 `UPPER_WITH_UNDER`；私有成员 `_camelCase`
|
||||
- 异步：优先 `async/await`；避免裸 `.then()` 链；错误必须处理
|
||||
- JavaScript 质量底线：必须通过 ESLint；推荐启用 `@ts-check` + JSDoc 做静态检查
|
||||
|
||||
## 安全红线（不可触碰）
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue