diff --git a/.trae/rules/typescript-rules.md b/.trae/rules/typescript-rules.md index b4103dde..e11d2194 100644 --- 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 { + await fetch("/api/data"); +} + +// ❌ 错误 - 使用 const + 箭头函数(除非需要捕获 this 或用于回调) +const getUser = (id: number): UserProfile => { + return { id, name: "User" }; +}; +``` + +**例外情况(可以使用箭头函数):** +- 需要捕获词法 `this` 时 +- 作为回调函数传递给其他函数时 +- 对象字面量中的方法(根据场景判断) + ## 类型注解 - 函数参数和返回值必须显式类型注解 diff --git a/.trae/skills/teyvat-guide/SKILL.md b/.trae/skills/teyvat-guide/SKILL.md index caef16c1..509e1800 100644 --- a/.trae/skills/teyvat-guide/SKILL.md +++ b/.trae/skills/teyvat-guide/SKILL.md @@ -44,9 +44,14 @@ const GameServerEnum = { 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 规范 diff --git a/.trae/skills/typescript-standards/SKILL.md b/.trae/skills/typescript-standards/SKILL.md index ac6e56e9..e62ad30c 100644 --- 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 = document.getElementById('id'); const data = 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 { + await fetch("/api/data"); +} + +// ❌ 错误 - 使用 const + 箭头函数(除非需要捕获 this 或用于回调) +const getUser = (id: number): UserProfile => { + return { id, name: "User" }; +}; + +const loadData = async (): Promise => { + 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 规则对应 diff --git a/.trae/skills/typescript-standards/tsdoc.md b/.trae/skills/typescript-standards/tsdoc.md index 18a1cfa1..f78bd82a 100644 --- 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) | +| 修改子成员 | 父级类型和文件头同步递增 | +| 重构无变更 | 保持原版本号 | + ## 常用标签 | 标签 | 用途 |