Flask 轻量开发

从 Flask 迁到 FastAPI:什么时候值得

不是所有 Flask 项目都需要迁移。当接口契约、异步 I/O 与自动生成文档成为刚需时,迁移才有明确回报。

约 3 分钟897 字

Flask 与 FastAPI 不是新旧关系,而是取舍不同。Flask 轻量、同步友好、生态成熟;FastAPI 基于类型注解生成校验与 OpenAPI 文档,天然适配异步与 AI 服务场景。

值得迁移的信号

  • 接口数量多,手写校验和文档已成主要维护成本。
  • 大量调用外部 AI 模型、搜索引擎或第三方 API,等待时间占比高。
  • 前端或合作方需要稳定的 OpenAPI Schema 生成客户端。
  • 团队已经普遍使用 Pydantic 与类型注解。

反过来,如果项目只是几个内部表单页面和 webhook 接收器,迁移带来的收益很难覆盖成本。

增量迁移比重写安全

# 用 ASGI/WSGI 混合挂载,先迁一个业务域
from fastapi import FastAPI
from starlette.middleware.wsgi import WSGIMiddleware
from flask_app import create_app

api = FastAPI(title="新接口")
flask_app = create_app()
api.mount("/legacy", WSGIMiddleware(flask_app))

先迁出最独立的读接口,观察性能与错误率,再逐步移动写接口。不要选在业务高峰期做「大爆炸式」切换。

迁移时最容易低估的部分

  1. 认证中间件。Flask 的 @login_required 与 FastAPI 的 Dependency 不是一一对应。
  2. 异常处理。错误码、响应结构要在迁移前统一定义,否则前端会先崩。
  3. 扩展替代。Flask-SQLAlchemy 换成 SQLAlchemy 2.x 会话管理,需要重新处理生命周期。
  4. 部署方式。ASGI 用 uvicorn / gunicorn worker class,与 WSGI 的运行模型不同。

先写契约再改实现

把请求与响应模型先定义成 Pydantic 类,用同一份契约驱动测试与文档。这样迁移过程中,即使实现还是 Flask,前端也能提前按新契约对接。