用 OpenAPI 和 AI 重构 Flutter 接口开发流程

为什么值得用 OpenAPI

Flutter 项目接后端接口，通常要先读在线文档，再手写 DTO、请求和错误处理。接口少时没有问题，项目做久以后，麻烦会慢慢出现：

• 文档写的是 String，实际偶尔返回 null。
• 示例只有成功数据，错误结构要等联调才知道。
• 后端增加了枚举值，旧版 App 解析失败。
• 文档、测试环境和生产环境对不上。

AI Agent 能快速写代码，却不能判断一份过期文档是不是事实。输入含糊时，它只是更快地完成猜测。

更稳妥的方式，是让三部分各自提供清楚的信息：

OpenAPI 负责减少猜测，项目代码负责限定实现方式，Agent 才能在正确的范围内提速。

OpenAPI 是什么，从哪里来

OpenAPI 是一份结构固定的接口说明文件，通常使用 YAML 或 JSON。它会记录路径、参数、认证、返回值和数据结构。

paths:
  /v1/tasks/{taskId}:
    get:
      operationId: getTask
      security: [{ bearerAuth: [] }]
      parameters:
        - name: taskId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Task" }

这几行已经告诉工具和 Agent：方法叫 getTask，taskId 必填，需要登录，并且成功后返回 Task。

OpenAPI 是标准，Swagger 是围绕这个标准的一组工具。例如 Swagger Editor 可以编辑和检查文件，Swagger UI 可以把文件展示成网页。项目里的文件即使叫 swagger.json，也可能遵循 OpenAPI 标准。

文件一般来自下面三种地方：

Apifox 支持导出 OpenAPI，Postman 也能导入 OpenAPI 3.0 和 3.1。选哪种方式并不重要，重要的是团队明确：接口改变后，修改哪一份才算数。

和传统接口文档有什么不同

传统文档更适合解释业务，OpenAPI 更擅长准确描述接口。两者不是替代关系，而是分工不同。

对比	传统接口文档	OpenAPI
表达内容	优点：适合讲背景、流程和特殊情况。 缺点：接口细节容易散落在文字中。	优点：路径、字段、枚举和错误结构清楚。 缺点：不适合解释复杂业务。
阅读对象	主要给人阅读，写法自由。	人和工具都能读取，也能生成网页文档。
代码与 AI	仍要把文字手动变成 DTO 和请求，AI 也可能猜错。	可以生成 DTO、Client 和 Mock，AI 也更容易定位接口。
维护方式	开始简单，但过期通常靠人发现。	能自动检查和比较版本，但前提是文件及时更新。

最实用的组合是：传统文档讲业务流程，OpenAPI 写准请求和返回值。不要在两边重复维护同一批字段表格。

最适合 Flutter 团队的工作方式

OpenAPI 带来的真正变化，不只是少写几个 DTO，而是把接口适配和页面开发拆开。

团队可以让专人或 AI 负责 OpenAPI、生成代码和 Repository，其他成员专注于 Task、Controller 和页面。代码审查的重点也会变得明确：DTO 到业务模型的转换是否正确，空值、枚举和错误是否处理完整。

下面是一个最小的 GetX 例子。生成的 TaskDto 只留在 Repository 中：

final class Task {
  const Task({required this.id, required this.isCompleted});

  final String id;
  final bool isCompleted;
}

final class TaskRepository {
  TaskRepository(this.api);
  final GeneratedTaskApi api;

  Future<Task> getTask(String id) async {
    final dto = await api.getTask(id);
    return Task(
      id: dto.id,
      isCompleted: dto.status == TaskDtoStatus.completed,
    );
  }
}

Controller 和 Widget 只认识项目自己的 Task：

final class TaskController extends GetxController {
  TaskController(this.repository);

  final TaskRepository repository;
  final task = Rxn<Task>();

  Future<void> load(String id) async {
    task.value = await repository.getTask(id);
  }
}

Obx(() {
  final task = Get.find<TaskController>().task.value;
  if (task == null) return const CircularProgressIndicator();
  return Text(task.isCompleted ? '已完成' : '处理中');
});

以后后端修改字段或状态值，主要调整生成层和 Repository；只要 Task 的含义不变，页面代码就不需要跟着改。这不是与后端完全断开，而是把变化集中在一个可检查的边界上。

怎么把任务交给 AI Agent

不要只说“根据 OpenAPI 生成 Flutter 代码”。Agent 还需要知道现有项目怎么组织，以及本次做到哪里为止。

这份提示词可以直接按项目修改：

请根据 docs/api/openapi.yaml，为当前 Flutter 项目实现：
- createTask
- getTask
- cancelTask

开始前：
1. 阅读项目的网络层、错误处理和相似模块。
2. 说明会复用什么、修改哪些文件。
3. 列出 OpenAPI 中需要人工确认的问题，不要自行猜测。

实现要求：
- 复用现有 Client、Result、Exception 和依赖注入。
- DTO 不进入 Controller 或 Widget。
- 在 Repository 中转换为项目的业务模型。
- 处理必填、空值、枚举、时间、认证和非 2xx 响应。
- 不手改 generated 目录，不实现范围外的接口。
- 补充序列化、请求和模型转换测试。

完成后列出修改文件、验证命令和未确认的问题。

适合交给 Agent 的工作包括 DTO、Client、序列化、Repository 转换和相关测试。网络架构、业务规则以及 OpenAPI 没写清楚的内容，仍然需要团队决定。

团队只需要约定这些事

约定不用很长，但下面几项最好写进项目文档：

约定	团队需要说清楚什么
可信来源	后端代码、Git 文件或协作平台，哪一份是最终答案
稳定标识	每个接口使用固定的 operationId，任务和评审都用它说明范围
目录边界	generated 可以覆盖；Repository 和业务模型由团队维护
遇到歧义	必填、空值、枚举、错误、单位不清楚时先确认，不自行猜测
自动检查	校验 OpenAPI，比较破坏性变更，并确认生成代码已经同步

一种简单的目录方式是：

lib/
  api/
    generated/       # 自动生成，不手改
    repositories/    # DTO 转业务模型
  features/
    tasks/            # Task、Controller 和页面

如果生成代码提交到仓库，CI 可以重新生成并检查差异：

npm run api:validate
npm run api:generate
git diff --exit-code -- lib/api/generated

OpenAPI Generator 可以校验文件和生成 Client，Spectral 可以检查定义是否规范，oasdiff 可以比较新旧版本。工具可以替换，检查目标不变：确保接口文件有效、变更可见、生成结果没有遗漏。

总结

我并不期待 OpenAPI 和 AI 把接口开发变成一次点击，也不认为生成出来的代码可以不经检查直接使用。真正吸引我的，是它能减少那些重复而又容易出错的工作。

如果 DTO、Client 和基础转换可以交给工具或 AI，页面开发者就不必反复确认后端字段，而是可以把时间用在交互、状态和真实的业务问题上。需要认真评审的地方，也能集中到 Repository 这一层：字段有没有转对，空值和枚举有没有遗漏，错误是否符合项目约定。

我更希望团队最终形成这样的协作方式：有人维护可靠的接口定义，有人负责接口到业务模型的边界，其他成员可以围绕稳定的模型并行开发页面。AI 不需要代替任何一个角色，它只要把中间大量机械工作做得更快、更一致，就已经很有价值。

这套方式不必一开始就做到很完整。先确定一份可信的 OpenAPI，再选一个小模块试着生成和适配。只要它确实减少了联调时的猜测和页面成员的重复劳动，就值得继续往下做。