FastAPI 进阶中间件：使用 add_middleware 集成 ASGI 中间件与 HTTPS 重定向、可信主机、GZip 压缩

FastAPI 进阶中间件使用 add_middleware 集成 ASGI 中间件与 HTTPS 重定向、可信主机、GZip 压缩【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi在 FastAPI 应用中中间件Middleware是拦截并处理每个请求/响应的通用处理层。本文围绕 FastAPI 官方进阶中间件文档展开讲解如何向 FastAPI 应用添加任意符合 ASGI 规范的第三方中间件并逐一介绍fastapi.middleware中内置的三类常用中间件——HTTPSRedirectMiddleware、TrustedHostMiddleware与GZipMiddleware——的使用方法、可配置参数与默认值并结合仓库源码说明这些内置中间件与 Starlette 的关系帮助你在生产环境中为应用加上安全重定向、主机头校验与响应压缩等能力。前置知识基础中间件与 CORS在进入进阶内容之前建议先了解两个前置主题如何为应用添加自定义中间件参见仓库中 自定义中间件文档其对应的示例代码位于docs_src/middleware/tutorial001_py310.py如何使用CORSMiddleware处理跨域资源共享CORS参见 CORS 文档对应示例位于docs_src/cors/tutorial001_py310.py。本文则聚焦于“如何引入其他尤其是第三方中间件以及 FastAPI 内置的几类开箱即用的中间件”。添加 ASGI 中间件由于FastAPI基于 Starlette 构建并实现了ASGI规范因此任何符合 ASGI 规范的中间件都可以直接使用——它不需要专门为 FastAPI 或 Starlette 编写只要遵循 ASGI 协议即可。从源码结构看ASGI 中间件普遍是“以 ASGI 应用作为第一个参数”的类。第三方 ASGI 中间件的文档通常会给出这样的用法from unicorn import UnicornMiddleware app SomeASGIApp() new_app UnicornMiddleware(app, some_configrainbow)即用一个新的中间件类把原应用“包”起来得到一个新的应用对象。这种写法在纯 ASGI 世界里是标准做法但在 FastAPI 中并不推荐因为它会改变中间件与框架内部机制的协作顺序。FastAPI实际上是 Starlette提供了一种更简单、更安全的注册方式app.add_middleware()。这样能保证框架内部用于处理服务器错误Server Error和自定义异常处理器Exception Handlers的中间件顺序正确、行为正常——如果在add_middleware之外手动包裹应用这些内部机制可能被跳过或顺序错乱。正确的注册方式是from fastapi import FastAPI from unicorn import UnicornMiddleware app FastAPI() app.add_middleware(UnicornMiddleware, some_configrainbow)app.add_middleware()的签名约定是第一个参数是中间件类本身不是实例其后所有关键字参数都会原样传递给该中间件的构造函数。上例中some_configrainbow会被传给UnicornMiddleware的构造函数app本身由框架在组装应用时自动注入。这个模式在所有内置中间件中都一致下面逐一演示。内置中间件总览FastAPI自带若干面向常见应用场景的中间件位于 fastapi/middleware/ 包中开发者可以直接使用。/// 技术细节它们来自哪里你可能会看到这样的导入方式from starlette.middleware.something import SomethingMiddleware。FastAPI 提供的这些中间件是通过fastapi.middleware暴露出来的“便捷入口”目的是简化你的导入路径。从源码可以直接验证这一点fastapi/middleware/包中的模块都是对 Starlette 的再导出。例如 GZip 中间件from starlette.middleware.gzip import GZipMiddleware as GZipMiddleware # noqaHTTPS 重定向中间件 与 可信主机中间件 同样是from starlette.middleware... import ... as ...的单行再导出包入口 则再导出 Starlette 的Middleware类。因此绝大多数可用中间件直接来自 Starlette其完整列表以 Starlette 官方文档为准使用from fastapi.middleware.xxx import XxxMiddleware与使用from starlette.middleware.xxx import XxxMiddleware功能等价选择前者只是更贴合 FastAPI 的项目习惯。fastapi/middleware/目录中还包含 FastAPI 自身实现的asyncexitstack.py依赖清理的异步上下文工具、cors.pyCORSMiddleware见前述 CORS 章节和wsgi.py用于在 ASGI 应用中挂载 WSGI 应用的WSGIMiddleware。下面介绍最常用的三个内置中间件示例代码均来自仓库 docs_src/advanced_middleware/ 目录。HTTPSRedirectMiddleware强制 HTTPS/WSS 重定向作用强制所有入站请求必须使用https或wss协议。任何以http或ws协议访问的入站请求都会被重定向到对应的安全协议地址。完整示例对应 tutorial001_py310.pyfrom fastapi import FastAPI from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware app FastAPI() app.add_middleware(HTTPSRedirectMiddleware) app.get(/) async def main(): return {message: Hello World}要点说明HTTPSRedirectMiddleware无需任何配置参数直接通过app.add_middleware(HTTPSRedirectMiddleware)注册即可该中间件适合部署在负载均衡器/反向代理已终结 TLS、或应用直接暴露 HTTP 端口的场景用于把不安全的http://与ws://连接统一跳转到https://与wss://它不参与业务逻辑只负责协议层面的 307 类重定向因此对端点代码无侵入。TrustedHostMiddleware防御 HTTP Host 头攻击作用强制所有入站请求必须携带合法设置的Host请求头用于防范HTTP Host 头攻击攻击者伪造Host头使应用生成指向恶意域名的链接常用于密码重置链接劫持、缓存投毒等。完整示例对应 tutorial002_py310.pyfrom fastapi import FastAPI from fastapi.middleware.trustedhost import TrustedHostMiddleware app FastAPI() app.add_middleware( TrustedHostMiddleware, allowed_hosts[example.com, *.example.com] ) app.get(/) async def main(): return {message: Hello World}支持的参数如下参数说明默认值allowed_hosts允许作为Host的域名列表。支持*.example.com这类通配符域名以匹配子域名。如果要允许任意主机名可设置allowed_hosts[*]——但更建议直接不启用这个中间件必选需明确传入www_redirect设为True时对非 www 版本的合法主机的请求会重定向到其对应的 www 版本True行为细节当一个入站请求的Host头未通过校验不在允许列表内、通配符不匹配等应用会返回400响应而不是处理该请求结合www_redirect的行为如果你的业务同时存在example.com与www.example.com可以借助该参数统一收口到 www 域名避免重复内容与 SEO 分裂。GZipMiddleware响应内容 GZip 压缩作用对Accept-Encoding请求头中包含gzip的请求处理压缩GZip 响应。该中间件同时支持普通响应与流式响应Streaming Responses因此对流式端点如 SSE、大文件分块传输同样有效。完整示例对应 tutorial003_py310.pyfrom fastapi import FastAPI from fastapi.middleware.gzip import GZipMiddleware app FastAPI() app.add_middleware(GZipMiddleware, minimum_size1000, compresslevel5) app.get(/) async def main(): return somebigcontent支持的参数如下参数说明默认值minimum_size只有响应体大小大于等于该最小字节数时才会进行 GZip 压缩更小的响应原样返回压缩小响应收益极低反而增加 CPU 开销500字节compresslevelGZip 压缩级别取值为1到9的整数。数值越低压缩越快但输出文件更大数值越高压缩越慢但输出文件更小9选型建议默认参数minimum_size500, compresslevel9偏向“尽可能压缩”如果对延迟敏感、且响应多为 JSON API压缩率有限可以适当调低compresslevel如示例中的5以提升吞吐如果响应多为纯文本/大 JSON可以调低minimum_size让更多响应参与压缩由于它兼容流式响应配合 FastAPI 的流式返回StreamingResponse等时压缩仍然生效无需额外处理。其他可用的 ASGI 中间件除上述内置中间件外生态中还有大量现成的 ASGI 中间件都可以按app.add_middleware()的同一模式接入例如Uvicorn 的ProxyHeadersMiddleware用于处理反向代理如 Nginx传来的代理头正确还原真实客户端 IP 与协议。如果你的 FastAPI 应用部署在代理之后这是必须了解的中间件仓库中 behind-a-proxy 文档 专门讲解该场景MessagePack ASGI 中间件为 ASGI 应用增加 MessagePack 编解码支持。更多可用中间件请参考 Starlette 官方中间件文档与社区维护的 ASGI 资源列表Awesome-ASGI。小结中间件接入的通用模式把本文的核心要点归纳为可复用的操作模式第三方中间件一律用app.add_middleware(中间件类, **kwargs)注册而不是手动新中间件(原应用)包裹以保证框架内部的错误处理与异常处理器中间件顺序正确FastAPI 内置中间件是 Starlette 的便捷再导出见 fastapi/middleware/理解它们的 Starlette 来源有助于查阅更详尽的参数文档三类高频内置中间件各有分工HTTPSRedirectMiddleware管协议安全无需参数TrustedHostMiddleware管Host头校验与 www 收口需allowed_hosts可选www_redirectGZipMiddleware管响应压缩minimum_size、compresslevel可按延迟/体积权衡调优所有中间件参数通过add_middleware的关键字参数传递默认值以 Starlette 文档为准GZipMiddleware默认minimum_size500、compresslevel9。按以上模式你可以在不影响端点代码的前提下把任意 ASGI 中间件安全、压缩、代理头等叠加到 FastAPI 应用中组成适合生产部署的中间件栈。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考