使用 Quarkus 和 Kiota 生成 SDK 的途径
挑战
Quarkus 应用程序通常通过 API 端点公开功能；在这里，我们讨论如何轻松使用这些 API，并为我们亲爱的用户提供顺畅的体验。虽然在任何编程语言和环境中执行 HTTP 调用都很容易，但随着 API 复杂性的增加，可用端点的数量变得数不胜数，对更好工具的需求就显而易见了。
开发者体验愿望清单
-
全类型编程 API，使 HTTP 端点的发现和调用安全、富有表现力和优雅
-
一种简单且符合习惯的方式来插入各种身份验证机制
-
当描述演变时，生成的代码可以顺利升级
从大规模面临此问题的公司那里吸取教训，一个可行的解决方案是提供多种特定语言的 SDK（软件开发工具包），例如 Java、Python、Go、JavaScript 等。多年来，公司一直支付开发人员手动提供抽象层，从而使云服务功能更容易访问。这种方法增加了维护负担，增加了发布的运营复杂性，而且最糟糕的是，这对于开发人员来说很繁琐。
为了更好地支持工具，计算机行业正在定义新的标准。对于构建基于 HTTP 的 API，OpenAPI 作为一种广泛采用的选项脱颖而出。在本文的上下文中，我们将假设您已经拥有服务的 OpenAPI 描述。
Quarkus 的当前状态
Quarkus 已经提供了一个富有表现力且完全集成的 Rest Client，使您能够以优雅的方式构建 HTTP 调用。此外，quarkus-openapi-generator 是一个成熟的 Quarkus 扩展，旨在从 OpenAPI 生成客户端代码。当您主要关注与 Quarkus 的紧密集成时，推荐使用此选项。
在这篇文章中，我们将介绍一个解决相同问题的替代方案，但它会做出不同的权衡，以优先考虑跨语言和框架的一致性。
开源协作的故事
Microsoft - Kiota
认识到行业在为各种 API 生成全面有效的 SDK 时面临的挑战，Microsoft Graph 团队率先推出了 Kiota，这是一个 CLI 工具，用于简化和自动化为 HTTP API 创建软件开发工具包 (SDK) 的过程。
Kiota 在开源环境中孕育和成长，它促进协作，并且从一开始就以 模块化 为设计理念。Kiota 项目的社区非常友好，并且已经证明，不仅可以轻松地为 bug 打开 issue，还可以改进设计决策。
如今，Kiota 通过为大量 Microsoft 服务自动生成 SDK 来展示其价值。像 GitHub 这样的更多大型行业也迅速效仿。
Red Hat - Apicurio
Apicurio 团队来自 Red Hat，专注于 API 并构建基于 OpenAPI 规范的契约优先产品，加入了 Kiota 的努力。这次合作带来了重要的里程碑，直接源于这次合作。
-
为了使生成的代码的使用与人工编写的产品几乎无法区分，我们彻底实现了特定语言的名称修饰。
-
为了方便从标准 Java 项目中使用 Kiota CLI，我们实现了一个 Maven 插件。
-
为了使 Kiota 在不同且有自己风格的技术栈中无缝使用，我们提供了替代的核心库，让用户可以轻松地替换 Microsoft 的默认设置 (OkHttp + Gson)：Jackson Serde、Vert.X Http、JDK Http。
-
为了提高与替代 Java 运行时的兼容性，我们完全从所有内部组件中移除了反射的使用。因此，Kiota 生成的 SDK 可以自动、无需任何配置地在 GraalVM native-image 上编译和运行。
-
我们深感 URI 模板实现（用于在内部组合 URL）缺乏维护且成熟度不一的痛苦，因此我们推出了一个 无依赖的统一库，该库可用于 Kiota 支持的所有语言。
除了额外的错误修复和改进，我们终于找到了一个最佳点，Kiota 可以轻松地集成到主流和成熟的软件项目中并加以利用。 Apicurio Registry 脱颖而出，它提供了（并在测试中广泛利用了）生成的 Java SDK 以及 Python SDK 和 Go SDK。
Quarkus 与 Kiota 相遇
现在所有的点都已连接起来，最后也是最关键的一步是与利用 Quarkus 的超音速、亚原子应用程序实现无缝集成！这就是新的 quarkus-kiota 扩展诞生的动机。该项目仍处于早期阶段，我们鼓励您尝试并提供反馈。
代码库位于 Quarkiverse，该项目列在 extensions 中，并且 文档 可在通常的位置找到。
通过添加此扩展开始
quarkus ext add io.quarkiverse.kiota:quarkus-kiota
由于这是一个代码生成器扩展，您需要在 quarkus-maven-plugin 的 executions 部分检查 generate-code 目标是否存在。默认 Quarkus 生成的项目包含它，但自定义或旧项目可能没有。
<plugin>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<extensions>true</extensions>
<executions>
<execution>
<goals>
<goal>build</goal>
<goal>generate-code</goal>
</goals>
</execution>
</executions>
</plugin>添加必要的依赖项，我们将替换 Microsoft 发布的默认 HTTP 和 JSON 序列化库，并引入 Vert.X 和 Jackson（来自此 仓库 发布），因为它们与典型 Quarkus 应用程序堆栈的其他部分配合得很好。
<dependency>
<groupId>com.microsoft.kiota</groupId>
<artifactId>microsoft-kiota-abstractions</artifactId>
<version>${kiota.libs.version}</version>
</dependency>
<dependency>
<groupId>io.kiota</groupId>
<artifactId>kiota-http-vertx</artifactId> <!-- alternatively <artifactId>kiota-http-jdk</artifactId> -->
<version>{kiota-java-extra.version}</version>
</dependency>
<dependency>
<groupId>io.kiota</groupId>
<artifactId>kiota-serialization-jackson-quarkus</artifactId>
<version>{kiota-java-extra.version}</version>
</dependency>
<dependency>
<groupId>com.microsoft.kiota</groupId>
<artifactId>microsoft-kiota-serialization-text</artifactId>
<version>${kiota.libs.version}</version>
</dependency>
<dependency>
<groupId>com.microsoft.kiota</groupId>
<artifactId>microsoft-kiota-serialization-form</artifactId>
<version>${kiota.libs.version}</version>
</dependency>
<dependency>
<groupId>com.microsoft.kiota</groupId>
<artifactId>microsoft-kiota-serialization-multipart</artifactId>
<version>${kiota.libs.version}</version>
</dependency>
<dependency>
<groupId>jakarta.annotation</groupId>
<artifactId>jakarta.annotation-api</artifactId>
</dependency>现在我们需要为 OpenAPI 描述生成实际的客户端，为此，您应该将 OpenAPI 文件（yaml 或 json 格式）放入项目中的 src/main/openapi 文件夹。您已经准备好在应用程序中使用该客户端了！
import io.apisdk.example.yaml.ApiClient;
import io.kiota.http.vertx.VertXRequestAdapter;
var client = new ApiClient(new VertXRequestAdapter(vertx));
client.在客户端后面输入一个点，您 IDE 的代码补全功能就会启动，并为您提供一个漂亮的、完全类型化的、匹配 OpenAPI 规范中提供的端点描述的构建器模式。
例如，像这样的一个端点定义在 Java 中可以很好地展开为
client
.groups()
.byGroupId(groupId)
.artifacts()
.byArtifactId(artifactId)
.meta()
.get();
