什么是 TypeSpec？

TypeSpec 是一种功能强大的灵活语言，用于设计 API。 它允许开发人员使用可扩展且易于理解的语言定义 API。 该编译使用发出器生成 API 规范、客户端代码和服务器端 API 代码。 TypeSpec 是由Microsoft开发的 开源项目 ，由社区提供支持。

TypeSpec 使你能够创建模块化的可重用组件，这些组件简洁且符合 API 准则。 标准 TypeSpec 库包括 OpenAPI 发出器，确保与现有工具和工作流兼容。

作为开源语言，TypeSpec 可以描述任何 API，而不仅仅是 Azure API。 这种多功能性使它成为 API 开发人员、架构师和经理的宝贵工具，他们需要在复杂且不断发展的环境中提供高质量的 API。

TypeSpec 的优点

• 简化 API 开发：提供一种清晰简洁的方式来定义 API，使开发人员能够专注于逻辑和功能。
• 加速部署：TypeSpec 通过单个 API 定义实现快速服务和客户端代码生成，简化部署并确保一致性。
• 确保符合性：使用可重用组件遵循既定的准则和标准，减少错误和不一致。
• 增强兼容性：包括 OpenAPI 发出器，以便与现有工具和工作流兼容，使集成更加轻松。
• 支持扩展性：灵活且可扩展，允许针对各种方案自定义和扩展 API 定义。
• 加速迁移： OpenApiMigration 工具 可简化转换为 TypeSpec 以加快采用速度。

作为 开源项目，TypeSpec 受益于社区贡献和反馈，确保基于真实用例的持续改进。

API 设计具有挑战性

TypeSpec 解决了 API 设计、治理和实现中的常见难题：

• 复杂规范：编写、审查和维护 API 规范可能比较繁琐。 即使是简单的 API 也可能导致数百行规范代码。
• 协议多样性：每个协议都有自己的规范格式，协议之间没有共享设计语言。 这一分散性使开发过程复杂化。
• 治理问题：如果没有统一的设计语言，管理 API 将变得困难，导致实现和质量不一致。
• 可伸缩性问题：随着 API 或 API 版本的增加，需要更多的工程团队，这可能会导致协调挑战和效率低下。

通过应对这些挑战，TypeSpec 简化了 API 设计过程，确保不同协议的一致性，并增强整体治理和可伸缩性。

TypeSpec API 开发工作流

下图演示了使用 TypeSpec 开发 API 所涉及的关键阶段。 此过程从两个选项开始：从头开始创建新的 API 规范或从现有 OpenAPI 规范迁移。开始后，API 使用 TypeSpec 定义，并使用其模块化和可重用组件。 然后，TypeSpec 编译器使用一组可靠的发出器来处理这些定义，以自动生成 API 规范、客户端代码和服务器端存根代码。 最后，生成的项目与现有工具链集成，确保工作流流畅且一致。

工作流步骤

TypeSpec 编译器的路径：
TypeSpec 编译器可以根据需要同时生成 OpenAPI 规范、客户端代码和服务器端存根代码的输出，同时允许你根据项目要求独立触发每个输出。

1. 生成 OpenAPI 规范
   OpenAPI 发出器生成标准化的 API 说明格式。

2. 生成 Client-Side 代码
   客户端代码发出器创建用于使用 API 的代码。

3. 生成服务器端存根代码
   服务端发出器生成用于启动 API 实现的服务器存根代码。

使用 TypeSpec 生成全面的代码

客户端代码生成

TypeSpec 通过自动生成代码，使客户端能够直接从 TypeSpec 定义中使用 API，从而简化了客户端代码的生成。 此过程利用关键功能（如标准运行时接口），确保无缝集成、自定义代码扩展性，为特定客户端需求定制输出，以及跨整个开发堆栈的全面生成。 因此，开发人员可以在应用程序之间保持一致性，减少手动编码工作，并快速将 API 与现有工具链集成，同时享受更高效且可缩放的开发工作流。

支持的语言：

• .NET
• 爪哇岛
• Javascript
• Python语言

服务器代码生成

TypeSpec 支持直接从 TypeSpec 定义生成服务器端存根代码。 这简化了开发过程，并确保客户端和服务器实现之间的一致性。

支持的语言：

• .NET
• Javascript

主要功能：

• 标准运行时接口：标准发出器侧重于最初生成运行时接口，确保灵活性和与各种运行时堆栈轻松集成。
• 自定义代码扩展性：TypeSpec 发出器提供自定义代码扩展性，使开发人员能够根据特定需求定制生成的代码，使其适应不同的环境。
• 综合代码生成：TypeSpec 支持跨整个开发堆栈（从客户端到服务器）生成代码，包括不同的协议和资产类型，确保采用统一的开发方法。

通过使用 TypeSpec 的服务端代码生成功能，开发人员可以减少手动编码、提高一致性并提高整体工作效率。

与行业工具链的互作性

TypeSpec 与现有行业工具链无缝集成，确保互作性并提高工作效率。 通过从 TypeSpec 定义生成 OpenAPI 规范，开发人员可以使用适用于 OpenAPI 的大量工具生态系统，例如用于 API 文档的 Swagger、用于 API 测试的 Postman 和用于部署 API 的 Azure API 管理。 这包括配置 API 网关、生成客户端和服务器代码以及验证 API 数据。 这种兼容性允许团队维护其当前工作流，同时受益于 TypeSpec 提供的结构化且一致的 API 设计。

出色的开发人员体验

开发人员集成包括 Visual Studio Code 扩展 和 Visual Studio。 这些集成通过自动完成、语法突出显示、生成时错误识别、符号重命名和文档格式等功能提供高效且无错误编码的功能。 例如，在 Visual Studio Code 中编写 TypeSpec 定义时，该扩展提供实时自动完成和语法突出显示，从而更轻松地编写正确且一致的 API 定义。

此外， TypeSpec Playground 还提供交互式环境，开发人员可以 实时试验 TypeSpec 语法和功能。 此基于 Web 的工具提供即时反馈和验证，使学习和采用 TypeSpec 更容易。 TypeSpec Playground 提供的交互式实践体验加深了开发人员的理解和熟练程度，最终导致更一致、更高质量的 API 设计。 这些工具通过简化开发过程、减少错误的可能性以及加速新团队成员的学习曲线，共同改善开发人员体验。

为了进一步支持从现有 API 转换的开发人员， OpenApiMigration 工具 提供了将 OpenAPI 规范转换为 TypeSpec 定义的高效方法。 此迁移工具可简化和加速 TypeSpec 的采用，同时保留现有 API 文档的完整性。 三个迁移示例包括：

• 将组件架构转换为模型
• 将组件参数转换为模型或字段
• 将路径路由转换为操作

实际用途

TypeSpec 已在各个行业成功用于简化 API 设计和开发。 以下是一些示例：

• 电子商务：在线零售平台使用 TypeSpec 设计和记录其 API，实现与第三方服务的无缝集成，并改进整体开发人员体验。
• 财务：金融服务公司采用 TypeSpec 来确保其 API 之间的一致性和合规性，从而减少 API 治理所需的时间和工作量。
• 医疗保健：医疗保健提供商使用 TypeSpec 设计用于患者数据管理的 API，确保其系统中的数据一致性和安全性。

开始吧

• 快速入门：使用 TypeSpec 和 .NET 创建新的 API 项目

开源支持

• 我们重视并鼓励你的想法、反馈和贡献，以帮助改进项目。
• 有关如何参与的详细信息，请参阅 参与者指南。
• 如果有疑问或需要帮助，请随时 询问社区 或在 GitHub 上提交问题。

了解详细信息

请观看以下 YouTube 视频，深入了解 TypeSpec：

• 使用 TypeSpec 实现大规模 API
• 使用 TypeSpec 进行架构优先的 API 设计
• TypeSpec 101
• 将 TypeSpec 用于开放式金融标准

相关内容

• TypeSpec.io
• TypeSpec Playground
• TypeSpec 社区