什么是 API 组合与聚合
API 组合指在聚合层对多个下游服务的数据做并行调用、内存拼接后一次性返回，常见于 BFF、网关或聚合服务。它减少客户端往返次数、屏蔽后端拆分细节，但也把部分失败语义与性能预算的复杂度转移到聚合层：关键字段缺失该整体失败还是给默认值，必须在设计阶段确定。
基本信息
| 实现形态 | 并行调用多个下游，在内存中按业务键拼接结果 |
|---|---|
| 失败语义 | 关键数据缺失整体失败；非关键缺失给默认值并标记不完整 |
| 性能要点 | 并行化、超时预算分配、避免按行循环调用（N+1 放大） |
| 常用手段 | 批量接口、并发控制、结果缓存与降级开关 |
部分失败语义设计
| 数据类型 | 缺失时的行为 | 说明 |
|---|---|---|
| 关键字段（金额、状态） | 整体失败，返回错误 | 业务无法在缺字段时给出正确结果 |
| 增强字段（头像、标签） | 给默认值并标记结果不完整 | 提升体验但不影响主流程 |
| 列表次要字段 | 省略字段，整体仍成功 | 客户端按可选字段处理 |
| 下游整体超时 | 快速失败并提示稍后重试 | 避免长时间占用聚合层资源 |
典型使用场景
- 移动端首页：一次请求聚合推荐、订单概览与未读消息，减少往返
- 订单详情：并行取订单、支付与物流状态，拼成一个响应
- BFF 层：按前端页面需要组合多个后端服务，屏蔽服务拆分
- 第三方对接：把内部多服务能力包装成单一稳定接口
- 性能优化：把串行调用改为并行，缩短端到端响应时间
- 降级设计：下游不可用时按字段重要性给出部分结果
并行聚合与超时预算（示意）
并行聚合与超时预算（示意）
# 聚合层调用示意
总预算：500ms
订单服务 超时 200ms 关键字段
支付服务 超时 200ms 关键字段
推荐服务 超时 150ms 非关键，失败即跳过
# 规则
- 先批量获取再拼接，禁止按行循环调用下游（避免 N+1）
- 关键字段任一失败即整体失败；非关键失败不阻塞主流程
- 记录每个下游的耗时与失败率，作为预算调整依据
- 缓存可复用的公共数据，减少重复调用组合层容易出现 N+1 放大：先批量拉取再在内存拼接，或使用下游提供的批量接口，避免逐条调用。
未定义部分失败语义时，前端会拿到残缺数据却无法判断是「本来没有」还是「取失败了」，只能显示错误或空白。