前后端协作改造记：从「口头协议」到 Mock 驱动开发

wuwenzen@outlook.com (wuwj) — Mon, 30 Aug 2021 00:00:00 +0000

很多项目的前后端协作，一开始都是这样：

「你先把页面搭着，接口我晚点给你。」
「返回字段大概就这些，不行再改。」

结果就是：

接口文档滞后甚至缺失，全靠口头约定；
字段今天叫 userName 明天叫 customerName；
前端经常等后端联调，后端也抱怨前端改来改去。

这篇文章是一次真实改造的复盘：我们从这种「口头协议」状态，逐步过渡到：

有规范的接口文档 + 可用的 Mock 服务 + 基于契约的联调流程。

1. 先承认问题：我们缺的不是工具，而是「契约」

一开始我们也装过各种工具：

Swagger / OpenAPI；
YApi / Rap2 之类的平台；
各种 Mock 插件。

但用一段时间就废掉了，根本原因是：文档没人维护，接口变更不走流程。

所以改造的第一步，不是换工具，而是统一几个规则：

所有新接口必须先有文档，再开发；
文档就是契约：前端后端都按契约来实现；
接口变更要么走版本，要么走兼容字段，不再「直接改」。

工具只是为了让这套流程变得没那么痛苦。

2. 选择和收敛接口文档工具

我们最终选的是：OpenAPI 规格 + 一套接口管理平台（如 YApi 或内部平台）：

提供可视化的接口列表、请求例子、响应示例；
支持一键导出 JSON / SDK 生成；
自带 Mock 功能。

接口粒度大致是：

paths:
  /api/order/list:
    post:
      summary: 订单列表
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderListRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'

当后端定义好这些 schema 后，前端就可以基于文档做代码生成、Mock 数据、类型定义。

前后端协作 on Saiga

前后端协作改造记：从「口头协议」到 Mock 驱动开发

1. 先承认问题：我们缺的不是工具，而是「契约」

2. 选择和收敛接口文档工具