参数验证

项目使用 WTForms 进行请求参数验证。所有请求体参数通过 WTForms 表单类定义，框架自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 src/common/forms/base_form.py。

基本用法

定义表单类

# src/modules/system/position/schema.py
# +======================================================================
# | 模块: 岗位表单验证
# | 说明: 岗位创建/编辑/状态更新的请求数据校验
# +======================================================================

from wtforms import StringField, IntegerField
from wtforms.validators import DataRequired, Length, NumberRange

from src.common.forms.base_form import BaseForm


# ============================================================
# 岗位表单类
# ============================================================
class PositionForm(BaseForm):
    """岗位创建/编辑表单"""
    name = StringField('岗位名称', validators=[
        DataRequired(message='岗位名称不能为空'),
        Length(min=1, max=150, message='岗位名称长度必须在1-150个字符之间')
    ])
    status = IntegerField('岗位状态', validators=[
        DataRequired(message='岗位状态不能为空'),
        NumberRange(min=1, max=2, message='岗位状态必须是1或2')
    ])
    sort = IntegerField('岗位排序', validators=[
        DataRequired(message='岗位排序不能为空'),
        NumberRange(min=0, max=99999, message='岗位排序必须在0-99999之间')
    ])


# ============================================================
# 设置状态表单类
# ============================================================
class PositionStatusForm(BaseForm):
    """岗位状态更新表单"""
    id = IntegerField('岗位ID', validators=[
        DataRequired(message='岗位ID不能为空'),
        NumberRange(min=1, message='岗位ID必须大于0')
    ])
    status = IntegerField('岗位状态', validators=[
        DataRequired(message='岗位状态不能为空'),
        NumberRange(min=1, max=2, message='岗位状态必须是1或2')
    ])

Router 使用

@position_blue.route('/add', methods=['POST'])
@check_permission('sys:position:add')
def add():
    from src.modules.system.position.service import add_position
    from src.modules.system.position.schema import PositionForm
    data = parse_request_body(request, PositionForm)
    return add_position(data)

自动验证

parse_request_body 函数在调用 Service 函数前自动完成参数验证。验证失败时返回标准格式错误：

{"code": 1, "data": null, "msg": "岗位名称不能为空"}

Validator 约束

WTForms 提供丰富的字段约束：

Validator	说明	示例
DataRequired	必填字段	DataRequired(message='不能为空')
Length	字符串长度	Length(min=1, max=150)
NumberRange	数值范围	NumberRange(min=0, max=99999)
Optional	可选字段	Optional()
Email	邮箱格式	Email(message='邮箱格式不正确')
URL	URL 格式	URL(message='URL格式不正确')
Regexp	正则匹配	Regexp(r'^[a-z]+$')

自定义验证器

使用 validate_ 方法添加自定义验证逻辑：

from wtforms import StringField
from wtforms.validators import DataRequired, Length, ValidationError

class UserForm(BaseForm):
    username = StringField('用户名', validators=[
        DataRequired(message='用户名不能为空'),
        Length(min=1, max=50, message='用户名长度必须在1-50个字符之间')
    ])
    email = StringField('邮箱', validators=[
        DataRequired(message='邮箱不能为空'),
        Length(max=100, message='邮箱长度不能超过100个字符')
    ])

    def validate_username(self, field):
        if not field.data.isalnum():
            raise ValidationError('用户名只能包含字母和数字')

    def validate_email(self, field):
        if '@' not in field.data:
            raise ValidationError('邮箱格式不正确')

BaseForm 基类

所有创建/编辑表单应继承 BaseForm，自动获得 id 字段和空字符串处理：

# src/common/forms/base_form.py
from wtforms import Form, IntegerField
from wtforms.validators import Optional


class BaseForm(FlaskForm):
    """
    表单基类

    所有创建/编辑表单应继承此类，自动获得：
        1. id 字段：Optional，前端传空字符串时自动转为 None
    """

    id = IntegerField('ID', validators=[Optional()])

前端空字符串

前端某些组件（如 el-select）在未选择时可能传空字符串 ""，parse_request_body 函数会自动将其转为 None，避免整数字段解析报错。

唯一性校验

在 WTForms 验证器中查询数据库校验唯一性：

from wtforms import StringField
from wtforms.validators import DataRequired, Length, ValidationError

class PositionForm(BaseForm):
    name = StringField('岗位名称', validators=[
        DataRequired(message='岗位名称不能为空'),
        Length(min=1, max=150, message='岗位名称长度必须在1-150个字符之间')
    ])

    def validate_name(self, field):
        from src.modules.system.position.repository import PositionRepository
        exclude_id = self.id.data if self.id.data else None
        if PositionRepository.exists_by([Position.name == field.data], exclude_id):
            raise ValidationError('岗位名称已存在')

登录表单示例

# src/modules/auth/schema.py
# +======================================================================
# | 模块: 登录表单验证
# | 说明: 用户登录的请求数据校验
# +======================================================================

from wtforms import StringField
from wtforms.validators import DataRequired, Length

from config.captcha import CAPTCHA_LENGTH


# ============================================================
# 登录表单类
# ============================================================
class LoginForm(BaseForm):
    """登录表单验证类"""
    username = StringField('登录账号', validators=[
        DataRequired(message='登录账号不能为空'),
        Length(min=1, max=20, message='登录账号长度必须在1-20个字符之间')
    ])
    password = StringField('登录密码', validators=[
        DataRequired(message='登录密码不能为空'),
        Length(min=6, max=128, message='登录密码长度必须在6-128个字符之间')
    ])
    code = StringField('验证码', validators=[
        DataRequired(message='验证码不能为空'),
        Length(min=CAPTCHA_LENGTH, max=CAPTCHA_LENGTH, message='验证码长度必须为{}个字符'.format(CAPTCHA_LENGTH))
    ])
    key = StringField('KEY值', validators=[
        DataRequired(message='KEY值不能为空')
    ])

错误响应格式

验证失败时，parse_request_body 函数捕获验证错误并返回标准格式：

{
    "code": 1,
    "data": null,
    "msg": "岗位名称不能为空",
    "ok": false
}

多个错误返回第一个错误信息。

总结

参数验证模块具备以下特点：

1. WTForms：类型安全、自动解析 JSON 请求体
2. 丰富约束：DataRequired、Length、NumberRange、Optional、Email、URL、Regexp
3. 自定义验证：validate_ 方法实现复杂校验逻辑
4. BaseForm 基类：统一 id 字段处理，兼容前端空字符串
5. 唯一性校验：验证器中查询数据库，确保字段唯一性
6. 标准错误：统一错误响应格式