1. 服务接口建模概述

各位同学，咱们今天聊一个看似基础、但实际坑特别多的话题——服务接口建模。我做了十几年系统架构，见过太多因为接口设计没想清楚，后期改得痛不欲生的项目。说白了，接口就是系统的门面，门面没装好，里面再漂亮也白搭。

1.1 什么是服务接口

服务接口，简单理解就是系统之间通信的契约。你想想看，两个服务要交换数据，总得有个双方都认可的格式和协议吧？这个约定就是接口。

我个人习惯把接口分成三个层次来看：

• 传输层：用什么协议？HTTP、gRPC、消息队列？
• 语义层：数据长什么样？字段含义是什么？
• 行为层：调用后会发生什么？是查询还是修改？

我在项目中遇到过最典型的反面教材：一个团队把订单查询接口设计成 POST 方法，理由是“参数太多，GET 放不下”。结果前端缓存没法做，安全扫描还报了一堆漏洞。嗯，这里要注意——接口设计不是“能用就行”，而是要考虑整个生态。

1.2 接口建模的目的与价值

为什么要花时间做接口建模？直接写代码不香吗？

我曾经在一个大型电商平台项目里，前期没做接口建模，开发到一半发现：订单服务和库存服务对“商品ID”的理解完全不一样——一个用字符串，一个用整数。联调时数据全对不上，重构花了三周。从那以后，我再也不敢跳过接口建模这一步。

接口建模的核心价值，我总结为四点：

维度	价值	我的经验
对齐	让前后端、服务间对数据格式达成共识	用 OpenAPI 规范做契约测试，比口头约定靠谱一百倍
复用	避免重复造轮子，相同数据结构统一建模	用户信息这种基础模型，一次建模到处引用
演进	接口版本管理，兼容升级	我习惯用 URL 路径版本号，简单粗暴有效
文档	自动生成文档，降低沟通成本	Swagger UI 直接给前端看，省去写接口文档的时间

1.3 RESTful 与 GraphQL 对比

说到接口设计风格，绕不开两个主流方案：RESTful 和 GraphQL。很多新手问我该选哪个，我的回答是：看场景。

RESTful：资源驱动的经典方案

RESTful 的核心思想是把一切抽象为资源，用 HTTP 方法表达操作。说白了就是：

• GET /users — 查用户列表
• POST /users — 创建用户
• GET /users/{id} — 查单个用户
• PUT /users/{id} — 全量更新
• PATCH /users/{id} — 部分更新
• DELETE /users/{id} — 删除用户

我在项目中遇到过一个问题：RESTful 接口经常面临“过度获取”或“获取不足”。比如前端只需要用户的名字和头像，但接口返回了整个用户对象，包含几十个字段。这就是典型的“over-fetching”。

// RESTful 典型响应
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",
  "address": "北京市朝阳区...",
  "avatar": "https://...",
  "createdAt": "2024-01-01",
  "updatedAt": "2024-06-01",
  // ... 还有十几个字段
}

GraphQL：按需查询的灵活方案

GraphQL 的出现就是为了解决 RESTful 的痛点。客户端可以精确指定需要哪些字段，不多不少。

// GraphQL 查询
query {
  user(id: 123) {
    name
    avatar
  }
}

// GraphQL 响应
{
  "data": {
    "user": {
      "name": "张三",
      "avatar": "https://..."
    }
  }
}

你想想看，这多爽？前端要什么给什么，后端也不用担心接口膨胀。但 GraphQL 也有自己的问题——查询复杂度不可控。我曾经见过一个前端同事写了个嵌套五层的查询，直接把数据库打挂了。

核心对比

维度	RESTful	GraphQL
数据获取	服务端决定返回结构	客户端决定返回结构
缓存	天然支持 HTTP 缓存	需要额外实现缓存层
学习曲线	低，HTTP 基础即可	中，需要理解 Schema 和 Resolver
版本管理	URL 或 Header 版本号	通过 Schema 演进，无需显式版本
适用场景	资源型 CRUD、公开 API	复杂数据聚合、前端驱动开发
性能风险	N+1 查询问题	查询深度爆炸、复杂度失控

我个人习惯这样选型：如果项目是标准的 CRUD 业务，对外提供 API，我倾向 RESTful。如果项目是数据聚合层，前端需求变化快，我会考虑 GraphQL。但记住——没有银弹。

1.4 知识体系总览

下面这张图是我自己总结的接口建模知识体系，你可以把它当作本章的思维导图：

这张图把接口建模拆成三个维度：定义、风格、治理。后面的课程会逐一深入。记住，建模不是画图，而是为了落地。没有治理的接口，早晚会变成一团乱麻。