用 Gemini 3.5 Flash 做接口设计与测试矩阵生成：从需求到 OpenAPI 的工程化实践

文章摘要：本文以“订单查询接口”为例，介绍如何用 Gemini 3.5 Flash 辅助完成从需求到接口契约的设计流程，包括需求澄清、字段拆解、参数校验、错误码设计、测试矩阵生成和 OpenAPI 3.0 草案输出。文章结合国内开发者常见场景，说明多模型 AI 在接口设计、文档整理、测试补全和 Bug 排查中的应用，帮助团队减少遗漏、统一规范、提升联调效率，并强调 AI 结果需经人工 Review 后再落地，适合后端、前端、测试及技术负责人参考。

写在前面：为什么开发者需要多模型 AI 工作流

这两年，AI 大模型已经不再只是“聊天工具”，而是逐渐进入了开发者的日常工作流。对国内开发者来说，真正有价值的不是单纯体验某一个模型，而是把 ChatGPT、Claude、Gemini、DeepSeek 等不同模型的能力，用在具体研发场景里，比如：

• 需求拆解；
• 接口设计；
• 技术文档整理；
• 代码 Review；
• 单元测试生成；
• Bug 排查；
• 日志分析；
• SQL 优化；
• 测试用例补全；
• OpenAPI 文档生成；
• 前后端联调说明整理。

尤其是在中小团队或个人开发者场景中，很多工作并不是“不会做”，而是缺少足够的时间反复检查细节。比如一个查询接口，从产品需求到最终上线，中间会经历需求澄清、字段定义、参数校验、错误码设计、接口文档、测试用例、联调说明等多个环节。任何一个环节遗漏，都可能在后期变成 Bug、返工或线上问题。

Gemini 3.5 Flash 这类响应速度较快、结构化输出能力较强的模型，比较适合参与这类高频、重复、但又需要一定工程判断的任务。它不能替代开发者做最终决策，但可以帮助我们更快地把模糊需求整理成可评审、可测试、可落地的技术材料。

如果团队希望对比不同模型在同一任务中的表现，也可以借助一些多模型工具进行横向验证，例如在同一个需求下分别查看 ChatGPT、Claude、Gemini、DeepSeek 的输出差异。像 KULA （https://ouai.me）这类支持多模型切换的工具，适合用来做模型结果对比，但本文重点不在工具本身，而在如何把 AI 能力真正接入研发流程。

本文会以一个“订单查询接口”为例，演示如何使用 Gemini 3.5 Flash 辅助完成：

需要强调的是，AI 生成的内容不能直接等同于最终方案。它更像一个高效率的技术助理：可以帮你快速列出遗漏项、生成初稿、补充边界场景，但最终仍然需要开发、测试、前端和产品共同 Review。

本文要解决的问题

在真实项目中，很多接口问题不是写代码时才出现的，而是在需求转接口设计时就已经埋下了隐患。

例如产品需求中常见这样的描述：

用户可以查询自己的订单列表。
支持按订单状态、下单时间和关键词筛选。
列表需要分页。
未登录用户不能查询。
时间范围不能超过 90 天。

这段需求看似清楚，但如果直接进入开发，很快就会遇到一堆问题：

• page 从 0 开始还是从 1 开始？
• pageSize 最大值是多少？
• 订单状态枚举值用中文还是英文？
• 时间格式是时间戳还是 ISO 8601？
• 金额字段单位是元还是分？
• 关键词匹配订单号还是商品名？
• 未登录返回 401 还是业务错误码？
• 时间范围超过 90 天时返回什么错误？
• 是否需要返回 total？
• 用户是否只能查自己的订单？
• 空状态表示查询全部，还是参数非法？
• 查询结果是否要返回商品明细？

这些问题如果不在接口设计阶段解决，后续就会在联调、测试甚至上线后暴露出来。

所以本文不讨论“让 AI 一次性生成完整系统”，而是讨论一个更实际的问题：

 如何用 Gemini 3.5 Flash 把一段普通需求，拆解成可 Review、可测试、可维护的接口设计材料。

接下来进入正式实践部分。

在后端开发中，很多接口问题不是出在代码实现阶段，而是出在更早的环节：

• 需求描述不够精确；
• 字段含义没有统一；
• 参数校验规则漏掉边界；
• 前后端对错误码理解不一致；
• 测试用例只覆盖正常流程；
• 接口文档和代码实现长期不一致。

这类问题一旦进入联调阶段，就会变成反复沟通、返工和补测试。

Gemini 3.5 Flash 这类响应速度较快的模型，比较适合参与“需求澄清、接口契约整理、测试矩阵生成”这类结构化任务。它不一定替你写最终代码，但可以帮你把模糊需求拆成可 Review 的技术产物。

本文以一个“订单查询接口”为例，记录一套更工程化的 AI 辅助流程：

 需求文本 → 字段拆解 → 接口契约 → 校验规则 → 错误码设计 → 测试矩阵 → 自动化测试草稿 → 人工验证。

一、本文适合谁

如果你是以下角色，这篇文章会比较有参考价值：

• 后端开发：需要把产品需求落成接口设计；
• 前端开发：需要提前明确接口字段、状态码和异常场景；
• 测试工程师：需要从需求中整理测试点和边界用例；
• 技术负责人：需要 Review 接口契约和团队协作流程；
• 产品/项目协作人员：希望减少需求到研发之间的信息损耗。

本文不会讨论“如何让 AI 一次性生成完整项目”，而是重点讨论：

 如何让 Gemini 3.5 Flash 参与接口设计流程，并通过工程验证控制 AI 输出风险。

二、为什么接口设计适合用 AI 辅助

接口设计有一个特点：它既需要理解自然语言需求，又需要输出结构化结果。

例如产品需求可能是这样的：

用户可以在订单列表页查询自己的订单。
支持按订单状态、下单时间范围、关键词搜索。
订单状态包括待支付、已支付、已取消、已完成。
列表需要分页。
如果用户未登录，返回未授权。
如果时间范围超过 90 天，需要提示参数不合法。

这段描述对人来说很容易理解，但对开发来说还远远不够。我们至少要继续明确：

• 查询接口是 GET 还是 POST？
• 分页字段叫什么？
• 页码从 0 开始还是 1 开始？
• 时间格式是时间戳还是 ISO 8601？
• 关键词支持搜索哪些字段？
• 状态枚举值如何定义？
• 空状态是否表示查询全部？
• 超出 90 天返回哪个错误码？
• 返回列表是否包含订单明细？
• 金额字段单位是分还是元？
• 是否需要排序？
• 是否需要幂等？
• 是否有数据权限限制？

这些都是典型的“需求到接口契约”的转换问题。

AI 的价值在于：它可以快速帮你列出遗漏项、生成初版结构、形成测试清单。但最终接口契约必须由开发、测试、前端、产品共同确认。

三、ChatGPT、Claude、Gemini、DeepSeek 在这个场景中的适配差异

接口设计不是单纯写代码，不同模型适合参与的环节略有差异。

四、示例需求：订单查询接口

假设我们拿到这样一段需求：

订单列表查询：

用户登录后，可以查询自己的订单列表。
支持按照订单状态筛选。
支持按照下单时间范围筛选。
支持关键词搜索，关键词可以匹配订单号或商品名称。
支持分页查询。
订单按下单时间倒序展示。

限制：
1. 时间范围最大不能超过 90 天；
2. pageSize 最大不能超过 100；
3. 未登录用户不能查询；
4. 用户只能查询自己的订单；
5. 查询结果需要返回订单号、订单状态、订单金额、下单时间、商品摘要。

这段需求可以直接让 Gemini 3.5 Flash 帮我们做第一轮拆解，但 Prompt 不能只写“帮我设计接口”。

五、Prompt 设计：让 AI 输出可 Review 的接口契约

更推荐的 Prompt 如下：

你是一名资深后端架构师和测试工程师。请根据下面的产品需求，整理一个可供前后端和测试共同评审的接口设计草案。

需求：
【粘贴需求】

请输出以下内容：

1. 需求澄清问题列表：
– 哪些信息当前需求没有明确？
– 哪些点需要产品、前端、后端、测试共同确认？

2. 接口契约草案：
– HTTP Method
– URL
– Request Header
– Query 参数
– Response Body
– 字段类型
– 是否必填
– 默认值
– 枚举值
– 示例值

3. 参数校验规则：
– 每个字段的合法范围
– 空值处理
– 边界值
– 异常返回

4. 错误码设计：
– 未登录
– 参数不合法
– 时间范围超限
– 无权限访问
– 系统异常

5. 测试矩阵：
– 正常用例
– 边界用例
– 异常用例
– 权限用例
– 分页用例
– 组合查询用例

6. OpenAPI 3.0 YAML 草案。

约束：
1. 不要引入复杂架构；
2. 不要生成数据库表结构；
3. 不要假设需求中没有出现的业务规则；
4. 如果信息不足，请明确标记“待确认”；
5. 输出要适合团队评审，不要只给代码。

这个 Prompt 的重点是让 AI 不直接跳到实现，而是先输出“可评审材料”。

六、AI 输出后，先看“待确认问题”

一个质量较高的接口设计草案，第一部分不应该是代码，而应该是问题列表。

例如 Gemini 3.5 Flash 可能会列出：

这一部分非常重要。AI 如果直接生成接口而不提出问题，反而说明它可能在“脑补需求”。

七、接口契约草案示例

经过人工筛选后，可以得到一个初版接口设计。

1. 请求方式

http

GET /api/v1/orders

2. 请求 Header

3. Query 参数

4. 状态枚举

5. 响应示例

json

{
"code": "0",
"message": "success",
"data": {
"page": 1,
"pageSize": 20,
"total": 128,
"items": [
{
"orderNo": "ORD202501010001",
"status": "PAID",
"amountCent": 129900,
"createdAt": "2025-01-01T10:30:00+08:00",
"productSummary": "iPhone 16 Pro 等 2 件商品"
}
]
}
}

这里有几个工程实践点：

• 金额用 amountCent，避免浮点精度问题；
• 时间使用带时区的 ISO 8601 字符串；
• 状态使用英文枚举，避免中文状态参与逻辑判断；
• 分页字段明确 page 从 1 开始；
• 返回 total，方便前端分页展示。

八、OpenAPI 3.0 草案

让 Gemini 3.5 Flash 生成 OpenAPI YAML 是一个比较实用的场景，但生成后一定要人工校验。

示例：

yaml

openapi: 3.0.3
info:
title: Order Query API
version: 1.0.0

paths:
/api/v1/orders:
get:
summary: Query current user's orders
operationId: queryOrders
parameters:
– name: status
in: query
required: false
schema:
type: string
enum:
– PENDING_PAYMENT
– PAID
– CANCELED
– COMPLETED
description: Order status filter
– name: startTime
in: query
required: false
schema:
type: string
format: date-time
description: Order created start time
– name: endTime
in: query
required: false
schema:
type: string
format: date-time
description: Order created end time
– name: keyword
in: query
required: false
schema:
type: string
maxLength: 50
description: Search by order number or product name
– name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
– name: pageSize
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
"200":
description: Query success
content:
application/json:
schema:
$ref: "#/components/schemas/OrderQueryResponse"
"400":
description: Invalid request parameter
"401":
description: Unauthorized
"403":
description: Forbidden

components:
schemas:
OrderQueryResponse:
type: object
properties:
code:
type: string
example: "0"
message:
type: string
example: success
data:
$ref: "#/components/schemas/OrderPage"

OrderPage:
type: object
properties:
page:
type: integer
example: 1
pageSize:
type: integer
example: 20
total:
type: integer
example: 128
items:
type: array
items:
$ref: "#/components/schemas/OrderItem"

OrderItem:
type: object
properties:
orderNo:
type: string
example: ORD202501010001
status:
type: string
example: PAID
amountCent:
type: integer
format: int64
example: 129900
createdAt:
type: string
format: date-time
example: 2025-01-01T10:30:00+08:00
productSummary:
type: string
example: iPhone 16 Pro 等 2 件商品

AI 生成 OpenAPI 后，建议检查：

• YAML 是否能被解析；
• schema 引用是否存在；
• 字段命名是否符合团队规范；
• 参数类型是否合理；
• 错误响应是否需要统一结构；
• 是否遗漏鉴权 Header；
• 是否和已有接口风格一致。

九、用 AI 生成参数校验规则

接口设计中，参数校验是最容易漏边界的部分。

可以继续追问：

请基于上面的接口契约，生成参数校验规则表。
要求：
1. 按字段维度输出；
2. 包含正常值、非法值、边界值；
3. 给出建议错误码；
4. 标记哪些规则必须后端强校验；
5. 不要只写自然语言，要适合测试工程师直接转成测试用例。

输出可以整理为：

这张表比单纯一段接口说明更适合团队协作，因为它能直接变成测试用例。

十、Spring Boot DTO 示例

如果项目使用 Spring Boot，可以基于接口契约生成请求对象草稿。

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Size;
import org.springframework.format.annotation.DateTimeFormat;

import java.time.OffsetDateTime;

public class OrderQueryRequest {

private OrderStatus status;

@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
private OffsetDateTime startTime;

@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
private OffsetDateTime endTime;

@Size(max = 50, message = "keyword length must not exceed 50")
private String keyword;

@Min(value = 1, message = "page must be greater than or equal to 1")
private Integer page = 1;

@Min(value = 1, message = "pageSize must be greater than or equal to 1")
@Max(value = 100, message = "pageSize must be less than or equal to 100")
private Integer pageSize = 20;

public OrderStatus getStatus() {
return status;
}

public void setStatus(OrderStatus status) {
this.status = status;
}

public OffsetDateTime getStartTime() {
return startTime;
}

public void setStartTime(OffsetDateTime startTime) {
this.startTime = startTime;
}

public OffsetDateTime getEndTime() {
return endTime;
}

public void setEndTime(OffsetDateTime endTime) {
this.endTime = endTime;
}

public String getKeyword() {
return keyword;
}

public void setKeyword(String keyword) {
this.keyword = keyword;
}

public Integer getPage() {
return page == null ? 1 : page;
}

public void setPage(Integer page) {
this.page = page;
}

public Integer getPageSize() {
return pageSize == null ? 20 : pageSize;
}

public void setPageSize(Integer pageSize) {
this.pageSize = pageSize;
}
}

枚举：

public enum OrderStatus {
PENDING_PAYMENT,
PAID,
CANCELED,
COMPLETED
}

但注意，跨字段校验不能只依赖注解。例如：

• endTime 不能早于 startTime；
• 查询时间范围不能超过 90 天。

这类规则通常需要在 Service 或自定义 Validator 中处理。

import java.time.Duration;
import java.time.OffsetDateTime;

public class OrderQueryValidator {

private static final long MAX_QUERY_DAYS = 90;

public void validate(OrderQueryRequest request) {
if (request == null) {
throw new IllegalArgumentException("request must not be null");
}

OffsetDateTime startTime = request.getStartTime();
OffsetDateTime endTime = request.getEndTime();

if (startTime != null && endTime != null) {
if (endTime.isBefore(startTime)) {
throw new IllegalArgumentException("endTime must not be earlier than startTime");
}

long days = Duration.between(startTime, endTime).toDays();
if (days > MAX_QUERY_DAYS) {
throw new IllegalArgumentException("query time range must not exceed 90 days");
}
}
}
}

AI 生成代码后，开发者至少要检查：

• 是否使用了项目当前版本支持的包；
• jakarta.validation 和 javax.validation 是否与项目版本一致；
• 时间类型是否符合现有规范；
• 异常是否应该换成统一业务异常；
• 错误码是否符合团队规范。

十一、用 Gemini 3.5 Flash 生成测试矩阵

测试矩阵是这个流程中最值得让 AI 参与的部分。

Prompt 示例：

请基于订单查询接口契约，生成测试矩阵。
要求：
1. 用 Markdown 表格输出；
2. 覆盖正常、异常、边界、权限、分页、组合查询；
3. 每条用例包含：用例编号、场景、输入参数、前置条件、预期结果、优先级；
4. 不要生成重复用例；
5. 标记哪些用例适合自动化测试。

可能得到如下结果：

这类表格非常适合进入测试评审，也方便转成自动化测试。

十二、自动化测试草稿：pytest 示例

如果团队有 API 自动化测试，可以让 AI 基于测试矩阵生成草稿。

下面是一个简化版 pytest 示例：

import requests
from datetime import datetime, timedelta, timezone

BASE_URL = "http://localhost:8080"
TOKEN = "test-token"

def auth_headers():
return {
"Authorization": f"Bearer {TOKEN}",
"X-Request-Id": "test-request-id"
}

def test_query_orders_default_success():
response = requests.get(
f"{BASE_URL}/api/v1/orders",
headers=auth_headers()
)

assert response.status_code == 200
body = response.json()

assert body["code"] == "0"
assert "data" in body
assert body["data"]["page"] == 1
assert body["data"]["pageSize"] == 20
assert "items" in body["data"]

def test_query_orders_invalid_status():
response = requests.get(
f"{BASE_URL}/api/v1/orders",
headers=auth_headers(),
params={"status": "UNKNOWN"}
)

assert response.status_code == 400
body = response.json()

assert body["code"] == "INVALID_PARAMETER"

def test_query_orders_page_size_exceeded():
response = requests.get(
f"{BASE_URL}/api/v1/orders",
headers=auth_headers(),
params={"pageSize": 101}
)

assert response.status_code == 400
body = response.json()

assert body["code"] == "INVALID_PARAMETER"

def test_query_orders_time_range_exceeded():
now = datetime.now(timezone.utc)
start_time = now – timedelta(days=91)

response = requests.get(
f"{BASE_URL}/api/v1/orders",
headers=auth_headers(),
params={
"startTime": start_time.isoformat(),
"endTime": now.isoformat()
}
)

assert response.status_code == 400
body = response.json()

assert body["code"] == "TIME_RANGE_EXCEEDED"

def test_query_orders_unauthorized():
response = requests.get(f"{BASE_URL}/api/v1/orders")

assert response.status_code == 401

这类代码只能作为草稿，不能直接认为可用。真实项目里还要处理：

• 测试数据准备；
• 测试账号隔离；
• 数据清理；
• 环境配置；
• 断言字段完整性；
• 接口响应耗时；
• 数据权限校验；
• CI/CD 集成。

十三、让 AI 做接口契约 Diff Review

接口在迭代中经常变化，例如：

• 新增字段；
• 修改枚举；
• 改错误码；
• 改分页规则；
• 改金额单位；
• 改时间格式。

这些变化如果没有明确记录，很容易导致前端、测试和后端理解不一致。

可以把两版 OpenAPI 文档或接口说明交给 Gemini 3.5 Flash 做 Diff 分析。

Prompt：

下面是订单查询接口的 v1 和 v2 契约，请帮我做接口变更 Review。

要求：
1. 列出新增字段、删除字段、字段类型变化、枚举变化、错误码变化；
2. 判断哪些变化可能不兼容；
3. 说明对前端、后端、测试分别有什么影响；
4. 给出回归测试建议；
5. 不要假设未提供的信息。

v1:
【粘贴 v1】

v2:
【粘贴 v2】

输出可以关注：

这类 Review 特别适合在接口评审、PR Review 或版本发布前使用。

十四、如何验证 AI 输出是否可靠

AI 生成接口文档和测试用例，看起来很完整，但仍然可能存在问题。

建议至少做 6 类验证。

1. 语法验证

OpenAPI YAML 可以用工具解析：

• Swagger Editor；
• OpenAPI Generator；
• Redocly；
• Spectral。

重点检查：

• YAML 格式是否正确；
• $ref 是否能解析；
• schema 是否重复；
• 类型是否符合 OpenAPI 规范。

2. 契约一致性验证

检查接口文档与代码是否一致：

• URL 是否一致；
• Method 是否一致；
• 参数名是否一致；
• 错误码是否一致；
• 返回结构是否一致。

3. 参数边界验证

重点检查：

• 空值；
• 超长字符串；
• 非法枚举；
• 时间范围；
• page/pageSize 边界；
• 特殊字符；
• 无匹配数据。

4. 权限验证

订单查询接口必须验证：

• 未登录不能访问；
• 用户 A 不能看到用户 B 的订单；
• 过期 token 不能访问；
• 被禁用用户是否允许访问；
• 管理员接口和普通用户接口是否隔离。

5. 性能验证

分页查询很容易被忽略性能问题：

• pageSize 最大值是否合理；
• keyword 是否走索引；
• 时间范围是否限制；
• 是否存在深分页问题；
• 是否有 N+1 查询；
• 是否需要缓存。

6. 回归验证

接口变更后，至少回归：

• 默认查询；
• 状态筛选；
• 时间筛选；
• 分页；
• 权限；
• 错误码；
• 空结果；
• 历史兼容字段。

十五、常见 Prompt 反例

反例 1：问题太短

帮我设计一个订单查询接口。

问题在于：

• 没有业务约束；
• 没有输出格式；
• 没有校验要求；
• 没有测试要求；
• AI 很容易自由发挥。

反例 2：直接让 AI 写最终代码

根据需求帮我写完整后端代码。

问题在于：

• 它不知道你的项目分层；
• 不知道统一异常格式；
• 不知道鉴权方式；
• 不知道数据库结构；
• 不知道团队代码规范。

更好的做法是先让 AI 输出接口契约、校验规则、测试矩阵，再由开发者实现。

反例 3：没有要求标记不确定信息

根据需求生成 OpenAPI。

AI 可能会把不明确的信息自动补全，比如：

• 自行定义错误码；
• 自行假设金额单位；
• 自行假设分页规则；
• 自行增加业务字段。

Prompt 里一定要写：

如果信息不足，请标记“待确认”，不要自行假设。

十六、开发团队可以落地的流程

一个相对稳妥的流程如下：

产品需求
↓
AI 辅助拆解待确认问题
↓
产品/前端/后端/测试评审
↓
AI 生成接口契约草案
↓
人工修订 OpenAPI
↓
AI 生成测试矩阵
↓
测试与开发补充边界用例
↓
开发实现接口
↓
自动化测试 + 契约测试
↓
接口变更 Diff Review
↓
发布前回归

其中 AI 参与的是“生成草稿”和“发现遗漏”，不是替代评审和验证。

十七、注意事项：不要把敏感信息直接给 AI

在接口设计和问题排查中，经常会涉及内部信息。使用 AI 时要注意：

• 不上传真实用户数据；
• 不上传生产 Token；
• 不上传数据库连接信息；
• 不上传公司内部接口域名；
• 不上传完整未公开代码仓库；
• 不上传敏感业务规则；
• 不上传日志中的手机号、身份证、邮箱等隐私字段。

可以使用脱敏后的示例：

json

{
"userId": "U123456",
"orderNo": "ORD202501010001",
"phone": "138****0000"
}

对于公司内部核心业务逻辑，建议只提供抽象后的最小复现信息。

十八、FAQ：几个常见问题

1. Gemini 3.5 Flash 适合做接口设计吗？

适合做初版拆解、测试矩阵、OpenAPI 草案和接口变更分析。但最终接口契约必须人工 Review，不能完全依赖 AI。

2. AI 生成的 OpenAPI 可以直接提交吗？

不建议。需要通过语法校验、团队规范校验、代码一致性校验，并由前后端和测试共同确认。

3. AI 生成测试用例有什么价值？

价值在于补充遗漏场景，尤其是边界值、异常值、权限场景和组合查询场景。但具体断言和测试数据仍需要测试工程师调整。

4. 多模型对比有必要吗？

对重要接口有必要。可以用不同模型分别生成测试矩阵，再合并高价值用例。不同模型的关注点不同，有助于发现遗漏。

5. 接口设计阶段最应该让 AI 做什么？

不是写代码，而是做这几件事：

• 提出待确认问题；
• 输出接口字段表；
• 生成参数校验规则；
• 整理错误码；
• 生成测试矩阵；
• 做接口变更 Diff Review。

十九、总结

Gemini 3.5 Flash 在接口设计场景中的优势，不是替代后端开发，而是提升“需求结构化”的效率。

对于开发团队来说，更实际的用法是：

接口设计的核心不是“文档写得多”，而是让前端、后端、测试和产品对同一个契约达成一致。AI 可以加速这个过程，但不能替代工程判断。