Flask扩展库 | Flask-WTF学习

我不是女神ヾ 2022-04-14 05:11 535阅读 0赞

Flask-WTF是Flask与WTForms的简单集成，是Flask的一个扩展库，实现的功能如下：

1.  集成了WTForms；
2.  使用CSRF token保护表单（防止CSRF）；
3.  全球CSRF保护；
4.  支持reCAPTCHA（验证码）；
5.  使用Flask-Uploads支持文件上传；
6.  使用Flask-Babel提供国际化。

CSRF：Cross-Site Request Forgery简写，跨站请求伪造。Flask-WTF封装了防止CSRF功能。原理可参考[博客][Link 1]。  
WTForms：是一个用于Python Web开发的提供灵活的表单验证和渲染的库。  
表单：在网页中主要负责数据采集功能。一个表单有3个基本组成部分（表单标签、表单域、表单按钮）。

flask\_wtf源码 目录结构：

├── _compat.py
    ├── csrf.py             ----防止CSRF
    ├── file.py             ----文件上传
    ├── form.py             ----表单
    ├── html5.py
    ├── i18n.py             ----国际化
    ├── __init__.py
    └── recaptcha           ----验证码
        ├── fields.py
        ├── __init__.py
        ├── validators.py
        └── widgets.py

# 1、安装 #

不作过多讲述  
像其他Flask扩展一样，安装时名称是`flask-wtf`，`import`时是`flask_wtf`，注意横线、下划线，这是惯例。

# 2、表单 #

创建表单主要是3方面：

1.  安全表单
2.  文件上传（表单）
3.  reCAPTCHA（表单）

## 2.1、安全表单 ##

### 2.1.1、创建表单 ###

from flask_wtf import FlaskForm # 从flask_wtf包中的__init__.py导入这个FlaskForm类，来自forms.py模块
    from wtforms import StringField # 从wtforms包导入StringField类
    from wtforms.validatiors import DataRequired
    
    class MyForm(FlaskForm):
    	name = StringField('name', validators=[DataRequired()])

注意：从flask-wtf 0.9.0开始，Flask-WTF不再从wtforms import任何内容，因此必须开发者自己从wtforms去导入（如StringField等）  
另外，CSRF token 会被自动创建，我们可以在模板中渲染它：

<form method="POST" action="/">
    	{
       { form.csrf_token }}
    	{
       { form.name.label }} {
       { form.name(size=20) }}
    	<input type="submit" value="Go">
    </form>

假如在表单中有多个隐藏字段（？？），可在块中使用hidden\_tag()：

<form method="POST" action="/">
    	{
       { form.hidden_tag() }}
    	{
       { form.name.label }} {
       { form.name(size=20) }}
    </form>

默认情况下：  
FlaskForm就是一个具有CSRF保护的session安全表单了。如果不想CSRF保护，可传入：

form = FlaskForm(csrf_enabled=False)

也可以在全局上配置它，但不建议这么做：

WTF_CSRF_ENABLED = False

为了生成csrf token，我们必须有一个secret key，通常它与我们的Flask app的secret key是相同的。但是若想设置一个不同的，也可以：

WTF_CSRF_SECRET_KEY = ' a random string'

### 2.1.2、验证表单 ###

在view handler中验证请求：

@app.route('/submit', methods=('GET', 'POST'))
    def submit():
    	form = MyForm()
    	if form.validate_on_submit():
    		return redirect('/success')
    	return render_template('submit.html', form=form)

注意：我们不必将`request.form`传递给Flask-WTF，因为它将自动load；便捷的是`validate_on_submit`将检查它是否为一个POST请求、以及是否有效。

## 2.2、文件上传 ##

### 2.2.1、创建文件上传表单 ###

Flask-WTF提供的FileField类 不同于WTForms提供的。它会检查文件是一个FileStorage的非空实例，另外data将是None。

from flask_wtf import FlaskForm
    from flask_wtf.file import FileField, FileRequired
    from werkzeug.utils import secure_filename
    
    class PhotoForm(FlaskForm):
    	photo = FileField(validators=[FileRequired()])
    
    @app.route('/upload', methods=['GET', 'POST'])
    def unpload():
    	if form.validate_on_submit():
    		f = form.photo.data
    		filename = secure_filename(f.filename)
    		f.save(os.path.join(
    			app.instance_path, 'photos', filename
    		))
    		return redirect(url_for('index'))
    	return render_template('upload.html', form=form)

记得将HTML模板 form标签的`enctype`设置为`multipart/form-data`，另外`request.files`为空：

Flask-WTF handler将会为我们将form data传递给表单。如果想在data中显式地传递，记得`request.form`必须结合`request.files`，这样让表单看到file data。

form = PhotoForm()
    
    # 等价于
    from flask import request
    from werkzeug.datastructures import CombinedMultiDict
    form = PhotoForm(CombinedMultiDict((request.files, request.form)))

### 2.2.2、验证表单 ###

Flask-WTF通过`FileRequired`和`FileAllowed`验证文件上传。他它们使用Flask-WTF和WTForms的`FileField`类都行。`FileAllowed`将和Flask-Uploads一起工作。

from flask_uploads import UploadSet, IMAGES
    from flask_wtf import FlaskForm
    from flask_wtf.file import FileField, FileAllowed, FileRequired
    
    images = UploadSet('images', IMAGES)
    
    class UploadForm(FlaskForm):
    	upload = FileField('image', validators=[
    		FileRequired(), FileAllowed(images, 'Images only!')
    	])

也可以直接通过传递扩展名，而不使用Flask-Uploads：

class UploadForm(FlaskForm):
        upload = FileField('image', validators=[
            FileRequired(),
            FileAllowed(['jpg', 'png'], 'Images only!')
        ])

## 2.3、reCAPTCHA（验证码） ##

Flask-WTF 通过`RecaptchaField`提供了reCAPTCHA：

from flask_wtf import FlaskForm, RecaptchaField
    from wtforms import TextField
    
    class SignupForm(FlaskForm):
    	username = TextField('Username')
    	recaptcha = RecaptchaField()

下方提供了一些配置，得实现它们：

<table> 
 <thead> 
  <tr> 
   <th></th> 
   <th></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>RECAPTCHA_PUBLIC_KEY</code></td> 
   <td>required A public key.</td> 
  </tr> 
  <tr> 
   <td><code>RECAPTCHA_PRIVATE_KEY</code></td> 
   <td>required A private key.</td> 
  </tr> 
  <tr> 
   <td><code>RECAPTCHA_API_SERVER</code></td> 
   <td>optional Specify your Recaptcha API server.</td> 
  </tr> 
  <tr> 
   <td><code>RECAPTCHA_PARAMETERS</code></td> 
   <td>optional A dict of JavaScript (api.js) parameters.</td> 
  </tr> 
  <tr> 
   <td><code>RECAPTCHA_DATA_ATTRS</code></td> 
   <td>optional A dict of data attributes options. <a href="https://developers.google.com/recaptcha/docs/display" rel="nofollow">https://developers.google.com/recaptcha/docs/display</a></td> 
  </tr> 
 </tbody> 
</table>

以下是`RECAPTCHA_PARAMETERS`和`RECAPTCHA_DATA_ATTRS`的示例：

RECAPTCHA_PARAMETERS = { 'hl': 'zh', 'render': 'explicit'}
    RECAPTCHA_DATA_ATTRS = { 'theme': 'dark'}

为了测试应用程序，假如`app.testing`为`True`，recaptcha字段必须总是有效。  
它可以在模板中很容易地设置：

<form action="/" method="post">
        {
       { form.username }}
        {
       { form.recaptcha }}
    </form>

## 3、CSRF保护 ##

任何使用FlaskForm来处理请求的视图都已经得到CSRF的保护。如果我们有不使用FlaskForm 或创建Ajax请求的视图，也可以使用所提供的CSRF扩展来保护这些请求的。

### 3.1、setup ###

若要对一个Flask应用程序全局提供CSRF保护，可注册`CSRFProtect`扩展。如下：

from flask_wtf.csrf import CSRFProject
    
    csrf = CSRFProtect(app)

也可以像其他Flask扩展一样，这样使用：

csrf = CSRFProject()
    
    def create_app():
    	app = Flask(__name__)
    	csrf.init_app(app)

**注意：**CSRF保护需要一个密钥来安全地签名token。默认情况下，它会使用Flask应用程序的`SECRET_KEY`。当然也可以单独地设置`WTF_CSRF_SECRET_KEY`。

### 3.2、HTML Forms ###

当在使用一个FlaskForm时，可以像正常一样渲染表单的CSRF字段：

<form method="post">
    	{
       { form.csrf_token }}
    </form>

如果模板没有使用FlaskForm，可以这样在表单中渲染一个带有token的隐藏输入：

### 3.3、JavaScript Requests ###

当发送一个AJAX请求时，可以添加X-CSRFToken header给它。例如，在jQuery中，可以配置所有请求去发送这个token：

### 3.4、自定义错误响应 ###

当CSRF验证失败时，将引发CSRFError异常。默认情况下，会返回一个有失败原因和400状态码的响应。我们也可以使用Flask的`errorhandler()`来自定义错误响应：

from flask_wtf.csrf import CSRFError
    
    @app.errorhandler(CSRFError)
    def handle_csrf_error(e):
        return render_template('csrf_error.html', reason=e.description), 400

### 3.5、给某些视图取消CSRF保护 ###

强烈建议给所有视图使用CSRF保护。但是，也可以使用装饰器排除一些视图：

@app.route('/foo', methods=('GET', 'POST'))
    @csrf.exempt
    def my_handler():
        # ...
        return 'ok'

也可以取消蓝图下的所有视图 保护：

csrf.exempt(account_blueprint)

也可以通过默认方式在所有视图里设置CSRF保护为不可用，即 WTF\_CSRF\_CHECK\_DEFAULT=False。也可以在需要时，选择调用`protect()`。还可以在检查CSRF token前对请求进行一些预处理：

@app.before_request
    def check_csrf():
        if not is_oauth(request):
            csrf.protect()

[开发者API][API]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODI1NjQ3NA_size_16_color_FFFFFF_t_70]

参考文档：  
1、[官方][Link 2]  
2、[github][] 包含所有历史版本的源码  
3、[WTForms官网][WTForms]  
4、[WTForm github源码][WTForm github]  
5、[官方实例][Link 3]  
6、[开发者接口][API]\----其实就是源码

附：WTForms 思维导图（其中最常用的）  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODI1NjQ3NA_size_16_color_FFFFFF_t_70 1]

[Link 1]: https://www.cnblogs.com/Erik_Xu/p/5481441.html
[API]: https://flask-wtf.readthedocs.io/en/stable/api.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODI1NjQ3NA_size_16_color_FFFFFF_t_70]: /images/20220414/07129778e8274df2b48fa8b12c93af53.png
[Link 2]: https://flask-wtf.readthedocs.io/en/stable/
[github]: https://github.com/lepture/flask-wtf
[WTForms]: https://wtforms.readthedocs.io/en/stable/#
[WTForm github]: https://github.com/wtforms/wtforms/
[Link 3]: https://github.com/lepture/flask-wtf/tree/master/examples
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODI1NjQ3NA_size_16_color_FFFFFF_t_70 1]: /images/20220414/be90461aad25457ab53b0eae4f1bece6.png