📚 课程目录第2章接口契约设计

接口契约设计：OpenAPI/Swagger规范入门

说到接口契约，我脑子里第一个蹦出来的词就是「沟通成本」。你想想看，前端和后端各写各的文档，联调时才发现字段名对不上、类型不一致——这种场景我见过太多次了。OpenAPI（以前叫Swagger）就是来解决这个问题的。

说白了，接口契约就是一份「双方都认的协议」。后端按这个协议实现，前端按这个协议调用。谁也别跑偏。

为什么需要接口契约？

我在2017年带过一个电商项目，前后端各20多人。那时候没有契约，全靠Word文档和微信群沟通。结果呢？上线前联调，发现订单接口的字段名改了三次，前端同学差点掀桌子。

从那以后，我强制团队所有接口必须走OpenAPI规范。效果立竿见影——联调时间缩短了60%。

核心价值：

消除歧义：一份规范，两端理解一致
自动生成：客户端SDK、服务端桩代码、测试用例都能自动生成
可验证：工具可以自动校验实现是否偏离契约
版本管理：接口变更可追溯、可评审

OpenAPI vs Swagger：别再搞混了

很多人问我：「Swagger和OpenAPI到底啥关系？」我习惯这么解释：

概念	说明
OpenAPI	规范本身，由Linux基金会管理，目前最新是3.1.0
Swagger	SmartBear公司的工具集，实现了OpenAPI规范
Swagger UI	可视化文档展示工具，最常用的Swagger组件
Swagger Editor	在线编辑OpenAPI规范的工具

嗯，记住一句话：OpenAPI是标准，Swagger是实现。就像HTTP协议和浏览器一样。

YAML与JSON：两种定义方式

OpenAPI规范支持两种格式：YAML和JSON。我个人更偏爱YAML，原因很简单——可读性强。你看下面这个对比：

JSON版本

{
  "openapi": "3.1.0",
  "info": {
    "title": "用户服务API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "获取用户信息",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回用户对象"
          }
        }
      }
    }
  }
}

YAML版本

openapi: 3.1.0
info:
  title: 用户服务API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: 获取用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户对象

我的建议：团队协作时用YAML写规范，因为代码评审时更容易看出差异。但如果是机器生成或解析，JSON更稳定。我一般让团队用YAML写源文件，CI/CD时自动转成JSON发布。

路径与参数设计：实战中的坑

这部分我踩过的坑最多。先看一个典型的路径设计：

paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            default: 20
    post:
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
  /users/{userId}:
    get:
      summary: 获取单个用户
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
    put:
      summary: 更新用户
    delete:
      summary: 删除用户

参数类型详解

参数位置	说明	典型场景
`path`	路径参数，必须	资源ID：`/users/{id}`
`query`	查询参数，可选	分页、过滤：`?page=1&size=20`
`header`	请求头参数	认证Token、请求ID
`cookie`	Cookie参数	会话标识

我曾经踩过的坑：

路径参数忘了加 required: true，结果生成的客户端代码没传ID，接口直接404
query参数没设 default 值，前端没传分页参数时后端收到 undefined
参数类型写错——比如用户ID用 integer 但实际是UUID字符串

知识结构总览

下面这张图是我自己总结的接口契约设计核心脉络，你可以把它当作学习地图：

实战建议：从零开始写第一个OpenAPI规范

如果你刚接触，我建议按这个步骤来：

先画资源图：把业务对象列出来，比如用户、订单、商品
确定端点：每个资源对应哪些操作（CRUD）
写YAML骨架：只写路径和基本参数，不急着写schema
用Swagger Editor预览：实时看效果，调整路径设计
补充schema：定义请求体和响应体的数据结构
加示例：每个接口至少给一个请求和响应的示例

小技巧：我习惯在项目根目录放一个 api/ 文件夹，里面按模块拆分YAML文件，然后用 $ref 引用。这样多人协作时不会冲突，评审也方便。

避坑指南

最后分享几个我亲身经历过的教训：

路径冲突：/users/{id} 和 /users/search 会冲突，因为search会被当成id。解决方案：把搜索放到 /users?q=xxx 或者 /users/search 用静态路径
参数命名不一致：有的接口用 userId，有的用 user_id。团队必须统一风格，我推荐小驼峰
忽略错误响应：只定义了200成功，没定义400、404、500。前端拿到错误时一脸懵
版本号放路径里：/v1/users 还是 /api/v1/users？我建议用请求头或URL前缀统一管理

接口契约设计不是一蹴而就的事。刚开始可能会觉得繁琐，但坚持下来，你会发现联调效率提升不是一点半点。嗯，先说到这里，动手写一个试试吧。