企业官网建设流程全解析

TypeSpec 样式指南：命名约定与代码布局规范（Style Guide）

【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec

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

命名约定（Naming Convention）

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

规则背后的设计意图

• 类型 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项目地址: https://gitcode.com/GitHub_Trending/ty/typespec