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