1. API网关安全与流量治理全景

在微服务与云原生架构中，API网关已经从“请求转发器”演变为系统的统一入口与治理中枢。它同时承担两类职责：一类是安全策略，决定“谁能访问、能访问什么、以什么方式访问”；另一类是流量治理，决定“请求如何被分配、被限制、被降级、被观测”。本课程围绕这两条主线展开，目标是让学习者能够独立设计、配置并验证一套可落地的网关安全与流量治理方案。

一、课程要解决的核心问题

当系统从单体走向微服务，入口数量从 1 个变成几十个甚至上百个，随之出现四类典型问题：

• 身份与权限失控：每个服务各自校验 Token，密钥分散、口径不一，越权访问难以追溯。
• 流量冲击：突发流量、爬虫、恶意重放直接打到后端服务，导致雪崩。
• 灰度与版本混乱：新版本上线缺少按比例、按用户、按 Header 的精细分流能力。
• 可观测性缺失：出问题时无法快速定位是网关、鉴权服务还是后端业务的问题。

本课程的技术栈以 Spring Cloud Gateway 与 Nginx/OpenResty 为双主线，辅以 JWT/OAuth2、Redis、Sentinel、Prometheus + Grafana 等组件。选择双主线的原因是：Spring Cloud Gateway 适合 Java 生态的细粒度编程式治理，Nginx/OpenResty 适合高性能边缘接入与 Lua 脚本扩展，两者组合能覆盖从边缘到应用层的完整链路。

二、安全与治理的能力全景

下图展示了 API 网关在请求生命周期中的核心处理链：请求从客户端进入后，依次经过接入层、安全层、治理层，最终到达后端服务，同时旁路输出日志与指标。这张图是本课程后续所有章节的“地图”，每一层对应若干具体章节。

从图中可以看到，一次请求要穿过四道关口。接入层负责“第一道过滤”，把明显非法的连接挡在门外；安全层负责“身份与权限”，确认请求代表谁、能做什么；治理层负责“稳定性与灵活性”，决定请求被送到哪个实例、是否被限流、失败后如何处理；可观测性则贯穿全程，为排障和容量规划提供依据。

三、关键概念与参数约定

在进入具体配置前，需要先统一几个贯穿全课程的概念：

• 路由（Route）：网关的最小转发单元，由 ID、目标 URI、断言（Predicate）和过滤器（Filter）组成。例如 Path=/api/order/** 表示匹配订单接口。
• 断言：匹配条件，常见有 Path、Method、Header、Query、Host、时间窗口等。
• 过滤器：对请求或响应做加工，分为前置（Pre）和后置（Post）两类，鉴权、限流、改写都通过过滤器实现。
• 令牌桶（Token Bucket）：限流常用算法，参数为桶容量 capacity 和补充速率 refillRate。例如 capacity=100、refillRate=20/s，表示允许突发 100 个请求，之后稳定在每秒 20 个。
• 熔断阈值：常用“错误率 + 最小请求数 + 熔断时长”三元组描述。例如错误率超过 50%、且 10 秒内请求数不少于 20 时熔断 30 秒。

四、学习路径与章节组织

课程按“先安全、后治理、再观测、最后综合实战”的顺序推进，共 30 章，可分为五个阶段：

建议的学习方式是“边学边配”。每章都会给出可运行的配置片段或代码示例，读者应在本地或测试环境启动一个最小网关实例，把示例配置实际加载进去，用 curl 或压测工具观察请求是否按预期被拦截、限流或转发。只有亲手验证过，才能真正理解断言与过滤器的执行顺序、限流参数的实际效果以及熔断恢复的行为。

五、一个最小可运行示例

为了建立直观感受，下面给出一个 Spring Cloud Gateway 的最小路由配置。它把 /api/order/** 的请求转发到订单服务，并附加一个简单的请求头校验过滤器：

spring:
  cloud:
    gateway:
      routes:
        - id: order-route
          uri: http://order-service:8080
          predicates:
            - Path=/api/order/**
            - Method=GET,POST
          filters:
            - name: RequestHeaderCheck
              args:
                requiredHeader: X-Request-Id
                rejectStatus: 400

加载后，可以用两条命令对比结果：

# 缺少 X-Request-Id，预期返回 400
curl -i http://localhost:9000/api/order/1001

# 携带 X-Request-Id，预期被转发到订单服务
curl -i -H "X-Request-Id: req-20240101-001" \
     http://localhost:9000/api/order/1001

判断依据很明确：第一条命令的响应状态码应为 400，且响应体中包含缺少请求头的提示；第二条命令应返回订单服务的正常响应，同时在网关日志中能看到该请求的转发记录。这个例子虽然简单，但已经包含了“路由匹配—过滤器执行—转发—日志观测”的完整闭环，后续章节会在此基础上逐步叠加鉴权、限流、熔断等能力。

掌握全景之后，接下来将从接入层开始，逐层深入每个能力点的实现细节、参数含义与验证方法。