在前后端联调中，最消耗时间的往往不是写代码，而是对齐“接口到底长什么样”。产品需求里写的是“展示用户最近订单和售后状态”，前端需要字段、后端需要表结构和状态枚举，测试需要边界条件，最后大家在群里反复确认：字段名叫什么？状态码有哪些？空列表怎么返回？分页参数是否必传？

这篇文章以一个“用户订单概览接口”为例，记录如何用 Gemini 3.5-flash 辅助完成需求拆解、OpenAPI 草稿生成、Mock 数据整理和联调检查。它适合做结构化信息处理、表格化输出和接口文档初稿，但不适合替代接口评审、代码实现和测试验证。

一、场景背景：需求描述很短，联调问题很多

假设产品需求如下：

在用户中心增加“最近订单”模块，展示用户最近 5 笔订单。每笔订单展示订单号、下单时间、订单金额、订单状态、售后状态。如果订单支持继续支付，前端展示“去支付”；如果支持申请售后，展示“申请售后”。

这段需求看起来不复杂，但直接进入开发，很容易产生分歧：

• “最近 5 笔”是否按下单时间倒序？
• 订单状态和售后状态是否是两个枚举？
• 已取消订单是否还能申请售后？
• 金额用分还是元？
• 时间格式用时间戳还是 ISO 字符串？
• 按钮是否由后端返回，还是前端自己判断？
• 没有订单时返回空数组还是特殊文案？

这类问题适合先让 AI 帮忙拆成结构化清单，再由团队 Review。

二、第一步：让 Gemini 3.5-flash 做需求拆解

不要只输入“帮我设计一个订单接口”。更稳定的方式是给它角色、上下文和输出格式。

text

你是一名有电商经验的后端接口设计工程师，请根据下面需求拆解 RESTful API。
需求：在用户中心增加“最近订单”模块，展示用户最近 5 笔订单。每笔订单展示订单号、下单时间、订单金额、订单状态、售后状态。如果订单支持继续支付，前端展示“去支付”；如果支持申请售后，展示“申请售后”。
请按以下格式输出：1. 需要澄清的问题；2. 推荐接口路径和请求方法；3. 请求参数；4. 响应字段表；5. 订单状态枚举；6. 售后状态枚举；7. 前端按钮展示逻辑；8. 潜在边界场景。
要求：- 不要假设支付和售后一定在同一个系统；- 金额字段请说明单位；- 不要编造复杂业务规则；- 输出尽量适合转成 OpenAPI 文档。

Gemini 3.5-flash 对这类“短需求 → 表格化结果”的任务比较友好，通常能快速列出字段、枚举和澄清问题。这里的重点不是让它一次性给出最终接口，而是把隐藏问题暴露出来。

三、把输出转成可评审的接口草稿

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

1. 接口定义

http

GET /api/v1/users/me/recent-orders?limit=5

说明：

• 当前用户由登录态识别，不从参数传 userId；
• limit 默认 5，最大 10；
• 按下单时间倒序返回；
• 金额统一使用分，避免浮点精度问题。

2. 响应示例

json

{  "code": 0,  "message": "success",  "data": {    "orders": [      {        "orderNo": "ORD202601010001",        "createdAt": "2026-01-01T10:30:00+08:00",        "amountCent": 129900,        "orderStatus": "PENDING_PAYMENT",        "afterSaleStatus": "NONE",        "actions": ["PAY"]      },      {        "orderNo": "ORD202601010002",        "createdAt": "2025-12-28T09:10:00+08:00",        "amountCent": 9900,        "orderStatus": "COMPLETED",        "afterSaleStatus": "AVAILABLE",        "actions": ["APPLY_AFTER_SALE"]      }    ]  }}

3. 字段说明

字段	类型	是否必返	说明
orderNo	string	是	订单号
createdAt	string	是	下单时间，ISO 8601
amountCent	number	是	订单金额，单位：分
orderStatus	string	是	订单状态
afterSaleStatus	string	是	售后状态
actions	string[]	是	当前订单可操作按钮

这里我倾向于后端返回 actions，前端只负责展示。原因是按钮规则经常变化，如果完全由前端根据状态组合判断，后续容易出现多端逻辑不一致。当然，如果团队已有统一前端规则，也可以只返回状态，由前端封装判断函数。

四、生成 OpenAPI 草稿

接下来可以让 Gemini 3.5-flash 把接口草稿转成 OpenAPI 片段。

text

请把下面的接口设计转成 OpenAPI 3.0 YAML。
要求：1. 只生成 paths 和 components.schemas；2. 响应结构包含 code、message、data；3. 枚举值需要写入 schema；4. amountCent 标注单位为分；5. 不要添加需求中没有出现的鉴权方案；6. YAML 保持简洁，方便人工 Review。

示例结果可以整理为：

yaml

paths:  /api/v1/users/me/recent-orders:    get:      summary: 查询当前用户最近订单      parameters:        - name: limit          in: query          required: false          schema:            type: integer            default: 5            maximum: 10      responses:        "200":          description: 查询成功          content:            application/json:              schema:                $ref: "#/components/schemas/RecentOrdersResponse"
components:  schemas:    RecentOrdersResponse:      type: object      properties:        code:          type: integer          example: 0        message:          type: string          example: success        data:          $ref: "#/components/schemas/RecentOrdersData"
    RecentOrdersData:      type: object      properties:        orders:          type: array          items:            $ref: "#/components/schemas/RecentOrderItem"
    RecentOrderItem:      type: object      required:        - orderNo        - createdAt        - amountCent        - orderStatus        - afterSaleStatus        - actions      properties:        orderNo:          type: string          example: ORD202601010001        createdAt:          type: string          format: date-time        amountCent:          type: integer          description: 订单金额，单位：分          example: 129900        orderStatus:          type: string          enum:            - PENDING_PAYMENT            - PAID            - SHIPPED            - COMPLETED            - CANCELED        afterSaleStatus:          type: string          enum:            - NONE            - AVAILABLE            - PROCESSING            - FINISHED        actions:          type: array          items:            type: string            enum:              - PAY              - APPLY_AFTER_SALE              - VIEW_AFTER_SALE

这份 YAML 不能直接视为最终文档，但已经可以进入接口评审了。

五、生成 Mock 数据和前端类型

前端开发常见诉求是：后端接口还没完成，但页面要先开发。可以继续让模型生成 Mock 数据和 TypeScript 类型。

text

基于上面的响应结构，请生成：1. TypeScript interface；2. 5 条覆盖不同订单状态的 Mock 数据；3. 一个根据 actions 判断按钮文案的函数。
要求：- 不要使用 any；- 金额展示函数单独写；- 代码适合 React 项目直接改造。

整理后的代码如下：

ts

type OrderStatus =  | "PENDING_PAYMENT"  | "PAID"  | "SHIPPED"  | "COMPLETED"  | "CANCELED";
type AfterSaleStatus =  | "NONE"  | "AVAILABLE"  | "PROCESSING"  | "FINISHED";
type OrderAction =  | "PAY"  | "APPLY_AFTER_SALE"  | "VIEW_AFTER_SALE";
interface RecentOrderItem {  orderNo: string;  createdAt: string;  amountCent: number;  orderStatus: OrderStatus;  afterSaleStatus: AfterSaleStatus;  actions: OrderAction[];}
interface RecentOrdersResponse {  code: number;  message: string;  data: {    orders: RecentOrderItem[];  };}
function formatAmount(amountCent: number): string {  return `¥${(amountCent / 100).toFixed(2)}`;}
function getActionText(action: OrderAction): string {  const actionMap: Record<OrderAction, string> = {    PAY: "去支付",    APPLY_AFTER_SALE: "申请售后",    VIEW_AFTER_SALE: "查看售后"  };
  return actionMap[action];}

Mock 数据示例：

ts

const mockOrders: RecentOrderItem[] = [  {    orderNo: "ORD202601010001",    createdAt: "2026-01-01T10:30:00+08:00",    amountCent: 129900,    orderStatus: "PENDING_PAYMENT",    afterSaleStatus: "NONE",    actions: ["PAY"]  },  {    orderNo: "ORD202601010002",    createdAt: "2025-12-28T09:10:00+08:00",    amountCent: 9900,    orderStatus: "COMPLETED",    afterSaleStatus: "AVAILABLE",    actions: ["APPLY_AFTER_SALE"]  }];

AI 生成的代码能节省起草时间，但字段命名、枚举值和业务规则必须和后端最终文档保持一致。

六、模型能力对比：谁更适合哪个环节

在这个场景里，不同模型可以这样分工：

模型	适合环节	注意事项
Gemini 3.5-flash	需求结构化、表格整理、OpenAPI 草稿、Mock 数据	需要明确输出格式
ChatGPT	接口方案讨论、代码草稿、Prompt 迭代	生成代码要结合项目规范 Review
Claude	长 PRD 阅读、复杂需求归纳、文档润色	适合处理长上下文
DeepSeek	中文技术解释、边界条件梳理、业务规则推理	适合做二次校验

多模型对比的价值不是“选一个最强的”，而是让不同输出互相补充。例如 Gemini 输出字段表，Claude 检查需求遗漏，DeepSeek 补充中文边界条件，ChatGPT 给出前端代码草稿。

七、如何验证 AI 生成的接口设计

1. 和产品确认业务规则

重点确认：

• 取消订单是否展示；
• 售后状态是否来自独立售后系统；
• “申请售后”的可见条件；
• 订单金额是否包含优惠、运费；
• 最近订单是否包含已删除或隐藏订单。

2. 和后端确认数据来源

接口字段必须能落到真实数据：

text

orderNo        -> order表订单号createdAt      -> order表创建时间amountCent     -> order_pay表应付金额或实付金额orderStatus    -> order表状态afterSaleStatus-> after_sale表状态聚合actions        -> 后端规则计算

如果字段跨多个系统，就要提前评估性能和降级策略。

3. 和前端确认展示逻辑

前端至少要验证：

• 空数组页面；
• 超长订单号；
• 金额格式；
• 时间格式；
• 多按钮展示；
• 未知枚举的兜底展示。

4. 用接口测试覆盖边界

可以补充一个简单的测试清单：

text

1. 用户无订单，返回 orders: []2. 用户有 1 笔待支付订单，actions 包含 PAY3. 用户有已完成订单，支持申请售后4. 用户有售后处理中订单，actions 包含 VIEW_AFTER_SALE5. limit 超过最大值时按规则处理6. 未登录访问返回认证错误7. 下游售后系统异常时是否降级

八、多模型工具的判断标准

如果团队希望把多模型 AI 工具放进研发流程，可以关注这些点：

1. 是否方便同一 Prompt 在多个模型间对比；
2. 是否支持 Markdown、表格、YAML 等结构化输出；
3. 是否能保存常用 Prompt 模板；
4. 是否方便复制代码块和文档片段；
5. 是否支持较长上下文，适合放 PRD、接口文档和日志；
6. 是否有清晰的数据处理规范，便于团队制定脱敏流程。

工具本身不是流程的终点，能否形成“需求输入模板、接口评审清单、Mock 数据规范、测试用例模板”才更重要。

九、风险边界：哪些内容不要直接交给 AI

在真实项目中，以下内容需要谨慎处理：

• 用户手机号、地址、身份证号等个人信息；
• 真实订单号、支付流水号；
• 内部接口域名、网关地址；
• 鉴权 Token、Cookie、密钥；
• 未公开的业务规则；
• 完整生产日志；
• 客户名称和合同信息。

更合理的做法是先脱敏：

text

真实订单号：ORD202601010001 -> ORDER_001真实用户ID：93827123       -> USER_001真实域名：https://api.xxx.com -> https://api.example.com真实金额：129876            -> 129900

AI 不需要知道真实敏感数据，也能帮助完成结构化分析。

十、FAQ：常见误区

1. AI 生成的 OpenAPI 能直接作为最终接口文档吗？

不建议。它更适合作为草稿，最终还需要经过产品、前端、后端和测试共同评审。

2. AI 生成的前端类型可以直接提交吗？

可以作为初稿，但要结合项目 ESLint、命名规范、接口封装方式和真实后端返回结果调整。

3. 单一模型够不够？

普通接口草稿一个模型通常够用。涉及支付、售后、权限、跨系统状态时，建议多模型交叉检查，再由人工确认。

4. 如何减少 AI 编造字段？

Prompt 中明确“不要添加需求中没有出现的字段”，并要求它把“假设项”和“待确认项”单独列出来。

5. 公司接口文档能不能直接发送给 AI？

不建议直接发送完整内部文档。应先脱敏、截取必要片段，并遵守团队数据安全规范。

十一、总结

Gemini 3.5-flash 在前后端联调准备阶段的价值，主要体现在三个方面：把模糊需求拆成字段和规则，把接口草稿转成 OpenAPI，把 Mock 数据和测试清单提前准备好。

比较稳妥的使用方式是：先选择一个高频场景，例如接口设计、文档整理或测试用例生成；再用清晰 Prompt 约束输出格式；随后通过产品确认、接口评审、代码 Review 和测试验证结果。重要接口可以使用多模型交叉验证，但最终决策仍然要回到业务规则、系统实现和团队规范。