ZhiqingResearch 命名规范（Node.js / JavaScript & TypeScript）
本规范覆盖 Node.js 下的 JavaScript 与 TypeScript 代码。
写代码前先按这个顺序自检：变量 → 函数/方法 → 类/接口 → 文件名。缩写词大小写（见第 5 节）贯穿所有元素。
1. 变量命名
1.1 一般变量：camelCase
小写字母开头，多单词驼峰拼接。
const userName = "John";
let userAge = 25;
1.2 常量：UPPER_SNAKE_CASE
全大写 + 下划线分隔，仅用于真正不变的值。
const MAX_RETRY_COUNT = 3;
const DEFAULT_TIMEOUT_MS = 5000;
只有"真正不变的字面量"才用全大写；像
const user = fetchUser()这种引用绑定仍然用 camelCase。
1.3 布尔变量：以 is / has / should 开头
读起来像一个判断句。
const isActive = true;
const hasPermission = false;
const shouldRetry = true;
1.4 集合 / 数组：用复数名词
存放多个元素的变量用复数，读代码时一眼能看出它是集合。
const users = await fetchUsers();
const orderIds = orders.map((o) => o.id);
需要强调底层数据结构时可加后缀（
userList、idSet），但默认优先用复数名词。
2. 函数 / 方法命名
2.1 动词 + 名词组合
函数名直接说明"它做了什么"。
function getUserById(id: number): User { /* ... */ }
function calculateTotalPrice(items: Item[]): number { /* ... */ }
function sendNotification(userId: number, message: string): void { /* ... */ }
常用动词参考：get / set / fetch / create / update / delete / validate / parse / format / handle / build。
2.2 私有方法：以 _ 开头
类的私有方法以 _ 开头。TS 里同时加 private 修饰符。
class UserService {
private _validateInput(input: string): void { /* ... */ }
}
3. 类与接口命名
3.1 类：PascalCase
每个单词首字母大写。描述具体实体（User、Order）或行为载体（UserService、OrderValidator）。
class UserService { /* ... */ }
class OrderValidator { /* ... */ }
3.2 接口：PascalCase，无 I 前缀
接口名描述行为或结构本身。
interface User {
id: number;
name: string;
}
interface UserRepository {
findById(id: number): Promise<User | null>;
}
4. 文件 / 模块命名
文件名用 kebab-case + 功能后缀，或主导出类用 PascalCase：
user.controller.ts // 控制器
auth.module.ts // 模块
order.service.ts // 服务
user-repository.ts // 仓储（多单词用 kebab-case）
UserEntity.ts // 主要导出一个同名类时，文件名与类同名
选择原则：
- 文件主要导出一个同名类（entity、DTO 等） →
PascalCase与类名一致 - 文件按功能/层次组织（controller、service、module 等） →
kebab-case加后缀
5. 缩写词 / 首字母缩略词
ID、URL、HTTP、API、DB 等缩写词一律当作普通单词处理：只大写首字母，其余小写，不要整体大写。这条规则贯穿变量、函数、类、文件名。
const userId = 1; // ✅ 不是 userID
const httpClient = createClient(); // ✅ 不是 HTTPClient
function parseUrl(raw: string): URL { /* ... */ } // ✅ 不是 parseURL
class HttpRequest { /* ... */ } // ✅ 不是 HTTPRequest
唯一例外：缩写词出现在常量里时，跟随
UPPER_SNAKE_CASE，如DEFAULT_API_TIMEOUT_MS、MAX_URL_LENGTH。
速查表
| 元素 | 风格 | 示例 |
|---|---|---|
| 变量 | camelCase |
userName |
| 常量 | UPPER_SNAKE_CASE |
MAX_RETRY_COUNT |
| 布尔 | is/has/should 前缀 |
isActive |
| 集合/数组 | 复数名词 | users |
| 函数/方法 | 动词+名词 camelCase |
getUserById |
| 私有方法 | _ 前缀 |
_validateInput |
| 类 | PascalCase |
UserService |
| 接口 | PascalCase，无 I 前缀 |
UserRepository |
| 文件名 | kebab-case + 后缀 或 PascalCase |
user.controller.ts |
| 缩写词 | 仅首字母大写 | userId httpClient |
代码生成/审查时的自检清单
应用本规范后，逐项确认：
- ☐ 所有变量是
camelCase，所有常量是UPPER_SNAKE_CASE - ☐ 布尔变量/字段/方法以
is/has/should开头 - ☐ 函数/方法是"动词+名词"组合，名字本身能说明做什么
- ☐ 私有方法以
_前缀开头（TS 同时加private） - ☐ 类和接口都是
PascalCase，接口没有I前缀 - ☐ 文件名符合
kebab-case + 后缀或PascalCase规则 - ☐ 集合/数组变量用复数名词（
users而非userList，除非要强调结构） - ☐ 缩写词只大写首字母（
userId而非userID，HttpRequest而非HTTPRequest）