跳转到内容

第 2 章 HTTP、FastAPI、WebSocket 与网关

来自《系统架构与工程化学习》 · 原稿更新 2026-11-09 · 服务器只读阅读视图

2.1 HTTP、SSE 与 WebSocket

普通请求返回一次结果,SSE 单向持续推送,WebSocket 双向持续通信。

方式 通信特点与适用场景
普通 HTTP 请求/响应 一次请求返回一个结果,适合查询、提交等操作;HTTP 也支持流式响应
SSE 服务端通过 HTTP 事件流持续推送文本,适合生成文字、通知进度
WebSocket 在同一连接上持续双向通信,适合实时语音或频繁交互

我踩过的坑

  • 把“能不能中断”当成 SSE 与 WebSocket 的区别。
  • AI 正在处理时用户又发来消息,我不确定该立即中断、完成当前步骤后切换,还是排队。

正确理解

  • 流式能让用户更早看到第一个字,但 Agent 如果要等完整的工具结果才能走下一步,总耗时不会因此变短。首字延迟、完整生成时间和工具耗时要分开测,还要确认消费方能处理增量。
  • 能不能取消由业务代码决定:SSE 可以另发一个 HTTP 请求取消,WebSocket 可以发取消消息。连接断了,不代表后台任务停了。
  • SSE 断线后能否补收事件,取决于事件 ID、服务端保留的数据和恢复机制。自动重连不保证消息完整。
  • 长任务可以独立于连接运行,客户端用 task_id 查询或订阅进度。任务同步返回还是后台执行,看业务要求,和选哪种传输方式是两回事。
  • 用户中途发新消息时,中断、切换还是排队,要看当前任务做到哪一步、已经产生了哪些操作。
  • MCP 旧 SSE 传输的认证与超时排障见附录 A.2.1。
来源

SSE 标准 · FastAPI WebSocket 示例

2.2 FastAPI 的请求链路

请求依次经过中间件、路由、参数校验与依赖解析,再进业务处理。

请求 → 中间件 → 路由匹配 → 参数校验与依赖解析 → 业务处理 → 响应
我当时的理解 正确理解
用“通用/不通用”区分请求模型与 Depends。 请求模型检查数据结构与约束;Depends 为处理函数提供依赖,二者职责不同。
把“是否是本校学生”放进 Pydantic 校验。 学号格式正确不能证明身份或资格;还要检查当前用户的身份和权限。

我踩过的坑

  • 2026-08-04 问“类型用 QuoteContent 啥意思”,当时分不清字段能否为空、能否不传、非空时又按什么结构校验。
  • 想在截图里确认新增输入字段放在哪里,当时看到的其实是响应 Header;响应头说明服务已经怎样回答,不是这次请求的输入。

正确理解

  • 业务还要判断当前状态是否允许操作。比如选课名额,检查和写入要一起做并发保护,否则两个请求可能同时抢到最后一个名额,见第 3.2、3.3 节。
  • Depends 负责提供用户、数据库 Session 等依赖。业务规则放在哪一层按职责划分,不按“要不要查数据库”来定。
  • 运行时校验由 BaseModel、model_validate 执行;Field、Literal 约束单个字段,跨字段关系用 validator 或业务规则检查。类型提示、TypedDict 和普通字典都不会自动校验。
  • 以 source_content: QuoteContent | None = None 为例:| None 允许值为空,= None 让字段可以不传,QuoteContent 规定非空时的嵌套结构。它只约束这一个字段,不改变外层对象的类型。
  • 原始 JSON 里有这个字段,不代表业务最终用到了。旧故障出在两处:解析时忽略了新字段,后面的输入构建器也没读取它。排查时沿“原始输入 → 解析后的对象 → 转换结果 → 最终消费者”逐段核对,并看实际的 extra 配置。
  • 兼容测试直接检查转换后的 JSON 是否保留了新字段、旧数据不带这个字段时是否还能处理,不用一次模型回答代替字段链路检查。
  • 输出字段先用 Pydantic 定义并校验,边界需要字典时再用 model_dump(mode="json") 转换,避免各个函数手拼出不同的结构。
  • 新增的输入字段应该放在请求 Body 的 JSON 里。客户端手工加了字段,服务端也得有对应的接收契约和处理逻辑,否则不算支持。
来源

《需要学习的》,2026-08-04 的“可选与类型复用”“新字段为什么使用不到”“兼容字段怎么测试” · Pydantic Fields(2026-10-22,可空与默认值语义按 Pydantic v2) · 旧库 90-归档/需要学习的.md 第 608—614 行(692 行旧稿,不是辅助材料中的同名长稿)

2.3 状态码与错误契约

让客户端能区分错误类型,详细异常留在内部日志。

正确理解

  • 输入错误、未认证、权限不足、资源不存在、状态冲突、限流和内部失败,常见对应 400、401、403、404、409、429、5xx,具体按接口契约选择。
  • 对外返回客户端能处理的错误结构,详细异常留在内部日志。OpenAPI 用来说明输入、输出和错误结构,身份与权限仍要在实际请求中校验。
  • 输入清理不等于输入校验。为了容忍复制带来的换行,可以先清掉编号里的空白,再用 fullmatch 校验整个字符串。只清理不校验,夹带说明文字或只有部分编号的输入也会被当成合法。
  • 一次 404 可能是“没有数据”,也可能是故障。个人工作台的账单趋势要读多个历史月,没建目录的月份返回 404,旧前端却把它当成整张图加载失败。应按接口契约把“该月为空”和网络、认证、格式损坏区分开,多来源聚合时保留已取到的月份,必要时提示“部分数据未加载”。

2.4 中间件、Depends 与 Lifespan

三者管不同层次:提供依赖、包裹请求、应用启停。

我踩过的坑

  • 以为“依赖注入就是中间件注入进去”。
机制 负责什么
Depends(依赖注入) 声明处理函数需要的用户、数据库 Session 等依赖,也可配置在路由组或应用层
Middleware(中间件) 包裹请求与响应,统一处理请求编号、日志、耗时等工作,也可按条件选择处理
Lifespan(应用生命周期) 应用启动时准备资源,关闭时释放资源

正确理解

  • Lifespan 只在应用启动和关闭时运行,不在每次请求末尾运行。多个 worker 或实例各有自己的生命周期,不是整个集群只初始化一次。
  • 请求编号、统一日志、基础身份解析适合放在横切层。“会话已关闭不能再发送”“余额不能扣成负数”这类依赖业务对象当前状态的规则,要在业务操作里和状态更新一起校验。只在中间件检查一次,可能被其他调用入口绕过。
  • 异步获取的 Nacos 配置,不要硬塞进模块导入时就创建的同步 Settings。可以在 Lifespan 启动阶段先拉取并校验远程配置,再构造依赖它的业务客户端。在已有事件循环里再调 asyncio.run() 可能报错。
  • Listener 收到变化只说明配置更新了。真正生效还要完成解析、校验、原子替换,并让使用方重新读取或重建。
来源

依赖注入 · 中间件 · Lifespan

2.5 网关与服务发现

网关处理外部进入,业务服务仍要校验资源权限。

我踩过的坑

  • 当时问过:Consul 和 Nacos 是不是同一类东西?对外域名和内部服务发现又怎么区分?

正确理解

  • 网关通常在“外部进入系统”的位置处理 TLS、路由、流量治理和基础认证;业务服务继续校验用户是否有权访问具体对象。
  • 服务发现回答“目标实例现在在哪”,网关负责把外部请求导到合适的服务。内部服务之间的调用不一定都要绕外部网关。
  • 南北向、东西向说的是网络路径,不是前端、后端的别名。外部入口到内部服务通常叫南北向,内部服务互相调用叫东西向。后端去调外部域名也可能经过外部网关,要按真实地址和路由判断。
  • 网关的普通访问日志尽量轻量;审计日志要追究“谁做了什么”,异步落盘的可靠性取舍见第 7.10 节。模型网关、MCP、API 网关职责不同,不能混称一种网关。
  • Consul 和 Nacos 都能承担一部分服务发现或配置职责,实际功能要按版本和部署核对,不能简单当成完全相同。
  • 公网 DNS 把域名解析到入口,服务发现用来动态寻找服务实例,内部也可能用 DNS。判断依据是谁发请求、路由指向哪里、实例变化怎么处理,而不是“前端永远直连、后端永远走发现”。
  • 数据源走 MQ/DAG 处理异步事件流,和 HTTP API 网关是两回事,数据源到编排器之间不一定有网关。
  • 接入模型报错时,先核对请求 URL、服务商、身份凭据所属渠道、权限、额度和真实返回码,案例见附录 A.2.4。

2.6 网络分层排障

按 DNS → 端口 → TLS → HTTP → 登录逐层检查,看哪一层先出现证据。

从域名解析到登录的分层排障顺序

正确理解

  • DNS 解析失败时还没走到认证;收到 401/403,说明已经有 HTTP 服务在响应。
  • 常用命令:dig 查 DNS,route -n get 看走哪块网卡或隧道,nc -vz 查端口,curl -vI 看连接和响应。ping 不通可能只是 ICMP 被禁,不能据此判断 HTTPS 不通。
  • 临时对照指定 IP 可用 curl --resolve;检查时保留证书验证,不用 -k 掩盖证书问题。
  • 端口能连,不代表 Redis 可用。TCP 握手成功后,用授权的 Redis 客户端发 PING,看是否返回 PONG。如果连上就断,再查 TLS、鉴权、代理或隧道,以及目标是不是真的 Redis。
  • 内网域名被交给不认识的 DNS 或代理时,先查 Fake-IP 规则与 DNS 分流,案例见附录 A.2.2。

从真正发起操作的进程查连接(待学习)

桌面程序或浏览器卡住时,先看实际失败的请求。一次启动页卡住时,进程仍在,更新也能查,界面依赖的脚本却返回 404。另一次代理检查通过,验证脚本仍在浏览器请求中断连。沿真实页面分别查脚本传输、执行和最后的验证结果,单独打开资源成功后仍要回到完整入口复测。

测私网时,把本机、远程终端和浏览器出口分开。保留执行主机、目标地址和实际路由,再看对端连线走直连还是中转。一次本机报告 UDP 可用,实际对端仍经中转。遇到 TUN、直连规则或 DNS 改动,保留原值,每次只改一个主要因素并从两端复测。

启动资源缺失记录 · 中转排查记录 · 验证脚本记录 · 内网执行位置记录

路径探测没有回应,不足以精确定位故障点(待复习)

旧内网诊断记录已经区分直连IP、连接拒绝与超时,但把最后有回应的一跳写成“在那里断开”,证据仍不足。探测包可能被过滤;服务宕机、回程路径、ACL与路由问题也需分别取证。客户端超时只能证明本次从本机连接未完成,不能据此断言服务器持续宕机。分层诊断方法本节已有,不带入原内部地址或网络配置。

网络不可达的历史诊断。

2.7 认证与风控

认证核对身份,风控限制猜测和滥用。授权检查放在当前资源和动作上。

正确理解

  • 登录要分清三层:认证确认是谁,授权确认能访问什么,风控限制密码猜测、验证码重放和短信滥发。
  • 验证码要有有效期、尝试次数和一次使用的限制,还要处理并发请求。改密码和解锁要留审计记录。
  • 2026-05 的项目规则:登录连续错 5 次锁定 10 分钟,用短信验证码重置密码后解锁。阈值是当时的产品决定,要按业务风险定。
  • 新增匿名短信登录接口时,请求立即返回 401。网关和应用服务各有一层安全规则,两层都要查。耗时很短只能提示先查入口过滤,仍要用日志和路由命中确认。放行范围要精确到必要端点,宽泛的前缀可能误放行其他 API。
  • 游客模式可以用 FastAPI Depends 加 OAuth2PasswordBearer(auto_error=False),没带 Token 就当游客处理。但带了 Token 仍要校验是否合法、是否过期、有什么权限,不能因为 auto_error=False 就把无效凭据悄悄当成已登录。需要身份的功能用强制鉴权,游客的配额另行限制。
  • 密码用 Argon2id、bcrypt 这类专门的慢哈希,不用通用的 SHA-256。

2.8 授权与多租户

角色和页面按钮不是权限。每次操作要核对调用者、租户和资源归属。

正确理解

  • 接入 SaaS 时,应用审核通过、用户或组织授权、安装范围、绑定目标工作区是四个不同步骤,某一步成功不代表整条连接可用。排障先记下卡在哪一步、看到了什么,避免反复找管理员审批。
  • 多租户和 RBAC 不能只靠前端藏按钮。服务端先确认请求身份是真的,再在业务层按租户、资源归属和角色检查授权,查询层也限定数据范围。
  • 白名单为空时应直接返回无权限,不能悄悄变成全量 SELECT。这是授权边界问题,和 SQL 注入防御无关。
  • 系统任务、管理员和默认租户要分别建模,不能因为“ID 是 0”或“默认租户”就天然豁免隔离。
  • 一个人可以在不同设备组分别当成员和组长,角色能叠加,但权限不是无条件取并集。取消某组职位前,先确认他在其他组的归属;敏感操作按当前组、操作类型和显式拒绝规则校验。

登录后先确认环境,接入后用目标身份读回(待学习)

登录完成后先查当前地址和环境标记,再打开业务内容。接入新数据源时分开验证三步。上游凭据能读取正确的资源 ID,运行中的程序真的加载了配置并同步,目标用户能从授权入口读到目标文档。某一层通过后只记录这一层的证据。

登录后的环境 · 新数据源接入

2.9 会话与令牌

会话失效和 Token 失效是两回事,必须检查实际验证链路。

正确理解

  • JWT 换密钥不是“数据库里改一下 SECRET_KEY 就无感生效”。签发和验证要用一致的密钥版本,旧 Token 怎么兼容、过期和吊销要有方案,可以按所用的 JWT 实现考虑 kid 和轮换窗口。
  • 强制下线时,删掉 Redis 里的 Session Key,只对每次都查 Redis 会话的认证链路有效。纯无状态 JWT 如果仍被直接验证,在过期前会继续有效,还需要令牌撤销或更短的有效期。
  • 字段名叫 refresh_token,不代表它真能刷新。第三方工具曾把浏览器会话令牌装进这个字段,案例见附录 A.2.3。个人认证材料不要写进普通日志和知识书。
来源

FastAPI 可选 OAuth2 依赖 · JWT 与密码哈希

统一登录之后,逐条验收权限回收(待学习)

SSO 统一身份入口,原有会话和各资源的授权可能各有生命周期。用测试账号先记录停用前的行为,再逐项核对新登录、已有会话、个人令牌、SSH 与项目成员权限。供自动化使用的共享凭据单独确认拥有者和交接或轮换方式。此处是测试设计,具体平台的联动仍待实测。

SSO 与权限回收问题

2.10 多租户数据归属

登录成功不等于有权限读这条业务数据,查询还要核对它属于哪个租户。

正确理解

  • 只在一个入口按租户过滤,其他接口或后台任务仍可能越权。租户条件要覆盖所有入口、后台任务和数据查询。
  • 项目例子:手机号登录时用户不存在就按方案创建账号,用 mainAccountId 关联主账户空间,查询时带上租户条件。这是应用层和查询层的逻辑隔离。注册、分配空间、更新关联要一起检查事务、唯一性和并发失败的路径。
  • 文档重新采集或迁移后,要按返回内容的真实租户和书库归属重新验权限。沿用旧 ID 的授权标签,可能让新来源的数据进到无权用户的索引里。可以用“跨权限移动”的合成样本验证防护,但模拟出的风险不能说成线上已经越权。

2.11 会话不是权限来源

会话保存创建时的角色作为历史元数据;执行工具和读写数据按当前请求的可信主体判断。

我踩过的坑

  • 旧学习平台在“教师建立任务会话、学生随后继续同一任务”时沿用 session.role_at_create 决定可用工具,造成当前用户与创建者的工具集不一致。

正确理解

  • 同类问题:继续任务的接口只核对了传进来的 student_id,没确认 plan_item 真的属于这个学生。
  • 三件事要分开:登录态说明调用者是谁;资源归属校验说明这个计划、试卷、会话是不是他能访问的;角色和动作规则说明他此刻能做什么。
  • 共享会话可以把 session.role_at_create 存成历史元数据,但执行工具、读写数据要按本次请求的可信主体、成员关系和最新授权检查。不能凭会话是谁建的、前端传的用户 ID 或模型在上下文里声称的角色来定权限。
  • 反例至少测三个:学生枚举别人的计划项;家长和学生切换入口后继续旧会话;授权取消后用旧会话重新请求。页面看不到不代表 API 不能越权。
来源

40-AI任务交接/2026/07/23-xcc学习平台-学习闭环审查修复L1L2.md。历史交接称相关热修曾部署,但没有重新验当前生产版本;这里保留跨入口权限设计教训。

本章原始笔记

《Web 协议》 · 《FastAPI》 · 《网关》

2.12 403 先定位响应层,再验证 MCP 往返(待学习)

TLS 校验失败尚未进入 HTTP;Cloudflare 的 403/1010 与应用自己的 401 也不是一层。一次同机同入口只改 User-Agent 就改变结果,能证明客户端条件相关,具体命中规则仍需管理日志,不能推断 Key 或账号被封。

远程 MCP 按 TLS→HTTP 状态与响应来源→initialize→initialized→tools/list→tools/call 逐层验证。证书与请求头正常后,Exa 在当时网络跑通无需命令桥接的直连;免费额度、长期可用性、JSON/SSE 与会话头仍待验证和学习。

来源与当时边界

原始记录 2026-10-29 · 原始记录 远程 MCP 的 4

2.13 错误契约共用注册表,状态头正文先分开(待学习)

把 gh api –include 全文匹配 rate limit,会让正常限流响应头把 404 误报成限流;先拆状态、头、正文,无状态才用 stderr 兜底。合成测试保留真实协议形状,并验最终 CLI/MCP 看到的错误。

连续修同类吞错时,把固定码和文案放一份注册表,测试遍历全部条目,并临时增加新码确认无需多处补名单。HTTP 自动升级只改协议,主机、路径、查询与私网、凭据、端口限制仍执行;真实代理可用性另验。

来源与当时边界

原始记录 响应头也会让错误分类 · 原始记录 修复一个错误后,用完