精通网关：协议、代理与现代网格
SchemaBridge Team · 2026-01-14 · Protocols, REST, API
为碎片化云打造的可配置 HTTP 网关：有上限的重试、按目标的速率限制，以及在出站时注入的密钥。
协议大杂烩：生活在无限碎片化的时代
如果你相信炒作，那么世界全是基于 HTTPS、使用 JSON 的 RESTful。如果你相信真正的炒作，那么世界正在转向 GraphQL 或 gRPC。但只要看看现代企业 IT 版图的现实，世界就是一锅混乱、缺乏协调的协议大杂烩，横跨四十年的架构潮流。
在同一个组织里，你很可能同时拥有：
- 现代层：一批与 GraphQL 端点通信的 React 应用。
- 主力层：成千上万个暴露 REST API 的内部微服务。
- 第三方：各种带有速率限制和特定请求头要求的 SaaS 提供商。
集成是在这锅协议大杂烩之上架桥的艺术。传统上，这意味着编写“适配器服务”——一些除了发起 HTTP 调用之外什么都不做的小巧而脆弱的 Node 或 Go 程序。我们称之为“胶水代码”（参见胶水代码危机），它是工程速度的沉重负担。
在 SchemaBridge，我们用 Managed Gateway 来应对这一问题：一个面向 REST 风格 API 的可配置 HTTP 网关，将你的业务逻辑与具体的端点实现解耦。它刻意只把一种协议做好（使用 GET、POST、PUT 和 DELETE 的 HTTP）；它没有内置的 GraphQL、gRPC 或 SOAP 客户端，因此这些端点要么通过其 HTTP 接口访问，要么无法访问。
Managed Gateway 的架构
SchemaBridge 网关不只是一个代理。它是一个中介，负责基础设施的“连接维护”：重试、速率限制和凭据。
响应规范化：JSONata 优先的方法
你无需编写解析响应的代码，而是将网关与一个 TRANSFORMATION 步骤搭配使用。
1. 调用：GATEWAY vertex 调用外部服务，并以 response.statusCode 和 response.body 的形式返回结果。JSON 响应体到达时已被解析；其他内容则以原始字符串形式到达。
2. 映射：下游的 JSONata 转换提取并重塑工作流所需的特定字段。
只要始终如一地这样做，你其余的可视化逻辑就只会看到你定义的干净结构，而不受底层数据源结构的影响。
自适应重试策略：超越“重试 3 次”
大多数开发者使用“固定重试”策略：每隔 1 秒重试，共重试 3 次。这往往弊大于利。如果服务因负载过高而宕机，一大批每秒重试的 worker 就像一次协同的 DDoS 攻击，使服务无法恢复。
SchemaBridge 网关的重试带有退避，并且有上限：
- 指数退避：5xx、429 或网络错误最多重试 3 次，每次等待时间翻倍（1 秒、2 秒、4 秒）。其他 4xx 响应不会重试，因为重复一个错误的请求并不能修复它。
- 遵守 Retry-After：遇到 429 时，网关会遵循提供商的
Retry-After请求头（上限 30 秒），而不是靠猜测。 - 自适应准入：对于过载的目标，平台的按目标速率限制器会根据提供商实际接受的量来调整速率，遇到限流时后退，成功时恢复，从而不会持续冲击一个正在挣扎的 API。
如果在 HTTP 重试之后提供商仍处于过载状态，该步骤会通过准入控制再重新调度几次（maxAutoRetries，默认 3）。如果此后提供商仍然失败，该步骤会可见地失败，并可在提供商恢复后重试，而不是无休止地循环。
应对速率限制之战：全局并发控制
每个 SaaS 提供商都有速率限制。有些很简单（每秒 10 个请求）。如果你有 100 个 worker 在运行集成，它们如何协调才能保持在限制之下？
如果每个 worker 都试图各自跟踪自己的速率，你必然会超出限制并被封禁。SchemaBridge 提供在调度（dispatch）时强制执行的全工作区、按目标的限制：
- 速率：每个工作区与目标组合一个令牌桶，限制所有 worker 合计的每秒请求数。
- 并发：每个目标一个并发上限（可在 Rate Limits 页面配置），限制同时进行中的对该 API 的调用数量。每个调用该 API 的 vertex 在运行前都必须通过它。
对比：传统 API 网关 vs. SchemaBridge 网关
| 特性 | API 网关（Apigee/Kong） | SchemaBridge Managed Gateway |
| :--- | :--- | :--- |
| 关注点 | 入站流量（南北向） | 出站（出口）业务调用 |
| 状态 | 主要为请求级（计数器、缓存） | 基于持久化运行的有上限重试 |
| 逻辑 | 脚本（Lua/JS） | 可视化（JSONata） |
| 身份 | 认证校验 | 在出站时注入的密钥（{{ secrets.NAME }}） |
Payload 规范化：适配器服务的终结
正如我们在本系列前文中讨论的，编写专门的服务来转换数据是在浪费资深工程人才。将网关与一个共享的转换搭配使用，就能让规范化成为链接的属性。
两个原语让这种复用成为现实。custom app 为你的工作区一次性录入某个提供商的连接设置（基础 URL、请求头、认证），并预填到每一个使用它的网关中。持久化的转换规则以 ruleId 一次性录入映射，使所有与同一个遗留 ERP 通信的工作流都能共享它。你把“技术开销”移入了平台，同时让“业务逻辑”保持干净和可视化。
示例场景：把遗留 API 移植到现代 Web
设想一家正在对订单管理系统进行现代化改造的跨国零售集团。
挑战
想象一下，它的核心库存位于一个覆盖数千家门店、并不稳定的遗留系统中，而新的电商前端是一个 React/Next.js 应用。用一组手写的“适配器微服务”来连接这两个世界，将是一项跨越多个季度的重大工程。
SchemaBridge 的方式
不妨设想团队转而使用 SchemaBridge 的网关原语。
1. 网关配置：他们不写代码，而是在 SchemaBridge 中把遗留系统配置为一个 custom app，其凭据保存在加密的密钥存储中。
2. 可视化逻辑：他们的产品团队直接构建“Check Inventory”的可视化图。
3. 内置韧性：网关的退避重试吸收遗留系统短暂的瞬时故障，而按目标的限制防止前端流量压垮它。
可能的结果
- 周期：许多看起来需要多个季度的适配器项目，可能会转变为配置工作。
- 负载：由于对遗留系统的并发被集中限制，前端的流量高峰会在平台侧排队，而不是把遗留系统冲垮。
未来：与协议无关的企业
API 的具体协议应当是一个实现细节，而不是路线图上的障碍。通过迈向精通网关的模式，我们摆脱了“遗留幽灵”。我们把业务逻辑建立在干净、层次分明的事实基础之上，而由基础设施去处理碎片化云的混乱现实。
网关设计专家检查清单
在设计集成层时，请对出站连接遵循以下经验法则：
1. 隔离协议：业务逻辑中绝不应包含特定于协议的实现细节。把它们抽象到网关及其转换步骤中。
2. 把凭据锁进保险库：绝不要把认证请求头粘贴进配置。以 {{ secrets.NAME }} 的形式引用它们，使令牌只在请求离开平台时才被注入。
3. 退避，并设上限：不要只是“1 秒后再试”。使用指数退避，遵守 Retry-After，并按目标限制并发。如果客户端由你控制，还要加入抖动（jitter），以打散同步的重试。
结论：桥就是网关
基础设施是处理混乱细节、让逻辑保持纯粹的艺术。精通网关是让工程速度摆脱过去技术债务的最后一步。别再编写适配器，开始架桥吧。
另请参阅“Building the Bridge”系列文章：错误恢复，讲述如何把故障作为一等的业务生命周期来处理。