API 上下游
在软件架构和业务逻辑中，API 的“上游”（Upstream）和“下游”（Downstream） 是一个非常核心的概念。简单来说，它是根据数据流向或调用关系来定义的。
想象一条河流：水从源头流向大海。在 API 的世界里，“请求”就像是逆流而上，而“数据/响应”则是顺流而下。
1. 什么是上游 (Upstream)？
上游是服务的提供方。 它是处理请求、存放数据或执行核心业务逻辑的地方。
- 定义： 当你的系统向另一个系统发送请求以获取数据时，那个系统就是你的上游。
- 类比： 餐厅的厨房。服务员（发起请求者）需要去厨房取菜，厨房就是上游。
- 特点： 上游通常不依赖于下游的状态，它只负责接收指令并返回结果。
2. 什么是下游 (Downstream)？
下游是服务的消费方。 它是发起请求、接收结果并将其展示给用户或进行进一步处理的地方。
- 定义： 任何调用 API 的客户端、APP 或其他微服务。
- 类比： 餐厅的顾客。顾客点餐（发起请求），接收菜肴，顾客就是下游。
- 特点： 下游依赖于上游的稳定性和数据质量。如果上游“断流”（宕机），下游就会受到直接影响。
3. 相对性：身份会随位置改变
上游和下游是相对的。在一个复杂的微服务链路中，一个服务既可以是上游，也可以是下游。
案例：一个电商查订单的流程
用户手机 App 调用 网关 API。
- App 是下游，网关是上游。
网关 API 为了获取数据，去调用 订单数据库服务。
- 此时，网关变成了下游，而订单数据库服务成了上游。
口诀： 谁给我数据，谁就是我上游；我给谁数据，谁就是我下游。
4. 为什么区分上下游很重要？
在实际开发和运维中，区分这两个概念主要是为了明确责任和风险控制：
- 故障传播（Cascading Failure）： 如果上游响应极慢，下游的连接池可能会被耗尽，导致下游也跟着挂掉。这叫“上游故障导致下游雪崩”。
- 版本兼容（Versioning）： 上游在更新 API 时，必须考虑是否会破坏下游的调用（即“向后兼容”）。
限流策略：
- 上游会设置限流，防止被过多的下游请求冲垮。
- 下游会设置熔断，防止被故障的上游拖死。
总结表格
| 维度 | 上游 (Upstream) | 下游 (Downstream) |
|---|---|---|
| 角色 | 服务提供者 (Provider) | 服务消费者 (Consumer) |
| 数据流向 | 输出数据 / 响应 | 输入数据 / 接收响应 |
| 请求流向 | 接收请求 | 发起请求 |
| 关注点 | 性能、稳定性、并发处理 | 异常处理、数据展示、用户体验 |
本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Web