Google Cloud API Gateway 新增流式传输：迁移前需要检查什么

流式后端会保持连接开放，并分块传输数据：例如，SSE 可以在模型生成回复时逐步发送文本，WebSocket 则可以进行双向通信。2026 年 10 月 22 日，Google 宣布 Cloud API Gateway 开放流式传输公开预览。网关可以转发这类响应，并对请求应用常见的身份验证规则和可观测性工具；要进行测试，需要创建一个启用了流式模式的新网关。

Google 的公告列出了 SSE、HTTP 响应流和分块传输编码、WebSockets，以及 gRPC 服务端流和双向流。HTTP 响应会在后端数据到达时逐步传送给客户端，包括 NDJSON。这样，流式路由就能继续由同一个 API Gateway 提供服务，无需另行处理常规请求。

API 和基础设施有哪些变化

流式操作不需要单独的 API 描述，也不需要在规范中添加专用扩展。在公开预览中，创建网关时通过 --enable-streaming 标志启用流式模式。Google 表示，API key 和 JWT 验证、通过 service account 对后端进行身份验证、路由，以及与 Cloud Logging 和 Cloud Monitoring 的集成都将保留。

此次预览还引入了基于网关 ID、项目编号和区域的可预测主机名。例如，地址格式为 GATEWAY_ID-PROJECT_NUMBER.REGION.gateway.dev。你可以提前将其填入客户端或 CI 配置。使用相同的 ID、项目和区域重新创建网关时，该地址会保持不变。

在不切换生产流量的情况下进行测试

1. 选择现有后端。 从已经发送 SSE 或 HTTP 流式响应的端点开始，这有助于区分网关行为与应用变更的影响。
2. 创建独立网关。 流式功能在创建时启用，现有网关无法更改模式。请使用测试 ID 和合适的区域。
3. 配置后端 deadline。 SSE 和 HTTP 流式传输的默认请求时限为 15 秒；设定的时限到期时，流会关闭。在 OpenAPI 配置中为后端设置适合场景的 deadline：流式网关的文档允许将其设为最长 3600 秒。还应考虑后端自身的 timeout，例如 Cloud Run 可能会更早关闭连接。
4. 检查后端协议。 gRPC 要求使用 HTTP/2（h2），WebSockets 则要求使用 HTTP/1.1。SSE 和 HTTP 流式传输支持 HTTP/1.1 或 HTTP/2；Google 建议这些场景使用 HTTP/2。
5. 确认数据能够到达。 确保客户端在完整响应结束前就能收到首批事件。对于 WebSocket，测试双向通信；同时规划连接结束后客户端的重连机制。
6. 核对策略和指标。 检查流式路由上的身份验证、日志和请求限制。request latency 指标反映整个流的持续时间，因此应在客户端单独测量首个事件到达时间以及事件间隔。

对于 WebSockets 和 gRPC，文档规定默认无消息间隔为 300 秒；WebSocket 不适用短于 300 秒的期限，并且连接无论如何最迟会在 3600 秒后结束。SSE 和 HTTP 流式传输则遵循设定的 wall-clock deadline。因此，request latency 曲线较长，并不能单独说明用户看到首个数据片段的速度。

公开预览的限制

在发布之初，无法通过 Cloud Console 或 Terraform 启用流式模式。此外，启用了流式传输的网关与 HTTP(S) Load Balancing 和 Serverless NEG 不兼容，因此依赖此架构的自定义域名不可用。Google 将这些功能列为预览期后续计划添加的内容。在规划生产路由和自动化之前，请查阅流式传输配置文档。

实际操作的第一步，是将新网关指向现有流式后端，明确设置 deadline，并比较直接连接与经网关路由的效果。这样，团队无需更改 API 合约或生产流量，就能验证协议兼容性、身份验证以及首个事件的实际到达时间。