FastAPI 集成 WSGI 应用Flask、Django 等完整指南使用 WSGIMiddleware 挂载子应用【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文面向希望在同一服务内同时运行 FastAPI 与既有 Flask、Django 等 WSGI 应用的开发者介绍如何借助a2wsgi提供的WSGIMiddleware将 WSGI 应用整体挂载到 FastAPI 的某个子路径下实现新老服务平滑共存、逐步迁移。读完本文将掌握依赖安装、挂载写法、路径分发规则、运行验证方法并理解为何官方已弃用fastapi.middleware.wsgi。本文对应的官方文档为 docs/pt/docs/advanced/wsgi.md英文原版见 docs/en/docs/advanced/wsgi.md仓库内配套了可直接运行的示例源码与测试用例。挂载MountWSGI 应用的适用场景在介绍具体用法之前先明确这套机制的定位。在 Subaplicações - Montagens子应用挂载 和 Atrás de um Proxy反向代理之后 中已经介绍了把独立应用挂载到指定路径下的能力挂载意味着在某个路径前缀上委托一个完全独立的应用程序让它接管该路径下的全部请求。FastAPI 本身是 ASGI 应用而 Flask、Django 等是WSGI应用二者协议不同不能直接互相嵌套。此时就需要WSGIMiddleware这类适配中间件把 WSGI 应用包装成一个可以被 ASGI 框架挂载的对象从而让 FastAPI 把/v1/等路径下的所有请求转交给 Flask/Django 处理其余路径仍由 FastAPI 原生处理。典型场景包括渐进式改造将已有的 Flask/Django 服务整体挂载到旧路径如/legacy/或/v1/新功能用 FastAPI 开发旧接口保持可用统一对外端口无需启动两个进程、两个端口让 FastAPI 作为统一入口代理分发复用中间件与基础设施挂载的应用依然可以在 FastAPI 的中间件、代理层之下统一运转。安装依赖a2wsgi要使用WSGIMiddleware需要先把a2wsgi添加到项目中。官方文档推荐使用uv管理依赖uv add a2wsgi如果你使用pip等价命令为pip install a2wsgi仓库中对应的示例项目依赖也体现在运行测试的环境里。请务必确认a2wsgi已成功安装否则import阶段就会报错详见下文弃用说明部分。完整示例在 FastAPI 中挂载 Flask 应用仓库提供了完整可运行的示例源码 docs_src/wsgi/tutorial001_py310.py全文如下from 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))该示例的核心步骤恰好对应官方文档的三步走导入中间件from a2wsgi import WSGIMiddleware包装 WSGI 应用WSGIMiddleware(flask_app)把 Flask 应用封装成可挂载对象在指定路径挂载app.mount(/v1, ...)将该应用挂到/v1路径下。细节提示Flask 应用内部定义的路由是/但在被挂载到/v1之后访问入口变为/v1/。也就是说Flask 侧的根路径/会与挂载前缀/v1组合这一点与 FastAPI 自身子应用的挂载语义一致详见 Sub Applications - Mounts 中关于路径前缀与root_path的说明。示例中对查询参数name做了escape转义处理markupsafe用于防止将用户输入直接拼入响应导致的注入问题值得在真实项目中沿用。运行与验证按官方文档说明运行该应用后访问 http://localhost:8000/v1/返回 Flask 的输出Hello, World from Flask!访问 http://localhost:8000/v2返回 FastAPI 的 JSON{ message: Hello World }也就是说/v1/前缀下的所有请求交给 Flask其余请求由 FastAPI 处理两个框架在同一进程内按路径各司其职。仓库用 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}其中test_flask断言挂载路径/v1/返回 Flask 的文本响应test_app断言 FastAPI 自身的/v2仍返回 JSON。如果你在本地复现也可以用fastapiCLI 或uvicorn启动应用后用浏览器或curl对照验证上面两组响应。为什么不再从 fastapi.middleware.wsgi 导入文档给出了一条重要的演进提示早期推荐从fastapi.middleware.wsgi导入WSGIMiddleware但现在它已被弃用deprecated建议改用a2wsgi包用法完全一致。在仓库源码中可以印证这一点。fastapi/middleware/wsgi.py 现在的内容仅是一行向后兼容的转发导入from starlette.middleware.wsgi import ( WSGIMiddleware as WSGIMiddleware, ) # pragma: no cover # noqa从源码结构可以推断FastAPI 保留了该模块作为兼容入口但不再推荐使用WSGIMiddleware的实际实现来自 Starlette 中间件体系。而文档明确建议的新方式是安装独立的a2wsgi包并从中导入from a2wsgi import WSGIMiddleware两个入口的使用方法完全相同区别仅在于依赖来源与维护方。若你沿用旧的导入路径代码在最新版中依然能运行兼容性重导出但应在新代码中切换到a2wsgi以便跟上官方推荐方向。底层工作方式与注意事项从机制上理解这个方案有助于排查问题协议桥接WSGIMiddleware的作用是把 ASGI 传入的scope请求信息翻译为 WSGI 约定的environ调用被包装的 Flask/Django 应用再把它写出的 WSGI 响应翻译回 ASGI 响应事件。a2wsgi正是专门做这种桥接的库FastAPI 自身源码中不含其实现属第三方依赖路径边界清晰挂载是前缀委托——凡请求路径以挂载点/v1开头FastAPI 自身的路由、OpenAPI、/docs文档界面都不会再参与该前缀下的请求分发因此不会被误路由根路径与子应用与挂载 FastAPI 子应用一样被挂载的 WSGI 应用也遵循挂载路径 应用内部路径的组合规则。若被挂载应用内部有静态文件、重定向或绝对路径 URL 生成逻辑需要留意路径前缀是否被正确携带分阶段迁移策略可以利用多个挂载点如同时挂载/flask/与/django/承接不同历史服务再由 FastAPI 对外统一暴露新接口逐步把流量从旧应用迁移到 FastAPI 后移除挂载实现平滑换代。相关文档与源码速查想继续深入了解挂载机制与代理场景可在仓库中对照阅读以下文件英文原版主题文档docs/en/docs/advanced/wsgi.md子应用挂载原理含root_path技术细节docs/en/docs/advanced/sub-applications.md反向代理与路径前缀处理docs/en/docs/advanced/behind-a-proxy.md可运行示例源码docs_src/wsgi/tutorial001_py310.py自动化验证测试tests/test_tutorial/test_wsgi/test_tutorial001.py已弃用的兼容入口模块fastapi/middleware/wsgi.py至此你已经可以基于这套模式在同一个 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），仅供参考