06.1.1.2 契约优先与协议选型
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.1 通用后端工程 / 06.1.1 API 设计与契约
本节要解决的问题
- REST、gRPC、GraphQL、WebSocket 各自解决什么问题,怎么选?
- 什么是契约优先,OpenAPI 在其中扮演什么角色?
- 契约如何做版本兼容、评审与测试?
06.1.1.2-001 REST / gRPC / GraphQL 三者怎么选?
一句话结论
REST 通用、缓存友好、易调试,适合对外开放;gRPC 基于 HTTP/2 + Protobuf,高性能强类型流式调用,适合内部服务;GraphQL 按需取字段、减少 over-fetching,适合聚合多资源的前端场景。
对比
| 维度 | REST | gRPC | GraphQL |
|---|---|---|---|
| 传输 | HTTP/1.1 + JSON | HTTP/2 + Protobuf 二进制 | HTTP + JSON 查询 |
| 类型契约 | OpenAPI 描述 | Protobuf IDL | Schema 定义 |
| 字段裁剪 | 靠接口设计 | 消息字段固定 | 查询时按需选字段 |
| 流式 | WebSocket/SSE 补充 | 原生四种流模式 | 订阅(Subscriptions) |
| 浏览器直连 | 友好 | 需代理/网关转码 | 友好 |
| 缓存 | HTTP 缓存成熟 | 弱 | 缓存需额外设计 |
常见误区
- 认为 gRPC 一定取代 REST:浏览器直连、公开 API、可读调试场景 REST 仍占优。
- 认为 GraphQL 解决所有数据需求:查询复杂度、缓存、N+1 与权限控制成本更高。
追问
- 内部服务调用为什么常用 gRPC?二进制小、多路复用、强类型契约、流式支持。
- 一个系统三者能否共存?可以:对外 REST,内部 gRPC,BFF 层用 GraphQL 聚合。
06.1.1.2-002 什么是契约优先(contract-first)?
一句话结论
先定义接口契约(路径、方法、请求/响应结构、错误码、示例),再由契约生成服务端骨架与客户端代码,而不是先写代码再补文档。
概念解释
契约(contract)是双方达成的接口约定。契约优先意味着契约是源头:前后端并行开发,mock 依据契约生成;代码变更必须先改契约并评审。与之相对的是代码优先(code-first):从实现反推文档,容易与实现漂移。
原理流程
- 设计 OpenAPI / Protobuf / GraphQL Schema。
- 评审契约:字段、类型、错误码、兼容性。
- 生成服务端 stub、客户端 SDK、文档与 mock。
- 实现填充业务逻辑;契约变更走版本流程。
示例
# OpenAPI 片段
paths:
/orders/{id}:
get:
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200': { description: OK }
常见误区
- 契约优先等于先写一份 Word 文档:可执行的契约必须是机器可读规范(OpenAPI/IDL/Schema)。
- 契约定死不允许演进:契约需要兼容版本策略,见 06.1.1.2-009。
追问
- 契约优先最大收益是什么?并行开发、类型对齐、减少联调返工。
- 代码-first 就一定差?小团队快速迭代时代码-first 配合生成文档也可行,但要防止文档漂移。
06.1.1.2-003 OpenAPI 规范解决什么问题?
一句话结论
OpenAPI(原 Swagger)用机器可读 YAML/JSON 描述 HTTP API 的路径、参数、请求响应结构、认证方式与示例,是 REST 契约的标准格式。
概念解释
OpenAPI Specification(OAS)定义接口的元数据:标题、版本、路径与操作、参数位置(path/query/header/body)、Schema 类型、响应状态码、安全方案、示例。工具据此生成文档页面、mock、客户端与服务端代码、契约测试用例。
示例
openapi: 3.0.3
info: { title: "Order API", version: "1.0.0" }
paths:
/orders:
post:
requestBody:
content:
application/json:
schema: { $ref: "#/components/schemas/OrderRequest" }
responses:
'201': { description: Created }
components:
schemas:
OrderRequest:
type: object
required: [items]
properties:
items: { type: array, items: { type: integer } }
常见误区
- OpenAPI 只是「接口文档页面」:它首先是契约文件,文档页面只是渲染产物之一。
- 把实现细节(内部字段、SQL 错误)写进公开 Schema。
追问
- OAS 3.0 与 3.1 主要差异?3.1 对齐 JSON Schema,放宽示例与类型表达;工具链兼容性需先确认。
- Schema 中如何表达可空字段?
nullable: true(3.0)或类型[T, "null"](3.1)。
06.1.1.2-004 如何维护 OpenAPI 文档与代码一致?
一句话结论
以生成或校验机制保证一致:契约优先则从 OAS 生成代码;代码优先则从注解/实体生成 OAS,并在 CI 中做契约校验,禁止手工改生成物。
概念解释
漂移的常见原因是文档手工维护。保持一致的三条路:
- 契约优先:OAS 生成 stub,实现不能改契约结构。
- 代码优先:从路由注解、模型类生成 OAS(如 Swashbuckle、SpringDoc)。
- CI 校验:对比生成的 OAS 与仓库中的契约文件,破坏性变更必须过评审。
常见误区
- 线上文档与接口长期不一致:前端按文档联调,实际行为另一样。
- 手工编辑 Swagger 页面再让代码适配:方向反了,生成物不应手改。
追问
- 如何防止字段悄悄加进响应?响应模型由 DTO 固定,序列化时排除未声明字段。
- 契约测试与文档校验什么关系?文档校验保证结构一致;契约测试保证行为符合样例。
06.1.1.2-005 如何从 OpenAPI 生成服务端/客户端代码?
一句话结论
用代码生成器读 OAS,产出客户端 SDK(带类型的请求方法)或服务端 stub(路由 + 模型 + 待实现接口);生成产物纳入版本控制或构建缓存,不手工修改。
概念解释
- 客户端生成:按 Schema 生成请求方法、类型定义、错误类型。
- 服务端生成:生成控制器接口/路由骨架,业务方法留空实现。
- 典型工具:OpenAPI Generator、Swagger Codegen;前端有 TypeScript 类型生成。
示例
openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-axios \
-o src/api/generated
常见误区
- 直接编辑生成目录:下次重新生成被覆盖。
- 把生成的模型当领域模型:生成类型用于传输,内部领域对象独立维护。
追问
- 生成代码版本锁定吗?锁定生成器版本,避免输出风格漂移。
- 服务端生成骨架有什么风险?脚手架把路由绑死,灵活定制受限;小项目可代码优先。
06.1.1.2-006 gRPC 的 Protobuf 有什么约束?
一句话结论
Protobuf 用 .proto IDL 定义消息与服务,字段用编号标识;编号一旦分配不可复用,字段可删除但编号要保留,以保证二进制前后兼容。
概念解释
- 消息字段:
string orderId = 1;,数字是字段编号,不是默认值。 - 兼容性:新增字段给新编号;删除字段保留编号(
reserved);不要改字段类型。 - 服务:
service OrderService { rpc GetOrder(...) returns (...); }。
示例
syntax = "proto3";
message GetOrderRequest {
string order_id = 1;
}
message GetOrderResponse {
string id = 1;
string status = 2;
reserved 3; // 已删除字段编号,禁止复用
}
service OrderService {
rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);
}
常见误区
- 字段编号从 1 重复使用给新字段:旧二进制数据按旧编号解析出错。
- 直接改字段类型:线格式不兼容,反序列化损坏。
追问
- proto3 与 proto2 差异?proto3 默认移除必填字段、简化语法;枚举首项必须为 0。
- 枚举新增值要注意什么?老客户端遇到未知枚举值按默认值处理,不能假设所有端都认识新值。
06.1.1.2-007 GraphQL 的查询与类型系统要点是什么?
一句话结论
GraphQL 用 Schema 定义类型与字段,客户端在查询中选择需要的字段,服务端解析成数据;有类型系统、查询参数(arguments)与嵌套关系,但需要控制查询深度与复杂度。
概念解释
- Schema:
type Order { id: ID!, items: [Item!]! },!表示非空。 - 查询:
query { order(id: "1") { id status items { name } } }。 - Resolver:每个字段对应一个解析函数;关联字段可能触发额外数据加载。
- 风险:深层嵌套查询、循环引用、N+1;需要深度限制、复杂度评分与批量加载(DataLoader)。
示例
query {
order(id: "1001") {
id
status
items { name price }
}
}
常见误区
- 认为 GraphQL 不需要后端设计:反而需要精心设计聚合、权限与批量加载。
- 不加深度/复杂度限制:单个查询拖垮数据库。
追问
- GraphQL 的 N+1 怎么解决?DataLoader 按批次聚合加载,同一轮合并请求。
- 缓存为什么更难?查询字段组合多变,HTTP 缓存键不好定;可按资源标识做持久化缓存。
06.1.1.2-008 不同协议内的错误如何表达?
一句话结论
错误都要包含稳定错误码、可读提示、调试标识;REST 用状态码 + 错误体,gRPC 用 Status Code + 消息,GraphQL 在响应的 errors 数组中表达;不要把堆栈返回客户端。
概念解释
- REST:HTTP 状态码分类 + body 错误对象(code/message/fieldErrors/traceId)。
- gRPC:
google.rpc.Status,标准码(NOT_FOUND/INVALID_ARGUMENT/...)+ 细节消息。 - GraphQL:数据在
data,部分失败在errors,可定位到字段路径。
示例
// REST 错误体
{
"code": "ORDER_NOT_FOUND",
"message": "订单不存在",
"traceId": "7f3a91c2"
}
常见误区
- 所有错误都用同一通用码:客户端无法分支处理。
- 错误体返回内部堆栈、类名、SQL。
追问
- 字段级校验错误放哪?REST 可在
fieldErrors中按字段列出;GraphQL errors 带locations/path。 - 错误码需要国际化吗?码稳定,提示文案可由前端按码映射多语言。
06.1.1.2-009 版本演进在契约层如何保证兼容?
一句话结论
优先向后兼容:只新增可选字段/枚举值/接口,不删不改旧字段;破坏性变更才升版本;弃用期内双版本并行。
概念解释
兼容规则:
- 新增:可选字段、新接口、新枚举值(旧端按未知处理)。
- 不兼容:删除字段、改字段类型/语义、改必填、收紧校验、改错误码。
- 版本载体:URL 路径、请求头、媒体类型版本;见 06.1.1.2 之外的版本化讨论(06.1.1.3-004 相关条目)。
常见误区
- 直接改字段含义而不升版本:老客户端解析错乱。
- 认为加字段一定安全:把可选字段改成必填就破坏兼容。
追问
- 废弃字段怎么处理?标注 deprecated,保留一段时间,公告迁移后再删。
- 如何检查破坏兼容?契约 diff 工具对比新旧 Schema,标记删除/类型变更/必填化。
06.1.1.2-010 枚举与新增字段的兼容规则是什么?
一句话结论
枚举新增值要考虑旧端未知;字段新增必须可选;旧端忽略未知字段是普遍行为,但不能依赖服务端宽松到丢弃错误类型。
概念解释
- 枚举:老客户端不认识新枚举值时通常落到默认值或报错,跨端发布顺序要安排。
- 字段:新老版本并存时,新字段设可选;老服务端收到未知字段应忽略而不是报错(宽松读取)。
- 写入:客户端不要假设新字段在老服务端存在。
常见误区
- 把枚举新值当作所有端都已支持。
- 服务端对未知字段直接 400 拒绝:前后端发布窗口内容易误拒。
追问
- 枚举值能否复用?不能;语义不同的值不要用同一编号/字符串。
- 布尔字段后续要扩成枚举怎么办?一开始就考虑用字符串标识,避免布尔扩展破坏兼容。
06.1.1.2-011 JSON 与 Protobuf 的序列化取舍?
一句话结论
JSON 可读、通用、浏览器友好,结构松散;Protobuf 二进制紧凑、解析快、带强类型 schema,但不可直读、需要 IDL 与生成代码。
对比
| 维度 | JSON | Protobuf |
|---|---|---|
| 可读性 | 文本可读 | 二进制,需解码 |
| 体积 | 较大 | 小 |
| 性能 | 解析相对慢 | 序列化/解析快 |
| 类型约束 | 弱,靠 Schema 描述 | IDL 强约束 |
| 浏览器 | 原生支持 | 需转码/代理 |
常见误区
- 内部高并发链路也坚持 JSON 文本:CPU 与带宽成本更高。
- 公开 API 直接上 Protobuf:调试与接入成本高。
追问
- MessagePack/FlatBuffers 是什么?同类二进制序列化方案,取舍在 schema、可读性与运行时。
- gRPC 能否换 JSON 编码?可以用 JSON 编解码做调试/兼容,但失去默认二进制优势。
06.1.1.2-012 内部服务调用与对外开放 API 分别选什么协议?
一句话结论
内部服务间按性能与语言生态选 gRPC/Thrift/消息队列;对外开放按可调试性与生态选 REST/HTTP + JSON,必要时 GraphQL 做 BFF 聚合。
概念解释
- 内部:调用双方可控、性能敏感、契约稳定 → 强类型 RPC。
- 外部:客户端多样、需要浏览器/缓存/文档生态 → REST 为主。
- 边界:内部 RPC 不直接暴露给外部,经网关协议转换。
常见误区
- 把内部 gRPC 端口直接给第三方接入:浏览器、调试、WAF/网关规则都不适配。
- 对外 API 模仿内部 RPC 方法命名:失去资源抽象与缓存能力。
追问
- 内部异步通信用什么?消息队列(见 09 分册);同步调用才用 RPC。
- 网关做协议转换要注意什么?超时、错误码映射、限流与鉴权在边界统一。
06.1.1.2-013 WebSocket/SSE 与请求-响应协议的边界是什么?
一句话结论
请求-响应适合一次性获取/提交;WebSocket 全双工长连接适合双向实时推送;SSE 是服务端单向推送的轻量方案,不要用轮询硬扛实时场景。
对比
| 方案 | 方向 | 适用 | 限制 |
|---|---|---|---|
| HTTP 请求-响应 | 客户端发起 | 查询、提交 | 无服务端主动推送 |
| SSE | 服务端 → 客户端 | 通知、进度推送 | 单向,文本事件流 |
| WebSocket | 双向 | 聊天、协作、实时交易 | 连接管理、背压、扩展 |
常见误区
- 用高频短轮询模拟实时:连接开销与延迟都差。
- 所有实时需求都上 WebSocket:单向通知 SSE 更简单,且走 HTTP 基础设施。
追问
- SignalR 与它们什么关系?SignalR 在 .NET 侧封装传输协商,可降级到 WebSocket/SSE/长轮询(见 06.3.2.4)。
- 长连接横向扩展怎么做?需要消息背板(Redis/队列)跨实例广播。
06.1.1.2-014 契约测试解决什么问题?
一句话结论
契约测试验证消费方与提供方对同一契约理解一致:提供方不破坏消费方依赖的字段与行为,消费方不滥用未约定的能力。
概念解释
- 提供方契约测试:基于消费方期望生成用例,验证提供方未破坏兼容。
- 消费方契约测试:mock 提供方,按契约验证自身调用。
- 典型工具:Pact、Spring Cloud Contract;与单元测试、E2E 测试分工不同。
常见误区
- 把接口联调当契约测试:联调只覆盖当下环境,不回归历史消费方。
- 契约测试替代端到端:它验证协议约定,不验证完整业务链路。
追问
- 微服务间为什么尤其需要契约测试?提供方独立发布,没有契约保护易出现静默破坏。
- 契约从哪里来?从 OpenAPI/IDL/Pact 文件生成,保持单一源头。
06.1.1.2-015 接口弃用(deprecation)流程怎么设计?
一句话结论
先公告与版本标记,新旧版本并行一个弃用周期,引导调用方迁移,最后下线;过程中保留通知机制(响应头、文档、监控)。
概念解释
- 标记:OpenAPI
deprecated: true;响应头Deprecation/Sunset。 - 周期:文档公告、兼容窗口、客户端升级监控。
- 下线:先停止新接入,再逐步切流,最后移除实现。
示例
Deprecation: true
Sunset: "2027-01-01"
Link: </docs/v2>; rel="successor-version"
常见误区
- 无公告直接删接口:线上集成方报错。
- 弃用接口不监控:不知道还有谁在调用,无法评估下线影响。
追问
- 如何统计旧版本调用?网关/访问日志按版本路径或头统计调用方。
- 弃用期多长?按调用方发布节奏定,通常至少一个发布周期并留出迁移窗口。
06.1.1.2-016 接口文档应包含哪些内容?
一句话结论
每个操作包含用途、认证要求、路径与方法、参数(位置/类型/必填/示例)、请求体、成功与错误响应、示例、兼容性与弃用说明。
概念解释
文档面向接入方:能据此构造请求、理解错误、判断权限。除结构外,还要给业务语义(字段取值范围、枚举含义、分页约定)与非功能约定(限流、超时、幂等)。
常见误区
- 文档只有 URL 和字段表,没有示例与错误场景。
- 字段语义靠代码注释,接入方猜含义。
追问
- 示例放哪里?OpenAPI 的
example/examples,同时渲染成文档页面。 - 异步接口文档怎么描述?AsyncAPI 规范描述消息主题、事件结构与投递语义。
06.1.1.2-017 多团队协作时契约如何评审?
一句话结论
契约作为独立变更评审:字段命名、类型、必填、错误码、兼容性与安全字段;评审通过后冻结基线,变更走版本与 diff 检查。
概念解释
- 评审参与:提供方、消费方代表、安全/架构角色。
- 检查项:语义是否清晰、是否暴露内部实现、是否破坏兼容、权限与敏感字段。
- 流程:PR 改契约 → 自动 diff → 人工评审 → 生成产物。
常见误区
- 契约评审只看代码能不能跑:漏掉命名一致性与兼容风险。
- 消费方没有代表参与:字段设计偏离使用场景。
追问
- 契约冲突如何裁决?以业务能力边界与版本兼容为依据,架构角色仲裁。
- 评审后发现字段不合理怎么办?在未发布前改;已发布则走新增/版本流程。
06.1.1.2-018 二进制/文件上传下载用什么形式?
一句话结论
小文件 multipart/form-data 上传;大文件分片上传 + 秒传;下载用文件流 + 正确 Content-Type 与 Content-Disposition;对象存储场景接口只返回标识/URL。
概念解释
- 上传:
multipart/form-data携带文件与表单字段;大文件分片、断点续传、校验哈希。 - 下载:流式返回,设置
Content-Type、Content-Length、Content-Disposition(附件/内联)。 - 大文件不建议经过应用服务器中转,优先对象存储直传/预签名 URL。
示例
POST /uploads
Content-Type: multipart/form-data; boundary=----
GET /files/88/download
Content-Disposition: attachment; filename="report.xlsx"
常见误区
- 把大文件读进内存再返回:内存暴涨。
- 下载 URL 直接暴露内部存储路径。
追问
- 预签名 URL 解决什么?客户端直传对象存储,应用服务器不中转字节流。
- 上传安全检查什么?类型白名单、大小限制、病毒扫描、内容校验、归属鉴权。
06.1.1.2-019 契约中的认证信息如何描述?
一句话结论
在 OpenAPI securitySchemes 中定义 Bearer JWT、ApiKey、OAuth2 等方案,并在操作上标注需要的 scope/角色;文档生成器据此展示鉴权要求。
概念解释
- 方案类型:
http(Bearer)、apiKey(header/query/cookie)、oauth2、openIdConnect。 - 操作级
security覆盖全局方案;公开接口显式声明无认证。
示例
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
常见误区
- 契约里不写鉴权要求:接入方不知道要带什么凭证。
- 在文档中放测试令牌或真实密钥。
追问
- 多租户接口鉴权在契约怎么体现?头/参数携带租户标识,权限说明在描述中。
- API Key 放 header 还是 query?优先 header;query 易进日志。
06.1.1.2-020 主流工具链有哪些?
一句话结论
REST 生态:OpenAPI Generator、Swagger UI/Redoc、Swashbuckle/SpringDoc;消息生态:AsyncAPI;RPC:Protobuf 编译器与 gRPC 工具;按团队技术栈选型,保持单一契约源头。
概念解释
- 文档渲染:Swagger UI(交互)、Redoc(文档风)。
- 生成:OpenAPI Generator 多语言客户端/服务端。
- 设计:编辑器校验 OAS;契约测试工具 Pact 类。
- 实时消息:AsyncAPI 描述事件通道与消息结构。
常见误区
- 同时维护多份契约文件(文档页、SDK、mock 各一份):必然漂移。
- 工具链锁定过重:先确认生成语言与框架支持再引入。
追问
- 如何选择代码优先还是契约优先工具?接口对外、消费方多时契约优先;内部快速迭代可代码优先生成文档。
- mock 服务从哪里来?由 OAS/IDL 生成,避免手写 mock 与契约不一致。
本节自检
- [ ] 能按场景在 REST/gRPC/GraphQL/实时协议间给出选型与理由
- [ ] 能写出基本 OpenAPI 片段并说明契约优先流程
- [ ] 能说出 Protobuf 字段编号兼容规则
- [ ] 能列出兼容变更与破坏性变更清单
- [ ] 能说明契约测试、弃用流程与文档必备内容