code-style-typescript

TypeScript 代码风格指南

适用场景

• 编写新的 TypeScript 代码时
• 审查 .ts 文件时
• 重构现有代码时
• 为 TypeScript 生成代码片段、示例或文档时
• 处理 Markdown、Vue.js 等文件中的 TypeScript 代码块时
• 格式化或清理代码时

规则

所有规则的完整代码示例见 references/examples.md。

规则：语句末尾不加分号

语句末尾不要加分号。

例外：TypeScript 接口、类型及类似类型定义中，属性之间必须使用分号分隔。

// Statements - no semicolons
const result = calculateValue()

// Interfaces - semicolons required
interface User {
  id: number;
}

type Config = {
  timeout: number;
}

更多内容请参阅 示例 → 不加分号。

规则：条件语句中不调用方法

在条件语句（if、while、for 等）中使用方法调用前，先将其提取到单独的变量中。

请参阅 示例 → 不调用方法。

规则：在类型化代码中显式检查是否存在

检查类型化值是否存在时，使用 value === undefined、value !== undefined、value === null 或 value === '' 等显式比较。

在常规应用代码中，不要依赖真值／假值收窄来检查是否存在。

请参阅 示例 → 显式存在性检查。

规则：不将函数调用用作参数

将函数调用用作其他函数的参数前，先将其提取到单独的变量中。

例外：在少数情况下（例如验证器架构、DSL 配置、查询构建器、匹配器 API），如果嵌套调用有助于提高可读性，则将其分行书写。请参阅 示例 → 嵌套函数调用。

请参阅 示例 → 不将函数调用用作参数。

规则：单行声明放在一起，多行声明分开

单行 const 和 let 声明应放在一起，中间不留空行。从单行声明切换到多行声明，或在不同的多行声明之间，应添加空行。

请参阅 示例 → 将单行声明放在一起。

规则：局部名称中不使用含义不清的缩写

使用清晰的局部变量名。如果完整单词更简短、更清楚，请避免使用 pv、prop、cat 或 cfg 等不易理解的缩写。

id、db、URL 和 HTML 等常见技术标识符可以使用。

请参阅 示例 → 清晰的局部名称。

规则：单行 JSDoc 注释放在同一行

单行 JSDoc 注释应与 /** 和 */ 写在同一行。

请参阅 示例 → 单行 JSDoc 注释。

规则：对象键排序

简写属性排在前面，常规属性排在后面。两组属性均按字母顺序排序。

const config = {
  isActive,
  timeout,
  apiKey: 'secret-key',
  baseUrl: 'https://api.example.com'
}

完整示例请参阅 示例 → 对象键排序。

规则：展开包含多个值的对象和数组字面量

单键对象和单项数组可以写在一行。包含多个键的对象和包含多个项的数组应每项单独一行。

请参阅 示例 → 展开包含多个值的字面量。

规则：多行对象值之间留空行

对象中的多行值之间应留空行。

请参阅 示例 → 分隔多行对象值。

规则：不使用尾随逗号

绝不在数组、对象或其他结构中使用尾随逗号。

请参阅 示例 → 不使用尾随逗号。

规则：在 return 之前计算派生数据

当处理程序或函数需要派生数据时，应先将其计算到单独的变量中，并让最终的 return 保持简单明确。

如果显式对象更清晰，就不要仅为了替换一个字段而通过 ...spread 重建对象。

参见 示例 → 在 return 之前计算派生数据。

规则：多行代码块与末尾的 return 之间空一行

多行代码块（if/else、循环、try/catch、函数等）应与其他代码之间空一行，除非它们位于父代码块的开头或结尾。如果同一代码块中前面还有语句，则在 return 之前也添加空行。

参见 示例 → 分隔多行代码块。

规则：扁平的接口结构

每个 interface（以及命名的 type 别名）都必须只有一层命名属性。如果某个属性的类型是对象结构，应将其提取为单独的命名接口。

// ✅ Correct - extracted interfaces
interface Brand {
  name: string;
  slug: string;
}

interface Item {
  brand: Brand;
  id: string;
  name: string;
}

// ❌ Wrong - nested object shapes inline
interface Item {
  id: string;
  brand: { name: string; slug: string; };
  name: string;
}

参见 示例 → 扁平的接口结构，了解深度嵌套的示例。