📚 课程目录第4章接口定义语言（IDL）

接口定义语言（IDL）：从WSDL到OpenAPI

说到接口定义，我刚开始做分布式系统那会儿，团队里最头疼的事就是「接口又对不上了」。前端说后端少了个字段，后端说前端传错了格式，两边扯皮能扯半天。后来我们才意识到——缺一个契约。

这个契约，就是接口定义语言（IDL）。

IDL 到底解决了什么问题？

说白了，IDL 就是一份接口说明书。它用一套标准化的语法，把接口的输入、输出、错误码、调用方式全部写清楚。机器能读，人也能读。

我见过不少团队，接口文档全靠 Word 写，或者干脆让开发「看代码」。结果呢？接口改了，文档没改，新人来了直接懵。嗯，这就是典型的「隐性知识」陷阱。

  IDL 的核心价值：
  契约先行——前后端、服务之间按同一份定义开发，减少联调成本
自动化生成——客户端 SDK、服务端桩代码、测试用例都能自动生成
版本管理——接口变更可追溯，兼容性一目了然
工具生态——文档预览、Mock 服务、契约测试，一套工具链全搞定

从 WSDL 到 OpenAPI：一场进化

最早接触 IDL 是在做 SOA 架构的时候。那时候的王者是 WSDL（Web Services Description Language）。

WSDL 配合 SOAP 协议，定义得非常严谨。请求是什么 XML 结构，响应是什么命名空间，连错误码都给你规定死。但问题也出在这里——太复杂了。一个简单的查询接口，WSDL 能写几百行。我记得有一次为了调通一个第三方支付接口，光解析 WSDL 就花了两天。

后来 RESTful 风格起来了，大家发现：接口定义不需要那么重。HTTP 方法、URL 路径、JSON 格式，这些天然就是自描述的。但光靠约定还不够，团队大了还是需要一份标准定义。

这时候 OpenAPI（原名 Swagger）出现了。它用 JSON 或 YAML 描述 RESTful 接口，轻量、可读、工具链丰富。现在基本成了业界事实标准。

对比维度	WSDL	OpenAPI
协议	SOAP（XML）	HTTP（JSON/YAML）
复杂度	高，学习曲线陡	中低，上手快
工具生态	有限，主要靠商业工具	丰富，开源为主
可读性	差，XML 嵌套深	好，YAML 简洁直观
适用场景	企业级、强类型、事务性	互联网、微服务、移动端

我的建议：新项目直接上 OpenAPI。除非你还在维护遗留的 SOAP 系统，否则别碰 WSDL。你想想看，现在哪个前端愿意去解析 XML？

用 OpenAPI 定义 RESTful 接口

OpenAPI 规范目前最新是 3.1 版本。核心结构其实不复杂，我拆成几个部分来讲。

1. 基本信息与路径

一个 OpenAPI 文档，最外层就是版本号、标题、服务器地址。然后就是 paths，定义所有接口路径。

openapi: "3.1.0"
info:
  title: 用户服务 API
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

你看，一个 GET /users 接口，参数、响应、状态码全写清楚了。前端拿到这个 YAML，直接就能生成 TypeScript 类型定义。

2. 数据模型（Schema）

接口里最常变的其实是数据结构。OpenAPI 用 components/schemas 来定义可复用的模型。

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          description: 用户唯一标识
        name:
          type: string
          maxLength: 50
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time

我曾经踩过的坑：一开始没加 required 字段，结果前端以为所有字段都可空，后端却默认 id 必传。联调时数据对不上，查了半天才发现是定义不严谨。所以，必填字段一定要显式声明。

3. 请求体与响应体

POST/PUT 接口需要定义请求体。用 requestBody 指定媒体类型和 schema。

paths:
  /users:
    post:
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: 参数校验失败

响应体同理。我习惯把成功和失败的响应都定义清楚，这样前端做错误处理时不用猜。

4. 安全认证

接口安全怎么定义？OpenAPI 支持多种认证方式：API Key、Bearer Token、OAuth2 等。

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: []

这样一写，工具就能自动生成带 token 的请求代码。省事不少。

OpenAPI 工具链实战

光有定义文件还不够，得用起来。我常用的工具链是这样的：

Swagger Editor——在线编辑 YAML，实时预览文档
Swagger UI——生成可交互的 API 文档，前端可以直接在页面上调试
OpenAPI Generator——自动生成客户端 SDK（Java、Python、TypeScript 都支持）
Prism——根据 OpenAPI 文档启动 Mock 服务，前后端可以并行开发

我的工作流：先写 OpenAPI 定义，然后提交到 Git 仓库。CI 里自动生成文档和 Mock 服务。前端拿到 Mock 地址就开始开发，后端按定义实现。联调时基本一次过。

一张图看懂 IDL 演进与 OpenAPI 核心

下面这张图，我把 IDL 的演进路线和 OpenAPI 的核心结构画在了一起。你可以对照着理解。

避坑指南

最后分享几个我踩过的坑，希望能帮你少走弯路。

别把 OpenAPI 当文档写——它首先是契约，其次才是文档。先定义，再实现，别反着来。
版本号别乱改——接口升级时，路径或参数要向后兼容。实在要 breaking change，就开新版本路径，比如 /v2/users。
别把所有字段都塞进一个 schema——拆成多个小模型，复用性更好。比如 User 和 CreateUserRequest 分开定义。
错误响应也要定义——很多团队只定义成功响应，前端遇到 4xx/5xx 全靠猜。把错误码和错误消息结构化定义清楚。

我曾经犯过的错：有一次接口返回的日期格式没在 OpenAPI 里声明，前端以为是 "2024-01-01"，后端实际返回的是 "2024-01-01T00:00:00Z"。结果页面日期显示全乱了。从那以后，所有字段的 format 我都写得明明白白。

好了，IDL 和 OpenAPI 的核心内容就这些。记住一句话：接口定义不是写文档，是定契约。契约写好了，团队协作才能顺畅。