06.1.1 API 设计与契约
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.1 通用后端工程
这个知识域解决什么问题
后端服务对外暴露的接口,本质是一份双方约定的契约:资源怎么表达、动作怎么发起、出错怎么通知、超时重试如何兜底。本知识域覆盖从资源建模、协议选型、契约维护到工程落地(分层、异常、日志链路、配置、测试)的完整链条。
知识地图
API 设计与契约
|
+-------------------+-------------------+
| | |
06.1.1.1 资源建模 06.1.1.2 契约与选型 06.1.1.3 可靠性
REST / HTTP 语义 OpenAPI / 协议对比 幂等 / 重试 / 错误模型
| | |
+-------------------+-------------------+
|
06.1.1.4 工程落地
分层 / 异常 / 日志链路 / 配置 / 测试 / CI
子主题导航
| 编号 | 子主题 | 核心问题 | 题量 |
|---|---|---|---|
| 06.1.1.1 | REST 资源建模与 HTTP 语义 | 资源如何命名、HTTP 方法与状态码怎么用 | 20 |
| 06.1.1.2 | 契约优先与协议选型 | REST/gRPC/GraphQL 怎么选,OpenAPI 怎么维护 | 20 |
| 06.1.1.3 | 幂等、重试、错误模型、限流与超时 | 写操作如何安全重试,错误与限流如何统一 | 20 |
| 06.1.1.4 | 工程落地:分层、异常、日志链路、配置与测试 | 代码如何分层,异常/日志/配置/测试如何规范 | 20 |
学习路径
REST 资源建模与 HTTP 语义
→ 契约优先与协议选型
→ 幂等、重试、错误模型、限流与超时
→ 工程落地:分层、异常、日志链路、配置与测试
- 先能把一个业务对象准确映射成资源路径与 HTTP 方法。
- 再理解契约优先如何让前后端、上下游并行开发。
- 可靠性部分是线上事故高频来源,重点掌握幂等与超时预算。
- 最后落到代码分层与可观测性,让设计能真正被工程实现。
高频题
| 排名 | 题目 | 所在页面 |
|---|---|---|
| 1 | RESTful 资源建模 | 06.1.1.1 |
| 2 | 状态码语义选用 | 06.1.1.1 |
| 3 | REST / gRPC / GraphQL 选型 | 06.1.1.2 |
| 4 | 契约优先与 OpenAPI | 06.1.1.2 |
| 5 | 接口幂等设计 | 06.1.1.3 |
| 6 | 限流算法对比 | 06.1.1.3 |
| 7 | 统一错误模型 | 06.1.1.3 |
| 8 | 全局异常处理 | 06.1.1.4 |
| 9 | traceId 透传 | 06.1.1.4 |
| 10 | 测试金字塔落地 | 06.1.1.4 |
参考来源
- OpenAPI Specification:https://spec.openapis.org/oas/latest.html
- Richardson Maturity Model:https://martinfowler.com/articles/richardsonMaturityModel.html
- Microsoft REST 规范:https://github.com/microsoft/api-guidelines
- Google API Improvement Proposals:https://google.aip.dev/
学完自检
- [ ] 能为一组业务实体设计资源路径、方法、状态码与分页约定
- [ ] 能说清三种主流协议的适用边界与代价
- [ ] 能为写操作设计幂等键、重试退避与错误返回结构
- [ ] 能画出分层调用链并说明异常与日志落点
- [ ] 能说出配置外置、健康检查与测试策略的基本要求