初始化

2026-09-15 15:25:05 +07:00
commit 77c16ab4a2
1310 changed files with 132250 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 命名规范（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); // 语义弱
+```