---
description: 前端应用的 TypeScript 编码标准和最佳实践
---

# TypeScript 最佳实践

## 类型系统
- 对对象定义优先使用 interface 而非 type
- 对联合类型、交叉类型和映射类型使用 type
- 避免使用 `any`，对未知类型优先使用 `unknown`
- 使用严格的 TypeScript 配置
- 利用 TypeScript 的内置工具类型
- 对可复用的类型模式使用泛型

## 命名约定
- 对类型名称和接口使用 PascalCase
- 对变量和函数使用 camelCase
- 对常量使用 UPPER_CASE
- 使用带辅助动词的描述性名称（例如 isLoading, hasError）
- React props 的接口前缀使用 'Props'（例如 ButtonProps）

## 代码组织
- 将类型定义保持在使用位置附近
- 共享时从专用类型文件导出类型和接口
- 使用桶导出（index.ts）组织导出
- 将共享类型放在 `types` 目录中
- 将组件 props 与其组件放在一起

## 函数
- 对公共函数使用显式返回类型
- 对回调和方法使用箭头函数
- 使用自定义错误类型实现适当的错误处理
- 对复杂类型场景使用函数重载
- 优先使用 async/await 而非 Promises

## 最佳实践
- 在 tsconfig.json 中启用严格模式
- 对不可变属性使用 readonly
- 利用可辨识联合类型确保类型安全
- 使用类型守卫进行运行时类型检查
- 实现适当的 null 检查
- 除非必要，否则避免类型断言

## 错误处理
- 为特定领域的错误创建自定义错误类型
- 对可能失败的操作使用 Result 类型
- 实现适当的错误边界
- 使用带类型的 catch 子句的 try-catch 块
- 正确处理 Promise 拒绝

## 设计模式
- 对复杂对象创建使用建造者模式
- 对数据访问实现仓储模式
- 对对象创建使用工厂模式
- 利用依赖注入
- 使用模块模式进行封装

## 类型安全
- 使用严格的 null 检查
- 避免使用类型断言（as），除非绝对必要
- 使用类型守卫函数进行运行时验证
- 利用 TypeScript 的控制流分析
- 使用 const 断言提高类型推断

## 泛型使用
- 为可复用组件和函数使用泛型
- 为泛型参数使用有意义的名称
- 使用泛型约束限制类型参数
- 避免过度使用泛型导致代码复杂化

## 导入和导出
- 使用命名导出而非默认导出
- 按逻辑分组组织导入语句
- 使用路径别名简化导入路径
- 避免循环依赖

## 性能考虑
- 使用适当的类型推断减少类型注解
- 避免过度复杂的类型计算
- 使用类型缓存优化编译性能
- 合理使用类型断言避免性能损失