# Nestjs Typescript Typescript General Guidelines

> 在整个项目中应用一般 TypeScript 编码标准，包括命名约定、函数结构、数据处理和异常处理。

- Skill: `liaosw97/nestjs-typescript-typescript-general-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add liaosw97/nestjs-typescript-typescript-general-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liaosw97/nestjs-typescript-typescript-general-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: liaosw97 (https://skillmd.com/u/liaosw97)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/liaosw97/nestjs-typescript-typescript-general-guidelines

---


- 对所有代码和文档使用英语。
- 始终声明每个变量和函数的类型（参数和返回值）。
- 避免使用 any。
- 创建必要的类型。
- 使用 JSDoc 记录公共类和方法。
- 不要在函数内留空行。
- 每个文件一个导出。
- 对类使用 PascalCase。
- 对变量、函数和方法使用 camelCase。
- 对文件和目录名使用 kebab-case。
- 对环境变量使用 UPPERCASE。
- 避免魔法数字并定义常量。
- 每个函数以动词开头。
- 对布尔变量使用动词。例如：isLoading、hasError、canDelete 等。
- 使用完整单词而不是缩写，并正确拼写。
  - 除了标准缩写如 API、URL 等。
  - 除了众所周知的缩写：
    - i、j 用于循环
    - err 用于错误
    - ctx 用于上下文
    - req、res、next 用于中间件函数参数
- 编写具有单一目的的短函数。少于 20 条指令。
- 用动词和其他内容命名函数。
- 如果返回布尔值，使用 isX 或 hasX、canX 等。
- 如果不返回任何内容，使用 executeX 或 saveX 等。
- 通过以下方式避免嵌套块：
  - 早期检查和返回。
  - 提取到工具函数。
- 使用高阶函数（map、filter、reduce 等）避免函数嵌套。
- 对简单函数（少于 3 条指令）使用箭头函数。
- 对非简单函数使用命名函数。
- 使用默认参数值而不是检查 null 或 undefined。
- 使用 RO-RO 减少函数参数
  - 使用对象传递多个参数。
  - 使用对象返回结果。
  - 为输入参数和输出声明必要的类型。
- 使用单一抽象级别。
- 不要滥用原始类型，将数据封装在复合类型中。
- 避免在函数中进行数据验证，使用具有内部验证的类。
- 优先使用数据的不可变性。
- 对不变的数据使用 readonly。
- 对不变的字面量使用 as const。
- 遵循 SOLID 原则。
- 优先使用组合而不是继承。
- 声明接口来定义合约。
- 编写具有单一目的的小类。
  - 少于 200 条指令。
  - 少于 10 个公共方法。
  - 少于 10 个属性。
- 使用异常处理你不期望的错误。
- 如果你捕获异常，应该是为了：
  - 修复预期的问题。
  - 添加上下文。
  - 否则，使用全局处理器。
- 对测试遵循 Arrange-Act-Assert 约定。
- 清楚地命名测试变量。
- 遵循约定：inputX、mockX、actualX、expectedX 等。
- 为每个公共函数编写单元测试。
- 使用测试替身模拟依赖项。
  - 除了执行成本不高的第三方依赖项。
- 为每个模块编写验收测试。
- 遵循 Given-When-Then 约定。