🐍 Python Day53：表单处理 — 安全地接收用户输入

🕐 预计用时：2-3 小时 ｜ 🎯 目标：掌握 WTForms 表单处理、CSRF 防护和文件上传

📖 今日目录

1. Web 表单基础
2. Flask 处理原生表单
3. WTForms 入门
4. 常用字段类型
5. 验证器
6. CSRF 保护
7. 文件上传
8. 文件上传安全
9. 表单实战：注册表单
10. 今日练习
11. 今日小结

1. Web 表单基础

📝 表单是什么？

表单是用户向网站提交数据的方式。 登录、注册、搜索、评论、发帖——这些交互全靠表单。

<!-- 最基本的 HTML 表单 -->
<form action="/login" method="POST">
    <label>用户名：</label>
    <input type="text" name="username">

    <label>密码：</label>
    <input type="password" name="password">

    <button type="submit">登录</button>
</form>

📬 GET vs POST

💡 什么时候用 GET，什么时候用 POST？

• GET：获取数据，不改变服务器状态。如：搜索"Python"→ /search?q=Python
• POST：提交数据，会改变服务器状态。如：注册账号、发评论、下订单

简单记忆：看不改用 GET，改数据用 POST。

2. Flask 处理原生表单

📥 用 request 对象获取表单数据

from flask import Flask, request, render_template

app = Flask(__name__)

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        username = request.form.get('username')    # 获取表单字段
        password = request.form.get('password')    # 获取表单字段
        remember = request.form.get('remember')    # 复选框（on/None）

        # 简单验证
        if not username or not password:
            return '用户名和密码不能为空'

        if username == 'admin' and password == '123456':
            return f'欢迎回来，{username}！'
        else:
            return '用户名或密码错误'

    # GET 请求：显示登录页面
    return render_template('login.html')

🔍 request 对象常用属性

💡 get() vs [] 的区别：

request.form['name'] — 字段不存在时抛出 400 错误
request.form.get('name') — 字段不存在时返回 None（推荐）
request.form.get('name', '默认值') — 字段不存在时返回默认值

但是，手动处理表单有太多问题：

• ❌ 要手动验证每个字段（非空、长度、格式……）
• ❌ 要手动处理 CSRF 攻击防护
• ❌ 要手动渲染表单 HTML 和错误信息
• ❌ 代码和 HTML 混在一起，难维护

WTForms 就是来解决这些痛点的。

3. WTForms 入门

🛠️ 安装

pip install flask-wtf

📦 定义表单类

# forms.py
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, BooleanField, SubmitField
from wtforms.validators import DataRequired, Length, Email

class LoginForm(FlaskForm):
    username = StringField('用户名', validators=[
        DataRequired(message='用户名不能为空'),
        Length(min=3, max=20, message='用户名长度 3-20 个字符')
    ])
    password = PasswordField('密码', validators=[
        DataRequired(message='密码不能为空'),
        Length(min=6, message='密码至少 6 个字符')
    ])
    remember = BooleanField('记住我')
    submit = SubmitField('登录')

🖥️ 在视图中使用

# app.py
from flask import Flask, render_template, redirect, url_for, flash
from forms import LoginForm

app = Flask(__name__)
app.secret_key = 'your-secret-key-here'  # 用于 CSRF 和 session

@app.route('/login', methods=['GET', 'POST'])
def login():
    form = LoginForm()

    if form.validate_on_submit():
        # 所有验证都通过了！
        username = form.username.data
        password = form.password.data
        remember = form.remember.data

        if username == 'admin' and password == '123456':
            flash('登录成功！', 'success')
            return redirect(url_for('index'))
        else:
            flash('用户名或密码错误', 'error')

    return render_template('login.html', form=form)

🎨 在模板中渲染表单

<!-- templates/login.html -->
{% extends "base.html" %}
{% block content %}
<h2>用户登录</h2>
<form method="POST">
    {{ form.hidden_tag() }}  {# CSRF token，必须有！ #}

    <div>
        {{ form.username.label }}<br>
        {{ form.username(size=30) }}
        {% for error in form.username.errors %}
            <span style="color:red">{{ error }}</span>
        {% endfor %}
    </div>

    <div>
        {{ form.password.label }}<br>
        {{ form.password(size=30) }}
        {% for error in form.password.errors %}
            <span style="color:red">{{ error }}</span>
        {% endfor %}
    </div>

    <div>
        {{ form.remember() }} {{ form.remember.label }}
    </div>

    <div>
        {{ form.submit(class="btn") }}
    </div>
</form>
{% endblock %}

💡 WTForms 的核心优势：

1. 表单类 = 数据结构：字段定义清晰，像数据库模型
2. 验证器链：多个验证器叠加，自动按序执行
3. 自动渲染：{{ form.username() }} 生成 HTML input 标签
4. 自动报错：form.username.errors 自动填充错误信息
5. CSRF 内置：form.hidden_tag() 自动添加 CSRF token

4. 常用字段类型

# SelectField 示例
from wtforms import SelectField

class PetForm(FlaskForm):
    pet_type = SelectField('宠物类型', choices=[
        ('dog', '🐕 狗'),
        ('cat', '🐱 猫'),
        ('fish', '🐟 鱼'),
        ('bird', '🐦 鸟'),
    ])
    name = StringField('宠物名字')

# RadioField 示例
from wtforms import RadioField

class GenderForm(FlaskForm):
    gender = RadioField('性别', choices=[
        ('male', '男'),
        ('female', '女'),
        ('other', '其他'),
    ])

5. 验证器

✅ 常用验证器一览

🔗 验证器链

# 多个验证器按顺序执行
username = StringField('用户名', validators=[
    DataRequired(message='用户名不能为空'),   # 第1个：检查非空
    Length(min=3, max=20),                    # 第2个：检查长度
    Regexp(r'^[a-zA-Z0-9_]+$', message='只能包含字母、数字和下划线')  # 第3个：检查格式
])

# 如果第1个验证失败，后面的不会执行

🧩 自定义验证器

from wtforms.validators import ValidationError

class RegistrationForm(FlaskForm):
    username = StringField('用户名', validators=[DataRequired()])

    def validate_username(self, field):
        """自定义验证：检查用户名是否已存在"""
        if User.query.filter_by(username=field.data).first():
            raise ValidationError('该用户名已被注册')

6. CSRF 保护

🛡️ 什么是 CSRF？

CSRF（跨站请求伪造） 是一种网络攻击：恶意网站伪造请求，冒充你对其他网站执行操作。

# 攻击场景：
# 1. 你登录了银行网站（bank.com），获得了 session cookie
# 2. 你访问了恶意网站 evil.com
# 3. evil.com 的页面里隐藏了一个表单：
#    <form action="bank.com/transfer" method="POST">
#      <input name="to" value="hacker">
#      <input name="amount" value="10000">
#    </form>
# 4. 表单自动提交，浏览器带上 bank.com 的 cookie
# 5. 银行服务器以为是你本人操作 → 钱被转走！

CSRF Token 的防御原理：

# 每个表单都有一个随机生成的 token（隐藏字段）
# 服务器验证：提交的 token 必须和 session 中存储的一致
# 恶意网站无法获取 token → 无法伪造请求 → 攻击失败

⚠️ CSRF 防护是必须的！

Flask-WTF 默认开启 CSRF 保护。你只需要：
1. 设置 app.secret_key
2. 在表单模板中添加 {{ form.hidden_tag() }}
3. 不要跳过 form.validate_on_submit()

🔧 CSRF 配置

# app.py
app = Flask(__name__)
app.secret_key = 'a-very-long-random-secret-key'  # 必须设置！

# 可选：自定义 CSRF 配置
app.config['WTF_CSRF_ENABLED'] = True         # 开启 CSRF（默认 True）
app.config['WTF_CSRF_TIME_LIMIT'] = 3600      # token 有效期（秒）

# 特定路由禁用 CSRF（不推荐，除非有充分理由）
@app.route('/api/data', methods=['POST'])
@csrf.exempt  # 需要 from flask_wtf.csrf import CSRFProtect
def api_data():
    pass

7. 文件上传

📤 基本文件上传

# forms.py
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileAllowed, FileRequired

class UploadForm(FlaskForm):
    photo = FileField('上传头像', validators=[
        FileRequired(message='请选择文件'),
        FileAllowed(['jpg', 'jpeg', 'png', 'gif'], message='只允许上传图片！')
    ])

# app.py
from flask import request
from werkzeug.utils import secure_filename
import os

UPLOAD_FOLDER = os.path.join(os.path.dirname(__file__), 'uploads')
os.makedirs(UPLOAD_FOLDER, exist_ok=True)

@app.route('/upload', methods=['GET', 'POST'])
def upload():
    form = UploadForm()
    if form.validate_on_submit():
        file = form.photo.data
        filename = secure_filename(file.filename)  # 安全化文件名
        file.save(os.path.join(UPLOAD_FOLDER, filename))
        return f'文件 {filename} 上传成功！'
    return render_template('upload.html', form=form)

🔒 secure_filename 做了什么？

secure_filename('../../../etc/passwd')     → 'etc_passwd'
secure_filename('my photo (1).jpg')        → 'my_photo_1.jpg'
secure_filename('../../hack.php.jpg')       → 'hack.php.jpg'
secure_filename('中文文件名.jpg')           → ''  ← 中文会被清空！

💡 中文文件名问题：

secure_filename() 会删除所有非 ASCII 字符，中文文件名会变成空字符串。解决方案：

filename = secure_filename(file.filename) or 'unnamed'
filename = f'{uuid.uuid4().hex}_{filename}'

8. 文件上传安全

⚠️ 文件上传的三大风险

# 安全配置
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024  # 最大 16MB

# 文件类型白名单（只允许图片）
ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg', 'gif'}

def allowed_file(filename):
    return '.' in filename and \
           filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS

# 文件重命名策略（避免文件名冲突）
import uuid

def generate_filename(original_filename):
    ext = original_filename.rsplit('.', 1)[1].lower()
    return f'{uuid.uuid4().hex}.{ext}'  # 如: a1b2c3d4e5f6.jpg

9. 表单实战：完整注册表单

综合运用今天学到的所有知识，做一个完整的用户注册表单：

📋 表单定义

# forms.py
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileAllowed
from wtforms import StringField, PasswordField, BooleanField, SelectField, SubmitField
from wtforms.validators import DataRequired, Email, Length, EqualTo, ValidationError

class RegistrationForm(FlaskForm):
    username = StringField('用户名', validators=[
        DataRequired('用户名不能为空'),
        Length(min=3, max=20, message='3-20 个字符')
    ])

    email = StringField('邮箱', validators=[
        DataRequired('邮箱不能为空'),
        Email('请输入有效的邮箱地址')
    ])

    password = PasswordField('密码', validators=[
        DataRequired('密码不能为空'),
        Length(min=8, message='密码至少 8 个字符')
    ])

    confirm_password = PasswordField('确认密码', validators=[
        DataRequired('请再次输入密码'),
        EqualTo('password', message='两次密码不一致')
    ])

    gender = SelectField('性别', choices=[
        ('', '请选择'),
        ('male', '男'),
        ('female', '女'),
        ('other', '其他'),
    ])

    agree = BooleanField('我同意用户协议', validators=[
        DataRequired('必须同意用户协议')
    ])

    avatar = FileField('头像（可选）', validators=[
        FileAllowed(['jpg', 'png', 'gif'], message='只允许图片格式')
    ])

    submit = SubmitField('注册')

    # 自定义验证器
    def validate_username(self, field):
        # 这里应该查数据库，示例用硬编码
        if field.data.lower() in ['admin', 'root', 'system']:
            raise ValidationError('该用户名不可使用')

    def validate_email(self, field):
        # 这里应该查数据库
        pass

🖥️ 视图函数

# app.py
@app.route('/register', methods=['GET', 'POST'])
def register():
    form = RegistrationForm()

    if form.validate_on_submit():
        # 所有验证通过
        username = form.username.data
        email = form.email.data
        password = form.password.data

        # 处理头像上传
        avatar_filename = 'default.png'
        if form.avatar.data:
            avatar_filename = generate_filename(form.avatar.data.filename)
            form.avatar.data.save(
                os.path.join(UPLOAD_FOLDER, avatar_filename)
            )

        # 创建用户（这里示例，实际应存数据库）
        flash(f'注册成功！欢迎 {username}', 'success')
        return redirect(url_for('login'))

    return render_template('register.html', form=form)

🎨 注册模板

<!-- templates/register.html -->
{% extends "base.html" %}
{% block content %}
<h2>📝 用户注册</h2>

<form method="POST" enctype="multipart/form-data">
    {{ form.hidden_tag() }}

    <div class="form-group">
        {{ form.username.label }}<br>
        {{ form.username(class="input", placeholder="3-20个字符") }}
        {% for e in form.username.errors %}<span class="error">{{ e }}</span>{% endfor %}
    </div>

    <div class="form-group">
        {{ form.email.label }}<br>
        {{ form.email(class="input", placeholder="example@mail.com") }}
        {% for e in form.email.errors %}<span class="error">{{ e }}</span>{% endfor %}
    </div>

    <div class="form-group">
        {{ form.password.label }}<br>
        {{ form.password(class="input", placeholder="至少8个字符") }}
        {% for e in form.password.errors %}<span class="error">{{ e }}</span>{% endfor %}
    </div>

    <div class="form-group">
        {{ form.confirm_password.label }}<br>
        {{ form.confirm_password(class="input") }}
        {% for e in form.confirm_password.errors %}<span class="error">{{ e }}</span>{% endfor %}
    </div>

    <div class="form-group">
        {{ form.gender.label }}<br>
        {{ form.gender(class="input") }}
    </div>

    <div class="form-group">
        {{ form.avatar.label }}<br>
        {{ form.avatar() }}
        {% for e in form.avatar.errors %}<span class="error">{{ e }}</span>{% endfor %}
    </div>

    <div class="form-group">
        {{ form.agree() }} {{ form.agree.label }}
        {% for e in form.agree.errors %}<span class="error">{{ e }}</span>{% endfor %}
    </div>

    {{ form.submit(class="btn") }}
</form>
{% endblock %}

10. 今日练习

🏋️ 练习 1：登录表单

# 创建一个完整的登录表单：
# - username: 必填，3-20 字符
# - password: 必填，至少 6 字符
# - remember: 记住我复选框
# - submit: 登录按钮
# 要求：验证失败时显示红色错误信息

🏋️ 练习 2：搜索表单

# 创建一个搜索表单：
# - keyword: 关键词（必填，至少 2 个字符）
# - category: 分类下拉框（全部/技术/生活/娱乐）
# - sort: 排序方式单选（时间/热度/相关度）
# 搜索结果用 jsonify 返回 JSON

🏋️ 练习 3：文件上传

# 创建图片上传功能：
# - 支持 jpg/png/gif 格式
# - 文件大小限制 5MB
# - 上传后显示图片预览
# - 文件名用 UUID 重命名避免冲突

11. 今日小结

🚀 明日预告：Day 54 — Flask 与数据库

表单收集了数据，但数据存哪里？明天我们学 Flask-SQLAlchemy——把 Python 对象映射到数据库表，用代码代替 SQL 语句。还有数据库迁移，再也不用手动改表结构了！