Flak快速上手

本文介绍如何上手 Flask 。 这里假定你已经安装好了 Flask ，否则请先阅读《 安装》。

如果已安装好Flask，通过以下命令查看

一个简单的例子：

from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello World!'

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

把它保存为 hello.py ，然后用 Python 解释器来运行。 不能保存为 flask.py ，因为这与 Flask 本身冲突。

$ python hello.py
 * Running on http://127.0.0.1:5000/

现在访问 http://127.0.0.1:5000/ ，你会看见 Hello World 问候。

那么，这段代码是什么意思呢？

1. 首先，导入了 Flask 类。这个类的实例将会成为我们的 WSGI 应用程序。
2. 接下来，我们创建一个该类的实例，第一个参数是应用模块或者包的名称。 如果使用单一的模块（如本例），应该使用 __name__，因为模块的名称 作为单独应用启动还是作为模块导入是不同的（ 也即是 '__main__' 或实际的导入名）。这个参数是必须的，这样 Flask 才知道到哪去找模板、静态文件等等。详情见 Flask 的文档。
3. 然后，我们使用 route() 装饰器告诉 Flask 哪些URL能触发我们的函数。
4. 这个函数的名字也在生成 URL 时被特定的函数采用，函数返回想在浏览器中显示的信息。
5. 最后我们用 run() 函数让应用运行在本地服务器上。 其中 if __name__ == '__main__': 确保服务器只会在该脚本被 Python 解释器直接执行的时候才会运行，而不是作为模块导入的时候。

想要关闭服务器，按 Ctrl+C。

外部可访问的服务器

如果你运行了这个服务器，你会发现它只能从你自己的计算机上访问，网络中其它任何的地方都不能访问。在调试模式下，用户可以在你的计算机上执行任意 Python 代码。因此，这个行为是默认的。

如果你禁用了 debug 或信任你所在网络的用户，你可以简单修改调用 run() 的方法使你的服务器公开可用，如下:

app.run(host='0.0.0.0')

这会让操作系统监听所有公网 IP。

调试模式

run() 方法适用于启动本地的开发服务器，但是每次修改代码后都要手动重启它。这样并不够优雅，如果你启用了调试模式，服务器会在代码修改后自动重新载入，并在发生错误时提供一个相当有用的调试器。

有两种途径来启用调试模式。一种是直接在应用对象上设置:

app.debug = True
app.run()

另一种是作为 run 方法的一个参数传入:

app.run(debug=True)

注意：调试器允许执行任意代码。这是一个巨大的安全隐患，因此调试模式 绝对不能用于生产环境 。

路由

现代 web 应用都使用有意义的 URL ，这样有助于用户记忆，提高回头率。

使用 route() 装饰器来把一个函数绑定到对应的 URL 上。

例如:

@app.route('/')
def index():
    return 'Index Page'

@app.route('/hello')
def hello():
    return 'Hello World'

但是能做的不仅仅是这些！你可以动态变化 URL 的某些部分， 还可以为一个函数指定多个规则。

变量规则

　　要给 URL 添加变量部分，你可以把这些特殊的字段标记为 <variable_name> ， 这个部分将会作为命名参数传递到你的函数。规则可以用 <converter:variable_name> 指定一个可选的转换器。这里有一些不错的例子:

　　通过把 URL 的一部分标记为  <variable_name>  就可以 在 URL 中添加变量，标记的部分会作为关键字参数传递给函数。

　　通过使用 <converter:variable_name>   可以 添加一个可选的转换器，为变量指定规则。

例如:

@app.route('/user/<username>')
def show_user_profile(username):
    # show the user profile for that user
    return 'User %s' % username

@app.route('/post/<int:post_id>')
def show_post(post_id):
    # show the post with the given id, the id is an integer
    return 'Post %d' % post_id

@app.route('/path/<path:subpath>')
def show_subpath(subpath):
    # show the subpath after /path/
    return 'Subpath %s' % subpath

post/英文会报错

转换器类型：

string	（缺省值） 接受任何不包含斜杠的文本
int	接受正整数
float	接受正浮点数
path	类似 string ，但可以包含斜杠
uuid	接受 UUID 字符串

唯一 URL / 重定向行为

　　Flask 的 URL 规则基于 Werkzeug 的路由模块。这个模块背后的思想是基于 Apache 以及更早的 HTTP 服务器主张的先例，保证优雅且唯一的 URL。

　　以下两条规则的不同点是否使用尾部的斜杠

@app.route('/projects/')
def projects():
    return 'The project page'

@app.route('/about')
def about():
    return 'The about page'

projects 的尾部有一个斜杠，看起来就像一个文件夹。 访问一个没有斜杠结尾的 URL 时 Flask 会自动进行重定向，帮你在尾部加上一个斜杠。

http://127.0.0.1:5000/projects =>  http://127.0.0.1:5000/projects/ 

about 的URL尾部没有斜杠，因此其行为表现与一个文件类似。如果访问这个 URL 时添加了尾部斜杠就会得到一个 404 错误。这样可以保持 URL 唯一，并帮助 搜索引擎避免重复索引同一页面。

构建 URL

   url_for() 本质是根据函数名反向生成url。它把函数名称作为第一个 参数。它可以接受任意个关键字参数，每个关键字参数对应 URL 中的变量。未知变量 将添加到 URL 中作为查询参数。

　　一般我们通过一个URL就可以执行到某一个函数。如果反过来，我们知道一个函数，怎么去获得这个URL呢？url_for函数就可以帮我们实现这个功能。

　　url_for()函数接收两个及以上的参数，他接收函数名作为第一个参数，接收对应URL规则的命名参数，如果还出现其他的参数，则会添加到URL的后面作为查询参数。

通过构建URL的方式而选择直接在代码中拼URL的原因有两点：

1. 将来如果修改了URL，但没有修改该URL对应的函数名，就不用到处去替换URL了。
2. url_for()函数会转义特殊字符和Unocode数据，这些工作都不需要我们自己处理。

　　这里我们使用 test_request_context() 方法来尝试使用 url_for() 。 test_request_context() 告诉 Flask 正在处理一个请求，而实际上也许我们正处在交互 Python shell 之中， 并没有真正的请求。参见 本地环境 。

from flask import Flask, url_for
app = Flask(__name__)

@app.route('/')
def index():
    return 'index'

@app.route('/login')
def login():
    return 'login'

@app.route('/user/<username>')
def profile(username):
    return '{}\'s profile'.format(username)

with app.test_request_context():
    print(url_for('index'))
    print(url_for('login'))
    print(url_for('login', next='/'))
    print(url_for('profile', username='John Doe'))

打印结果：

/
/login
/login?next=/
/user/John%20Doe

HTTP 方法

　　HTTP 协议有多种方式处理 URL。默认情况下，路由只回应 GET 请求，但是通过 route() 装饰器传递 methods 参数可以处理不同的HTTP请求，比如POST。　　

from flask import Flask, request
app = Flask(__name__)

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        return do_the_login()
    else:
        return show_the_login_form()

如果存在 GET ，那么Flask也会替你自动地添加 HEAD，所以你可以完全忽略这部分的 HTTP 规范。同样，OPTIONS也会自动实现。

HTTP 方法（也经常被叫做“谓词”）告知服务器，客户端想对请求的页面 做 些什么。下面的都是非常常见的方法：

GET
    浏览器告知服务器：只 获取 页面上的信息并发给我。这是最常用的方法。
HEAD
    浏览器告诉服务器：欲获取信息，但是只关心 消息头 。应用应像处理 GET 请求一样来处理它，但是不分发实际内容。在 Flask 中你完全无需 人工 干预，底层的 Werkzeug 库已经替你打点好了。
POST
    浏览器告诉服务器：想在 URL 上 发布 新信息。并且，服务器必须确保 数据已存储且仅存储一次。这是 HTML 表单通常发送数据到服务器的方法。
PUT
    类似 POST 但是服务器可能触发了存储过程多次，多次覆盖掉旧值。你可 能会问这有什么用，当然这是有原因的。考虑到传输中连接可能会丢失，在 这种 情况下浏览器和服务器之间的系统可能安全地第二次接收请求，而 不破坏其它东西。因为 POST 它只触发一次，所以用 POST 是不可能的。
DELETE
    删除给定位置的信息。
OPTIONS
    给客户端提供一个敏捷的途径来弄清这个 URL 支持哪些 HTTP 方法。 从 Flask 0.6 开始，实现了自动处理。 

HTTP 方法

静态文件

　　动态 web 应用也需要静态文件，通常是 CSS 和 JavaScript 文件。理想状况下， Web 服务器已经配置好了服务来提供静态文件。但是在开发中，Flask 也可以做到。

　　只要在你的包中或是模块的所在目录中创建一个名为 static 的文件夹，在应用中使用 /static 即可访问静态文件。

　　给静态文件生成 URL ，使用特殊的 'static' 端点名:

url_for('static', filename='style.css')

　　这个静态文件在文件系统中的位置应该是 static/style.css

渲染模板

　　用 Python 生成 HTML 十分无趣，且相当繁琐，因为你必须手动转义 HTML 来保证应用的安全。为此，Flask 配备了 Jinja2 模板引擎。

　　使用 render_template() 方法来渲染模板，只要提供模板名和想作为参数传递给模板的变量就行了。

from flask import render_template

@app.route('/hello/')
@app.route('/hello/<name>')
def hello(name=None):
    return render_template('hello.html', name=name)

　　Flask 会在 templates 文件夹内寻找模板。如果你的应用是一个模块， 模板文件夹应该在模块旁边；如果是一个包，那么就应该在包里面：

情形 1 : 一个模块:

/application.py
/templates
    /hello.html

情形 2 : 一个包:

/application
    /__init__.py
    /templates
        /hello.html

模板示例：

<!doctype html>
<title>Hello from Flask</title>
{% if name %}
  <h1>Hello {{ name }}!</h1>
{% else %}
  <h1>Hello, World!</h1>
{% endif %}

　　在模板内部可以和访问 get_flashed_messages() 函数一样访问 request 、 session 和 g 对象。

　　（g 对象，它是某个可以根据需要储存信息的 东西。更多信息参见 g 对象的文档和 使用 SQLite 3 文档。）

　　模板在继承使用的情况下尤其有用。其工作原理参见 模板继承 方案文档。

　　简单的说，模板继承可以使每个页面的特定元素（如页头、导航和页尾） 保持一致。

　　自动转义默认开启。因此，如果 name 包含 HTML ，那么会被自动转义。如果你可以 信任某个变量，且知道它是安全的 HTML （例如变量来自一个把 wiki 标记转换为 HTML 的模块），那么可以使用 Markup 类或|safe 过滤器把它标记为安全的。更多例子参见 Jinja 2 文档。

>>> from flask import Markup
>>> Markup('<strong>Hello %s!</strong>') % '<blink>hacker</blink>'
Markup(u'<strong>Hello &lt;blink&gt;hacker&lt;/blink&gt;!</strong>')
>>> Markup.escape('<blink>hacker</blink>')
Markup(u'&lt;blink&gt;hacker&lt;/blink&gt;')
>>> Markup('<em>Marked up</em> &raquo; HTML').striptags()
u'Marked up \xbb HTML'

操作请求数据

　　对于 web 应用来说对客户端向服务器发送的数据作出响应很重要。在 Flask 中由全局 对象 request 来提供请求信息。如果你有一些 Python 基础，那么 可能 会奇怪：既然这个对象是全局的，怎么还能保持线程安全？答案是本地环境

请求对象

　　请求对象在 API 一节中有详细说明这里不细谈（参见 Request ）。 这里简略地谈一下最常见的操作。

　　首先，你必须从 flask 模块导入请求对象request:

from flask import request

　　通过使用 method 属性可以操作当前请求方法，通过 form 属性处理表单数据（在 POST 或者 PUT 请求 中传输的数据）。

@app.route('/login', methods=['POST', 'GET'])
def login():
    error = None
    if request.method == 'POST':
        if valid_login(request.form['username'],
                       request.form['password']):
            return log_the_user_in(request.form['username'])
        else:
            error = 'Invalid username/password'
    # the code below is executed if the request method
    # was GET or the credentials were invalid
    return render_template('login.html', error=error)

缺少演示

　　当 form 属性中不存在这个键时，会引发一个 KeyError 。 如果你不像捕捉一个标准错误一样捕捉 KeyError ，那么会显示一个 HTTP 400 Bad Request 错误页面。因此，多数情况下你不必处理这个问题。

　　要操作 URL （如 ?key=value ）中提交的参数可以使用 args 属性:

searchword = request.args.get('key', '')

　　用户可能会改变 URL 导致出现一个 400 请求出错页面，这样降低了用户友好度。因此， 我们推荐使用 get 或通过捕捉 KeyError 来访问 URL 参数。

　　完整的请求对象方法和属性参见 Request文档。

文件上传

　　用 Flask 处理文件上传很容易，只要确保 HTML 表单中设置了  enctype="multipart/form-data"  属性就可行。否则浏览器将不会传送你的文件。

　　已上传的文件被储存在内存或文件系统的临时位置。可以通过请求对象的 files 属性来访问上传的文件。每个上传的文件都储存在这个 字典型属性中。这个属性基本和标准 Python file 对象一样，另外多出一个 用于把上传文件保存到服务器的文件系统中的 save() 方法。

from flask import request

@app.route('/upload', methods=['GET', 'POST'])
def upload_file():
    if request.method == 'POST':
        f = request.files['the_file']
        f.save('/var/www/uploads/uploaded_file.txt')
    ...

　　如果想知道上传前文件在客户端的名称，你可以使用 filename 属性。但请记住， 永远不要信任这个值，这个值是可以伪造的。如果想要把客户端的文件名作为服务器上的文件名， 可以通过 Werkzeug 提供的secure_filename() 函数:

from flask import request
from werkzeug.utils import secure_filename

@app.route('/upload', methods=['GET', 'POST'])
def upload_file():
    if request.method == 'POST':
        f = request.files['the_file']
        f.save('/var/www/uploads/' + secure_filename(f.filename))
    ...

更好的例子参见 上传文件 方案。

Cookies

　　要访问 cookies ，可以使用 cookies 属性。可以使用响应 对象 的 set_cookie 方法来设置 cookies 。请求对象的 cookies 属性是一个包含了客户端传输的所有 cookies 的字典。

　　在 Flask 中，如果使用 会话 ，那么就不要直接使用 cookies ，因为 会话 比较安全一些。

读取 cookies:

from flask import request

@app.route('/')
def index():
    username = request.cookies.get('username')
    # use cookies.get(key) instead of cookies[key] to not get a
    # KeyError if the cookie is missing.

储存 cookies:

from flask import make_response

@app.route('/')
def index():
    resp = make_response(render_template(...))
    resp.set_cookie('username', 'the username')
    return resp

　　注意， cookies 设置在响应对象上。通常只是从视图函数返回字符串， Flask 会把它们 转换为响应对象。如果你想显式地转换，那么可以使用 make_response() 函数，然后再修改它。

　　使用 延迟的请求回调 方案可以在没有响应对象的情况下设置一个 cookie 。

　　同时可以参见 关于响应 。

重定向和错误

　　使用 redirect() 函数可以重定向。使用 abort() 可以 更早退出请求，并返回错误代码:

from flask import abort, redirect, url_for

@app.route('/')
def index():
    return redirect(url_for('login'))

@app.route('/login')
def login():
    abort(401)
    this_is_never_executed()

　　上例实际上是没有意义的，它让一个用户从索引页重定向到一个无法访问的页面（401 表示禁止访问）。但是上例可以说明重定向和出错跳出是如何工作的。

　　缺省情况下每种出错代码都会对应显示一个黑白的出错页面。使用 errorhandler() 装饰器可以定制出错页面:

from flask import render_template

@app.errorhandler(404)
def page_not_found(error):
    return render_template('page_not_found.html'), 404

　　注意 render_template() 后面的 404 ，这表示页面对就的出错 代码是 404 ，即页面不存在。缺省情况下 200 表示：一切正常。

　　详见 错误处理 。

关于响应

　　视图函数的返回值会自动转换为一个响应对象。如果返回值是一个字符串，那么会被转换 为一个包含作为响应体的字符串、一个 200 OK 出错代码 和一个 text/html 类型的响应对象。以下是转换的规则：

1. 如果视图返回的是一个响应对象，那么就直接返回它。
2. 如果返回的是一个字符串，那么根据这个字符串和缺省参数生成一个用于返回的 响应对象。
3. 如果返回的是一个元组，那么元组中的项目可以提供额外的信息。元组中必须至少 包含一个项目，且项目应当由 (response, status, headers) 或者 (response, headers) 组成。 status 的值会重载状态代码， headers 是一个由额外头部值组成的列表或字典。
4. 如果以上都不是，那么 Flask 会假定返回值是一个有效的 WSGI 应用并把它转换为 一个响应对象。

如果想要在视图内部掌控响应对象的结果，那么可以使用 make_response() 函数。

　　假如有如下视图:

@app.errorhandler(404)
def not_found(error):
    return render_template('error.html'), 404

　　可以使用 make_response() 包裹返回表达式，获得响应对象，并对该对象 进行修改，然后再返回:

@app.errorhandler(404)
def not_found(error):
    resp = make_response(render_template('error.html'), 404)
    resp.headers['X-Something'] = 'A value'
    return resp

会话

　　除了请求对象之外还有一种称为 session 的对象，允许你在不同请求 之间储存信息。这个对象相当于用密钥签名加密的 cookie ，即用户可以查看你的 cookie ，但是如果没有密钥就无法修改它。

　　使用会话之前你必须设置一个密钥。举例说明:

from flask import Flask, session, redirect, url_for, escape, request

app = Flask(__name__)

# Set the secret key to some random bytes. Keep this really secret!
app.secret_key = b'_5#y2L"F4Q8z\n\xec]/'

@app.route('/')
def index():
    if 'username' in session:
        return 'Logged in as %s' % escape(session['username'])
    return 'You are not logged in'

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        session['username'] = request.form['username']
        return redirect(url_for('index'))
    return '''
        <form method="post">
            <p><input type=text name=username>
            <p><input type=submit value=Login>
        </form>
    '''

@app.route('/logout')
def logout():
    # remove the username from the session if it's there
    session.pop('username', None)
    return redirect(url_for('index'))

　　这里用到的 escape() 是用来转义的。如果不使用模板引擎就可以像上例 一样使用这个函数来转义。

如何生成一个好的密钥

　　生成随机数的关键在于一个好的随机种子，因此一个好的密钥应当有足够的随机性。 操作系统可以有多种方式基于密码随机生成器来生成随机数据。使用下面的命令 可以快捷的为 Flask.secret_key （ 或者 SECRET_KEY ）生成值:

$ python -c 'import os; print(os.urandom(16))'
b'_5#y2L"F4Q8z\n\xec]/'

　　基于 cookie 的会话的说明： Flask 会取出会话对象中的值，把值序列化后储存到 cookie 中。在打开 cookie 的情况下，如果需要查找某个值，但是这个值在请求中 没有持续储存的话，那么不会得到一个清晰的出错信息。请检查页面响应中的 cookie 的大小是否与网络浏览器所支持的大小一致。

　　除了缺省的客户端会话之外，还有许多 Flask 扩展支持服务端会话。

消息闪现

　　一个好的应用和用户接口都有良好的反馈，否则到后来用户就会讨厌这个应用。 Flask 通过闪现系统来提供了一个易用的反馈方式。闪现系统的基本工作原理是在请求结束时 记录一个消息，提供且只提供给下一个请求使用。通常通过一个布局模板来展现闪现的 消息。

　　flash() 用于闪现一个消息。在模板中，使用 get_flashed_messages() 来操作消息。完整的例子参见 消息闪现 。

日志

　　有时候可能会遇到数据出错需要纠正的情况。例如因为用户篡改了数据或客户端代码出错 而导致一个客户端代码向服务器发送了明显错误的 HTTP 请求。多数时候在类似情况下 返回 400 Bad Request 就没事了，但也有不会返回的时候，而代码还得继续运行 下去。

　　这时候就需要使用日志来记录这些不正常的东西了。自从 Flask 0.3 后就已经为你配置好 了一个日志工具。

app.logger.debug('A value for debugging')
app.logger.warning('A warning occurred (%d apples)', 42)
app.logger.error('An error occurred')

　　logger 是一个标准的 Logger Logger 类， 更多信息详见官方的 logging 文档 。

　　更多内容请参阅 应用错误处理 。

集成 WSGI 中间件

　　如果想要在应用中添加一个 WSGI 中间件，那么可以包装内部的 WSGI 应用。假设为了 解决 lighttpd 的错误，你要使用一个来自 Werkzeug 包的中间件，那么可以这样做:

from werkzeug.contrib.fixers import LighttpdCGIRootFix
app.wsgi_app = LighttpdCGIRootFix(app.wsgi_app)

使用 Flask 扩展

　　扩展是帮助完成公共任务的包。例如 Flask-SQLAlchemy 为在 Flask 中轻松使用 SQLAlchemy 提供支持。

更多关于 Flask 扩展的内容请参阅 扩展 。

部署到网络服务器

　　已经准备好部署你的新 Flask 应用了？请移步 部署方式 。

参考

1. http://docs.jinkan.org/docs/flask/quickstart.html

2. https://dormousehole.readthedocs.io/en/latest/quickstart.html