⚡

TypeScript编码标准 TypeScriptCodingStandards

TypeScript编码标准技能提供了一套全面的指南，用于编写类型安全、可维护的代码。涵盖严格配置、命名约定、类型定义、错误处理、异步模式和环境验证，适用于前后端开发，旨在提高代码质量、减少错误并增强团队协作。关键词：TypeScript, 编码标准, 类型安全, 错误处理, 异步编程, 环境验证, 代码质量, 软件工程。

架构设计 0 次安装 0 次浏览 更新于 3/5/2026

name: TypeScript Coding Standards description: TypeScript开发的专家级框架，包括严格配置、类型安全、命名约定、错误处理、异步模式和环境验证。

TypeScript编码标准

概述

TypeScript编码标准提供了全面的指南，用于编写类型安全、可维护的代码。此技能涵盖严格的TypeScript配置、命名约定、类型定义、错误处理模式、async/await最佳实践、实用类型、依赖注入以及适用于后端（Node.js）和前端（Next.js）项目的环境变量验证。

为什么重要

  • 提高代码质量：类型提示和验证能早期捕获错误；严格模式确保代码一致性和可读性
  • 减少错误：全面的错误处理和适当验证防止运行时异常和数据损坏
  • 增强可维护性：清晰的代码模式和适当抽象使代码更易于理解、修改和扩展
  • 启用更好的工具支持：类型提示改善IDE自动补全和错误检测；linter自动捕获问题
  • 支持AI/ML开发：现代TypeScript模式（异步、类型提示、数据类）对AI/ML工作流至关重要
  • 促进团队协作：一致的编码标准使代码审查更有效，新成员入职更顺畅

核心概念

1. TypeScript配置

为类型安全设置严格模式：

  • 严格模式：启用所有严格类型检查选项
  • 目标与模块：后端使用ES2022和NodeNext，前端使用bundler
  • 路径别名：配置@/*以实现干净导入
  • 声明映射：启用源映射以改善调试
  • 无未使用项：消除未使用的局部变量和参数
  • 未检查的索引访问：防止数组/索引访问错误
  • 精确可选属性：区分缺失和未定义属性

2. 命名约定

整个代码库的一致命名：

  • 变量和函数：camelCase（getUser、processData）

  • 类型、接口、类：PascalCase（User、UserService、ApiClient）

  • 常量：SCREAMING_SNAKE_CASE用于真正常量（API_KEY、MAX_RETRIES）

  • 布尔值：is/has/can/should前缀（isLoading、hasPermission）

  • 事件处理器：handle/on前缀（handleClick、onSubmit）

  • 文件：组件用PascalCase，工具用camelCase，类型用.types.ts

3. 类型定义

正确使用类型系统：

  • 避免any：对动态数据使用特定类型或unknown
  • 接口 vs 类型：使用接口用于对象形状和扩展，类型用于联合和映射类型
  • 泛型：使用带约束的描述性名称（TEntity、TResult）
  • 鉴别联合：标签联合用于状态管理和API操作
  • 类型守卫：自定义守卫用于运行时类型窄化

4. 错误处理模式

结构化错误管理：

  • 自定义错误类：继承AppError并带有状态码的层次结构
  • 结果类型：使用Ok/Err模式的函数式错误处理
  • 错误边界：服务错误处理的包装函数
  • Try-Catch模式：适当的错误日志和上下文保留
  • 操作错误 vs 程序员错误：区分预期和意外错误

5. API响应模式

一致的API响应：

  • 基础响应：success、meta（时间戳、请求ID、版本）
  • 成功响应：data字段带有类型化内容
  • 错误响应：code、message、details、stack（仅开发环境）
  • 分页响应：items带有分页元数据
  • 响应辅助函数：创建一致响应的函数

6. Async/Await最佳实践

正确的异步编程：

  • 无即发即弃：始终处理Promise
  • 并行执行：使用Promise.all进行独立操作
  • 部分失败：使用Promise.allSettled进行批处理操作
  • 控制并发：使用p-limit限制并发操作
  • 超时处理：使用withTimeout或AbortController
  • 重试模式：对瞬时故障使用指数退避

7. 实用类型

高级类型操作：

  • 深度Partial：嵌套可选字段
  • 必填字段：使特定字段必填
  • Nullable/NonNullable：字段可空性工具
  • Extract/Filter：按值类型过滤类型
  • 函数类型：异步返回类型、函数签名
  • 构建器类型：可变/不可变类型
  • 路径类型：类型安全嵌套对象访问

8. 依赖注入模式

通过DI实现松散耦合：

  • 构造函数注入：通过构造函数传递依赖
  • 工厂模式：带有容器模式的服务工厂
  • 函数式DI：依赖作为函数参数
  • 测试：单元测试的模拟实现

9. 环境变量验证

类型安全环境配置：

  • Zod模式：验证所有环境变量
  • 类型推断：从验证模式推断类型
  • 环境特定配置：开发/生产的单独配置
  • 默认值：带验证的合理默认值
  • 快速失败：在无效环境配置时退出

10. 导入组织

一致的导入结构：

  • 导入顺序：Node内置、外部依赖、内部别名、仅类型导入、相对导入
  • 仅类型导入：使用import type减少打包大小
  • 桶文件：索引导出以实现干净导入
  • 路径别名：配置@/以实现干净导入

快速开始

  1. 配置TypeScript：设置tsconfig.json并启用严格模式
  2. 配置ESLint：设置TypeScript ESLint并推荐规则
  3. 配置Prettier：设置代码格式化
  4. 定义命名约定：文档化和强制执行命名模式
  5. 创建类型定义：在专用.types.ts文件中定义类型
  6. 实现错误处理：创建自定义错误类层次结构
  7. 设置响应辅助函数：创建标准API响应函数
  8. 配置环境变量：设置Zod验证环境变量
  9. 编写TypeScript代码：使用严格类型、避免any、显式返回类型
  10. 设置CI/CD：配置类型检查、linting和测试流水线
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "resolveJsonModule": true,
    "moduleResolution": "NodeNext"
  }
}

生产清单

  • [ ] TypeScript配置并启用严格模式
  • [ ] ESLint配置并包含TypeScript规则
  • [ ] Prettier配置并集成
  • [ ] 命名约定文档化和强制执行
  • [ ] 类型定义在专用.types.ts文件中
  • [ ] 自定义错误类层次结构实现
  • [ ] API响应辅助函数创建
  • [ ] 环境变量使用Zod验证
  • [ ] 代码库中无any类型（使用unknown代替）
  • [ ] 显式函数返回类型
  • [ ] 运行时类型窄化的类型守卫
  • [ ] 正确使用async/await（无即发即弃）
  • [ ] 服务的依赖注入
  • [ ] 遵循导入顺序约定
  • [ ] 适当使用仅类型导入
  • [ ] CI/CD流水线包含类型检查和linting
  • [ ] >95%类型覆盖目标达成

反模式

  1. 使用any类型：违背TypeScript目的；使用特定类型或unknown
  2. 隐式Any：不指定类型导致未检查代码
  3. 跳过类型注解：没有显式类型，IDE支持受限
  4. 不使用严格模式：缺少严格模式允许不安全代码模式
  5. 错误处理不当：通用catch块隐藏错误和上下文
  6. 命名不一致：混合命名约定降低可读性
  7. 不测试类型：TypeScript错误应在开发期间捕获
  8. 即发即弃Promise：未处理Promise导致静默失败
  9. 过度使用类型断言：强制转换绕过类型安全
  10. 循环依赖：导致构建问题和耦合

集成点

  • TypeScript文档：TypeScript手册 和 TypeSpec
  • Linting：ESLint与TypeScript ESLint用于代码质量
  • 格式化：Prettier用于一致代码格式化
  • 验证：Zod用于运行时类型验证
  • 测试：Jest、Vitest用于TypeScript测试
  • 构建工具：Vite、esbuild、tsup用于TypeScript编译
  • 框架集成：Next.js、NestJS、Express用于TypeScript框架
  • api-design 用于API类型定义
  • code-review 用于审查TypeScript代码

进一步阅读