📝 更新 TypeScript 函数定义规范和相关文档

2026-03-27 05:49:45 +08:00 · 2026-03-26 05:12:20 +08:00
parent 6445ac4dc1
commit 8a0543d627
4 changed files with 299 additions and 6 deletions
--- a/.trae/rules/typescript-rules.md
+++ b/.trae/rules/typescript-rules.md
@@ -54,7 +54,20 @@ const PostNewsTypeEnum: TGApp.BBS.Post.NewsTypeEnum = { ... };

 ## JSDoc 注释

-所有导出函数必须包含 `@since` 标签：
+所有导出函数、类型、枚举必须包含 `@since` 标签，版本号格式为 `Beta v{版本号}`。
+
+### 文件头注释
+
+在 `.ts` 或 `.d.ts` 文件顶部添加文件级注释：
+
+```typescript
+/**
+ * 角色相关类型定义
+ * @since Beta v0.9.6
+ */
+```
+
+### 函数和类型定义

 ```typescript
 /**
@@ -63,10 +76,85 @@ const PostNewsTypeEnum: TGApp.BBS.Post.NewsTypeEnum = { ... };
 * @param id - 角色 ID
 */
 function getCharacter(id: number): Character;
+
+/**
+ * 角色信息对象
+ * @since Beta v0.9.6
+ */
+type Character = {
+  id: number;
+  name: string;
+};
+```
+
+### 版本更新规则
+
+当修改类型定义的子成员时（如添加字段），需要同步更新：
+1. **父级类型的 `@since`**：递增为当前项目版本（参考 `package.json`）
+2. **文件头的 `@since`**：如该文件是主要变更文件，同步更新
+
+**示例：** 项目版本从 `0.9.8` → `0.9.9`
+
+```typescript
+// 修改前
+/**
+ * 角色相关类型定义
+ * @since Beta v0.9.6
+ */
+
+/**
+ * 角色信息对象
+ * @since Beta v0.9.6
+ */
+type Character = {
+  id: number;
+  name: string;
+};
+
+// 修改后 - 添加新字段
+/**
+ * 角色相关类型定义
+ * @since Beta v0.9.9  // 文件头同步更新
+ */
+
+/**
+ * 角色信息对象
+ * @since Beta v0.9.9  // 父级类型递增
+ */
+type Character = {
+  id: number;
+  name: string;
+  element: string; // 新增字段
+};
 ```

 常用标签：`@param` `@returns` `@remarks` `@see` `@example` `@deprecated`

+## 函数定义
+
+**优先使用 `function` 关键字定义函数，而不是箭头函数赋值给 `const`**
+
+```typescript
+// ✅ 正确 - 使用 function 关键字
+function getUser(id: number): UserProfile {
+  return { id, name: "User" };
+}
+
+async function loadData(): Promise<void> {
+  await fetch("/api/data");
+}
+
+// ❌ 错误 - 使用 const + 箭头函数（除非需要捕获 this 或用于回调）
+const getUser = (id: number): UserProfile => {
+  return { id, name: "User" };
+};
+```
+
+**例外情况（可以使用箭头函数）：**
+- 需要捕获词法 `this` 时
+- 作为回调函数传递给其他函数时
+- 对象字面量中的方法（根据场景判断）
+
 ## 类型注解

 - 函数参数和返回值必须显式类型注解
--- a/.trae/skills/teyvat-guide/SKILL.md
+++ b/.trae/skills/teyvat-guide/SKILL.md
@@ -44,9 +44,14 @@ const GameServerEnum = <const>{
 enum GameServerEnum { ... }
 ```

-**JSDoc**: 导出函数必须包含 `@since` 标签
+**JSDoc**: 导出函数必须包含 `@since` 标签，类型定义的子成员修改时需同步更新版本号

 ```typescript
+/**
+ * 角色相关类型定义
+ * @since Beta v0.9.6
+ */
+
 /**
 * 函数描述
 * @since Beta v0.9.6
@@ -55,6 +60,35 @@ enum GameServerEnum { ... }
 */
 ```

+**版本更新规则**：当修改类型的子成员时（如添加字段），需要：
+1. 更新父级类型的 `@since` 为当前项目版本（递增）
+2. 如该文件是主要变更文件，同步更新文件头的 `@since`
+
+示例（项目版本从 0.9.8 → 0.9.9）：
+
+```typescript
+// 修改前
+/**
+ * 角色信息对象
+ * @since Beta v0.9.6
+ */
+type Character = {
+  id: number;
+  name: string;
+};
+
+// 修改后 - 添加新字段
+/**
+ * 角色信息对象
+ * @since Beta v0.9.9  // 递增版本号
+ */
+type Character = {
+  id: number;
+  name: string;
+  element: string; // 新增字段
+};
+```
+
 **Import 顺序**: 1. 内置模块 2. 外部包 3. 别名 (@/*) 4. 相对导入

 ### Vue 规范
--- a/.trae/skills/typescript-standards/SKILL.md
+++ b/.trae/skills/typescript-standards/SKILL.md
@@ -57,7 +57,7 @@ const result: string = getValue();
 const el: HTMLInputElement = <HTMLInputElement>document.getElementById('id');
 const data = <MyDataType>unknownValue;

-// ✅ 正确 - 函数参数和返回值
+// ✅ 正确 - 函数定义优先使用 function 关键字
 function getUser(id: number): UserProfile {
  return { id, name: "User" };
 }
@@ -66,6 +66,11 @@ function getUser(id: number): UserProfile {
 const value = someValue as string;
 const result = getValue() as string;

+// ❌ 错误 - 使用 const 定义函数（优先使用 function）
+const getUser = (id: number): UserProfile => {
+  return { id, name: "User" };
+};
+
 // ❌ 错误 - 缺少类型注解
 function getUser(id): UserProfile {
  return { id, name: "User" };
@@ -110,7 +115,36 @@ interface UserProfile {
 }
 ```

-### 5. 类型注解规范
+### 5. 函数定义规范
+
+**优先使用 `function` 关键字定义函数，而不是箭头函数赋值给 `const`**
+
+```typescript
+// ✅ 正确 - 使用 function 关键字
+function getUser(id: number): UserProfile {
+  return { id, name: "User" };
+}
+
+async function loadData(): Promise<void> {
+  await fetch("/api/data");
+}
+
+// ❌ 错误 - 使用 const + 箭头函数（除非需要捕获 this 或用于回调）
+const getUser = (id: number): UserProfile => {
+  return { id, name: "User" };
+};
+
+const loadData = async (): Promise<void> => {
+  await fetch("/api/data");
+};
+```
+
+**例外情况（可以使用箭头函数）：**
+- 需要捕获词法 `this` 时
+- 作为回调函数传递给其他函数时
+- 对象字面量中的方法（根据场景判断）
+
+### 6. 类型注解规范

 - 函数参数和返回值必须显式类型注解
 - 使用 `unknown` 而非 `any`
@@ -135,18 +169,64 @@ function getUser(id): UserProfile { // 缺少参数类型
 }
 ```

-### 6. JSDoc 注释
+### 7. JSDoc 注释

 - 所有导出函数必须包含 `@since` 标签
 - 枚举常量需要 `@see` 标签
+- 类型定义的子成员修改时，需同步更新父级类型和文件头的 `@since` 版本号

 ```typescript
+/**
+ * 角色相关类型定义
+ * @since Beta v0.9.6
+ */
+
 /**
 * 获取角色信息
 * @since Beta v0.9.6
 * @param id - 角色 ID
 */
 function getCharacter(id: number): Character;
+
+/**
+ * 角色信息对象
+ * @since Beta v0.9.6
+ */
+type Character = {
+  id: number;
+  name: string;
+};
+```
+
+**版本更新规则：**
+
+当修改类型的子成员时（如添加字段），需要：
+1. 更新父级类型的 `@since` 为当前项目版本（递增）
+2. 如该文件是主要变更文件，同步更新文件头的 `@since`
+
+示例（项目版本从 0.9.8 → 0.9.9）：
+
+```typescript
+// 修改前
+/**
+ * 角色信息对象
+ * @since Beta v0.9.6
+ */
+type Character = {
+  id: number;
+  name: string;
+};
+
+// 修改后 - 添加新字段
+/**
+ * 角色信息对象
+ * @since Beta v0.9.9  // 递增版本号
+ */
+type Character = {
+  id: number;
+  name: string;
+  element: string; // 新增字段
+};
 ```

 ## ESLint 规则对应
--- a/.trae/skills/typescript-standards/tsdoc.md
+++ b/.trae/skills/typescript-standards/tsdoc.md
@@ -8,15 +8,106 @@

 ### `@since` - 版本信息

-所有导出类型、函数、枚举必须包含：
+所有导出类型、函数、枚举必须包含 `@since` 标签，版本号格式为 `Beta v{版本号}`。
+
+#### 1. 文件头注释
+
+在 `.ts` 或 `.d.ts` 文件顶部添加文件级注释，说明文件整体信息：

 ```typescript
 /**
+ * 角色相关类型定义
 * @since Beta v0.9.6
 */
+```
+
+#### 2. 函数定义
+
+所有导出函数必须包含：
+
+```typescript
+/**
+ * 获取角色信息
+ * @since Beta v0.9.6
+ * @param id - 角色 ID
+ * @returns 角色信息对象
+ */
 function getCharacter(id: number): Character;
 ```

+#### 3. 类型定义
+
+类型定义（type/interface）必须包含：
+
+```typescript
+/**
+ * 角色信息对象
+ * @since Beta v0.9.6
+ */
+type Character = {
+  id: number;
+  name: string;
+};
+```
+
+#### 4. 子成员版本更新
+
+当修改类型定义的子成员时，需要同步更新：
+- 父级类型的 `@since` 版本号（递增）
+- 文件头的 `@since` 版本号（如该文件是主要变更文件）
+
+**示例：**
+
+假设项目当前版本为 `0.9.8`（见 `package.json`），修改类型后应更新为 `0.9.9`：
+
+```typescript
+// 修改前（v0.9.8）
+/**
+ * 角色信息对象
+ * @since Beta v0.9.6
+ */
+type Character = {
+  id: number;
+  name: string;
+};
+
+// 修改后（v0.9.9）- 添加了新字段
+/**
+ * 角色信息对象
+ * @since Beta v0.9.9
+ */
+type Character = {
+  id: number;
+  name: string;
+  element: string; // 新增字段
+};
+```
+
+**文件头同步更新示例：**
+
+```typescript
+// 修改前
+/**
+ * 角色相关类型定义
+ * @since Beta v0.9.6
+ */
+
+// 修改后（如该文件是主要变更）
+/**
+ * 角色相关类型定义
+ * @since Beta v0.9.9
+ */
+```
+
+#### 5. 版本号规则
+
+| 场景 | 版本号 |
+|------|--------|
+| 新增文件 | 使用当前项目版本 |
+| 修改类型/函数 | 递增版本号（如 0.9.8 → 0.9.9） |
+| 修改子成员 | 父级类型和文件头同步递增 |
+| 重构无变更 | 保持原版本号 |
+
 ## 常用标签

 | 标签 | 用途 |