WTForms Schema 规范

概述

Schema 层负责请求数据的校验。项目使用 WTForms 定义表单类，通过 validators 约束字段格式，框架在接收请求体时自动执行校验。

设计原则

• 创建/编辑共用一个表单类，继承 BaseForm
• 特殊操作单独建类（如状态更新、排序调整）
• message 必填，用于返回给前端的错误信息
• 唯一性校验通过自定义 validate_ 方法实现

BaseForm 继承

以岗位模块为例，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')
    ])

Validator 选择表

Validator	作用	示例
DataRequired	必填字段，不允许空值	DataRequired(message='不能为空')
Length	字符串长度限制	Length(min=1, max=150)
NumberRange	数值范围限制	NumberRange(min=1, max=2)
Optional	可选字段	Optional()
Email	邮箱格式	Email(message='邮箱格式不正确')
URL	URL 格式	URL(message='URL格式不正确')
Regexp	正则表达式	Regexp(r'^[a-zA-Z]+$')

自定义校验器

唯一性校验

from wtforms import ValidationError
from src.modules.system.position.repository import PositionRepository

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

    def validate_name(self, field):
        """自定义校验：检查岗位名称是否已存在"""
        exclude_id = self.id.data if self.id.data else None
        if PositionRepository.exists_by([Position.name == field.data], exclude_id):
            raise ValidationError('岗位名称已存在')

跨字段校验

class DateRangeForm(BaseForm):
    """日期范围表单"""
    start_date = DateField('开始日期', validators=[DataRequired()])
    end_date = DateField('结束日期', validators=[DataRequired()])

    def validate_end_date(self, field):
        """自定义校验：结束日期必须大于开始日期"""
        if field.data < self.start_date.data:
            raise ValidationError('结束日期必须大于开始日期')

在 Router 中使用

from flask import request
from src.common.utils.request import parse_request_body

@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)

错误响应格式

校验失败时，框架自动返回标准错误响应：

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

开发要点

1. 创建/编辑共用一个表单类：继承 BaseForm，利用其内置的可选 id 字段
2. 特殊操作单独建类：如状态更新、排序调整等，只包含必要的字段
3. 合理设置 Validator：DataRequired / Length / NumberRange 等，让框架自动校验
4. message 必填：用于返回给前端的错误信息，方便调试
5. 唯一性校验：通过自定义 validate_ 方法实现，使用 Repository 层的 exists_by 方法
6. 字段名与前端一致：确保前后端字段名对应

总结

WTForms Schema 通过 BaseForm 继承公共字段（id 等），使用 validators 声明约束，自定义 validate_ 方法实现唯一性校验。特殊操作单独建类，message 必填用于返回给前端的错误信息。