2.8 KiB
2.8 KiB
命名规范（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) 快速示例
// good
const DEFAULT_RETRY_COUNT = 2;
interface QueryMediaListParams {
pageNumber: number;
pageSize: number;
}
async function fetchMediaList(params: QueryMediaListParams) {
// ...
}
const isListEmpty = computed(() => state.list.length === 0);
// bad
const retryCountDefault = 2; // 常量未使用 UPPER_SNAKE_CASE
interface IQuery {} // 不建议 I 前缀
async function getdata(d: any) {} // 命名与类型均不规范
const temp = computed(() => state.list.length === 0); // 语义弱