API 网关与 API 管理工具

一个入口返回 200，并不等于 API 已经正确发布。消费者可能绕过了认证，灰度请求可能全部落到旧版本，网关返回的成功也可能只是本地 mock；等故障发生，团队只剩一张绿色控制台截图，却说不清请求命中了哪条路由、执行了哪些策略、选择了哪个上游、使用哪一版配置。

API 网关真正交付的是一条可治理的请求链。它既要把入口、路由和上游连接起来，也要让消费者身份、授权结论、限流计数、版本选择、配置发布和回滚状态能够被证明。工具是否启动只是起点，团队最终要能判断一次失败属于客户端、网关策略、控制面、数据面、网络还是业务上游。

从消费者身份、路由和策略，到上游、证据与退出治理高清原图

从故障现场进入，而不是从产品名单进入

这组工具解决的是同一条生产链上的不同问题：客户端怎样抵达入口，入口怎样识别消费者，哪条路由与策略作出决定，数据面怎样选择上游，控制面怎样发布配置，以及团队怎样证明一次变更可以回退。阅读顺序也应沿这条链展开。

1. 先用网关请求证据模型与选型建立 request、attempt 与 deployment 三类记录。没有这一步，后续产品实验只能证明“端口可访问”。
2. 再按运行位置选择实现。Kubernetes 平台先理解 Gateway API 与控制器关系；虚机或独立集群再比较 Kong、APISIX、KrakenD、Tyk 与 Gravitee；云平台团队分别进入 AWS、Azure 与 Google 的托管实现。
3. 产品最小链路稳定后，再叠加认证、授权与身份策略、限流、配额与韧性策略、版本、灰度与请求变换。安全策略和流量策略不能在第一次启动时同时打开，否则失败责任层不可判定。
4. 最后补齐观测与分层排障、高可用、升级与迁移治理和消费者生命周期。此时验证对象已经从单个实例扩展到配置权威、数据面代际、证书、状态存储、分析链和退出路径。

目录中的每个产品都要落回同一组判据：配置权威在哪里，控制面中断时数据面保留什么，消费者与上游身份由谁签发，路由变更怎样关联 revision，故障时能取得哪些证据，删除后怎样证明流量、凭证、存储与账单已经收口。产品功能再丰富，也不能替代这些工程答案。

先把反向代理和 API 管理分开

反向代理解决监听、TLS、路径转发和负载均衡，开发机上的稳定入口尤其依赖这些能力。API 管理在这条链上继续增加消费者、订阅、凭证、策略、发布版本、分析和生命周期。两者共享数据面概念，却承担不同的组织责任。

只有几个内部服务、路由长期稳定、身份由应用处理时，本地 Nginx、Caddy、Traefik 或 Envoy 已经足够。开始出现多团队发布、外部消费者、统一认证、配额、审计、开发者门户、跨集群数据面或独立升级节奏后，才值得承担 API 网关控制面的状态、数据库、插件和迁移成本。

判断时不要先问哪个产品功能最多，先回答四个问题：

1. 谁能发布路由和策略，配置权威存在哪里；
2. 数据面失去控制面后还能以哪一版配置运行；
3. 消费者身份和上游身份分别由谁签发、验证与撤销；
4. 网关退出时，路由、凭证、日志、门户数据和 DNS 怎样迁走。

一次请求要留下六类证据

排障时最有价值的不是配置全文，而是能把请求还原成一条状态链。网关请求证据模型与选型给出了控制面、数据面和真实请求分开验收的方法：

六类证据分别回答：调用者是谁、请求从哪个入口进入、命中哪条路由、执行哪些策略、实际访问哪个上游、最终由谁产生状态码。配置版本、request ID 和时间窗口把这些证据绑定在一起。任何一环缺失，401、404、429、502 和超时都可能被错误归因。

客户端可以携带 request ID，但网关不能无条件信任它。入口应按团队规则验证或重建关联标识，并把外部标识与内部追踪标识分开保存。查询参数、Authorization、Cookie、API Key、JWT 和请求体默认不进入共享日志；需要临时采样时也要有审批、字段允许列表和到期删除。

根据控制面和状态模型选工具

Kubernetes Gateway API 是资源与状态规范，不是一个可独立转发流量的程序。它适合已经以 Kubernetes API、namespace 和声明式对象管理入口的团队；最终行为仍取决于控制器、实现支持度和数据面。

Envoy Gateway 用 Gateway API 驱动 Envoy 数据面，适合希望把标准资源、策略状态和 Envoy 能力结合起来的 Kubernetes 平台。需要直接编写原生 listener、route、cluster 和 filter 时，应回到原生 Envoy，而不是把控制器生成结果当手写配置接口。

Kong Gateway 提供传统数据库、DB-less 和混合控制/数据面等模式，插件生态和 API 管理能力较完整；选择它意味着必须管理声明式配置、数据库或控制面状态、插件兼容和 Admin API 权限。

Apache APISIX 以 etcd 动态配置和插件链见长，也提供 Standalone 路径。它适合需要快速路由更新和可扩展策略的团队，但 etcd、Admin API、插件顺序和配置恢复都进入故障域。

KrakenD 更接近声明式、无状态的 API 聚合器，适合聚合多个后端并控制响应形态。它不是完整 API 管理平台；消费者门户、复杂生命周期和集中分析需要相邻系统承担。

Tyk 与 Gravitee 都覆盖网关和管理能力，但组件、状态存储、分析、门户和许可边界不同。不能用单容器演示推导生产拓扑，也不能把 Dashboard 正常等同于数据面可用。

AWS API Gateway、Azure API Management 和 Google Apigee 把更多控制面和基础设施责任交给云平台。代价是对象模型、私网连接、身份、区域、配额、计费和退出受平台约束。价格与能力会变化，架构决策应绑定当期官方能力和真实账单，不写死静态比较表。

选型评审不能用“支持 JWT、限流、灰度”这样的勾选表结束。同一个功能在本地计数、共享状态、外部策略服务和托管控制面中有不同故障域。评审记录至少要包含目标部署形态、目标版本、状态依赖、控制面断连行为、配置传播上界、插件或策略执行位置、证据导出能力、灾备恢复点、单位请求成本和退出所需的数据迁移。缺少其中任何一项，都只能进入隔离验证，不能形成生产结论。

层级	必须掌握的对象	失效时先看什么
入口与数据面	DNS、证书、监听器、连接、路由、上游与本地配置快照	SNI/Host、数据面实例身份、实际 revision、上游尝试
控制面与状态	声明对象、管理 API、数据库、配置分发、插件和策略依赖	接受状态、引用解析、节点同步、最后成功配置与回退点
产品与治理	消费者、订阅、凭证、配额、门户、分析、审计和账单	身份生命周期、策略 owner、数据保留、异常成本与退出清单

小团队可以让一个平台小组同时承担三层，但证据和权限仍要分层。数据面运行身份不应拥有控制面管理权限，发布流水线不应读取消费者明文凭证，门户管理员也不应直接修改生产路由。

先跑通最短发布链

无论选择哪个实现，第一次实验都使用两个能返回不同实例标识的上游，例如 blue 与 green。先直接访问两者，确认应用和网络基线；再经网关发布 /demo，保存命中路由、上游标识和配置版本。随后依次加入错误路径、停止一个上游、错误凭证和限流，不要一次打开所有插件。

最小验收不能只写：

curl -fsS https://api.example.test/demo

它至少还要保存响应头、状态码、响应体摘要和关联标识，并从网关状态或日志证明请求经过预期配置：

set -o pipefail
curl --fail-with-body --silent --show-error \
  --dump-header /tmp/gateway-headers.txt \
  --output /tmp/gateway-body.json \
  https://api.example.test/demo
test -s /tmp/gateway-headers.txt
test -s /tmp/gateway-body.json

实验域名、证书和输出目录必须是隔离资产。清理时删除测试路由、消费者与凭证，停止临时上游，复查监听端口和云资源；不能只删除本地 YAML，让控制面里的对象继续运行和计费。

身份策略和流量策略分开验证

认证、授权与身份策略 负责确定调用者是谁、能做什么、以哪个身份访问上游。签名正确并不代表 token 可用，还要验证发行者、受众、有效期、算法、密钥状态和所需声明。外部授权服务故障时选择 fail-open 还是 fail-close，是业务连续性与越权风险的明确取舍。

限流、配额与韧性策略 负责保护容量。单实例本地计数、副本间共享计数、消费者月度配额、并发限制、超时、重试、熔断和异常实例摘除不是同一能力。重试会放大请求，必须受幂等性、总超时、单次超时和重试预算共同约束。

策略推广先使用只观察或小流量模式，比较候选结论与现网行为，再逐步阻断。错误凭证、过期凭证、错误受众、限流服务不可达、授权服务超时和上游部分失败都要有明确预期；无法解释的默认行为必须保持在隔离环境。

版本、灰度和变换不能隐藏契约问题

API 版本、灰度与请求变换 处理 Host、Path、Header、权重和消费者分组。每种分流都要用足够样本证明比例和粘性，还要验证 WebSocket、SSE、缓存键、Cookie、重定向、签名和重试后的版本选择。

网关可以改写路径、Header 和响应结构，却不应把破坏性 Schema 变化伪装成兼容。契约仍由 API/事件 Schema 治理链负责；网关只执行已批准的兼容策略。回滚时必须恢复路由、策略和缓存语义，不能只把上游权重改回 100/0。

门户与分析服务于消费者生命周期

API 产品、开发者门户与分析 从 API 发现、申请、审批、订阅和凭证发放开始，到配额、用量、退订、凭证撤销和个人数据删除结束。门户不是一组静态 OpenAPI 页面，分析也不是访问日志截图。

产品 owner、API owner、平台 owner 和安全 owner 要有可分辨职责。消费者离开后，账号停用、订阅撤销、Key/证书失效、缓存刷新、日志保留和账单停止需要分别验证。通用服务目录仍由开发者门户家族负责，这里只处理 API 消费关系。

故障从责任层开始定位

网关观测与分层排障 把故障分为入口/TLS、路由、身份、策略依赖、上游连接、业务响应和控制面同步。404 可能来自没有路由，也可能来自上游；401/403 要区分网关策略和业务授权；429 要指出哪个计数器、哪个消费者和哪个窗口；502/503/504 要区分无健康上游、连接错误、重试耗尽和超时层级。

控制面成功发布后仍要看数据面已接收哪一版配置。状态、日志、指标和 Trace 使用统一关联字段，但不记录完整敏感请求。排障材料在共享前做路径、域名、租户、Header、Token 和客户数据扫描。

高可用首先保护配置权威

高可用、升级与迁移治理 不只增加数据面副本，还要保护配置数据库、控制面、证书、插件、策略依赖、门户和分析链。控制面短暂不可用时，数据面是继续使用最后配置还是停止接收流量，必须从实际产品和部署模式验证。

升级先验证配置转换、插件兼容、数据库迁移和回退限制，再做候选数据面和小流量。跨产品迁移使用双跑与请求镜像时，写请求、认证副作用和计费必须隔离；比较的是状态码、Header、响应摘要、上游选择和延迟，不是只比较吞吐。

退出计划至少包括配置导出、契约归档、消费者与凭证迁移、DNS/证书切换、旧日志保留、旧门户下线、云资源核销和应急回切窗口。没有退出路径的网关，功能越丰富，长期锁定成本越高。

团队落地检查

• 配置权威、发布入口、审批人和回滚人已经明确。
• 控制面、数据面、状态存储和策略依赖的故障域已经画清。
• 两个上游、正确请求和至少三类失败反例能够重复验证。
• 消费者身份、上游身份、凭证轮换和撤销都有证据。
• 限流、配额、超时、重试和熔断使用各自的容量模型。
• 日志、指标和 Trace 能绑定 request ID 与配置版本，且敏感字段受控。
• 升级、数据库迁移、插件变化和云平台能力变化有回退入口。
• 删除实验后，路由、凭证、端口、存储、日志和账单残留均已复查。