使用代码生成器加速API驱动开发

背景

随着技术的不断发展，AI（人工智能）和ML（机器学习）模型生成代码的应用正逐渐普及，未来我们可能会看到这些技术在全球范围内被广泛采用。目前，大多数此类应用仍处于初期阶段，研究方向主要集中在如何补充人类开发者的代码编写工作。同时，我们也需要利用现有工具快速响应需求，提升开发效率。

在 TechConative，我们推出了一系列博客，主题为“快速跟踪您的软件开发”，旨在分享我们在软件开发、测试和部署阶段的经验和方法，帮助开发者节省时间和精力。

当一部分开发者致力于构建能够根据需求生成代码的应用时，另一部分开发者则在探索不同的开发范式，例如“OpenAPI 代码生成器来加速开发过程。

假设

在开始之前，我们需要明确以下前提条件：

• 您已经选择了设计优先的开发方法。
• 您计划通过 设计 API。Stoplight 是一个常用的工具，可帮助编写和验证 OAS。
• 您计划使用与 OpenAPI 生成器插件兼容的基于 JVM 的编程语言来开发应用程序。

战略

为了实现快速开发，我们将采用以下策略：

• 维护 OAS 规范文件：将 OAS 规范文件（JSON 或 YAML 格式）作为代码库的一部分进行管理。OpenAPI 生成器插件将利用这些规范文件，在每次 CI（持续集成）构建时生成控制器接口。这种方法被称为“主动代码生成”。
• 生成代码的管理：生成的代码（包括控制器接口和 DTO）将存储在“目标”文件夹中，作为临时文件，不会纳入版本控制。
• 扩展控制器接口：API 控制器将扩展生成的接口，这些接口仅包含实现逻辑。同时，所有 OpenAPI 文档和 API 规范都将在生成的接口中可用。

方法

以下是实现快速开发的具体步骤：

1. 添加 OAS 规范文件

   将 OAS 规范文件添加到项目中，并通过 SCM（源代码管理）跟踪文件的更改。

2. 配置 Maven 插件

   在 Maven 项目的 pom.xml 文件中，在 <build> 节点下添加 OpenAPI 生成器插件的配置。

3. 自定义类型映射（可选）

   如果需要，可以使用 typeMapping 配置自定义 Java 中的对象类型映射。

4. 自动生成代码

   在编译阶段，代码生成将自动完成。例如，运行 mvn clean compile 命令时，代码将根据配置生成。

5. 编写控制器类

   在生成的代码基础上，编写控制器类并扩展由 OpenAPI 生成的 API 接口。

6. 注释与文档

   生成的接口将包含与 OAS 文档相关的注释，这些注释在运行应用程序时也会显示在 Swagger 页面中。

通过这些步骤，开发者可以快速实现逻辑实现，并利用生成的接口和 DTO 提高开发效率。

示例

以下是一个示例项目，该项目展示了如何从 OAS 文件生成类。

生成的 API 类存储在目标文件夹中，具体如下所示：

总结

通过采用设计开发 REST API 的方法，不妨尝试使用 OpenAPI 代码生成器。

原文链接: https://techconative.com/blog/oac-code-gen/