第 2 章 程序的基本结构

第 2 章 程序的基本结构

本章将带你了解Flask程序各部分的作用,编写并运行第一个Flask Web程序。

2.1 初始化

所有Flask程序都必须创建一个程序实例。Web服务器使用一种名为Web服务器网关接口(Web Server Gateway Interface,WSGI)的协议,把接收自客户端的所有请求都转交给这个对象处理。程序实例是Flask类的对象,经常使用下述代码创建:

from flask import Flask
app = Flask(__name__)

Flask类的构造函数只有一个必须指定的参数,即程序主模块或包的名字。在大多数程序中,Python的__name__变量就是所需的值。

松鼠将构造函数的name参数传给Flask程序,这一点可能会让Flask开发新手心生迷惑。Flask用这个参数决定程序的根目录,以便稍后能够找到相对于程序根目录的资源文件位置。

后文会介绍更复杂的程序初始化方式,对于简单的程序来说,上面的代码足够了。

2.2 路由和视图函数

客户端(例如Web浏览器)把请求发送给Web服务器,Web服务器再把请求发送给Flask程序实例。程序实例需要知道对每个URL请求运行哪些代码,所以保存了一个URL到Python函数的映射关系。处理URL和函数之间关系的程序称为路由

在Flask程序中定义路由的最简便方式,是使用程序实例提供的app.route修饰器,把修饰的函数注册为路由。下面的例子说明了如何使用这个修饰器声明路由:

@app.route('/')
def index():
    return '<h1>Hello World!</h1>'

鸟修饰器是Python语言的标准特性,可以使用不同的方式修改函数的行为。惯常用法是使用修饰器把函数注册为事件的处理程序。

前例把index()函数注册为程序根地址的处理程序。如果部署程序的服务器域名为www.example.com,在浏览器中访问http://www.example.com后,会触发服务器执行index()函数。这个函数的返回值称为响应,是客户端接收到的内容。如果客户端是Web浏览器,响应就是显示给用户查看的文档。

index()这样的函数称为视图函数(view function)。视图函数返回的响应可以是包含HTML的简单字符串,也可以是复杂的表单,后文会介绍。

鸟在Python代码中嵌入响应字符串会导致代码难以维护,此处这么做只是为了介绍响应的概念。你将在第3章了解生成响应的正确方法。

如果你仔细观察日常所用服务的某些URL格式,会发现很多地址中都包含可变部分。例如,你的Facebook资料页面的地址是http://www.facebook.com/<your-name>,用户名(your-name)是地址的一部分。Flask支持这种形式的URL,只需在route修饰器中使用特殊的句法即可。下例定义的路由中就有一部分是动态名字:

@app.route('/user/<name>')
def user(name):
    return '<h1>Hello, %s!</h1>' % name

尖括号中的内容就是动态部分,任何能匹配静态部分的URL都会映射到这个路由上。调用视图函数时,Flask会将动态部分作为参数传入函数。在这个视图函数中,参数用于生成针对个人的欢迎消息。

路由中的动态部分默认使用字符串,不过也可使用类型定义。例如,路由/user/<int:id>只会匹配动态片段id为整数的URL。Flask支持在路由中使用intfloatpath类型。path类型也是字符串,但不把斜线视作分隔符,而将其当作动态片段的一部分。

2.3 启动服务器

程序实例用run方法启动Flask集成的开发Web服务器:

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

__name__=='__main__'是Python的惯常用法,在这里确保直接执行这个脚本时才启动开发Web服务器。如果这个脚本由其他脚本引入,程序假定父级脚本会启动不同的服务器,因此不会执行app.run()

服务器启动后,会进入轮询,等待并处理请求。轮询会一直运行,直到程序停止,比如按Ctrl-C键。

有一些选项参数可被app.run()函数接受用于设置Web服务器的操作模式。在开发过程中启用调试模式会带来一些便利,比如说激活调试器重载程序。要想启用调试模式,我们可以把debug参数设为True

鸟Flask提供的Web服务器不适合在生产环境中使用。第17章会介绍生产环境Web服务器。

2.4 一个完整的程序

前几节介绍了Flask Web程序的不同组成部分,现在是时候开发一个程序了。整个hello.py程序脚本就是把前面介绍的三部分合并到一个文件中。程序代码如示例2-1所示。

示例2-1 hello.py:一个完整的Flask程序

from flask import Flask
app = Flask(__name__)

@app.route('/')
def index():
    return '<h1>Hello World!</h1>'

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

松鼠如果你已经从GitHub上克隆了这个程序的Git仓库,那么可以执行git checkout 2a签出程序的这个版本。

要想运行这个程序,请确保激活了你之前创建的虚拟环境,并在其中安装了Flask。现在打开Web浏览器,在地址栏中输入http://127.0.0.1:5000/。图2-1是浏览器连接到程序后的示意图。

图 2-1

图2-1 hello.py Flask程序

然后使用下述命令启动程序:

(venv) $ python hello.py
 * Running on http://127.0.0.1:5000/
 * Restarting with reloader

如果你输入其他地址,程序将不知道如何处理,因此会向浏览器返回错误代码404。访问不存在的网页时,你也会经常看到这个熟悉的错误。

示例2-2是这个程序的增强版,添加了一个动态路由。访问这个地址时,你会看到一则针对个人的欢迎消息。

示例2-2 hello.py:包含动态路由的Flask程序

from flask import Flask
app = Flask(__name__)

@app.route('/')
def index():
    return '<h1>Hello World!</h1>'

@app.route('/user/<name>')
def user(name):
    return '<h1>Hello, %s!</h1>' % name

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

松鼠如果你已经从GitHub上克隆了这个程序的Git仓库,那么可以执行git checkout 2b签出程序的这个版本。

测试动态路由前,你要确保服务器正在运行中,然后访问http://localhost:5000/user/Dave。程序会显示一个使用name动态参数生成的欢迎消息。请尝试使用不同的名字,可以看到视图函数总是使用指定的名字生成响应。图2-2展示了一个示例。

图 2-2

图2-2 动态路由

2.5 请求-响应循环

现在你已经开发了一个简单的Flask程序,或许希望进一步了解Flask的工作方式。下面几节将介绍这个框架的一些设计理念。

2.5.1 程序和请求上下文

Flask从客户端收到请求时,要让视图函数能访问一些对象,这样才能处理请求。请求对象就是一个很好的例子,它封装了客户端发送的HTTP请求。

要想让视图函数能够访问请求对象,一个显而易见的方式是将其作为参数传入视图函数,不过这会导致程序中的每个视图函数都增加一个参数。除了访问请求对象,如果视图函数在处理请求时还要访问其他对象,情况会变得更糟。

为了避免大量可有可无的参数把视图函数弄得一团糟,Flask使用上下文临时把某些对象变为全局可访问。有了上下文,就可以写出下面的视图函数:

from flask import request

@app.route('/')
def index():
    user_agent = request.headers.get('User-Agent')
    return '<p>Your browser is %s</p>' % user_agent

注意在这个视图函数中我们如何把request当作全局变量使用。事实上,request不可能是全局变量。试想,在多线程服务器中,多个线程同时处理不同客户端发送的不同请求时,每个线程看到的request对象必然不同。Flask使用上下文让特定的变量在一个线程中全局可访问,与此同时却不会干扰其他线程。

鸟线程是可单独管理的最小指令集。进程经常使用多个活动线程,有时还会共享内存或文件句柄等资源。多线程Web服务器会创建一个线程池,再从线程池中选择一个线程用于处理接收到的请求。

在Flask中有两种上下文:程序上下文请求上下文。表2-1列出了这两种上下文提供的变量。

表2-1 Flask上下文全局变量

变量名

上下文

说明

current_app

程序上下文

当前激活程序的程序实例

g

程序上下文

处理请求时用作临时存储的对象。每次请求都会重设这个变量

request

请求上下文

请求对象,封装了客户端发出的HTTP请求中的内容

session

请求上下文

用户会话,用于存储请求之间需要“记住”的值的字典

Flask在分发请求之前激活(或推送)程序和请求上下文,请求处理完成后再将其删除。程序上下文被推送后,就可以在线程中使用current_appg变量。类似地,请求上下文被推送后,就可以使用requestsession变量。如果使用这些变量时我们没有激活程序上下文或请求上下文,就会导致错误。如果你不知道为什么这4个上下文变量如此有用,先别担心,后面的章节会详细说明。

下面这个Python shell会话演示了程序上下文的使用方法:

>>> from hello import app
>>> from flask import current_app
>>> current_app.name
Traceback (most recent call last):
...
RuntimeError: working outside of application context
>>> app_ctx = app.app_context()
>>> app_ctx.push()
>>> current_app.name
'hello'
>>> app_ctx.pop()

在这个例子中,没激活程序上下文之前就调用current_app.name会导致错误,但推送完上下文之后就可以调用了。注意,在程序实例上调用app.app_context()可获得一个程序上下文。

2.5.2 请求调度

程序收到客户端发来的请求时,要找到处理该请求的视图函数。为了完成这个任务,Flask会在程序的URL映射中查找请求的URL。URL映射是URL和视图函数之间的对应关系。Flask使用app.route修饰器或者非修饰器形式的app.add_url_rule()生成映射。

要想查看Flask程序中的URL映射是什么样子,我们可以在Python shell中检查为hello.py生成的映射。测试之前,请确保你激活了虚拟环境:

(venv) $ python
>>> from hello import app
>>> app.url_map
Map([<Rule '/' (HEAD, OPTIONS, GET) -> index>,
 <Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>,
 <Rule '/user/<name>' (HEAD, OPTIONS, GET) -> user>])

//user/<name>路由在程序中使用app.route修饰器定义。/static/<filename>路由是Flask添加的特殊路由,用于访问静态文件。第3章会详细介绍静态文件。

URL映射中的HEADOptionsGET请求方法,由路由进行处理。Flask为每个路由都指定了请求方法,这样不同的请求方法发送到相同的URL上时,会使用不同的视图函数进行处理。HEADOPTIONS方法由Flask自动处理,因此可以这么说,在这个程序中,URL映射中的3个路由都使用GET方法。第4章会介绍如何为路由指定不同的请求方法。

2.5.3 请求钩子

有时在处理请求之前或之后执行代码会很有用。例如,在请求开始时,我们可能需要创建数据库连接或者认证发起请求的用户。为了避免在每个视图函数中都使用重复的代码,Flask提供了注册通用函数的功能,注册的函数可在请求被分发到视图函数之前或之后调用。

请求钩子使用修饰器实现。Flask支持以下4种钩子。

  • before_first_request:注册一个函数,在处理第一个请求之前运行。
  • before_request:注册一个函数,在每次请求之前运行。
  • after_request:注册一个函数,如果没有未处理的异常抛出,在每次请求之后运行。
  • teardown_request:注册一个函数,即使有未处理的异常抛出,也在每次请求之后运行。

在请求钩子函数和视图函数之间共享数据一般使用上下文全局变量g。例如,before_request处理程序可以从数据库中加载已登录用户,并将其保存到g.user中。随后调用视图函数时,视图函数再使用g.user获取用户。

请求钩子的用法会在后续章中介绍,如果你现在不太理解,也不用担心。

2.5.4 响应

Flask调用视图函数后,会将其返回值作为响应的内容。大多数情况下,响应就是一个简单的字符串,作为HTML页面回送客户端。

但HTTP协议需要的不仅是作为请求响应的字符串。HTTP响应中一个很重要的部分是状态码,Flask默认设为200,这个代码表明请求已经被成功处理。

如果视图函数返回的响应需要使用不同的状态码,那么可以把数字代码作为第二个返回值,添加到响应文本之后。例如,下述视图函数返回一个400状态码,表示请求无效:

@app.route('/')
def index():
    return '<h1>Bad Request</h1>', 400

视图函数返回的响应还可接受第三个参数,这是一个由首部(header)组成的字典,可以添加到HTTP响应中。一般情况下并不需要这么做,不过你会在第14章看到一个例子。

如果不想返回由1个、2个或3个值组成的元组,Flask视图函数还可以返回Response对象。make_response()函数可接受1个、2个或3个参数(和视图函数的返回值一样),并返回一个Response对象。有时我们需要在视图函数中进行这种转换,然后在响应对象上调用各种方法,进一步设置响应。下例创建了一个响应对象,然后设置了cookie:

from flask import make_response

@app.route('/')
def index():
    response = make_response('<h1>This document carries a cookie!</h1>')
    response.set_cookie('answer', '42')
    return response

有一种名为重定向的特殊响应类型。这种响应没有页面文档,只告诉浏览器一个新地址用以加载新页面。重定向经常在Web表单中使用,第4章会进行介绍。

重定向经常使用302状态码表示,指向的地址由Location首部提供。重定向响应可以使用3个值形式的返回值生成,也可在Response对象中设定。不过,由于使用频繁,Flask提供了redirect()辅助函数,用于生成这种响应:

from flask import redirect

@app.route('/')
def index():
    return redirect('http://www.example.com')

还有一种特殊的响应由abort函数生成,用于处理错误。在下面这个例子中,如果URL中动态参数id对应的用户不存在,就返回状态码404:

from flask import abort

@app.route('/user/<id>')
def get_user(id):
    user = load_user(id)
    if not user:
        abort(404)
    return '<h1>Hello, %s</h1>' % user.name

注意,abort不会把控制权交还给调用它的函数,而是抛出异常把控制权交给Web服务器。

2.6 Flask扩展

Flask被设计为可扩展形式,故而没有提供一些重要的功能,例如数据库和用户认证,所以开发者可以自由选择最适合程序的包,或者按需求自行开发。

社区成员开发了大量不同用途的扩展,如果这还不能满足需求,你还可使用所有Python标准包或代码库。为了让你知道如何把扩展整合到程序中,接下来我们将在hello.py中添加一个扩展,使用命令行参数增强程序的功能。

2.6.1 使用Flask-Script支持命令行选项

Flask的开发Web服务器支持很多启动设置选项,但只能在脚本中作为参数传给app.run()函数。这种方式并不十分方便,传递设置选项的理想方式是使用命令行参数。

Flask-Script是一个Flask扩展,为Flask程序添加了一个命令行解析器。Flask-Script自带了一组常用选项,而且还支持自定义命令。

Flask-Script扩展使用pip安装:

(venv) $ pip install flask-script

示例2-3显示了把命令行解析功能添加到hello.py程序中时需要修改的地方。

示例2-3 hello.py:使用Flask-Script

from flask.ext.script import Manager
manager = Manager(app)

# ...

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

专为Flask开发的扩展都包含在flask.ext命名空间下。Flask-Script输出了一个名为Manager的类,可从flask.ext.script中引入。

这个扩展的初始化方法也适用于其他很多扩展:把程序实例作为参数传给构造函数,初始化主类的实例。创建的对象可以在各个扩展中使用。在这里,服务器由manager.run()启动,启动后就能解析命令行了。

松鼠如果你从GitHub上克隆了这个程序的Git仓库,那么可以执行git checkout 2c签出程序的这个版本。

这样修改之后,程序可以使用一组基本命令行选项。现在运行hello.py,会显示一个用法消息:

$ python hello.py
usage: hello.py [-h] {shell,runserver} ...

positional arguments:
  {shell,runserver}
    shell            在Flask应用上下文中运行Python shell
    runserver        运行Flask开发服务器:app.run()

optional arguments:
  -h, --help         显示帮助信息并退出

shell命令用于在程序的上下文中启动Python shell会话。你可以使用这个会话中运行维护任务或测试,还可调试异常。

顾名思义,runserver命令用来启动Web服务器。运行python hello.py runserver将以调试模式启动Web服务器,但是我们还有很多选项可用:

(venv) $ python hello.py runserver --help
usage: hello.py runserver [-h] [-t HOST] [-p PORT] [--threaded]
                           [--processes PROCESSES] [--passthrough-errors] [-d]
                           [-r]

运行Flask开发服务器:app.run()

optional arguments:
  -h, --help            显示帮助信息并退出
  -t HOST, --host HOST
  -p PORT, --port PORT
  --threaded
  --processes PROCESSES
  --passthrough-errors
  -d, --no-debug
  -r, --no-reload

--host参数是个很有用的选项,它告诉Web服务器在哪个网络接口上监听来自客户端的连接。默认情况下,Flask开发Web服务器监听localhost上的连接,所以只接受来自服务器所在计算机发起的连接。下述命令让Web服务器监听公共网络接口上的连接,允许同网中的其他计算机连接服务器:

(venv) $ python hello.py runserver --host 0.0.0.0
 * Running on http://0.0.0.0:5000/
 * Restarting with reloader

现在,Web服务器可使用http://a.b.c.d:5000/网络中的任一台电脑进行访问,其中“a.b.c.d”是服务器所在计算机的外网IP地址。

本章介绍了请求响应的概念,不过响应的知识还有很多。对于使用模板生成响应,Flask提供了良好支持,这是个很重要的话题,下一章我们还要专门介绍模板。

目录

  • 版权声明
  • O'Reilly Media, Inc.介绍
  • 前言
  • 第一部分 Flask简介
  • 第 1 章 安装
  • 第 2 章 程序的基本结构
  • 第 3 章 模板
  • 第 4 章 Web表单
  • 第 5 章 数据库
  • 第 6 章 电子邮件
  • 第 7 章 大型程序的结构
  • 第二部分 实例:社会化博客程序
  • 第 8 章 用户认证
  • 第 9 章 用户角色
  • 第 10 章 用户资料
  • 第 11 章 博客文章
  • 第 12 章 关注者
  • 第 13 章 用户评论
  • 第 14 章 应用编程接口
  • 第三部分 成功在望
  • 第 15 章 测试
  • 第 16 章 性能
  • 第 17 章 部署
  • 第 18 章 其他资源
  • 关于封面图