88 lines
2.8 KiB
Markdown
88 lines
2.8 KiB
Markdown
# 命名规范（Vue3 + TypeScript）
|
||
|
||
本规范参考 Vue 官方风格与 TypeScript 主流实践，目标是统一可读性、可检索性、可维护性。
|
||
|
||
## 0) 历史代码兼容原则
|
||
|
||
- 存量代码可暂时保留历史命名，不做一次性全量改名。
|
||
- 增量从严：新增文件、目录、类型、变量、函数、组件命名必须符合本规范。
|
||
- 改动旧文件时，至少保证“新增/修改行”不引入旧命名反模式。
|
||
- 大范围改名需单独评估风险（路由、动态导入、缓存键、埋点字段），建议独立 PR 分批执行。
|
||
|
||
## 1) 目录与文件命名
|
||
|
||
- 目录名：`kebab-case`
|
||
- 示例：`src/views/user-center/`
|
||
- 页面入口文件：`index.vue`
|
||
- 组件文件：`PascalCase.vue`
|
||
- 示例：`UserProfileCard.vue`
|
||
- hooks/composable 文件：`useXxx.ts`
|
||
- 示例：`useMediaEpisodePaging.ts`
|
||
- 其他 TS 文件：`kebab-case.ts`
|
||
- 示例：`media-content-parser.ts`
|
||
- 样式文件：`kebab-case.scss`
|
||
|
||
## 2) 代码符号命名
|
||
|
||
- class/type/interface/enum：`PascalCase`
|
||
- 示例：`UserProfileService`、`MediaListItem`、`ApiError`
|
||
- 变量/函数/方法：`camelCase`
|
||
- 示例：`fetchMediaList`、`buildRequestParams`
|
||
- 常量：`UPPER_SNAKE_CASE`
|
||
- 示例：`DEFAULT_PAGE_SIZE`
|
||
- 布尔变量：`is/has/can/should + PascalCase`
|
||
- 示例：`isLoading`、`hasPermission`
|
||
- Promise 异步动作：动词开头
|
||
- 示例：`fetchUserInfo`、`loadEpisodeList`
|
||
|
||
## 3) Vue 约定命名
|
||
|
||
- 事件处理函数统一 `handleXxx`
|
||
- 示例：`handleSubmit`、`handleEpisodeChange`
|
||
- 事件命名（emit）使用 `kebab-case`
|
||
- 示例：`episode-change`、`submit-success`
|
||
- props 命名在代码中使用 `camelCase`，模板中可使用 `kebab-case`。
|
||
- 计算属性命名以业务语义为主，避免 `data1`、`tempVal` 这类占位名。
|
||
|
||
## 4) 类型命名细则
|
||
|
||
- DTO/接口模型建议加语义后缀：
|
||
- 入参：`XxxParams`
|
||
- 返回：`XxxResp` 或 `XxxResponse`
|
||
- 列表项：`XxxItem`
|
||
- 错误类型建议统一：`XxxError`
|
||
- 避免使用 `IUser` 这类 `I` 前缀接口命名。
|
||
|
||
## 5) 禁止项
|
||
|
||
- 禁止拼音命名（业务专有词且已有共识除外）。
|
||
- 禁止无语义缩写（如 `tmp`, `obj2`, `aaa`）。
|
||
- 禁止单字符业务变量命名（循环计数器 `i/j/k` 除外）。
|
||
- 禁止同一模块混用多种命名风格。
|
||
|
||
## 6) 快速示例
|
||
|
||
```ts
|
||
// good
|
||
const DEFAULT_RETRY_COUNT = 2;
|
||
|
||
interface QueryMediaListParams {
|
||
pageNumber: number;
|
||
pageSize: number;
|
||
}
|
||
|
||
async function fetchMediaList(params: QueryMediaListParams) {
|
||
// ...
|
||
}
|
||
|
||
const isListEmpty = computed(() => state.list.length === 0);
|
||
```
|
||
|
||
```ts
|
||
// bad
|
||
const retryCountDefault = 2; // 常量未使用 UPPER_SNAKE_CASE
|
||
interface IQuery {} // 不建议 I 前缀
|
||
async function getdata(d: any) {} // 命名与类型均不规范
|
||
const temp = computed(() => state.list.length === 0); // 语义弱
|
||
```
|