Thread Local 的概念

从面向对象设计的角度看，对象是保存“状态”的地方。Python 也是如此，一个对象的状态都被保存在对象携带的一个特殊字典中，可以通过 vars 函数拿到它。

Thread Local 则是一种特殊的对象，它的“状态”对线程隔离 —— 也就是说每个线程对一个 Thread Local 对象的修改都不会影响其他线程。这种对象的实现原理也非常简单，只要以线程的 ID 来保存多份状态字典即可，就像按照门牌号隔开的一格一格的信箱。

在 Python 中获得一个这样的 Thread Local 最简单的方法是 threading.local()：

Python Shell

>>> import threading

>>> storage = threading.local()

>>> storage.foo = 1

>>> print(storage.foo)

1

>>> class AnotherThread(threading.Thread):

...     def run(self):

...         storage.foo = 2

...         print(storage.foo)  # 这这个线程里已经修改了

>>>

>>> another = AnotherThread()

>>> another.start()

2

>>> print(storage.foo)  # 但是在主线程里并没有修改

1

这样来说，只要能构造出 Thread Local 对象，就能够让同一个对象在多个线程下做到状态隔离。这个“线程”不一定要是系统线程，也可以是用户代码中的其他调度单元，例如 Greenlet。[5]

Werkzeug 实现的 Local Stack 和 Local Proxy

Werkzeug 没有直接使用 threading.local，而是自己实现了 werkzeug.local.Local 类。后者和前者有一些区别：

• 后者会在 Greenlet 可用的情况下优先使用 Greenlet 的 ID 而不是线程 ID 以支持 Gevent 或 Eventlet 的调度，前者只支持多线程调度；
• 后者实现了 Werkzeug 定义的协议方法 __release_local__，可以被 Werkzeug 自己的 release_pool 函数释放（析构）掉当前线程下的状态，前者没有这个能力。

除 Local 外，Werkzeug 还实现了两种数据结构：LocalStack 和 LocalProxy。

LocalStack 是用 Local 实现的栈结构，可以将对象推入、弹出，也可以快速拿到栈顶对象。当然，所有的修改都只在本线程可见。和 Local 一样，LocalStack 也同样实现了支持 release_pool 的接口。

LocalProxy 则是一个典型的代理模式实现，它在构造时接受一个 callable 的参数（比如一个函数），这个参数被调用后的返回值本身应该是一个 Thread Local 对象。对一个 LocalProxy 对象的所有操作，包括属性访问、方法调用（当然方法调用就是属性访问）甚至是二元操作 [6] 都会转发到那个 callable 参数返回的 Thread Local 对象上。

LocalProxy 的一个使用场景是 LocalStack 的 __call__ 方法。比如 my_local_stack 是一个 LocalStack 实例，那么 my_local_stack() 能返回一个 LocalProxy 对象，这个对象始终指向 my_local_stack 的栈顶元素。如果栈顶元素不存在，访问这个 LocalProxy 的时候会抛出 RuntimeError。

Flask 基于 Local Stack 的 Context

Flask 是一个基于 Werkzeug 实现的框架，所以 Flask 的 App Context 和 Request Context 也理所当然地基于 Werkzeug 的 Local Stack 实现。

在概念上，App Context 代表了“应用级别的上下文”，比如配置文件中的数据库连接信息；Request Context 代表了“请求级别的上下文”，比如当前访问的 URL。

这两种上下文对象的类定义在 flask.ctx 中，它们的用法是推入 flask.globals 中创建的 _app_ctx_stack 和 _request_ctx_stack 这两个单例 Local Stack 中。因为 Local Stack 的状态是线程隔离的，而 Web 应用中每个线程（或 Greenlet）同时只处理一个请求，所以 App Context 对象和 Request Context 对象也是请求间隔离的。

当 app = Flask(__name__) 构造出一个 Flask App 时，App Context 并不会被自动推入 Stack 中。所以此时 Local Stack 的栈顶是空的，current_app 也是 unbound 状态。

Python Shell

>>> from flask import Flask

>>> from flask.globals import _app_ctx_stack, _request_ctx_stack

>>>

>>> app = Flask(__name__)

>>> _app_ctx_stack.top

>>> _request_ctx_stack.top

>>> _app_ctx_stack()

<LocalProxy unbound>

>>>

>>> from flask import current_app

>>> current_app

<LocalProxy unbound>

这也是一些 Flask 用户可能被坑的地方 —— 比如编写一个离线脚本时，如果直接在一个 Flask-SQLAlchemy 写成的 Model 上调用 User.query.get(user_id)，就会遇到 RuntimeError。因为此时 App Context 还没被推入栈中，而 Flask-SQLAlchemy 需要数据库连接信息时就会去取 current_app.config，current_app 指向的却是 _app_ctx_stack 为空的栈顶。

解决的办法是运行脚本正文之前，先将 App 的 App Context 推入栈中，栈顶不为空后 current_app 这个 Local Proxy 对象就自然能将“取 config 属性” 的动作转发到当前 App 上了：

Python Shell

>>> ctx = app.app_context()

>>> ctx.push()

>>> _app_ctx_stack.top

<flask.ctx.AppContext object at 0x102eac7d0>

>>> _app_ctx_stack.top is ctx

True

>>> current_app

<Flask '__main__'>

>>>

>>> ctx.pop()

>>> _app_ctx_stack.top

>>> current_app

<LocalProxy unbound>

那么为什么在应用运行时不需要手动 app_context().push() 呢？因为 Flask App 在作为 WSGI Application 运行时，会在每个请求进入的时候将请求上下文推入 _request_ctx_stack 中，而请求上下文一定是 App 上下文之中，所以推入部分的逻辑有这样一条：如果发现 _app_ctx_stack为空，则隐式地推入一个 App 上下文。

所以，请求中是不需要手动推上下文入栈的，但是离线脚本需要手动推入 App Context。如果没有什么特殊困难，我更建议用 Flask-Script 来写离线任务。[7]

两个疑问

到此为止，就出现两个疑问：

• 为什么 App Context 要独立出来：既然在 Web 应用运行时里，App Context 和 Request Context 都是 Thread Local 的，那么为什么还要独立二者？
• 为什么要放在“栈”里：在 Web 应用运行时中，一个线程同时只处理一个请求，那么 _req_ctx_stack 和 _app_ctx_stack 肯定都是只有一个栈顶元素的。那么为什么还要用“栈”这种结构？

我最初也被这两个疑问困惑过。后来看了一些资料，就明白了 Flask 为何要设计成这样。这两个做法给予我们 多个 Flask App 共存 和 非 Web Runtime 中灵活控制 Context 的可能性。

我们知道对一个 Flask App 调用 app.run() 之后，进程就进入阻塞模式并开始监听请求。此时是不可能再让另一个 Flask App 在主线程运行起来的。那么还有哪些场景需要多个 Flask App 共存呢？前面提到了，一个 Flask App 实例就是一个 WSGI Application，那么 WSGI Middleware 是允许使用组合模式的，比如：

wsgi

from werkzeug.wsgi import DispatcherMiddleware

from biubiu.app import create_app

from biubiu.admin.app import create_app as create_admin_app

application = DispatcherMiddleware(create_app(), {

    '/admin': create_admin_app()

})

这个例子就利用 Werkzeug 内置的 Middleware 将两个 Flask App 组合成一个一个 WSGI Application。这种情况下两个 App 都同时在运行，只是根据 URL 的不同而将请求分发到不同的 App 上处理。

如果仅仅在 Web Runtime 中，多个 Flask App 同时工作倒不是问题。毕竟每个请求被处理的时候是身处不同的 Thread Local 中的。但是 Flask App 不一定仅仅在 Web Runtime 中被使用 —— 有两个典型的场景是在非 Web 环境需要访问上下文代码的，一个是离线脚本（前面提到过），另一个是测试。这两个场景即所谓的“Running code outside of a request”。

在非 Web 环境运行 Flask 关联的代码

离线脚本或者测试这类非 Web 环境和和 Web 环境不同 —— 前者一般只在主线程运行。

设想，一个离线脚本需要操作两个 Flask App 关联的上下文，应该怎么办呢？这时候栈结构的 App Context 优势就发挥出来了。

offline_script.py

from biubiu.app import create_app

from biubiu.admin.app import create_app as create_admin_app

app = create_app()

admin_app = create_admin_app()

def copy_data():

    with app.app_context():

        data = read_data()  # fake function for demo

        with admin_app.app_context():

            write_data(data)  # fake function for demo

        mark_data_copied()  # fake function for demo

无论有多少个 App，只要主动去 Push 它的 App Context，Context Stack 中就会累积起来。这样，栈顶永远是当前操作的 App Context。当一个 App Context 结束的时候，相应的栈顶元素也随之出栈。如果在执行过程中抛出了异常，对应的 App Context 中注册的 teardown 函数被传入带有异常信息的参数。

这么一来就解释了两个疑问 —— 在这种单线程运行环境中，只有栈结构才能保存多个 Context 并在其中定位出哪个才是“当前”。而离线脚本只需要 App 关联的上下文，不需要构造出请求，所以 App Context 也应该和 Request Context 分离。

另一个手动推入 Context 的场景是测试。测试中我们可能会需要构造一个请求，并验证相关的状态是否符合预期。例如：

tests.py

def test_app():

    app = create_app()

    client = app.test_client()

    resp = client.get('/')

    assert 'Home' in resp.data

这里调用 client.get 时，Request Context 就被推入了。其特点和 App Context 非常类似，这里不再赘述。

为何建议使用 App Factory 模式

从官方文档来看，Flask 有 Singleton 和 App Factory 两种用法。前一种用法和其他的一些 Web 框架（如 Bottle、Sinatra）的门面广告很相似，因为代码精简，所以显得非常的“帅”：

app.py

from flask import Flask, render_template

from flask.ext.sqlalchemy import SQLAlchemy

from flask.ext.login import LoginManager

app = Flask(__name__)

db = SQLAlchemy(app)

login_manager = LoginManager()

@app.route('/')

def home():

    return render_template('home.html')

但是这种“帅”是有代价的。一个最麻烦的问题就是编写测试的时候：

test_app.py

class TestApp(unittest.TestCase):

    DEBUG = False

    TESTING = True

    SQLALCHEMY_DATABASE_URI = None

    def setUp(self):

        self.app = create_app()

        self.app.config.from_object(self)

        self.client = self.app.test_client()

    def test_app(self):

        @self.app.route('/test/<int:id_>')

        def my_view(id_):

            return '#%d' % id_

        resp = self.client.get('/test/42')

        self.assertEqual(resp.data, '#42')

    def test_home(self):

        resp = self.client.get('/')

        self.assertIn('Welcome', resp.data)

在上面的例子中，我为了测试给 App 新挂载了一个 View 函数。这是很常见的一个测试需求。但是如果 Flask App 实例是单例的，这种做法就会“弄脏”下一个测试的运行。更加麻烦的是，上述例子中如果 test_home 在 test_app 之前运行了，Flask 的开发者防御机制会认为这是一个“已经开始处理 Web 请求了，又挂载了视图” [8] 的失误，从而抛出 RuntimeError。

所以除非是应用简单到不需要 Web 层测试，否则还是尽量使用 App Factory 模式比较好。况且配合 Blueprint 的情况下，App Factory 还能帮助我们良好地组织应用结构：

happytree/app.py

from flask import Flask

from werkzeug.utils import import_string

extensions = [

    'happytree.ext:db',

    'happytree.ext:login_manager',

]

blueprints = [

    'happytree.views:bp',

]

def create_app():

    app = Flask(__name__)

    for ext_name in extensions:

        ext = import_string(ext_name)

        ext.init_app(app)

    for bp_name in blueprints:

        bp = import_string(bp_name)

        app.register_blueprint(bp)

    return app

这样就能彻底摆脱 app.py 和 View 模块“互相 Import”的纠结了。

好吧其实这一节和 Context 没啥关系……

拖延不好

这篇文章动笔开始写是 6 月 21 日，到今天发布出来，已经过去了整整一个月。而事实上我开始列提纲准备写这篇文章已经是三四月份的事情了。

_(:з」∠)_