flask

用途

Flask 是一个用 Python 构建 Web 应用的框架。本技能面向使用 Flask 开发生产级应用的场景，提供经过生产验证的代码模式，重点解决应用工厂模式、蓝图（Blueprints）和 Flask-SQLAlchemy 的实践问题，并预防 9 个已记录的错误。

主要能力

• 提供应用工厂模式（application factory）的项目结构与实现示例，便于多配置实例、避免循环导入。
• 提供蓝图（Blueprints）的创建与注册方式，支持蓝图专属模板与静态文件。
• 提供 Flask-SQLAlchemy 数据模型、Flask-Login 认证、Flask-WTF 表单的示例代码。
• 预防 9 个已记录问题：
  1. stream_with_context 拆卸回归（Flask 3.1.2）：teardown 回调需幂等，使用 g.pop(key, None)。
  2. 异步视图与 gevent 不兼容：需二选一，或使用特定 workaround。
  3. 测试客户端重定向后会话未更新：Flask 3.1.2 已修复，旧版本需手动跟随重定向。
  4. 线程中应用上下文丢失：需用 _get_current_object() 解包代理并推送应用上下文。
  5. Flask-Login 会话保护导致意外登出：建议使用 basic 模式。
  6. CSRF 保护与缓存干扰：需对齐缓存时长与令牌有效期，或排除表单缓存。
  7. 按请求覆盖 max_content_length（Flask 3.1.0 新特性）。
  8. SECRET_KEY 轮换（Flask 3.1.0 新增 SECRET_KEY_FALLBACKS）。
  9. Werkzeug 3.1+ 依赖冲突：需同步升级 Pallets 项目依赖。

使用方式

快速开始（使用 uv）：

uv init my-flask-app
cd my-flask-app
uv add flask flask-sqlalchemy flask-login flask-wtf python-dotenv
uv run flask --app app run --debug

最小示例：

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return {"message": "Hello, World!"}

if __name__ == "__main__":
    app.run(debug=True)

运行：uv run flask --app app run --debug

推荐项目结构采用应用工厂模式，包含 config.py、run.py、app/（init.py、extensions.py、models.py、各蓝图目录、templates、static）和 tests/。

核心模式包括：应用工厂 create_app、扩展模块 extensions.py、配置类、入口 run.py、蓝图创建与注册、数据库模型、Flask-Login 认证表单与路由、API JSON 路由。

适用场景

• 使用 Python 构建 Web 应用或 REST API。
• 需要可维护、可测试的项目结构（应用工厂 + 蓝图）。
• 需要集成数据库（Flask-SQLAlchemy）、认证（Flask-Login）、表单与 CSRF 保护（Flask-WTF）。
• 需要规避 Flask 3.1.x 及依赖升级中的已知问题。

限制

• 要求 Python 3.9+（Flask 3.1.0 起不再支持 3.8）。
• 最新版本（2026 年 1 月验证）：Flask 3.1.2、Flask-SQLAlchemy 3.1.1、Flask-Login 0.6.3、Flask-WTF 1.2.2、Werkzeug 3.1.5。
• 部分问题（如 stream_with_context 回归）将在 Flask 3.2.0 修复，当前需按预防方案处理。
• 异步与 gevent 同时使用需特定 workaround，且维护者指出这会“违背两者的初衷”。
• SECRET_KEY_FALLBACKS 需要扩展显式支持，Flask-Login 和 Flask-WTF 可能需要更新。
• 资料未提供收费、价格、平台支持范围等信息。