📚 课程目录第2章 API网关核心架构解析

2. API网关核心架构解析

API网关之所以能成为微服务流量的统一入口，核心在于它把四件事做扎实：把请求准确送到目标服务、把不同协议统一成内部可处理的格式、把安全与治理能力以插件方式动态叠加、并保证自身不成为单点故障。理解这四条主线，比记住某个产品的配置项更重要，因为无论换成 Nginx、Spring Cloud Gateway、Kong 还是 APISIX，架构骨架都高度相似。

请求路由：从入口到后端的定位过程

路由的本质是"匹配 + 转发"。一个请求进入网关后，先经过监听端口（如 80/443），再进入路由匹配阶段。匹配依据通常包括 Host、Path、HTTP Method、Header、Query 参数等。以路径匹配为例，配置可以写成：

route:
  id: order-service-route
  uri: lb://order-service        # lb 表示走负载均衡
  predicates:
    - Path=/api/order/**
    - Method=GET,POST
  filters:
    - StripPrefix=1              # 去掉 /api 前缀再转发

这里 Path=/api/order/** 是断言（predicate），决定"哪些请求归我管"；StripPrefix=1 是过滤器，决定"转发前对请求做什么加工"。当外部请求 GET /api/order/1001 到达时，网关先匹配到该路由，剥离一层前缀后变成 /order/1001，再通过服务发现拿到 order-service 的实例列表，按负载均衡策略选中一个实例转发。若没有任何路由匹配，网关应返回 404 而不是把请求透传到未知后端，这是安全边界的一部分。

路由匹配存在优先级问题。当 /api/order/** 与 /api/** 同时存在时，更具体的路径应优先命中，否则粗粒度路由会"吃掉"细粒度路由。多数网关按路由定义顺序或显式 order 值决定优先级，配置时需明确约定，避免出现"改了配置但流量走错服务"的排障难题。

协议转换：让内外通信解耦

网关面对的协议往往不止一种：外部客户端可能用 HTTP/1.1、HTTP/2 或 WebSocket，内部服务可能用 gRPC、Dubbo 或 REST。协议转换层负责在入口协议与后端协议之间做映射。典型场景是外部 REST 转内部 gRPC：客户端发 POST /api/user 携带 JSON，网关把 JSON 反序列化为 gRPC 消息，通过 HTTP/2 调用后端，再把 protobuf 响应序列化回 JSON 返回。

转换过程中要重点关注三件事：一是字段映射，JSON 字段名与 protobuf 字段名不一致时需要显式映射；二是错误码转换，gRPC 的 NOT_FOUND 应映射为 HTTP 404，INVALID_ARGUMENT 映射为 400，否则客户端拿到统一 500 无法判断；三是超时与流式语义，gRPC 流式调用与 HTTP 短连接在超时、背压上的行为不同，需要单独设置。协议转换做得好，客户端只感知一种协议，后端可以自由选型；做得不好，就会出现"网关能通但业务报错"的隐蔽问题。

插件机制：安全与治理能力的动态叠加

插件机制是网关可扩展性的关键。它把认证、限流、熔断、日志、灰度等横切能力从业务代码中抽离，以"责任链"方式在请求生命周期中执行。一个请求通常经过：入口 → 全局插件 → 路由级插件 → 转发 → 响应插件 → 返回。插件按优先级排序，认证类插件应最先执行，日志类插件最后执行，限流插件则要在认证之后、转发之前，避免未认证流量消耗限流配额。

以限流插件为例，常见配置为令牌桶：rate=100/s, burst=200，表示稳态每秒放行 100 个请求，允许瞬时突发 200 个。当桶满时返回 429 并携带 Retry-After。插件应支持热加载，即不重启网关即可生效，否则每次调整限流阈值都要重启，高可用就无从谈起。

高可用部署：让网关自身不成为瓶颈

网关是所有流量的必经之路，一旦宕机，整个系统对外不可用。因此高可用部署至少要满足三点：多实例、无状态、配置统一。多实例意味着至少部署两个网关节点，前面用 VIP、DNS 轮询或四层负载均衡分发流量；无状态意味着会话、限流计数等状态不能只存在单机内存中，限流应使用 Redis 等共享存储，否则多节点限流阈值会被放大 N 倍；配置统一意味着路由和插件配置通过配置中心（如 Nacos、Consul）统一下发，避免各节点配置漂移。

健康检查是高可用的最后一道保险。网关节点应暴露 /actuator/health 或类似探针，负载均衡器定期探测，连续失败则摘除该节点。同时网关对后端服务的健康检查也要配置，当某个 order-service 实例连续返回 5xx 或连接超时，应自动从负载均衡列表中剔除，待恢复后再重新加入。这样即使后端部分实例故障，整体服务仍可用。

排障提示：当出现"部分请求 404、部分正常"时，优先检查多网关节点配置是否一致；当出现"限流阈值明显偏大"时，优先检查限流计数是否落在单机内存而非共享存储。

把四条主线串起来看：请求路由决定"去哪"，协议转换决定"怎么通"，插件机制决定"安不安全、稳不稳"，高可用部署决定"一直可用"。四者缺一不可，且相互影响——路由配置错误会让插件形同虚设，插件状态不共享会让高可用部署失去意义。理解这层耦合关系，才是掌握 API 网关核心架构的关键。