你的 AI 智能体正确吗？API 开发中 10+ 个智能体的启示与反思

Phodal

发布于 2024-11-22 18:59:20

1390

文章被收录于专栏：phodal

尽管，如过去构建 AutoDev 的 AutoCRUD、精准测试功能一样，我们有意去构建一个完全自动化的 API 开发智能体。但是依旧的，我们会遇到一些问题：

API 设计是需要人类参与的，因为它需要考虑到业务逻辑、数据结构等等。
API 文档是结合上下文与业务背景的。
一次生成大量 API 代码存在大量的安全风险。
AI 生成大量的代码，需要人类参与进行代码审查。
大量的测试可以提升 API 的质量，但是测试的覆盖率、测试的准确性等等，都是需要人类参与的。
……

也因此，在当前阶段，我们预期的一个智能体变为了 10+ 个智能体，以降低人的心智负担。也因此，我们开始思考三个问题：

过去的流程中，AI 可以参与到哪些环节？
如何在 AI 自动化与人类参与之间取得平衡？
如何确保生成的 API 和文档符合高质量标准？

也由此，这有了这篇文章的内容。

回顾：经典 API 开发流程

在构建 API 时，通常我们会有两个阶段：商业战略阶段与技术实现阶段。在商业战略阶段，我们会考虑到 API 的业务价值、API 的商业模式等等。在技术实现阶段，我们会考虑到 API 的设计、API 的文档、API 的测试等等。

在技术实现阶段，我们会有以下几个步骤：

设计阶段：
- API 上下游的契约设计：确定 API 的输入输出格式，使用开放 API 规范（如Swagger/OpenAPI）定义契约，确保接口清晰一致。
- API 文档编写：编写易于理解的文档，涵盖使用示例、错误码及认证信息，使开发者快速上手。
实现阶段：
- 编码实现 API：根据设计文档进行编码，遵循编码规范与最佳实践，注重错误处理和日志记录。
- 开发者手动测试：初步测试 API 的基本功能，确保接口能正常响应请求并返回正确的数据。
- API 单元测试：编写单元测试验证 API 各组件的正确性，确保代码在不同情况下的稳定性与可靠性。
集成与联调阶段：
- 应用间集成：确保 API 能与其他系统或服务有效集成，进行端到端测试验证数据流和交互正常。
- 前后端联调：开发团队与前端工程师合作，进行接口联调，确保前端能正确调用 API 并处理响应数据。
测试阶段：
- API 功能测试：验证 API 每个功能是否按照设计要求正常工作，确保接口逻辑正确。
- API 性能测试：测试 API 在高负载下的响应时间与稳定性，包括压力测试与负载测试，确保满足业务需求。
- API 安全测试：进行安全性审查与测试，检测潜在安全漏洞，如认证、授权、数据加密等，确保API不易受到攻击。
发布阶段：
- API 发布与文档更新：在测试通过后，准备 API 的生产环境部署，更新 API 文档，确保相关方获取最新使用信息。
- 监控与反馈：上线后持续监控 API 使用情况与性能表现，通过用户反馈和日志分析不断迭代与优化 API。

这是一个非常完美的 API 开发流程，但是在实际开发中，我们会遇到大量的问题。毕竟，白天你和各个上下游的人员沟通完，只剩下下班前的半小时，又或者是晚上的时间来写代码。在你加班加点干完活后，你的代码写完了，但是文档没写完，测试没写完，甚至是你的代码写完了，又或者你的代码不符合规范。

那 AI 可以吗？

试验：API 开发的 10+ 个本地智能体

最近，我们在 Shire 语言中开发了 API 开发相关的智能体包，以支持开发者更好地构建 API。在这个过程中，我们结合了标准 API 开发的流程与 AI 智能体的能力，以向开发者提供更好的 AI 辅助 API 开发体验。

我们创建了 10+ 个智能体，以支持 API 开发的各个阶段，如需求分析、API 设计、API 文档生成、API 代码生成、API 测试等等。当然，对于联调来说，我们暂时没有很好的设计，除此在发布阶段，暂时也不需要 AI 的参与。

设计阶段：3 个智能体

设计阶段主要由远程（Dify）需求 Agent、本地 Swagger 生成、 Mock 代码生成三个智能体组成。

需求 Agent：采用的是远程 Dify 来辅助需求分析，即结合内部的需求信息，生成 API 设计所需要的信息。
Swagger 生成：根据需求信息，生成 Swagger API 文档。
Mock 代码与服务生成：根据 Swagger API 文档，生成 WireMock 代码与服务。

在这里，事实上，我们还欠缺了一个设计：结合内部的 API 文档规范和现有的代码库设计。我们在 Shire 中引入了 mock 函数，以直接运行 Mock 服务，示例： mock("docs/mock_v0-stubs.json")。

开发阶段：3 个智能体

开发阶段主要由三个智能体组成：结合需求的代码生成、开发测试 API 代码、API 代码测试。

结合需求的代码生成：同样的采用的也是在 Dify 中的需求信息，只是在粒度上更细一些，会自动修改 Controller 和 Service 代码。
开发测试 API 代码：开发阶段我们经常会采用 Postman 来测试，而在 IDE 中，我们可以使用 Http Client 来测试。所以，我们的智能体会生成 Http Client 手动或者自动进行测试，以检查 API 的正确性。
API 测试代码生成：根据 Mock API 文档，生成 REST Assured 测试代码。

为此，我们还在 execute 函数中，支持了原先的 Gradle 任务方式，即通过 execute(":bootRun") 可以直接启动 Spring Boot 项目。当然，我们还支持了 commit、 push 函数，以支持 Git 操作。

测试阶段：2 个智能体

在测试阶段，我们主要结合了四不同的测试框架，以支持 API 的测试：ab 测试、Python 语言的 Locust 测试、JavaScript 语言的 K6 测试、Playwright 测试。

ab 测试：使用 Apache Benchmark 进行 API 性能测试。
Locust 测试：使用 Python 语言的 Locust 进行 API 性能测试。
Grafana k6 负载测试：使用 JavaScript 语言的 K6 进行 API 性能测试。
Playwright 测试：使用 Playwright 进行 API 功能测试。

虽然这里的四个智能体吹得有点过，但是实际上只是 API 流程中的两个步骤。

遗留文档生成：2 个智能体

而针对于应用缺少 Swagger API 文档的情况，我们构建了四个智能体来解决这个问题：

SpringDoc OpenAPI 方式
- 添加 SpringDoc OpenAPI 依赖，采用 patch 方式添加 Gradle 依赖。
- 在 Controller 中批量添加 Spring REST Docs 注解。
Spring REST Docs 方式
- 添加 Spring REST Docs 依赖，同样的也是，采用 patch 方式添加 Gradle 依赖。
- 在测试中批量添加 Spring REST Docs 注解。

我们在 Shire 中添加了 batch 函数，以便于批量添加 Spring RestDocs 注解，示例： batch("add-annotation-to-controller-test.shire) 脚本。