Cursor rule

1---
2globs: *.ts,*.vue
3alwaysApply: false
4---
5 
6---
7 
8description: 现代 Web 开发的 TypeScript 编码标准与最佳实践
9globs: **/\*.ts, **/_.tsx, \*\*/_.d.ts
10 
11---
12 
13# TypeScript 最佳实践
14 
15## 类型系统
16 
17- 对象定义时优先使用接口（`interface`）而非类型别名（`type`）
18- 联合类型、交叉类型及映射类型使用`type`声明
19- 避免使用`any`，未知类型优先使用`unknown`
20- 启用严格的 TypeScript 配置（`strict: true`）
21- 善用 TypeScript 内置的工具类型（如`Partial`、`Readonly`、`Pick`等）
22- 可复用的类型模式使用泛型（`generics`）实现
23 
24## 命名规范
25 
26- 类型名与接口名使用帕斯卡命名法（PascalCase，如`UserModel`）
27- 变量与函数名使用小驼峰命名法（camelCase，如`userName`）
28- 常量使用全大写下划线命名法（UPPER_CASE，如`MAX_RETRY_TIMES`）
29- 使用描述性名称并搭配辅助动词（如`isLoading`表示加载状态，`hasError`表示错误状态）
30- React 组件 props 接口前缀统一为`Props`（如`ButtonProps`）
31 
32## 代码组织
33 
34- 类型定义尽量靠近其使用位置
35- 共享类型通过独立类型文件导出（如`types/user.ts`）
36- 使用索引导出（`index.ts`）统一管理文件导出
37- 共享类型集中存放在`types`目录下
38- 组件 props 与其组件文件放在一起（如`Button.tsx`中直接定义`ButtonProps`）
39 
40## 函数规范
41 
42- 公共函数显式声明返回类型（避免隐式`any`）
43- 回调函数与方法使用箭头函数（保持`this`上下文一致性）
44- 自定义错误类型实现精细化错误处理
45- 复杂类型场景使用函数重载（`overloads`）
46- 优先使用`async/await`而非 Promise 链
47 
48## 核心原则
49 
50- `tsconfig.json`中启用严格模式（`strict: true`）
51- 不可变属性使用`readonly`修饰
52- 使用可辨识联合类型（Discriminated Unions）保障类型安全
53- 运行时类型检查使用类型守卫（`type guards`）
54- 实现严谨的空值校验（避免`undefined`/`null`遗漏）
55- 非必要不使用类型断言（`as`），优先通过类型守卫明确类型
56 
57## 错误处理
58 
59- 业务相关错误使用自定义错误类型（如`ApiError`、`ValidationError`）
60- 可能失败的操使用`Result`类型封装（如`{ success: boolean; data?: T; error?: Error }`）
61- 实现错误边界（Error Boundaries）捕获组件层异常
62- `try-catch`块中使用类型化`catch`子句（明确捕获错误的类型）
63- 正确处理 Promise 拒绝（`unhandledrejection`事件监听）
64 
65## 设计模式
66 
67- 复杂对象创建使用构建器模式（Builder Pattern）
68- 数据访问层实现仓储模式（Repository Pattern）
69- 对象创建使用工厂模式（Factory Pattern）
70- 依赖管理采用依赖注入（Dependency Injection）
71- 封装逻辑使用模块模式（Module Pattern）
72