这个系列的第一篇里，我主张在写任何代码之前先把OpenAPI契约定下来。这一篇要讲的，是让这份契约真正“回本”的工具。

手写前端的API层，是那种没人会承认自己喜欢的活儿。从后端文档里抄类型，第四十次写同一个请求封装，三周后有人把某个字段改了名，一半的调用就悄无声息地坏掉了。Orval直接把这个活儿删掉了。把它指向你的OpenAPI规范，客户端代码就自动生成：每个接口都有带类型的函数，模型和契约完全一致，还有后端根本不存在时就能用来开发的mock。

前端团队为什么喜欢它

#

mock生成是最被低估的部分。规范一旦谈定，前端就能起一个假服务器，对着它把整个UI做完，不用再等那些永远“快好了”的接口。等真正的后端上线，把客户端指过去，大部分东西直接就能跑，因为两边是照着同一份文档做的。

另一个收获是：无聊的代码从此“天生正确”。没有人会在手写的请求体里敲错字段名了，因为根本没有人再手写请求体。

后端团队为什么也喜欢它

#

规范成为唯一事实来源之后，日常沟通都变了。不再有“这个接口到底返回什么来着？”的群聊追问，前端直接看生成的类型就行。后端开发者被打断得更少，反馈来得更早：前端对着mock开发时觉得哪个API别扭，你在改起来还便宜的阶段就知道了，而不是等它进了生产环境。

怎么融入工作流

#

没什么花哨的。后端提出规范，两个团队一起评审；前端用Orval生成客户端和mock，直接开工；后端按同一份契约实现真实接口。规范一变，两边重新生成，编译器会准确告诉你哪里坏了。最后这一点才是全部意义所在：前后端之间的偏差，从生产事故变成了编译错误。

配置

#

先把它装成开发依赖，再装上生成的代码要import的那些包。要生成React Query hooks和mock的话，就是TanStack Query、MSW和Faker：

npm install --save-dev orval msw @faker-js/faker
npm install @tanstack/react-query

然后在项目根目录加一个orval.config.ts。下面这份和Orval官方文档里的示例很接近：

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml', // a path or a URL
    },
    output: {
      mode: 'single',
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
      httpClient: 'fetch',
      mock: true, // MSW handlers plus Faker data
      override: {
        fetch: { includeHttpResponseReturnType: false },
      },
    },
  },
});

client决定你拿到什么：普通的fetch或axios函数，React Query、Vue Query、Svelte Query或SWR的hooks，Angular service，或者Zod schema。includeHttpResponseReturnType: false这一行让fetch客户端直接返回响应体，而不是{ data, status }，组件要的通常就是这个。

再加一条script，省得每个人都得记命令：

{
  "scripts": {
    "api": "orval"
  }
}

npm run api会生成hooks和模型。组件里用起来和别的React Query hook没什么两样，类型都已经填好了：

import { useListPets } from './api/petstore';

export function PetList() {
  const { data: pets, isLoading } = useListPets();
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {pets?.map((pet) => <li key={pet.id}>{pet.name}</li>)}
    </ul>
  );
}

在规范里给某个字段改个名，再跑一次npm run api，所有用到pet.name的地方都会变红。这就是上面说的偏差检查，而且跑一次不花任何成本。

对着mock开发

#

开了mock: true之后，Orval还会为每个接口生成一个MSW请求handler，返回按响应结构填充的Faker数据，外加一个把所有handler一次性返回的函数。把这份列表交给浏览器里MSW的setupWorker，或者测试里的setupServer，应用就跑在一个已经符合契约的假后端上了。每个handler还能传入覆盖值，测试想返回特定的payload、空列表或错误状态都行，不用有人手写fixture。

前端能从第一天就开工，靠的就是这一点。mock不是另一份需要有人维护的产物：它和客户端从同一份规范重新生成，所以不可能落后于规范。

Orval vs openapi-generator、openapi-typescript和Hey API

#

它们都从OpenAPI规范出发，只是走到的地方不一样。

如果只需要类型，openapi-typescript最轻，很难挑出毛病。openapi-generator的用武之地，是规范要喂给不止一种语言的时候；它的TypeScript输出能用，但读起来像是先为Java写的。Orval和Hey API之间，基本就看口味，以及你更愿意读哪一家生成的代码。我一直用Orval，是因为mock和hooks出自同一次运行，而正是这一点改变了两个团队的协作方式。

这不是什么光鲜的工具。它只是安安静静地消灭了团队之间一整类争吵，这笔买卖我每次都愿意做。

简单说，这套设计优先的流程每个 Sprint 走一遍：

1. 为本 Sprint 的 API 工作定两名负责人，后端一名、前端一名。
2. 两人对照本 Sprint 的需求编写（或更新）OpenAPI 接口定义，反复评审，直到双方都认可。
3. 把接口定义提交到仓库。从这一刻起，它就是契约。
4. CI 根据提交的接口定义拉起一个模拟服务器。
5. 前端对着模拟服务器开发，后端同时实现真实的端点。
6. 真实服务部署后，由它生成的规范文件就是下一个 Sprint 接口定义的起点。

事情的起因

#

起因是一次回顾会。反馈说得很不客气：API 的规划几乎没有任何可见性。后端按自己对需求的理解去实现端点，前端事后才知道响应长什么样，分歧全都在集成阶段——也就是代价最高的时刻——才暴露出来。于是有了这个提案：把两边都拉进计划阶段，让 OpenAPI 接口定义（schema）成为一切的锚点。

流程

#

每周选两名代表，后端一名、前端一名。他们的任务是吃透本次 Sprint 的需求，并让计划用的 OpenAPI 接口定义与之对齐。两人一起评审这份定义，把对不上的地方改掉。等这一步做完，在动手之前，双方就已经确切知道要造的是什么了。

修订定稿后，把接口定义提交到仓库，CI/CD 会根据这份 yaml 生成模拟 API。Sprint 结束时，再切一份覆盖下个 Sprint API 需求的新 yaml，循环往复。

工具备忘

#

可视化 yaml 用 Swagger Editor 就够了：把文件传上去，就能看到渲染好的 Swagger 文档。

CI/CD 流水线需要能接收 yaml 并据此拉起一个模拟服务器。Stoplight 的 Prism 用的人很多，也支持 OpenAPI 3.1：

npm install -g @stoplight/prism-cli
prism mock openapi.yaml

这样接口定义里的所有路径都会在 http://127.0.0.1:4010 上提供服务，返回的就是定义里的 examples，比如请求 GET /lists/10，拿到的就是附录里那条示例列表。它还会替你守住契约：示例声明了 API key，所以不带 X-API-Key 请求头的请求会直接收到 401，而这正是前端应该照着去做的行为。在容器里跑的话，记得加上 -h 0.0.0.0，外面才访问得到。openapi-mock 是个更轻量的替代品，会用随机数据填充响应。

拉起模拟服务器之前，最好先给接口定义做一遍 lint。契约写坏了，构建直接失败，总比让前端一头雾水强。Spectral 只要一行规则集就能跑起来：

npm install -g @stoplight/spectral-cli
echo 'extends: ["spectral:oas"]' > .spectral.yaml
spectral lint openapi.yaml

最后，这份接口定义纯粹是计划产物。真实 API 部署之后，应该由各服务自己生成 openapi.json，下载下来再喂给下一轮计划。

为什么值得费这个劲

#

因为争论被挪到了代价最低的地方。写接口定义的时候前后端工程师都在场，误解还没变成代码就被抓住了。API 需求一次谈妥，不用在 Sprint 中途反复扯皮；有了模拟服务器，前端立刻就能开工，不用干等；关键细节被漏掉的机会也小得多——它们得同时躲过两双眼睛和一份白纸黑字的契约才行。

这里没有任何革命性的东西。只是把计划做得足够具体，具体到机器能把它当成模拟服务还给你——事实证明，一份计划需要的具体程度，恰好就是这个程度。

附录A - yaml示例

#

openapi: 3.1.0
info:
  title: MyApp Sprint 3
  description: Planning schema for sprint 3. Drives the mock server only.
  version: 0.3.0
servers:
  - url: https://api-mock.example.com/v1
tags:
  - name: lists
    description: Saved lists feature (PROJ-123)
security:
  - api_key: []
paths:
  /lists:
    get:
      tags: [lists]
      summary: Return the current user's saved lists
      operationId: getLists
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/List'
  /lists/{listId}:
    get:
      tags: [lists]
      summary: Find a list by ID
      operationId: getListById
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          description: List not found
components:
  schemas:
    List:
      type: object
      required: [id, title]
      properties:
        id:
          type: integer
          format: int64
          examples: [10]
        title:
          type: string
          examples: [Weekend reading]
        itemCount:
          type: integer
          examples: [7]
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header

等待的游戏

#

传统流程是串行的：后端先设计并实现 API，等接口真正能跑了，前端才开始对接。后端的每一次延误都会直接砸到前端的日程表上，而发布日期恰恰写在前端的日程表里。

契约在前，代码在后

#

按“接口定义优先”（schema-first）的流程，两边几乎可以同时起跑。在一行代码都不存在的时候，先把 API 的结构写进 OpenAPI 接口定义——每个端点、请求和响应模型、认证方式、错误码。这份文档就是前后端之间的合同。

回报来得很快。功能还没开工，所有人对它的理解就已经一致。后端还在实现，前端就能开始搭 UI。变更也转得更快，因为只有一份公认的事实来源需要更新。而且接口定义可以直接生成模拟服务器，在一个真实接口都没有的时候，前端测试就能开跑。

实际怎么跑

#

1. 收集需求，跟做任何东西一样。
2. 设计接口定义：端点、请求/响应模型、认证、错误码。
3. 让前端和后端一起评审——契约的价值就体现在这一步。
4. 生成模拟服务器（Swagger 和 Postman 都能做），前端先对着它集成。
5. 后端照着同一份接口定义实现真实接口。
6. 接口做好一个就替换一个模拟端点，持续测试，确保契约没被破坏。
7. 保持沟通。接口定义是活文档，不是石碑。

要付的代价

#

这套流程不是免费的。提前写一份周全的接口定义要花实打实的时间。需求一变，得先改接口定义，涟漪会波及两个团队。另外每个人都得对 OpenAPI 和配套工具有基本的手感。

即便如此，我还没见过这笔前期投入输给它省下的集成混乱。前端第一天就能开工，而争论发生在文档上，而不是发生在挂掉的构建里。