TypeSpec 样式指南:命名约定与代码布局规范(Style Guide)
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 规范。