flask-项目结构

项目结构

【多文件 Flask 程序的基本结构】

4 个顶级文件夹：
- app 目录包含Flask 程序；
- migrations 文件夹包含数据库迁移脚本
- tests 目录包含测试代码；
- venv 目录包含 Python 虚拟环境。

同时还创建了一些新文件：

• requirements.txt 列出了所有依赖包，便于在其他电脑中重新生成相同的虚拟环境；
• config.py 存储配置；
• manage.py 用于启动程序以及其他的程序任务。

配置选项:config.py

程序经常需要设定多个配置。这方面最好的例子就是开发、测试和生产环境要使用不同的数据库，
这样才不会彼此影响。

我们使用层次结构的配置类。 config.py 文
件的内容如下所示：

【 config.py】

# coding:utf-8
import os

basedir = os.path.abspath(os.path.dirname(__file__))

# 基类
class Config:
    SECRET_KEY = 'hard to guess string'
    SQLALCHEMY_COMMIT_ON_TEARDOWN = True
    FLASKY_MAIL_SUBJECT_PREFIX = '[Flask]'
    FLASKY_MAIL_SENDER = 'Flask Admin'
    FLASKY_ADMIN = 'dimples'

    @staticmethod
    def init_app(app):
        pass

# 开发环境
class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(basedir, 'data-dev.sqlite')

# 测试环境
class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(basedir, 'data-test.sqlite')

# 生产环境
class ProductionConfig(Config):
    SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(basedir, 'data.sqlite')

# 设置一个config 字典中,注册了不同的配置环境
config = {
    'development': DevelopmentConfig,
    'testing': TestingConfig,
    'production': ProductionConfig,
    'default': DevelopmentConfig

基类 Config 中包含通用配置，子类分别定义专用的配置，主要是数据库。在 3 个子类中，
SQLALCHEMY_DATABASE_URI 变量都被指定了不同的值。这样程序就可在不同的配置环境中运行，每
个环境都使用不同的数据库。

配置类可以定义 init_app() 类方法，其参数是程序实例。在这个方法中，可以执行对当前环境的
配置初始化。现在，基类 Config 中的 init_app() 方法为空。

程序包：app/

程序包用来保存程序的所有代码、模板和静态文件。我们可以把这个包直接称为 app（应用），
可使用一个程序专用名字。

templates 和 static 文件夹是程序包的一部分，因此这两个文件夹移到了 app 中。 数据库模型和电子邮件支持函数也被移到了这个包中，分别保存为
app/models.py 和 app/email.py。

1.程序工厂函数：app/_init_.py

为了提高测试覆盖度，必须在不同的配置环境中运行程序。

这个问题的解决方法是延迟创建程序实例， 把创建过程移到可显式调用的工厂函数中。这种方法不
仅可以给脚本留出配置程序的时间，还能够创建多个程序实例，这些实例有时在测试中非常有用。
程序的工厂函数在 app 包的构造文件中定义，如下所示。

【app/init.py】

from flask import Flask
from flask_bootstrap import Bootstrap
from flask_mail import Mail
from flask_sqlalchemy import SQLAlchemy
from config import config

bootstrap = Bootstrap()
mail = Mail()
db = SQLAlchemy()

# 工厂函数
def create_app(config_name):
    app = Flask(__name__)
    app.config.from_object(config[config_name])
    config[config_name].init_app(app)

    bootstrap.init_app(app)
    mail.init_app(app)
    db.init_app(app)

    #注册蓝本
    from .main import main as main_blueprint
    app.register_blueprint(main_blueprint)

    return app

构造文件导入了大多数正在使用的 Flask 扩展。由于尚未初始化所需的程序实例，所以没有初始化
扩展， 创建扩展类时没有向构造函数传入参数。

create_app() 函数就是程序的工厂函数，接受一
个参数，是程序使用的配置名。配置类在 config.py 文件中定义，其中保存的配置可以使用 Flask
app.config 配置对象提供的 from_object() 方法直接导入程序。至于配置对象， 则可以通过名字
从 config 字典中选择。程序创建并配置好后，就能初始化扩展了。在之前创建的扩展对象上调用
init_app() 可以完成初始化过程。

2. 在蓝本中实现程序功能：app/main/_init_.py

转换成程序工厂函数的操作让定义路由变复杂了。在单脚本程序中，程序实例存在于全局作用域
中， 路由可以直接使用 app.route 修饰器定义。但现在程序在运行时创建，只有调用
create_app() 之后才能使用 app.route 修饰器，这时定义路由就太晚了。和路由一样，自定义的错误页面处理程序也面临相同的困难，因为错误页面处理程序使用 app.errorhandler 修饰器定
义。

Flask 使用蓝本提供了更好的解决方法。 蓝本和程序类似，也可以定义路由。不同的是，在蓝本中定义的路由处于休眠状态， 直到蓝本注册到程序上后，路由才真正成为程序的一部分。使用
位于全局作用域中的蓝本时，定义路由的方法几乎和单脚本程序一样。

和程序一样， 蓝本可以在单个文件中定义，也可使用更结构化的方式在包中的多个模块中创建。为
了获得最大的灵活性，程序包中创建了一个子包，用于保存蓝本。下面是这个子包的构造文件，蓝
本就创建于此：

【app/main/init.py】

from flask import Blueprint
main = Blueprint('main', __name__)
from . import views, errors

通过实例化一个 Blueprint 类对象可以创建蓝本。
这个构造函数有两个必须指定的参数：蓝本的名
字和蓝本所在的包或模块。 和程序一样，大多数情况下第二个参数使用 Python 的name 变量。

程序的路由保存在包里的 app/main/views.py 模块中，而错误处理程序保存在
app/main/errors.py 模块中。 导入这两个模块就能把路由和错误处理程序与蓝本关联起来。注
意，这些模块在 app/main/init.py 脚本的末尾导入，这是为了避免循环导入依赖，因为在
views.py 和 errors.py 中还要导入蓝本 main。

蓝本在app/init.py的工厂函数 create_app() 中注册到程序上。

【app/main/errors.py：蓝本中的错误处理程序】

from flask import render_template
from . import main

@main.app_errorhandler(404)
def page_not_found(e):
    return render_template('404.html'), 404

@main.app_errorhandler(500)
def internal_server_error(e):
    return render_template('500.html'), 500

在蓝本中编写错误处理程序稍有不同，如果使用 errorhandler 修饰器，那么只有蓝本中的错误才
能触发处理程序。要想注册程序全局的错误处理程序，必须使用 app_errorhandler。

【app/main/views.py：蓝本中定义的程序路由】

from flask import render_template, session, redirect, url_for, current_app
from .. import db
from ..models import User
from ..email import send_email
from . import main
from .forms import NameForm

@main.route('/', methods=['GET', 'POST'])
def index():
    form = NameForm()

   if form.validate_on_submit():
        user = User.query.filter_by(username=form.name.data).first()
        if user is None:
            user = User(username=form.name.data)
            db.session.add(user)
            session['known'] = False
            if current_app.config['FLASKY_ADMIN']:
                send_email(current_app.config['FLASKY_ADMIN'], 'New User',
                           'mail/new_user', user=user)
        else:
            session['known'] = True
        session['name'] = form.name.data
        return redirect(url_for('.index'))
    return render_template('index.html',
                           form=form, name=session.get('name'),
                           known=session.get('known', False))

在蓝本中编写视图函数主要有两点不同：
- 第一，和前面的错误处理程序一样，路由修饰器由蓝本提供；
- 第二， url_for() 函数的用法不同。

url_for() 函数的第一个参数是路由的
端点名， 在程序的路由中，默认为视图函数的名字。例如，在单脚本程序中， index() 视图函数
的 URL 可使用 url_for(‘index’) 获取。

在蓝本中就不一样了， Flask 会为蓝本中的全部端点加上一个命名空间，这样就可以在不同的蓝本
中使用相同的端点名定义视图函数， 而不会产生冲突。命名空间就是蓝本的名字（Blueprint 构造
函数的第一个参数），所以视图函数 index() 注册的端点名是 main.index，其 URL 使用
url_for(‘main.index’) 获取。

url_for() 函数还支持一种简写的端点形式，在蓝本中可以省略蓝本名.

例如 url_for(‘.index’)。

在这种写法中，命名空间是当前请求所在的蓝本。这意味着同一蓝本中的重定
向可以使用简写形式，但跨蓝本的重定向必须使用带有命名空间的端点名。

为了完全修改程序的页面，表单对象也要移到蓝本中，保存于 app/main/forms.py 模块。

3. 启动脚本：manage.py

顶级文件夹中的 manage.py 文件用于启动程序。脚本内容如下所示

【manage.py】

#!/usr/bin/env python
from app import create_app, db
from flask_script import Manager
from flask_migrate import Migrate, MigrateCommand

app = create_app('default')
manager = Manager(app)
migrate = Migrate(app, db)

manager.add_command('db', MigrateCommand)

if __name__ == '__main__':
    manager.run()

这个脚本先使用工厂函数创建程序。然后初始化 Flask-Script、 Flask-Migrate。出于便利，脚本
中加入了#!/usr/bin/env python 声明，所以在基于 Unix 的操作系统中可以通过 ./manage.py 执行脚
本，而不用使用复杂的 python manage.py。

4. 需求文件：requirements.txt

程序中必须包含一个 requirements.txt 文件，用于记录所有依赖包及其精确的版本号。如果要在
另一台电脑上重新生成虚拟环境， 这个文件的重要性就体现出来了，例如部署程序时使用的电脑。
pip 可以使用如下命令自动生成这个文件：

(venv) $ pip freeze >requirements.txt

安装或升级包后，最好更新这个文件。
如果你要创建这个虚拟环境的完全副本，可以创建一个新的虚拟环境，并在其上运行以下命令：

(venv) $ pip install -r requirements.txt

5. 创建数据库

重组后的程序和单脚本版本使用不同的数据库。3种配置环境中的数据库文件名都不一样。例如，
在开发环境中，数据库使用名为data-dev.sqlite 的 SQLite 数据库。

不管是什么环境的数据库，都要在新数据库中创建数据表。如果使用 Flask-Migrate 跟踪迁移，可
使用如下命令创建数据表或者升级到最新修订版本：

(venv) $ python manage.py db upgrade