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 问候。
那么,这段代码是什么意思呢?
- 首先,导入了 Flask 类。这个类的实例将会成为我们的 WSGI 应用程序。
- 接下来,我们创建一个该类的实例,第一个参数是应用模块或者包的名称。 如果使用单一的模块(如本例),应该使用 __name__,因为模块的名称 作为单独应用启动还是作为模块导入是不同的( 也即是 '__main__' 或实际的导入名)。这个参数是必须的,这样 Flask 才知道到哪去找模板、静态文件等等。详情见 Flask 的文档。
- 然后,我们使用 route() 装饰器告诉 Flask 哪些URL能触发我们的函数。
- 这个函数的名字也在生成 URL 时被特定的函数采用,函数返回想在浏览器中显示的信息。
- 最后我们用 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
的原因有两点:
- 将来如果修改了
URL
,但没有修改该URL
对应的函数名,就不用到处去替换URL
了。 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也会自动实现。
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
HTTP 方法(也经常被叫做“谓词”)告知服务器,客户端想对请求的页面 做 些什么。下面的都是非常常见的方法: GET 浏览器告知服务器:只 获取 页面上的信息并发给我。这是最常用的方法。 HEAD 浏览器告诉服务器:欲获取信息,但是只关心 消息头 。应用应像处理 GET 请求一样来处理它,但是不分发实际内容。在 Flask 中你完全无需 人工 干预,底层的 Werkzeug 库已经替你打点好了。 POST 浏览器告诉服务器:想在 URL 上 发布 新信息。并且,服务器必须确保 数据已存储且仅存储一次。这是 HTML 表单通常发送数据到服务器的方法。 PUT 类似 POST 但是服务器可能触发了存储过程多次,多次覆盖掉旧值。你可 能会问这有什么用,当然这是有原因的。考虑到传输中连接可能会丢失,在 这种 情况下浏览器和服务器之间的系统可能安全地第二次接收请求,而 不破坏其它东西。因为 POST 它只触发一次,所以用 POST 是不可能的。 DELETE 删除给定位置的信息。 OPTIONS 给客户端提供一个敏捷的途径来弄清这个 URL 支持哪些 HTTP 方法。 从 Flask 0.6 开始,实现了自动处理。
静态文件
动态 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 <blink>hacker</blink>!</strong>') >>> Markup.escape('<blink>hacker</blink>') Markup(u'<blink>hacker</blink>') >>> Markup('<em>Marked up</em> » 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 类型的响应对象。以下是转换的规则:
- 如果视图返回的是一个响应对象,那么就直接返回它。
- 如果返回的是一个字符串,那么根据这个字符串和缺省参数生成一个用于返回的 响应对象。
- 如果返回的是一个元组,那么元组中的项目可以提供额外的信息。元组中必须至少 包含一个项目,且项目应当由
(response, status, headers)
或者(response, headers)
组成。status
的值会重载状态代码,headers
是一个由额外头部值组成的列表或字典。 - 如果以上都不是,那么 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