Flask 应用对象 API
Flask 类是整个框架的核心，它作为 WSGI 应用运行，并集中管理路由、模板、配置、钩子等所有功能。
创建方式：
app = Flask(__name__)
构造函数参数
以下是创建 Flask 实例时可以传递的全部参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| import_name | str | 必填 | 应用模块/包名，Flask 用它定位模板和静态文件的位置。单文件传递 __name__，包传递包名 |
| static_url_path | str | None | 静态文件对外暴露的 URL 路径。不设置时使用 static_folder 的文件夹名，如 /static |
| static_folder | str | "static" | 存放静态文件（CSS、JS、图片）的文件夹路径，相对于 root_path 或绝对路径 |
| static_host | str | None | 静态文件路由的主机名，仅在 host_matching=True 时需要 |
| host_matching | bool | False | 是否按 Host 头匹配路由 |
| subdomain_matching | bool | False | 是否启用子域名路由匹配 |
| template_folder | str | "templates" | 存放 Jinja2 模板文件的文件夹路径 |
| instance_path | str | None（自动发现） | instance 文件夹路径，存储运行时不提交版本控制的文件。设为绝对路径 |
| instance_relative_config | bool | False | 为 True 时，配置文件的相对路径基于 instance_path 而非 root_path |
| root_path | str | None（自动发现） | 应用的根路径，通常自动推断，仅命名空间包需要手动设置 |
核心属性
| 属性 | 类型 | 说明 |
|---|---|---|
| name | str | 应用名称。如果 import_name 为 __main__，则取主文件名 |
| config | Config | 配置字典对象，存储所有配置项 |
| debug | bool | 是否开启调试模式。等价于 config["DEBUG"] |
| testing | bool | 是否开启测试模式。等价于 config["TESTING"] |
| secret_key | str | 安全密钥，用于 Session 签名。等价于 config["SECRET_KEY"] |
| permanent_session_lifetime | timedelta | 永久 Session 的有效期，默认 31 天 |
| url_map | Map | Werkzeug 的 URL 映射表，存储所有路由规则 |
| view_functions | dict | endpoint → 视图函数的映射字典 |
| blueprints | dict | 已注册的蓝图名称 → Blueprint 实例映射 |
| extensions | dict | 扩展存储字典，扩展按模块名存储自己的状态 |
| logger | Logger | Python 标准 logging.Logger，应用名作为 logger 名 |
| jinja_env | Environment | Jinja2 环境实例，控制模板加载方式 |
| json | JSONProvider | JSON 处理提供者实例，可替换为自定义 JSON 库 |
| aborter | Aborter | HTTP 异常抛出器，被 abort() 函数调用 |
| cli | AppGroup | Click 命令组，可添加自定义 CLI 命令 |
| instance_path | str | instance 文件夹的绝对路径 |
| root_path | str | 应用根目录的绝对路径 |
可重写的类属性
以下属性可在子类中覆盖，以自定义框架行为：
| 属性 | 默认值 | 说明 |
|---|---|---|
| request_class | Request | 用于创建请求对象的类 |
| response_class | Response | 用于创建响应对象的类 |
| session_interface | SecureCookieSessionInterface() | Session 后端接口，可替换为 Redis/数据库 Session |
| jinja_environment | Environment | Jinja2 环境类 |
| app_ctx_globals_class | _AppCtxGlobals | g 对象的类 |
| config_class | Config | 配置对象的类 |
| aborter_class | Aborter | 异常抛出器的类 |
| json_provider_class | DefaultJSONProvider | JSON 处理器的类 |
| url_rule_class | Rule | URL 规则的类（Werkzeug） |
| url_map_class | Map | URL 映射表的类（Werkzeug） |
| test_client_class | None（默认 FlaskClient） | 测试客户端的类 |
| test_cli_runner_class | None（默认 FlaskCliRunner） | CLI 测试运行器的类 |
| jinja_options | {} | 传递给 Jinja2 环境的额外选项 |
URL 路由方法
| 方法 | 签名 | 说明 |
|---|---|---|
| route | (rule, **options) | 装饰器，将一个 URL 规则绑定到视图函数 |
| get | (rule, **options) | 装饰器，仅绑定 GET 方法（等价于 methods=["GET"]） |
| post | (rule, **options) | 装饰器，仅绑定 POST 方法 |
| put | (rule, **options) | 装饰器，仅绑定 PUT 方法 |
| delete | (rule, **options) | 装饰器，仅绑定 DELETE 方法 |
| patch | (rule, **options) | 装饰器，仅绑定 PATCH 方法 |
| add_url_rule | (rule, endpoint, view_func, provide_automatic_options, **options) | 以编程方式添加 URL 规则。route 装饰器底层调用此方法 |
| url_for | (endpoint, *, _anchor, _method, _scheme, _external, **values) | 根据 endpoint 和参数生成 URL。蓝图中 endpoint 需加蓝图名前缀 |
| register_blueprint | (blueprint, **options) | 注册一个蓝图，可指定 url_prefix、subdomain 等覆盖参数 |
| iter_blueprints | () | 按注册顺序遍历所有蓝图 |
route 装饰器支持的 options 包括：methods（HTTP 方法列表）、endpoint（自定义端点名）、defaults（默认参数）、subdomain（子域名）等。
请求生命周期钩子（装饰器）
以下方法均可用作装饰器，在请求的不同阶段插入自定义逻辑。
| 方法 | 执行时机 | 返回非None的行为 | 典型用途 |
|---|---|---|---|
| before_request | 路由分发之前 | 返回值作为最终响应，跳过视图函数 | 登录检查、权限验证 |
| after_request | 响应构建之后、发送之前 | 必须接收并返回 Response 对象 | 添加安全头、CORS 头 |
| teardown_request | 请求上下文弹出时 | 返回值被忽略 | 释放请求级资源 |
| teardown_appcontext | 应用上下文弹出时 | 返回值被忽略 | 关闭数据库连接 |
| errorhandler | 指定状态码或异常发生时 | 返回值作为错误页面的响应 | 自定义 404/500 页面 |
| url_value_preprocessor | URL 变量提取后、视图调用前 | 返回值被忽略 | 对 URL 参数做预处理 |
| url_defaults | url_for 构建 URL 时 | 修改传入的 values 字典 | 为 url_for 添加默认参数 |
| template_filter | —（注册性质） | — | 注册 Jinja2 模板过滤器 |
| template_test | —（注册性质） | — | 注册 Jinja2 模板测试 |
| template_global | —（注册性质） | — | 注册 Jinja2 全局函数 |
| shell_context_processor | flask shell 启动时 | 返回 dict，合并到 shell 上下文中 | 预导入常用对象到 flask shell |
请求处理方法
以下方法在请求处理流程中被内部调用，可在子类中重写：
| 方法 | 说明 |
|---|---|
| preprocess_request(ctx) | 请求预处理：执行 before_request 函数和 URL 预处理器 |
| dispatch_request(ctx) | 核心分发：匹配 URL，调用对应视图函数 |
| make_response(rv) | 将视图函数的返回值转换为 Response 对象 |
| finalize_request(ctx, rv) | 最终化：调用 make_response 和 after_request 钩子 |
| process_response(ctx, response) | 响应后处理：执行 after_request 函数和 Session 保存 |
| full_dispatch_request(ctx) | 完整的请求调度入口：preprocess → dispatch → finalize |
| handle_http_exception(ctx, e) | 处理 HTTP 异常，查找对应的 errorhandler |
| handle_user_exception(ctx, e) | 处理用户代码异常，区分 HTTP 异常和普通异常 |
| handle_exception(ctx, e) | 最终异常处理，返回 500 响应 |
| ensure_sync(func) | 确保函数同步执行。async 函数会被包装为同步 |
| make_default_options_response(ctx) | 生成自动的 OPTIONS 响应 |
| raise_routing_exception(request) | 处理路由异常（如尾斜线重定向） |
模板和静态文件
| 方法 | 说明 |
|---|---|
| create_jinja_environment() | 创建并配置 Jinja2 环境。首次访问 jinja_env 时自动调用 |
| create_global_jinja_loader() | 创建 Jinja2 全局加载器，支持应用和蓝图的模板分发 |
| select_jinja_autoescape(filename) | 判断给定文件是否需要自动转义。默认 .html/.htm/.xml/.xhtml/.svg 返回 True |
| update_template_context(ctx, context) | 向模板上下文注入 request、session、g、config 等内置变量 |
| send_static_file(filename) | 从 static_folder 发送文件，自动注册为 /static/ |
| get_send_file_max_age(filename) | 获取静态文件的缓存时间，默认使用 SEND_FILE_MAX_AGE_DEFAULT 配置 |
| open_resource(resource, mode="rb") | 以二进制模式打开 root_path 下的资源文件 |
| open_instance_resource(resource, mode="rb") | 打开 instance_path 下的资源文件，支持写入模式 |
上下文管理
| 方法 | 说明 |
|---|---|
| app_context() | 创建应用上下文，用 with 语句手动推入。使 current_app 和 g 可用 |
| request_context(environ) | 根据 WSGI environ 创建请求上下文 |
| test_request_context(*args, **kwargs) | 创建模拟的请求上下文，用于测试。接收 path、method、data、json 等参数 |
| wsgi_app(environ, start_response) | 核心 WSGI 应用方法。可通过 app.wsgi_app = Middleware(app.wsgi_app) 包装中间件 |
测试和开发工具
| 方法 | 说明 |
|---|---|
| test_client(use_cookies=True, **kwargs) | 创建测试客户端，模拟浏览器发送请求。返回 FlaskClient 实例 |
| test_cli_runner(**kwargs) | 创建 CLI 测试运行器，用于测试自定义命令。返回 FlaskCliRunner 实例 |
| run(host, port, debug, load_dotenv, **options) | 启动开发服务器。生产环境应使用 Gunicorn/ Waitress |
| make_shell_context() | 构建 flask shell 的上下文字典。运行所有 shell_context_processor |
| log_exception(ctx, exc_info) | 记录异常到 logger，传入 exc_info 元组 |
工具方法
| 方法 | 说明 |
|---|---|
| redirect(location, code=303) | 创建重定向响应对象 |
| async_to_sync(func) | 将异步协程函数转换为同步函数 |
| create_url_adapter(request) | 根据请求或配置创建 URL 适配器，用于 URL 构建 |
| inject_url_defaults(endpoint, values) | 向 URL 构建过程注入默认参数 |
| handle_url_build_error(error, endpoint, values) | 处理 url_for 构建失败的情况，可返回替代 URL |
| make_config(instance_relative) | 创建 Config 实例，可被子类重写以自定义配置 |
| make_aborter() | 创建 Aborter 实例 |
| trap_http_exception(e) | 判断是否将 HTTP 异常作为普通异常向上抛出 |
| auto_find_instance_path() | 自动查找 instance 文件夹路径 |
代码示例
实例
from flask import Flask
# 创建应用，指定模板和静态文件夹
app = Flask(__name__,
template_folder="templates",
static_folder="static",
instance_relative_config=True)
# 设置密钥
app.secret_key = "your-secret-key"
# 注册路由
@app.route("/")
def index():
return "<h1>Hello, RUNOOB!</h1>"
# 注册 before_request 钩子
@app.before_request
def check_auth():
# 在此检查用户认证状态
pass
# 注册 after_request 钩子
@app.after_request
def add_header(response):
# 为每个响应添加自定义头
response.headers["X-Custom-Header"] = "RUNOOB"
return response
# 注册错误处理器
@app.errorhandler(404)
def not_found(error):
return "<h1>页面未找到</h1>", 404
# 注册自定义 CLI 命令
@app.cli.command("hello")
def hello_command():
"""打印问候语"""
print("Hello from RUNOOB Flask App!")
# 创建应用，指定模板和静态文件夹
app = Flask(__name__,
template_folder="templates",
static_folder="static",
instance_relative_config=True)
# 设置密钥
app.secret_key = "your-secret-key"
# 注册路由
@app.route("/")
def index():
return "<h1>Hello, RUNOOB!</h1>"
# 注册 before_request 钩子
@app.before_request
def check_auth():
# 在此检查用户认证状态
pass
# 注册 after_request 钩子
@app.after_request
def add_header(response):
# 为每个响应添加自定义头
response.headers["X-Custom-Header"] = "RUNOOB"
return response
# 注册错误处理器
@app.errorhandler(404)
def not_found(error):
return "<h1>页面未找到</h1>", 404
# 注册自定义 CLI 命令
@app.cli.command("hello")
def hello_command():
"""打印问候语"""
print("Hello from RUNOOB Flask App!")