TypeSpec 样式指南:命名约定与代码布局规范(Style Guide)

原创2026-09-18 23:33:311,702 阅读
文章标签:编程语言编译器后端

TypeSpec 样式指南:命名约定与代码布局规范(Style Guide)

本文档是 TypeSpec 语言官方推荐的规范编码指南,完整收录 TypeSpec 标准库(TypeSpec Core)实际采用的一套命名约定与布局约定,可直接用于团队、组织或公司级 TypeSpec 工程代码库。读完本文,你将掌握 TypeSpec 各类语法元素的命名法则(camelCase / PascalCase / kebab-case 的适用场景)、2 空格缩进与花括号排版等布局细节、Model 属性分组排布技巧,以及如何借助内置格式化器(tsp format)、Prettier 插件和编辑器配置将这些规范一键落地并纳入 CI 强制校验。

命名约定(Naming Convention)

TypeSpec 作为一门专注于 API 定义的语言,对不同类型的语法元素采用差异化的命名策略。下表是 TypeSpec Core 库自身使用的推荐命名方式:

类型 命名方式 示例
scalar(标量) camelCase scalar uuid extends string;
model(模型) PascalCase model Pet {}
model property(模型属性) camelCase model Pet {furColor: string}
enum(枚举) PascalCase enum Direction {}
enum member(枚举成员) camelCase enum Direction {up, down}
namespace(命名空间) PascalCase namespace Org.PetStore
interface(接口) PascalCase interface Stores {}
operation(操作) camelCase op listPets(): Pet[];
operation params(操作参数) camelCase op getPet(petId: string): Pet;
unions(联合类型) PascalCase union Pet {cat: Cat, dog: Dog}
unions variants(联合变体) camelCase union Pet {cat: Cat, dog: Dog}
alias(别名) 视上下文用 camelCase 或 PascalCase alias myString = string 或 alias MyPet = Pet
decorators(装饰器) camelCase @format、@resourceCollection
functions(函数) camelCase addedAfter
文件名 kebab-case my-lib.tsp
template parameter(模板参数) PascalCase <ExampleParameter>

规则背后的设计意图

  • 类型 vs 值:凡代表"类型"的声明(model、enum、interface、union、scalar、模板参数)统一使用 PascalCase,便于在阅读代码时一眼区分类型与普通值;而属性、操作、参数、枚举成员等"值"层面的元素使用 camelCase。
  • namespace 采用 PascalCase:TypeSpec 的命名空间常用于表达如 Org.PetStore 这样的组织/业务归属,PascalCase 并支持点号分段。
  • alias 灵活处理:别名没有固定的范式,取决于其语义——当它是值的别名时用 camelCase(alias myString = string),当它代表一个类型时用 PascalCase(alias MyPet = Pet)。
  • 文件名统一 kebab-case:.tsp 源文件一律使用短横线分隔的小写命名,例如 my-lib.tsp。

需要刻意避免的"匈牙利前缀"惯例

在部分面向对象语言中,人们习惯用前缀字母标识类型归属,例如用 I 前缀表示接口(IPet),或用 T 前缀表示模板参数(TResponse)。在 TypeSpec 中不推荐这种做法——TypeSpec 的类型与模板参数已经是语言级的一等公民,遵循上表的命名规则即可自然区分,无需额外前缀,这也与 TypeSpec 本身的风格惯例保持一致。

与标识符语法规则的衔接

命名约定要真正生效,首先得保证名字合法。TypeSpec 标识符必须以字母(a-z、A-Z)、emoji、下划线(_)或美元符号($)开头,后续可包含字母、数字、emoji、下划线或美元符号,长度至少 1 个字符,并完整支持 Unicode 字符(遵循 UAX31-R1b stable identifiers 的 emoji profile,详见 标识符文档)。当确实需要使用保留字或非常规字符时,可用反引号转义,例如 model `enum` {}。

布局约定(Layout Convention)

TypeSpec 内置格式化器(built-in formatter),所有布局规则都由它在格式化时统一落实。其使用方式详见 格式化器章节。以下是官方推荐的布局规则:

1. 使用 2 空格缩进

// bad
model Pet {
    name: string;
}

// good
model Pet {
  name: string;
}

2. 左花括号前放置一个空格

// bad
model Pet{
  name: string;
}

// good
model Pet {
  name: string;
}

3. 块起始左花括号 { 应放在同一行

// bad
model Pet
{
  name: string;
}

// good
model Pet {
  name: string;
}

4. 块与块之间添加空行

// bad
model Pet {
  name: string;
}
model Cat extends Pet {}

// good
model Pet {
  name: string;
}

model Cat extends Pet {}

5. 操作/装饰器/函数名与参数列表之间不留空格

注意:这条规则对装饰器同样适用,@doc 与括号之间不能有空格。

// bad
op list (filter: string): Pet[];

// bad
@doc ("This is a pet")

// good
op list(filter: string): Pet[];

// good
@doc("This is a pet")

6. 括号内不要添加空格

// bad
op list( filter: string ): Pet[];

// good
op list(filter: string): Pet[];

7. 花括号内侧添加空格(对象字面量场景)

// bad
alias foo = {type: "cat"};

// good
alias foo = { type: "cat" };

8. 方括号内不要添加空格

// bad
alias foo = [ 1, 2, 3 ];

// good
alias foo = [1, 2, 3];

9. 所有注释以空格开头

//bad

// good

10. 避免行尾的尾随空格

行尾不要残留空白字符,保持 diff 干净。

Model 布局细则

除通用布局规则外,Model 内部还有两条专门的排布原则:

属性之间应紧贴,除非它们带有装饰器或注释:

// bad
model Foo {
  one: string;

  two: string;

  three: string;
}

// good
model Foo {
  one: string;
  two: string;
  three: string;
}

带有前置注释或装饰器的属性,需要用空行与其他属性分隔包裹:

// bad
model Foo {
  one: string;
  @doc("Foo")
  two: string;
  // line comment
  three: string;
  /**
   *  Block comment
   */
  four: string;
  five: string;
}

// good
model Foo {
  one: string;

  @doc("Foo")
  two: string;

  // line comment
  three: string;

  /**
   *  Block comment
   */
  four: string;

  five: string;
}

这样处理可以让装饰器、文档注释与其所修饰的属性在视觉上成为一个整体,同时避免注释被错误地"粘"到相邻属性上。

用内置格式化器一键落地规范

样式指南本身是"纸面规则",TypeSpec 真正的工作方式是用格式化器自动产出符合规范的代码,避免人工校对。格式化器支持三种接入方式(详见 格式化器文档):

方式一:通过 CLI

格式化所有 TypeSpec 文件:

tsp format "**/*.tsp"

仅检查格式而不修改文件(适合 CI 强制校验):

tsp format --check "**/*.tsp"

方式二:通过 VS Code / Visual Studio 扩展

安装 TypeSpec 官方扩展后,格式化器自动可用;在 .tsp 文件中按编辑器默认格式化快捷键 alt+shift+F 即可格式化整个文档。

方式三:作为 Prettier 插件

@typespec/prettier-plugin-typespec 把 TypeSpec 格式化器包装成标准 Prettier 插件。如果项目中已有 Prettier 流水线,可直接把 TypeSpec 纳入进来(插件源码见 prettier-plugin-typespec):

npm install --save-dev prettier @typespec/prettier-plugin-typespec
plugins:
  - "./node_modules/@typespec/prettier-plugin-typespec"
overrides: [{ "files": "*.tsp", "options": { "parser": "typespec" } }]

随后即可用 Prettier 命令格式化全部 .tsp 文件:

./node_modules/.bin/prettier --write '**/*.tsp'

若项目根目录存在 .prettierrc.yaml、.prettierrc.json 等 Prettier 配置文件,格式化器会读取其中配置;未显式配置时默认采用 TypeSpec 样式指南规则。注意:该配置只影响格式化输出,使用 tab 键缩进时仍遵循编辑器自身配置,因此建议同时配置编辑器。

编辑器配套配置

VS Code(.vscode/settings.json):

{
  "[typespec]": {
    "editor.detectIndentation": false,
    "editor.insertSpaces": true,
    "editor.tabSize": 2
  }
}

EditorConfig(配合 editor config 扩展,.editorconfig):

[*.tsp]
indent_size = 2
indent_style = space

源码视角:格式化器如何工作

为了让样式指南真正"可执行",TypeSpec 编译器内部将其实现为基于 Prettier 架构的格式化器。相关实现位于 packages/compiler/src/formatter:

  • formatter/index.ts 将 TypeSpec 声明为 Prettier 的一个语言(SupportLanguage)与解析器:扩展名为 .tsp,astFormat 为 typespec-format,locStart/locEnd 直接映射到 AST 节点的 pos/end 文本区间,从而让 Prettier 能精确定位每个语法节点;
  • formatter/parser.ts 复用编译器核心解析器(../core/parser.js 的 parse),以 comments: true, docs: true 模式解析源码,并将文档注释从普通注释中剥离单独处理;
  • formatter/print/printer.ts 是约两千行的打印器,借助 Prettier 的 group、indent、hardline、conditionalGroup 等文档构建原语,把 AST 按 2 空格缩进、花括号同行、括号内不留空格等规则重新排版输出。

从源码结构可以推断:格式化器走的是"完整解析 → AST → 重新打印"的管道,因此任何语法上合法的 TypeSpec 文件都能被稳定地归一化为规范格式,这正是样式指南能作为团队强制标准的前提。同样地,packages/compiler/src/casing/index.ts 中提供的 capitalize 等大小写工具,也为代码生成等场景处理命名转换提供了基础设施。

常见问题与最佳实践

  • 规范是"建议"而非"硬约束":文档开头的说明明确指出,本指南的规则被 TypeSpec Core 库自身采用,团队可以按需采纳或调整。核心目标是在项目、团队、组织或公司代码库内部保持一致性(consistency)与可读性(readability),而不是强制所有外部项目遵循同一套风格。
  • 让机器代替人校对:强烈建议在 CI 中加入 tsp format --check "**/*.tsp",或在 Prettier 流水线中对 *.tsp 做格式校验,从源头阻止不符合样式指南的代码合入。
  • 编辑器与 CLI 保持一致:配置好 VS Code / EditorConfig 的 2 空格设置后,手动编辑时的体验才会与 tsp format 的输出完全对齐,避免"保存前格式化"与"CI 校验"结果不一致。
  • 命名先行,格式随后:先按命名约定表确定每个声明元素的名称(类型用 PascalCase、值用 camelCase、文件用 kebab-case),再用格式化器统一排版,两者结合才能产出一致、干净、可维护的 TypeSpec 规范。
登录后查看全文
typespec