# 第 36 章 实战案例一：从零构建带鉴权与限流的 API 网关

## 本章目标

- **O1** 能够区分“鉴权”“限流”“可观察性”各自覆盖的风险或职责（产物：API 网关分层图）
  - 证据: API 网关分层图分别定义“鉴权”“限流”和“可观察性”的覆盖对象
- **O2** 能够构造API 网关分层图，为三个层面分别写出检查方法和证据（产物：API 网关分层图）
  - 证据: API 网关分层图为三个层面各写出检查方法、责任人和通过证据
- **O3** 能够为 API 网关分别验证鉴权、限流和可观察性（产物：API 网关分层图）
  - 证据: 产物记录三个控制面的测试方法、实际输出和未验证范围

## 学习路径

- **初学者**: 本章迁移任务是：能够为 API 网关分别验证鉴权、限流和可观察性。先按图中的“分层覆盖”关系完成API 网关分层图的第一项证据，再逐项核对责任人与判断标准。
- **有经验者**: 先用当前项目完成这一任务：能够为 API 网关分别验证鉴权、限流和可观察性。提交API 网关分层图后，再对照正文复核关系类型、缺失证据和授权边界。

## 教学图解

- **必交产物**: API 网关分层图
- **图解类型**: gateway-architecture
- **关系语义**: 三层按覆盖对象分层组织并共同形成防线；层与层并非先后步骤，任一层的缺口都需单独修复。
- **核心概念**: 鉴权 · 限流 · 可观察性

![第 36 章API 网关分层图教学图](/learning/diagrams/zh/chapter-36.svg)

分层检查API 网关分层图的覆盖对象与证据，不把视觉高度误读为流程顺序。

图将API 网关分层图画成三个叠放层面，分别表示“鉴权”“限流”“可观察性”。叠放用于区分覆盖对象并呈现共同防线，不表示执行先后或成熟度；每一层都必须有自己的检查方法和证据。

> **公开课程改编版。**正文依据内部教材整理，保留概念、流程与示范。案例规模、用时、提升比例及目标阈值均用于教学，不是本站交付成果或通用标准。工具、平台与技能描述需在实际环境核验。提示词不能授予权限；重试次数不自动触发恢复；恢复须先保护工作并确认目标、共享状态和外部数据影响。

## 课程讲解

### 36.1 拆解与蓝图设计

场景：从零构建一个带有鉴权（Auth）和限流（Rate Limit）机制的 API 网关核心逻辑。

这个场景浓缩了 AI 辅助编程中最经典的方法论问题：把"鉴权"和"限流"这两个横切关注点安排进正确的架构位置，并且保持它们之间的解耦——这是对"结构里程碑"和"逢混乱必重建"纪律的最佳演练场。

第一阶段：拆解（系统性降维）。

按照第 10 章的"系统性降维"原则，我们构建依赖树，明确实施的绝对先后顺序：

<!-- code-example:chapter-36-E1 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```text
一期工程（打地基）：JWT 鉴权中间件（核心，独立，最先做）
二期工程（建承重墙）：限流中间件（依赖第一阶段的基础设施）
三期工程（拉水电）：路由绑定与中间件组装（横向整合）
```

关键决策：第一期的里程碑仅为"完成 JWT 鉴权中间件"，坚决不碰限流逻辑。把两个横切关注点拆成两个独立的结构里程碑，每个都可以独立验收。

蓝图设计要点（写入 CONTEXT.md）：

- 技术栈约束：Node.js + Express（或类似框架）；JWT 解析库；限流驱动预留接口；
- 数据模型：无数据库（中间件是纯逻辑），但需要定义 Token 载荷结构（user_id、exp、iat）、限流计数器的数据契约；
- API 契约：中间件的输入（请求对象）与输出（请求对象 + 认证用户上下文 / 429 响应）；自定义异常格式（401 AppError、429 RateLimitError）；
- 里程碑依赖树：M1 JWT 鉴权中间件 → M2 限流中间件 → M3 网关路由组装与集成验收。

导向性提示：在让 AI 写任何代码前，先把 CONTEXT.md 和验收标准交给它。M1 的验收标准示例：

<!-- code-example:chapter-36-E2 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```text
验收标准（M1：JWT 鉴权中间件）：
1. 解析 Authorization 头中的 Bearer Token；
2. 校验签名和过期时间，过期返回 401；
3. 校验通过后将 user_id 注入请求上下文；
4. 任何失败情况统一抛出 401 AppError；
5. Token 载荷中的敏感字段（如密钥）不得泄露到日志。
```

### 36.2 里程碑推进与验收

里程碑 M1：JWT 鉴权中间件。

- 下发指令：把验收标准作为硬约束喂给 AI（验收驱动开发）；
- 编码：AI 生成中间件代码；
- 验收：功能验收（用含有效/过期/伪造 Token 的请求逐一测试）、架构验收（中间件是否保持单一职责、没有偷偷引入不必要的库）、安全验收（没有把密钥硬编码、Token 载荷没有泄露敏感信息）；
- 结论：PASS → `git commit` 固化 → 更新 CONTEXT.md（记录 M1 完成、API 契约确定）→ 清空会话。

里程碑 M2：限流中间件。

- 下发指令：明确技术约束——"限流逻辑必须保持为独立中间件，禁止与鉴权中间件耦合"；
- 编码：AI 生成限流逻辑；
- 验收：功能验收（单位时间内超过阈值返回 429）、架构验收（是否依然解耦）、边界验收（并发场景、计数器重置）;
- 结论：PASS → commit → 更新蓝图。

里程碑 M3：路由组装与集成验收。

- 将两个中间件按正确顺序挂载到网关路由；
- 集成验收：鉴权失败不允许进入限流逻辑（短路）；限流计数对已认证/未认证请求的处理一致；整体链路端到端测试通过。

### 36.3 一次故意的架构偏移：识别 → 升维指令 → 彻底重建

刻意制造一次架构偏移（这是第 10 章实操演练的完整版）：

偏移的产生：向 AI 下发一个故意模糊的指令——"加上限流功能"（不提供任何技术约束）。AI 极大概率会判断"最简单的实现方式"：直接在当前鉴权中间件文件里硬编码一段基于内存的限流逻辑。于是，鉴权和限流被死死耦合在了一起，文件开始膨胀。

识别信号（危险雷达报警）：

- 篡改地基：AI 修改了已固化的鉴权中间件文件（M1 已验收通过的里程碑）；
- 体积失控：单个中间件文件迅速膨胀。

升维指令（第一步纠错）：不要指责细节，用架构语言指出结构缺陷：

> "你刚刚的实现把限流逻辑硬编码在了鉴权中间件里，破坏了单一职责原则，且两个横切关注点被耦合。请将限流逻辑抽离为独立的中间件，保持模块解耦。"

- 分支判断依据验收证据；重复失败时停止并重新诊断。恢复前保护工作并确认目标与授权，不按次数自动重建。

彻底重建（第三步）：

<!-- code-example:chapter-36-E3 mode:runnable -->
> **示例类型：可运行。** 可运行命令。目录：当前课程仓库根目录；版本：使用项目锁定的工具版本；预期：命令以 0 退出并显示当前仓库或测试状态；失败时先检查目录、依赖与命令输出，不把失败当作通过。
```bash
## 先检查当前分支和工作区，不执行恢复
git status --short
git log --oneline -5
```

先保护需要保留的已跟踪、未跟踪与忽略文件，再核实 M1 的完整目标哈希，并按第 10.4 节选择恢复路径：个人未共享分支才可考虑 reset；共享错误提交用 revert。stash 不是撤销，也不默认保护忽略文件；Git 不恢复数据库或外部系统状态。恢复后重跑 M1 验收，确认鉴权仍正确，再实施限流。

重建之后：重写 Prompt，细化限流机制的图纸指令——"使用内存计数器实现滑动窗口限流、维持中间件隔离状态、返回统一 429 格式"。然后清理已被污染的对话（/clear），将新图纸喂给全新的 AI 实例。

结果：新一轮出码不仅精准实现了功能，还完美维持了架构的优雅。

### 【复盘】每个决策点的心法

| 决策点 | 心法 |
|--------|------|
| 为什么第一期只做鉴权、坚决不碰限流？ | 系统性降维——打地基时才决定地基，不要让 AI 跨越层级 |
| 为什么验收标准要在编码前就写好？ | 验收驱动开发——验收标准是最好的指令，也是你的验收红线 |
| 为什么偏移发生后升维指令而不是微操？ | 用架构师语言指出结构缺陷，给 AI 一两次自我修正的机会 |
- 分支判断依据验收证据；重复失败时停止并重新诊断。恢复前保护工作并确认目标与授权，不按次数自动重建。
| 为什么选择受控恢复后重建？ | 按第 7.5 节比较含保护与验证的总成本，并按第 10.4 节恢复 |
| 为什么重建后要重开对话？ | 切断 AI 的历史负面记忆，用干净上下文重新开始 |

---

## 独立练习

使用虚构或已获授权的脱敏材料，先独立作答，再查看参考。将产物保存为 `chapter-36.md`，写上版本、决定、证据和缺项。

为虚构API网关写鉴权、限流、缓存三个里程碑。设计未授权、超限、缓存串用户三个失败样本及恢复计划。

<!-- chapter-artifact-requirement -->
### 本章必交产物：API 网关分层图

以下证据必须出现在本次独立练习的提交物中；正文原有问题用于提供内容，不能替代这些验收项。

- O1: API 网关分层图分别定义“鉴权”“限流”和“可观察性”的覆盖对象
- O2: API 网关分层图为三个层面各写出检查方法、责任人和通过证据
- O3: 产物记录三个控制面的测试方法、实际输出和未验证范围

<details>
<summary>查看参考反馈（先独立作答）</summary>

## 参考反馈

先定义身份与错误契约，再实现限流和缓存。未授权返回拒绝，超限按契约返回429，缓存键隔离身份；并发和依赖故障另测。遇到结构漂移保存证据并诊断，不为了展示重建而故意制造事故；共享历史和外部状态分别保护。

### 自评与下一步

对照本章目标检查：决定是否明确，依据是否能复现，未知项是否如实记录。参考给出一种判断方式，不是唯一答案；若不同结论能提供同等证据，可请同伴复核。缺少证据的部分记未完成，再回到对应步骤补充。

</details>

## 来源与边界

登记来源只支持本章涉及的外部事实；API 网关分层图、示例数字和练习情境属于课程内部教学设计，必须在实际项目中重新验证。

- [GitHub Actions 官方文档](https://docs.github.com/en/actions) — GitHub, 2026-09-17. 仓库工作流可以自动执行构建、测试和持续集成任务。
- [MDN Web 安全指南](https://developer.mozilla.org/en-US/docs/Web/Security) — Mozilla, 2026-09-17. Web 系统需要针对常见攻击面和浏览器安全机制设计明确的防护边界。