FastAPI 挂载 WSGI 应用：通过 WSGIMiddleware 无缝集成 Flask、Django 等框架

FastAPI 挂载 WSGI 应用通过 WSGIMiddleware 无缝集成 Flask、Django 等框架【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi将 Flask、Django 等经典 WSGI 框架编写的存量 Web 应用挂载进 FastAPI 应用是很多渐进式迁移场景的真实需求。本文基于 FastAPI 官方高级用法文档 docs/hi/docs/advanced/wsgi.md完整演示如何使用a2wsgi提供的WSGIMiddleware把任意 WSGI 应用挂载到指定路径下并让挂载路径之外的请求继续由 FastAPI 原生处理。读完本文你将掌握 WSGI 应用的挂载方法、依赖安装与弃用 API 规避并能借助仓库源码与测试用例理解其底层原理。背景FastAPI 与 WSGI 应用并存FastAPI 是建立在 Starlette 之上的异步ASGIWeb 框架而 Flask、Django 属于传统的 WSGI 框架两者基于不同的接口协议。FastAPI 应用天然支持在某个路径下「挂载」子应用正如官方文档 Sub Applications - Mounts 与 Behind a Proxy 所介绍的那样。借助这一机制你可以将一个 WSGI 应用当作一个被挂载的子应用嵌入 FastAPI 主应用挂载路径例如/v1/下的所有请求交给 WSGI 应用处理其余路径继续由 FastAPI 路由处理。实现这一能力的关键就是WSGIMiddleware——一个把 WSGI 应用转换为可被 ASGI 调用方使用的中间件。前提安装a2wsgi在开始之前需要先把a2wsgi添加到项目中。官方文档推荐使用 uv 添加依赖uv add a2wsgi也可以使用 pip 安装pip install a2wsgi需要说明的是这个依赖并不是可选的锦上添花而是必须项——WSGIMiddleware现在要从a2wsgi包中导入而非从 FastAPI 或 Starlette 直接导入。在当前仓库中a2wsgi也被声明为官方测试依赖见 pyproject.tomla2wsgi 1.9.0,2.0.0,仓库的测试套件同样依赖 Flask声明于 pyproject.tomlflask 3.0.0,4.0.0,核心步骤导入、包装、挂载整体只有三步从a2wsgi导入WSGIMiddleware用WSGIMiddleware包装 WSGI 应用例如 Flask 应用调用app.mount()将其挂载到某个路径下。官方教程的完整示例代码位于 docs_src/wsgi/tutorial001_py310.pyfrom a2wsgi import WSGIMiddleware from fastapi import FastAPI from flask import Flask, request from markupsafe import escape flask_app Flask(__name__) flask_app.route(/) def flask_main(): name request.args.get(name, World) return fHello, {escape(name)} from Flask! app FastAPI() app.get(/v2) def read_main(): return {message: Hello World} app.mount(/v1, WSGIMiddleware(flask_app))逐段拆解示例1. 创建 Flask 应用flask_app Flask(__name__) flask_app.route(/) def flask_main(): name request.args.get(name, World) return fHello, {escape(name)} from Flask!这里定义了一个最朴素的 Flask 应用根路径/返回一段问候文本。escape(name)对用户传入的 query 参数做了 HTML 转义避免把用户输入直接拼进响应导致 XSS 注入。演示代码刻意这样处理是为了提示接入 WSGI 应用后其自身的安全性仍由该框架的既有规范负责。2. 创建 FastAPI 应用与原生路由app FastAPI() app.get(/v2) def read_main(): return {message: Hello World}FastAPI 部分定义了一个/v2路径操作用来证明挂载之外的路由不受影响。3. 挂载 WSGI 应用app.mount(/v1, WSGIMiddleware(flask_app))这是最关键的一行先用WSGIMiddleware把flask_app包装为 ASGI 兼容的子应用再通过app.mount(/v1, ...)把它挂载在/v1路径下。挂载路径之下包括/v1/、/v1/anything的所有请求都会转发给 Flask 处理/v1之外的请求则走 FastAPI 自己的路由。从框架源码看FastAPI直接继承自 Starlette见 fastapi/applications.py 中的class FastAPI(Starlette)因此mount()是继承自 Starlette 的标准挂载能力这也保证了挂载子应用与 FastAPI 自身的生命周期、文档和中间件体系兼容。运行并验证路由分发使用 uvicorn 启动应用uvicorn docs_src.wsgi.tutorial001_py310:app --reload启动后访问 http://localhost:8000/v1/请求会命中挂载在/v1下的 Flask 应用页面返回Hello, World from Flask!再访问 http://localhost:8000/v2该路径不属于 Flask 挂载范围由 FastAPI 原生路由响应得到 JSON{ message: Hello World }来自官方测试用例的验证仓库中已经为这一教程编写了自动化测试 tests/test_tutorial/test_wsgi/test_tutorial001.py通过TestClient直接对应用发起请求来断言路由分发结果from fastapi.testclient import TestClient from docs_src.wsgi.tutorial001_py310 import app client TestClient(app) def test_flask(): response client.get(/v1/) assert response.status_code 200, response.text assert response.text Hello, World from Flask! def test_app(): response client.get(/v2) assert response.status_code 200, response.text assert response.json() {message: Hello World}两个测试分别验证了/v1/请求确实被 Flask 应用接管并返回纯文本响应/v2请求仍由 FastAPI 处理并返回结构化 JSON。这组测试是从行为层面对「WSGI 子应用与 FastAPI 原生路由各司其职」的官方背书也是你在自己的集成代码中可以直接复用的测试范式。注意fastapi.middleware.wsgi已弃用在旧版本中官方推荐从fastapi.middleware.wsgi导入WSGIMiddleware如今这一入口已经弃用deprecated官方文档明确建议改用a2wsgi包用法保持一致。在当前仓库源码中可以看到fastapi/middleware/wsgi.py 已经变成了一个极简的兼容性转发模块仅保留了对 Starlette 实现的重新导出from starlette.middleware.wsgi import ( WSGIMiddleware as WSGIMiddleware, ) # pragma: no cover # noqa文件尾部的# pragma: no cover与# noqa注释表明该模块已不参与测试覆盖率统计、不期望被新的代码路径直接使用只是为历史 API 保留向后兼容的通道。因此编写新代码时请务必确保安装a2wsgi包从a2wsgi正确导入WSGIMiddlewarefrom a2wsgi import WSGIMiddleware而不是从fastapi.middleware.wsgi导入。两条路径的使用方式完全相同但走a2wsgi是当前官方推荐的迁移方向。实战建议与注意事项迁移存量 WSGI 服务如果你想逐步把旧的 Flask / Django 服务迁往 FastAPI不必一次性重写全部路由。可以先让 FastAPI 承载新接口把旧 WSGI 应用挂载在如/legacy或/v1路径下对外继续提供服务再按业务逐步收敛。路径边界要规划清楚app.mount()会把指定前缀下所有请求含子路径交给 WSGI 应用。挂载前要确认前缀在 FastAPI 路由中不冲突避免新旧路由「抢路径」造成难以排查的 404 或错配。安全性由 WSGI 应用自理中间件只负责协议转换和请求转发不额外做鉴权、过滤或参数清洗。Flask 侧是否使用escape、是否校验输入仍取决于 WSGI 应用自身的实现。性能预期WSGI 是同步接口中间件引入的是协议桥接而非性能加速。若对高并发吞吐敏感可优先将热点接口改造为原生 FastAPI 异步路由仅保留低频或未迁移的功能走 WSGI 挂载。参考同系列高级用法挂载行为与路径、代理等主题联系紧密可继续阅读仓库中的 Sub Applications - Mounts 与 Behind a Proxy 两篇文档理解挂载与反向代理场景的配合方式。通过上述步骤你就可以让 FastAPI 与 Flask / Django 等 WSGI 框架在同一进程中共存为渐进式迁移和混合架构落地提供了一条清晰、可测试、有官方示例背书的路径。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考