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

06.14.5 OpenAPI / 契约优先与版本演进(tRPC、BFF 协议转换)

所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.14 API 协议专题

覆盖范围

  • OpenAPI(Swagger)规范
  • 契约优先(Contract First)
  • API 版本演进与兼容
  • tRPC 与端到端类型安全
  • BFF 协议转换

高频题速览

编号 题目 难度 频率
06.14.5-001 OpenAPI 是什么? 基础 ★★★★
06.14.5-002 契约优先 vs 代码优先? 进阶 ★★★★
06.14.5-003 API 版本怎么演进? 进阶 ★★★★
06.14.5-004 什么是向后兼容? 进阶 ★★★
06.14.5-005 tRPC 解决什么? 进阶 ★★★
06.14.5-006 BFF 协议转换怎么做? 进阶 ★★★
06.14.5-007 API 废弃(Deprecation)怎么处理? 高级 ★★★
06.14.5-008 接口变更怎么防止破坏前端? 高级 ★★★

06.14.5-001 OpenAPI 是什么?

频率 ★★★★ | 难度 基础

一句话结论

OpenAPI(原 Swagger)是 REST API 的机器可读描述规范:用 YAML/JSON 描述路径、参数、响应、Schema,可生成文档、Mock Server、客户端 SDK。

概念解释

  • 描述:path、method、parameters、responses、schemas。
  • 工具:Swagger UI、Redoc 渲染文档;OpenAPI Generator 生成 SDK。

06.14.5-002 契约优先 vs 代码优先?

频率 ★★★★ | 难度 进阶

一句话结论

契约优先(Contract First)先写 OpenAPI/proto,再生成服务端骨架与客户端 SDK,前后端并行开发;代码优先先写代码再反推文档,文档容易与代码脱节。

概念解释

  • 契约优先:设计先行,契约即合同。
  • 代码优先:快速起步但文档漂移。
  • 多端协作:契约优先适合前后端/多团队。

06.14.5-003 API 版本怎么演进?

频率 ★★★★ | 难度 进阶

一句话结论

版本策略:URL 路径(/v1/orders)、Header(Accept-Version)、或不版本化(保持向后兼容);优先用向后兼容演进,避免多版本维护成本。

概念解释

  • URL 版本:直观、常见。
  • Header 版本:URL 干净。
  • 无版本:永远兼容旧客户端。

06.14.5-004 什么是向后兼容?

频率 ★★★ | 难度 进阶

一句话结论

向后兼容:新版本不破坏旧客户端——新增可选字段、不删除字段、不改变语义;不兼容变更必须升版本号。

概念解释

  • 兼容:加字段、加可选参数。
  • 不兼容:删字段、改类型、改语义、改错误码。

06.14.5-005 tRPC 解决什么?

频率 ★★★ | 难度 进阶

一句话结论

tRPC 让 TypeScript 前后端共享类型定义,端到端类型安全,无需手写 OpenAPI/proto;适合全栈 TS 项目,跨语言/跨组织场景不适用。

概念解释

  • 原理:后端暴露 Router 类型,前端 import 类型自动推断。
  • 价值:改后端字段前端立即类型报错。
  • 局限:前后端都必须是 TS。

06.14.5-006 BFF 协议转换怎么做?

频率 ★★★ | 难度 进阶

一句话结论

BFF 对外 REST(对端友好)、对内 gRPC(高性能),在 BFF 层做协议转换:REST 请求 → BFF 调 gRPC → gRPC 响应转成 JSON DTO;错误码映射见 06.14.3。

06.14.5-007 API 废弃(Deprecation)怎么处理?

频率 ★★★ | 难度 高级

一句话结论

废弃接口在 OpenAPI 里标 deprecated: true,响应加 Deprecation 与 Sunset 头,公告迁移期,到期下线;不能悄悄删,要给客户端迁移时间。

06.14.5-008 接口变更怎么防止破坏前端?

频率 ★★★ | 难度 高级

一句话结论

契约测试(见 06.13.3)+ OpenAPI 变更审查 + 灰度发布:后端变更先在契约测试里看是否破坏前端期望,灰度放量观察错误率,再全量。

06.14.5-009 OpenAPI 文档怎么生成?

频率 ★★ | 难度 基础

一句话结论

代码优先用 SpringDoc/Swagger 注解从代码生成 OpenAPI;契约优先手写 YAML;两种都能生成 Swagger UI 文档;契约优先的文档与代码一致性靠代码生成保证。

06.14.5-010 tRPC 有什么局限?

频率 ★★ | 难度 进阶

一句话结论

tRPC 要求前后端都是 TypeScript,跨语言(Python/Java)不支持;不适合开放 API(第三方语言调用);只适合内部全栈 TS 项目。

06.14.5-011 怎么设计向后兼容的变更?

频率 ★★★ | 难度 进阶

一句话结论

加字段(可选)兼容;删字段、改类型、改语义不兼容;新增可选字段、新增枚举值、加宽数值类型是兼容的;不兼容变更必须升版本。

06.14.5-012 BFF 协议转换时错误码怎么映射?

频率 ★★ | 难度 进阶

一句话结论

后端 gRPC/内部错误码映射到 HTTP 状态码与业务错误码:gRPC NOT_FOUND → HTTP 404 + 业务码;前端按 HTTP 状态 + 业务码双层判断。

06.14.5-013 契约优先工作流怎么落地?

频率 ★★ | 难度 进阶

一句话结论

前后端先在 OpenAPI YAML 上对齐接口,评审通过后:后端从 YAML 生成服务端骨架(Spring/Express),前端从 YAML 生成 SDK;双方按生成代码开发,文档即代码。

06.14.5-014 接口废弃时怎么通知客户端?

频率 ★★ | 难度 进阶

一句话结论

响应头加 Deprecation: true 与 Sunset: 日期,文档标 deprecated,公告邮件/工单通知主要客户端;保留至少一个版本周期,再下线。

06.14.5-015 为什么不建议 URL 版本?

频率 ★★ | 难度 进阶

一句话结论

URL 版本会导致资源重复(/v1/users 与 /v2/users),代码分叉;但 URL 版本直观、易调试;多数团队仍用 URL 版本,Header 版本更干净但调试麻烦。

06.14.5-016 BFF 协议转换怎么处理 gRPC 流式?

频率 ★★ | 难度 高级

一句话结论

gRPC 服务端流式转 REST:BFF 把流式响应转成 SSE(Server-Sent Events)或 WebSocket 推给前端;不能直接转普通 REST(HTTP 是请求-响应),需要用长连接。

06.14.5-017 OpenAPI 怎么生成 SDK?

频率 ★★ | 难度 进阶

一句话结论

用 OpenAPI Generator 从 YAML 生成 TypeScript/Java/Python 客户端;前后端共用同一契约,避免手写 SDK 出错;生成代码提交到仓库,版本化管理。

06.14.5-018 怎么设计好的错误响应?

频率 ★★ | 难度 进阶

一句话结论

统一错误格式:HTTP 状态码 + body 里 {code, message, details};code 是业务错误码(字符串,如 ORDER_NOT_FOUND),message 给用户看,details 给开发者。

06.14.5-019 接口版本兼容怎么测试?

频率 ★★ | 难度 进阶

一句话结论

契约测试(Pact)验证向后兼容;新版本部署后,老客户端的契约仍通过;不兼容变更必须升版本号,老版本保留一个周期。

06.14.5-020 tRPC 适合什么项目?

频率 ★★ | 难度 基础

一句话结论

全栈 TypeScript 项目(Next.js/Nuxt + 前端 TS),追求端到端类型安全,不想写 OpenAPI;跨语言或开放 API 不适合。

06.14.5-021 怎么设计好的 API 错误码?

频率 ★★ | 难度 进阶

一句话结论

业务错误码字符串(如 ORDER_NOT_FOUND),HTTP 状态码分大类;code 给程序判断,message 给用户看,details 给开发者;不要只用 HTTP 500。

06.14.5-022 接口怎么版本演进?

频率 ★★ | 难度 进阶

一句话结论

优先向后兼容(加字段不删字段);不兼容才升版本;URL 版本直观,Header 版本干净;老版本保留一个周期再下线。

06.14.5-023 怎么做 API 文档?

频率 ★★ | 难度 基础

一句话结论

OpenAPI 规范 + Swagger UI/Redoc 自动渲染;契约优先从 YAML 生成;代码优先用注解生成;文档与代码同步,不手写。

06.14.5-024 BFF 协议转换怎么处理错误?

频率 ★★ | 难度 进阶

一句话结论

后端 gRPC/内部错误码映射 HTTP 状态 + 业务码;前端按 HTTP + 业务码双层判断;不要把内部错误码直接暴露给前端。

06.14.5-024 OpenAPI 怎么写好?

频率 ★★ | 难度 基础

考察点

  • 文档即代码(Document as Code)
  • 复用组件(components/schemas)

参考答案

  • 定义 components/schemas 复用数据模型
  • 每个 endpoint 写清楚 request/response、错误码、示例
  • 用 $ref 引用,避免重复
  • YAML 格式,Git 版本管理

追问

  • 怎么保证文档和代码一致?(契约优先:先写 OpenAPI 再生成代码;或用插件自动同步)

06.14.5-025 契约优先怎么落地?

频率 ★★ | 难度 进阶

考察点

  • 先写契约(OpenAPI/proto)再写代码
  • 代码生成(server stub / client SDK)

参考答案

  • 第一步:团队评审 OpenAPI/proto 定义
  • 第二步:工具生成 server stub 和 client SDK
  • 第三步:业务逻辑填实现
  • 好处:接口先对齐、文档自动生成、SDK 一致

追问

  • 生成的代码怎么维护?(生成代码不手工改,业务逻辑写在手写层;生成层可重新生成)

06.14.5-026 API 版本怎么演进?

频率 ★★ | 难度 进阶

考察点

  • URL 版本(/v1/)vs Header 版本
  • 向后兼容 vs 破坏性变更

参考答案

  • 向后兼容:新增字段、可选参数,不改旧行为
  • 破坏性变更:新开 v2 路径,旧版本保留到客户端升级率达标
  • 废弃流程:文档标注 deprecated → 通知 → 宽限期 → 下线

追问

  • 客户端什么时候必须升级?(安全漏洞、严重 bug、强制下线时)

06.14.5-027 怎么管理 API 生命周期?

频率 ★ | 难度 进阶

考察点

  • Design → Build → Deploy → Deprecate → Retire
  • API 门户

参考答案

  • API 门户展示所有 API、文档、版本、状态
  • 每个 API 有 owner、SLA、废弃计划
  • 变更走评审,重大版本通知所有调用方

追问

  • 怎么知道谁在用这个 API?(网关统计调用方、SDK 版本)

06.14.5-028 tRPC 是什么?

频率 ★ | 难度 基础

考察点

  • TypeScript 端到端类型安全
  • 无运行时契约文件

参考答案

  • 前后端都是 TypeScript,tRPC 直接复用类型定义
  • 不需要 OpenAPI/proto,类型自动推导
  • 适合全 TS 栈的中小项目,类型安全 + 开发体验好
  • 跨语言、开放 API 场景仍需 OpenAPI/REST

追问

  • 什么场景不适合 tRPC?(需要开放 API、跨语言客户端、移动端原生)

06.14.5-029 BFF 怎么做协议转换?

频率 ★★ | 难度 进阶

考察点

  • 后端 REST/gRPC,前端 GraphQL/BFF
  • 字段裁剪、聚合、转换

参考答案

  • BFF 接收前端请求,调用后端多个服务
  • 把后端 REST 响应聚合成前端需要的形状
  • 协议转换:gRPC → JSON、REST → GraphQL、字段重命名
  • 后端不感知前端需求,BFF 做适配

追问

  • 协议转换的性能开销?(序列化/反序列化有开销,聚合场景可接受;纯转发不如直连)

待整理清单

  • [ ] OpenAPI 3.1 与 JSON Schema 对齐
  • [ ] tRPC 与其他 RPC 框架对比(待确认)
  • [ ] API 网关聚合多个 OpenAPI