TypeSpec：一种受TypeScript启发的实用的API定义语言

最近，微软工程师正式发布了 TypeSpec。这是一种新语言，专门为以 API 为中心的开发量身定制，可以解决现代 API 设计的复杂需求。TypeSpec 是一种开源、可扩展的语言，其灵感来自 TypeScript 和 C#。它支持各种协议和序列化格式，使开发人员使用一个工具就可以管理多种 API 规范。

TypeSpec 使用支持的协议或序列化格式描述 API。它采用了简洁的语法，并提供了 Visual Studio 和 VS Code 编辑器工具。使用 TypeSpec，开发人员可以将常见的数据类型、API 模式和 API 指南封装到高层可重用组件中，实现跨团队或生态系统共享。

示例：TypeSpec 规范及生成的 OpenAPI schema（来源）

定义好规范之后，开发人员就可以将其编译为符合标准的 OpenAPI、JSON Schema、Protobuf 或三者同时。

该语言具有很高的可扩展性，支持自定义修饰词表和类型模板，使开发人员可以根据特定的业务或应用程序逻辑域定制 API。TypeSpec 还允许通过 NPM 创建和分发包，从而促进生态系统的发展。这些包既可以在组织内部使用，也可以在更广泛的开发社区里共享。

在微软内部，TypeSpec 得到了积极应用，尤其是 Azure 服务和 Microsoft Graph 团队。通过在开发过程中使用 TypeSpec，微软工程师提高了在其他实际场景中使用 TypeSpec 进行 API 开发的可靠性和效率。

Brian Terlson 是微软 Azure 开发体验首席软件架构师，也是 TypeSpec 和 Azure JavaScript SDK 的架构师。自 2019 年以来，他就一直在从事与 TypeSpec 相关的工作。Brian 说：“由于我们一直在对 TypeSpec 进行迭代和改进，所以我们认为现在是时候从更广泛的 API 开发社区获得更多的反馈了。”他指出，TypeSpec 团队”渴望得到更多的反馈，从而更好地理解 1.0 版本应该优先提供什么。”

InfoQ 采访了 Terlson，谈了 TypeSpec、它的价值主张以及它与其他类型定义语言的区别。

Brian Terlson：TypeSpec 源于我们在 Azure 中大规模交付服务的经验。在这种情况下，服务和团队很多，我们需要一个解决方案来帮助开发人员快速创建一致的高质量 API。

TypeSpec 有几个方面是独一无二的。首先，我们将重点放在了支持 API 抽象上，为的是 API 设计人员可以构建可重用 API 组件库。在规模很大时，这一点很重要。在 Azure，我们广泛依赖于这一点，降低开发成本、审查成本和服务规范的复杂性，同时提高 API 质量和一致性。

其次，TypeSpec 是协议无关的。它支持随库添加的特定协议或序列化格式。这使得 TypeSpec 可以作为不止一个协议的单一事实来源。开发人员和应用程序越来越多地使用多语言，在涉及跨多种语言和协议的实现时，这一点尤其有价值。

最后是开发人员熟悉度：TypeSpec 的灵感来自现有的语言，主要是 TypeScript，也有 C#，所以许多开发人员都会觉得我们的语言是他们所熟悉的。此外，在扩展性和打包方面，我们使用了 JavaScript，它带来了强大的功能，而且不需要开发人员学习新东西。

Terlson：TypeSpec 的目标是降低构建和使用 API 的成本，使它们更实用。优先构建 API，可以带来许多可扩展性和 API 质量方面的优势。

API 优先的方法支持跨若干应用程序栈的生成代码，并将流程中的审查和治理职责前移，提高了可扩展性，降低了变更成本。

此外，它还能够将常见的 API 外形抽象为可重用的组件，使开发人员可以做最简单的事，使架构师可以做正确的事，两者实现了有效的统一。在这两种情况下都应该使用组件。

TypeSpec 还致力于实现与 OpenAPI 等 API 描述格式的互操作。因此，在现有的工具链上就可以获得这些好处。

Terlson： 现在，我们正在努力构建 1.0 的稳定版本，包括将 Azure SDK 的代码生成技术转移到 TypeSpec 项目中，希望社区在此之前继续为我们提供反馈。

对于这项技术，我们感到非常自豪。人们开始使用它生成 API 客户端和服务器，我们为此感到兴奋。

我们将继续构建这门语言，比如使其能够定义特定的值，并使用这些值来定义诸如 API 示例之类的东西。我们还添加了新的库特性，比如定义流和事件 API，以支持服务器发送事件和流式 JSONL 等。

长远来看，在很大程度上，我们的工作取决于我们从社区获得的反馈。我们希望在语言中添加更多的功能用于描述新的 API 类型，扩展标准库从而支持新的协议、序列化格式和标准数据形状，并进行代码生成方面的创新，使它可以在软件生态系统的更多地方使用。

欢迎访问我们的 GitHub(https://github.com/microsoft/typespec)，告诉我们你的想法！

原文链接：

https://www.infoq.com/news/2024/05/typespec/

声明：本文为 InfoQ 翻译，未经许可禁止转载。