罗罗编程学习记录
本页内容 展开查看

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):从实现反推文档,容易与实现漂移。

原理流程

  1. 设计 OpenAPI / Protobuf / GraphQL Schema。
  2. 评审契约:字段、类型、错误码、兼容性。
  3. 生成服务端 stub、客户端 SDK、文档与 mock。
  4. 实现填充业务逻辑;契约变更走版本流程。

示例

# 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 中做契约校验,禁止手工改生成物。

概念解释

漂移的常见原因是文档手工维护。保持一致的三条路:

  1. 契约优先:OAS 生成 stub,实现不能改契约结构。
  2. 代码优先:从路由注解、模型类生成 OAS(如 Swashbuckle、SpringDoc)。
  3. 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 字段编号兼容规则
  • [ ] 能列出兼容变更与破坏性变更清单
  • [ ] 能说明契约测试、弃用流程与文档必备内容