Marshmallow: اعتبارسنجی و سریالی‌سازی قدرتمند

Marshmallow یک کتابخانه قدرتمند برای سریالی‌سازی/دسریالی‌سازی آبجکت‌ها و اعتبارسنجی داده‌ها در پایتون است. این کتابخانه به ویژه برای ساخت APIهای RESTful که نیاز به تبدیل آبجکت‌های پایتون به فرمت‌هایی مانند JSON و بالعکس دارند، بسیار مفید است. Marshmallow به شما اجازه می‌دهد تا اسکیماهای (schemas) داده‌ای تعریف کنید که هم ساختار داده‌ها را مشخص می‌کنند و هم قوانین اعتبارسنجی را اعمال می‌نمایند.

ویژگی‌های کلیدی:

• سریالی‌سازی/دسریالی‌سازی: تبدیل آبجکت‌های پیچیده پایتون به فرمت‌های ساده‌تر (مانند دیکشنری‌های پایتون که قابل تبدیل به JSON هستند) و بالعکس.
• اعتبارسنجی مبتنی بر اسکیما: تعریف قوانین اعتبارسنجی به صورت متمرکز در یک اسکیما.
• فیلدها و ولیدیتورهای متنوع: مجموعه‌ای غنی از فیلدها (String, Integer, Nested, List) و ولیدیتورها (Email, Length, Range, Regexp).
• یکپارچگی با ORMها: به خوبی با ORMهایی مانند SQLAlchemy کار می‌کند (از طریق Flask-Marshmallow).

نصب:

pip install marshmallow Flask-Marshmallow # اگر می‌خواهید با Flask یکپارچه کنید

مثال استفاده:

from flask import Flask, request, jsonify
from marshmallow import Schema, fields, validate, ValidationError

app = Flask(__name__)

class UserSchema(Schema):
    id = fields.Int(dump_only=True) # فقط برای سریال‌سازی، نه برای ورودی
    username = fields.Str(required=True, validate=validate.Length(min=3, max=20))
    email = fields.Email(required=True)
    password = fields.Str(required=True, validate=validate.Length(min=8))
    is_admin = fields.Bool(dump_default=False) # مقدار پیش‌فرض در زمان سریالی‌سازی

@app.route('/api/users_marshmallow', methods=['POST'])
def create_user_marshmallow():
    data = request.get_json()
    if not data:
        return jsonify({'message': 'درخواست باید شامل داده‌های JSON باشد.'}), 400

    user_schema = UserSchema()
    try:
        # load() داده‌ها را دسریالایز و اعتبارسنجی می‌کند
        validated_data = user_schema.load(data)
    except ValidationError as err:
        return jsonify({'errors': err.messages}), 400

    # اگر اعتبارسنجی موفق بود، می‌توانید از validated_data استفاده کنید
    # ... مثلاً یک کاربر جدید در دیتابیس ایجاد کنید
    # user = User(**validated_data)
    # db.session.add(user)
    # db.session.commit()

    # سریالی‌سازی آبجکت کاربر برای بازگشت
    # result = user_schema.dump(user) # اگر user یک آبجکت واقعی بود
    return jsonify({'message': 'کاربر با موفقیت ایجاد شد.', 'data': validated_data}), 201

در این مثال، UserSchema تمام قوانین اعتبارسنجی را در یک مکان متمرکز می‌کند. متد load() داده‌های ورودی را اعتبارسنجی و دسریالایز می‌کند و در صورت وجود خطا، یک ValidationError پرتاب می‌کند. dump() برعکس عمل می‌کند و یک آبجکت پایتون را به یک دیکشنری قابل سریالی‌سازی تبدیل می‌کند.

Pydantic: اعتبارسنجی با Type Hints پایتون

Pydantic یک کتابخانه مدرن است که از Type Hints پایتون برای اعتبارسنجی داده‌ها و تنظیمات استفاده می‌کند. این کتابخانه به سرعت محبوبیت پیدا کرده است، به خصوص در پروژه‌هایی که از FastAPI استفاده می‌کنند (که Pydantic را به عنوان هسته خود به کار می‌گیرد)، اما به راحتی می‌توان آن را در برنامه‌های Flask نیز به کار برد. Pydantic به شما امکان می‌دهد مدل‌های داده‌ای را با استفاده از کلاس‌های پایتون و type hints تعریف کنید، و سپس Pydantic به طور خودکار اعتبارسنجی را بر اساس این تعاریف انجام می‌دهد و داده‌ها را به انواع صحیح تبدیل می‌کند.

ویژگی‌های کلیدی:

• اعتبارسنجی مبتنی بر Type Hints: استفاده از type hints استاندارد پایتون (PEP 484) برای تعریف ساختار داده و قوانین اعتبارسنجی.
• تبدیل خودکار نوع: Pydantic به طور خودکار انواع داده‌ها را در صورت امکان تبدیل می‌کند (مثلاً "123" به 123).
• پیام‌های خطای دقیق: تولید پیام‌های خطای خوانا و ساختاریافته.
• یکپارچگی با IDE: به دلیل استفاده از type hints، IDEها می‌توانند تکمیل کد و بررسی نوع را به خوبی انجام دهند.
• پشتیبانی از انواع پیچیده: پشتیبانی از لیست‌ها، دیکشنری‌ها، Union، Optional و مدل‌های تو در تو.

نصب:

pip install pydantic

مثال استفاده:

from flask import Flask, request, jsonify
from pydantic import BaseModel, Field, EmailStr, ValidationError
from typing import Optional

app = Flask(__name__)

class UserCreate(BaseModel):
    username: str = Field(min_length=3, max_length=20)
    email: EmailStr
    password: str = Field(min_length=8)
    is_admin: Optional[bool] = False # Optional field with a default value

@app.route('/api/users_pydantic', methods=['POST'])
def create_user_pydantic():
    data = request.get_json()
    if not data:
        return jsonify({'message': 'درخواست باید شامل داده‌های JSON باشد.'}), 400

    try:
        # ایجاد یک نمونه از مدل Pydantic، که به طور خودکار اعتبارسنجی می‌کند
        user_data = UserCreate(**data)
    except ValidationError as e:
        # e.errors() یک لیست از دیکشنری‌های خطا را برمی‌گرداند
        return jsonify({'errors': e.errors()}), 400
    
    # اگر اعتبارسنجی موفق بود، user_data یک آبجکت Pydantic معتبر است
    # می‌توانید به فیلدها به صورت user_data.username دسترسی پیدا کنید
    # print(user_data.username, user_data.email, user_data.password)

    # تبدیل مدل به دیکشنری برای ذخیره سازی یا بازگشت (اگر لازم باشد)
    validated_data = user_data.model_dump() # در Pydantic v2
    # validated_data = user_data.dict() # در Pydantic v1

    return jsonify({'message': 'کاربر با موفقیت ایجاد شد.', 'data': validated_data}), 201

Pydantic یک راه حل بسیار تمیز و مدرن برای اعتبارسنجی داده‌ها ارائه می‌دهد که به خوبی با اکوسیستم پایتون و ابزارهای توسعه همکاری می‌کند. انتخاب بین این کتابخانه‌ها بستگی به نیازهای پروژه، ترجیحات تیم و نوع برنامه‌ای که می‌سازید (فرم‌های سنتی وب در مقابل APIهای RESTful) دارد. برای فرم‌های وب سنتی، Flask-WTF یک انتخاب عالی است، در حالی که برای APIهای قدرتمند و انعطاف‌پذیر، Marshmallow یا Pydantic گزینه‌های برتری هستند.

پیاده‌سازی اعتبارسنجی سفارشی و پیچیده

در حالی که کتابخانه‌های اعتبارسنجی مانند WTForms، Marshmallow و Pydantic مجموعه‌ای غنی از ولیدیتورهای داخلی را ارائه می‌دهند، اما اغلب نیاز به پیاده‌سازی منطق اعتبارسنجی سفارشی دارید که مختص منطق کسب‌وکار یا الزامات خاص برنامه شما باشد. این شامل بررسی‌های پایگاه داده برای منحصر به فرد بودن، اعتبارسنجی فرمت‌های خاص یا منطق‌های پیچیده‌تر بین فیلدها می‌شود.

اعتبارسنجی سفارشی در Flask-WTF / WTForms

در WTForms، شما می‌توانید متدهای validate_<field_name> را در کلاس فرم خود تعریف کنید. این متدها به طور خودکار توسط form.validate_on_submit() فراخوانی می‌شوند.

from wtforms import StringField, ValidationError
from wtforms.validators import DataRequired, Email, Length
from flask_wtf import FlaskForm

# فرض کنید یک مدل کاربر دارید و با SQLAlchemy کار می‌کنید
# class User(db.Model):
#     id = db.Column(db.Integer, primary_key=True)
#     username = db.Column(db.String(80), unique=True, nullable=False)
#     email = db.Column(db.String(120), unique=True, nullable=False)

class CustomRegistrationForm(FlaskForm):
    username = StringField('نام کاربری', validators=[DataRequired(), Length(min=3, max=20)])
    email = StringField('ایمیل', validators=[DataRequired(), Email()])
    password = StringField('رمز عبور', validators=[DataRequired(), Length(min=8)])

    def validate_username(self, field):
        # این ولیدیتور سفارشی بررسی می‌کند که نام کاربری از قبل موجود نباشد
        # if User.query.filter_by(username=field.data).first():
        #     raise ValidationError('این نام کاربری از قبل گرفته شده است. لطفاً نام دیگری را انتخاب کنید.')
        # برای مثال:
        if field.data == 'admin':
            raise ValidationError('نام کاربری "admin" مجاز نیست.')

    def validate_email(self, field):
        # این ولیدیتور سفارشی بررسی می‌کند که ایمیل از قبل موجود نباشد
        # if User.query.filter_by(email=field.data).first():
        #     raise ValidationError('این ایمیل از قبل ثبت شده است. لطفاً وارد شوید یا ایمیل دیگری را انتخاب کنید.')
        # برای مثال:
        if field.data == 'test@example.com':
            raise ValidationError('این ایمیل برای تست رزرو شده است.')

    def validate(self, extra_validators=None):
        # این متد می تواند برای اعتبارسنجی های پیچیده تر بین چند فیلد استفاده شود
        initial_validation = super().validate(extra_validators)
        if not initial_validation:
            return False

        # مثال: بررسی اینکه رمز عبور شامل نام کاربری نباشد
        if self.username.data and self.password.data and self.username.data in self.password.data:
            self.password.errors.append('رمز عبور نمی‌تواند شامل نام کاربری باشد.')
            return False
        
        return True # اگر همه اعتبارسنجی‌ها موفق بودند

متدهای validate_<field_name> برای اعتبارسنجی‌های مربوط به یک فیلد خاص ایده‌آل هستند، در حالی که متد validate() برای اعتبارسنجی‌های پیچیده‌تر که به چندین فیلد نیاز دارند، مناسب است.

اعتبارسنجی سفارشی در Marshmallow

Marshmallow چندین راه برای تعریف ولیدیتورهای سفارشی ارائه می‌دهد:

1. ولیدیتورهای تابع (Function Validators): می‌توانید توابع پایتون را مستقیماً به عنوان ولیدیتور به فیلدها اضافه کنید.
2. متدهای validate_<field_name>: مشابه WTForms، می‌توانید این متدها را در کلاس اسکیما تعریف کنید.
3. متد @validates_schema: برای اعتبارسنجی‌های در سطح اسکیما که شامل چندین فیلد هستند.
4. کلاس‌های ولیدیتور سفارشی: ایجاد کلاس‌هایی که از marshmallow.validate.Validator ارث‌بری می‌کنند.

from marshmallow import Schema, fields, validate, ValidationError, validates_schema
from marshmallow.validate import Length, Email
from flask import jsonify, request, Flask

app = Flask(__name__)

def validate_even_number(n):
    if n % 2 != 0:
        raise ValidationError('عدد باید زوج باشد.')

class ProductSchema(Schema):
    name = fields.Str(required=True, validate=Length(min=2, max=100))
    price = fields.Float(required=True, validate=validate.Range(min=0.01))
    quantity = fields.Int(required=True, validate=[validate.Range(min=1), validate_even_number]) # ولیدیتور تابع

    def validate_name(self, name):
        # اعتبارسنجی سفارشی برای نام محصول
        if name.lower() == "test product":
            raise ValidationError("نام 'Test Product' مجاز نیست.")

    @validates_schema
    def validate_product_logic(self, data, **kwargs):
        # اعتبارسنجی در سطح اسکیما
        if data['price'] < 10 and data['quantity'] > 50:
            raise ValidationError('محصولات ارزان‌قیمت نمی‌توانند در مقادیر بسیار زیاد سفارش داده شوند.', 'quantity')
        
        # فرض کنید یک سرویس برای بررسی موجودی دارید
        # if not check_product_inventory(data['name'], data['quantity']):
        #     raise ValidationError('موجودی کافی برای این محصول نیست.', 'quantity')

@app.route('/api/products', methods=['POST'])
def create_product():
    json_data = request.get_json()
    if not json_data:
        return jsonify({'message': 'درخواست باید شامل داده‌های JSON باشد.'}), 400

    schema = ProductSchema()
    try:
        validated_data = schema.load(json_data)
    except ValidationError as err:
        return jsonify(err.messages), 400
    
    return jsonify(validated_data), 201

اعتبارسنجی سفارشی در Pydantic

Pydantic امکانات قدرتمندی برای اعتبارسنجی سفارشی با استفاده از متدهای validator و root_validator (در Pydantic v1) یا @field_validator و @model_validator (در Pydantic v2) ارائه می‌دهد.

from flask import Flask, request, jsonify
from pydantic import BaseModel, Field, EmailStr, ValidationError, model_validator, field_validator
from typing import Optional

app = Flask(__name__)

class UserPydantic(BaseModel):
    username: str = Field(min_length=3, max_length=20)
    email: EmailStr
    password: str = Field(min_length=8)
    age: Optional[int] = Field(None, ge=18, le=120) # بزرگتر مساوی 18، کوچکتر مساوی 120

    @field_validator('username') # Pydantic v2
    @classmethod
    def validate_username_custom(cls, value):
        if value == 'root':
            raise ValueError('نام کاربری "root" مجاز نیست.')
        # فرض کنید چک منحصر به فرد بودن نام کاربری را اینجا انجام می‌دهید
        # if User.exists(username=value):
        #     raise ValueError('این نام کاربری از قبل وجود دارد.')
        return value

    @model_validator(mode='after') # Pydantic v2
    def validate_password_complexity(self):
        # اعتبارسنجی پیچیدگی رمز عبور در سطح مدل
        if self.password.lower() == self.username.lower():
            raise ValueError('رمز عبور نمی‌تواند با نام کاربری یکسان باشد.')
        
        # یک مثال پیچیده تر: بررسی اینکه رمز عبور شامل حداقل یک عدد و یک حرف بزرگ باشد
        if not any(char.isdigit() for char in self.password):
            raise ValueError('رمز عبور باید حداقل یک عدد داشته باشد.')
        if not any(char.isupper() for char in self.password):
            raise ValueError('رمز عبور باید حداقل یک حرف بزرگ داشته باشد.')
        
        return self

@app.route('/api/users_pydantic_custom', methods=['POST'])
def create_user_pydantic_custom():
    data = request.get_json()
    if not data:
        return jsonify({'message': 'درخواست باید شامل داده‌های JSON باشد.'}), 400

    try:
        user_data = UserPydantic(**data)
    except ValidationError as e:
        return jsonify({'errors': e.errors()}), 400
    
    return jsonify({'message': 'کاربر با موفقیت ایجاد شد.', 'data': user_data.model_dump()}), 201

@field_validator به شما امکان می‌دهد تا قبل از اختصاص داده به یک فیلد خاص، آن را اعتبارسنجی و حتی تغییر دهید. @model_validator به شما اجازه می‌دهد تا اعتبارسنجی‌هایی را انجام دهید که به مقادیر چندین فیلد نیاز دارند، و این کار را بعد از اعتبارسنجی‌های فیلد انجام می‌دهد.

انتخاب روش مناسب برای اعتبارسنجی سفارشی به کتابخانه مورد استفاده و پیچیدگی منطق شما بستگی دارد. در هر سه کتابخانه، اصول کلی یکسان است: شناسایی خطاهای اعتبارسنجی، ایجاد پیام‌های خطا و پرتاب یک استثنا یا اضافه کردن خطا به لیست خطاها. استفاده صحیح از این قابلیت‌ها به شما این امکان را می‌دهد که اعتبارسنجی‌های پیچیده و مختص به نیازهای برنامه خود را به صورت تمیز و قابل نگهداری پیاده‌سازی کنید.

مدیریت و گزارش‌دهی خطاها در اعتبارسنجی

اعتبارسنجی ورودی تنها نیمی از کار است؛ نحوه مدیریت و گزارش‌دهی خطاها به کاربر نیز به همان اندازه اهمیت دارد. یک سیستم گزارش‌دهی خطای خوب باید اطلاعات واضح، دقیق و سازنده‌ای را به کاربر ارائه دهد تا بتواند به راحتی مشکل را برطرف کند. این نه تنها تجربه کاربری را بهبود می‌بخشد، بلکه در عیب‌یابی و اشکال‌زدایی نیز به توسعه‌دهندگان کمک می‌کند.

کدهای وضعیت HTTP (HTTP Status Codes)

برای APIهای RESTful، استفاده صحیح از کدهای وضعیت HTTP برای نشان دادن نتیجه اعتبارسنجی بسیار مهم است. این کدها به کلاینت (خواه یک مرورگر، اپلیکیشن موبایل یا سرویس دیگر) اجازه می‌دهند تا به سرعت وضعیت درخواست را درک کند:

• 200 OK / 201 Created: نشان‌دهنده موفقیت درخواست (پس از اعتبارسنجی موفق).
• 400 Bad Request: رایج‌ترین کد برای خطاهای اعتبارسنجی. این کد به این معنی است که سرور نمی‌تواند درخواست را به دلیل خطاهای کلاینت (مانند داده‌های نامعتبر یا از دست رفته) پردازش کند.
• 422 Unprocessable Entity: این کد وضعیت توسط برخی APIها برای نشان دادن خطاهای معنایی اعتبارسنجی استفاده می‌شود. به این معنی که درخواست به درستی فرمت شده است (نه مانند 400 که ممکن است مربوط به JSON نامعتبر باشد)، اما محتوای آن از نظر منطقی قابل پردازش نیست (مثلاً یک فیلد ایمیل معتبر از نظر ساختار، اما ایمیل در پایگاه داده وجود ندارد و باید منحصر به فرد باشد).
• 401 Unauthorized: برای خطاهای احراز هویت (Authentication).
• 403 Forbidden: برای خطاهای مجوز (Authorization).

همیشه سعی کنید از 400 Bad Request برای خطاهای اعتبارسنجی استفاده کنید مگر اینکه دلیلی خاص برای استفاده از 422 داشته باشید.

فرمت پاسخ خطا (Error Response Format)

علاوه بر کد وضعیت HTTP، بدنه پاسخ خطا باید به گونه‌ای ساختاریافته باشد که کلاینت بتواند به راحتی آن را تجزیه و تحلیل کند. فرمت JSON برای این منظور بسیار محبوب است. یک فرمت رایج شامل یک شیء JSON با یک کلید errors است که شامل جزئیات خطاها می‌شود.

مثال عمومی:

{
    "errors": {
        "username": [
            "نام کاربری نمی‌تواند خالی باشد.",
            "نام کاربری باید حداقل 3 کاراکتر باشد."
        ],
        "email": [
            "فرمت ایمیل نامعتبر است."
        ],
        "general": [
            "رمز عبور نمی‌تواند شامل نام کاربری باشد."
        ]
    }
}

برخی APIها ممکن است یک کلید message نیز برای خطای کلی فراهم کنند:

{
    "message": "خطا در اعتبارسنجی ورودی",
    "errors": {
        "username": "نام کاربری از قبل وجود دارد.",
        "password": "رمز عبور بسیار ضعیف است."
    }
}

این ساختار به کلاینت اجازه می‌دهد تا پیام‌های خطا را به فیلدهای مربوطه در فرم یا رابط کاربری نمایش دهد.

مدیریت خطاها در Flask-WTF / WTForms

Flask-WTF به طور خودکار خطاها را در شیء form.errors جمع‌آوری می‌کند، که یک دیکشنری است. در تمپلیت، می‌توانید این خطاها را به راحتی نمایش دهید:

@app.route('/register', methods=['POST'])
def register():
    form = RegistrationForm()
    if form.validate_on_submit():
        # ... پردازش موفقیت آمیز
        return redirect(url_for('success'))
    # اگر اعتبارسنجی ناموفق بود، form.errors پر می‌شود
    return render_template('register.html', form=form)

در تمپلیت Jinja2:

<p>
    {{ form.username.label }}<br>
    {{ form.username() }}<br>
    {% if form.username.errors %}<ul>{% for error in form.username.errors %}<li style="color: red;">{{ error }}</li>{% endfor %}</ul>{% endif %}
</p>

برای APIها، می‌توانید form.errors را مستقیماً به JSON تبدیل کرده و با کد 400 بازگردانید:

@app.route('/api/register', methods=['POST'])
def api_register():
    form = RegistrationForm()
    if form.validate_on_submit():
        # ... پردازش موفقیت آمیز
        return jsonify({'message': 'User registered successfully'}), 201
    return jsonify({'errors': form.errors}), 400

مدیریت خطاها در Marshmallow

Marshmallow در صورت وجود خطای اعتبارسنجی، یک استثنا ValidationError پرتاب می‌کند. این استثنا شامل یک ویژگی messages است که یک دیکشنری حاوی جزئیات خطاهاست:

from marshmallow import ValidationError

@app.route('/api/data', methods=['POST'])
def process_data_marshmallow():
    json_data = request.get_json()
    schema = MySchema()
    try:
        validated_data = schema.load(json_data)
        # ... پردازش داده‌ها
        return jsonify(validated_data), 200
    except ValidationError as err:
        return jsonify({'errors': err.messages}), 400

مدیریت خطاها در Pydantic

مشابه Marshmallow، Pydantic نیز در صورت عدم موفقیت اعتبارسنجی، یک ValidationError پرتاب می‌کند. ویژگی errors() در شیء استثنا، یک لیست از دیکشنری‌ها را برمی‌گرداند که هر دیکشنری جزئیات یک خطا را شامل می‌شود:

from pydantic import ValidationError

@app.route('/api/item', methods=['POST'])
def create_item_pydantic():
    json_data = request.get_json()
    try:
        item = ItemModel(**json_data)
        # ... پردازش item
        return jsonify(item.model_dump()), 200 # یا item.dict() در Pydantic v1
    except ValidationError as e:
        return jsonify({'errors': e.errors()}), 400

هر عنصر در لیست e.errors() به طور معمول دارای کلیدهایی مانند loc (مکان خطا، یعنی فیلد), msg (پیام خطا) و type (نوع ولیدیتور) است. این اطلاعات می‌تواند برای نمایش خطاها به کاربر مفید باشد.

نکات تکمیلی برای مدیریت خطاها:

• ثبت خطاها (Logging): همیشه خطاهای اعتبارسنجی را در لاگ‌های برنامه خود ثبت کنید. این می‌تواند به شناسایی الگوهای ورودی مخرب یا مشکلات رایج کاربران کمک کند.
• بین‌المللی‌سازی (Internationalization - i18n): برای برنامه‌های چندزبانه، پیام‌های خطا باید قابل ترجمه باشند. کتابخانه‌های اعتبارسنجی معمولاً از این قابلیت پشتیبانی می‌کنند یا با ابزارهای i18n Flask (مانند Flask-Babel) یکپارچه می‌شوند.
• یکپارچگی در فرمت: سعی کنید فرمت پاسخ خطای خود را در سراسر برنامه یکسان نگه دارید تا کلاینت‌ها بتوانند به طور سازگار با آن برخورد کنند.
• عدم افشای اطلاعات حساس: هرگز اطلاعات حساس یا جزئیات پیاده‌سازی داخلی (مانند tracebacks) را در پیام‌های خطای عمومی نمایش ندهید.

مدیریت خطای مؤثر یک بخش حیاتی از ساخت یک برنامه Flask قوی و کاربرپسند است. با انتخاب کدهای وضعیت HTTP مناسب و ارائه پیام‌های خطای واضح و ساختاریافته، می‌توانید تجربه کاربری را به میزان قابل توجهی بهبود بخشیده و به توسعه‌دهندگان کلاینت کمک کنید تا به طور مؤثرتری با API شما تعامل داشته باشند.

بهترین روش‌ها و نکات پیشرفته برای اعتبارسنجی جامع

پیاده‌سازی اعتبارسنجی ورودی به تنهایی کافی نیست؛ باید اطمینان حاصل شود که این اعتبارسنجی جامع، ایمن و قابل نگهداری است. در ادامه به بهترین روش‌ها و نکات پیشرفته‌ای می‌پردازیم که به شما کمک می‌کنند تا سیستم اعتبارسنجی قوی‌تری در برنامه‌های Flask خود بسازید.

اعتبارسنجی در لایه‌های مختلف (Layered Validation)

اعتبارسنجی نباید فقط در یک نقطه از برنامه انجام شود. یک رویکرد دفاعی عمیق (Defense in Depth) شامل اعتبارسنجی در چندین لایه است:

1. اعتبارسنجی سمت کلاینت (Client-Side Validation): از طریق HTML5 (required, type="email", minlength, pattern) و جاوااسکریپت. این نوع اعتبارسنجی برای بهبود تجربه کاربری و ارائه بازخورد فوری است و هرگز نباید به عنوان تنها لایه امنیتی مورد اعتماد قرار گیرد، زیرا به راحتی می‌توان آن را دور زد.
2. اعتبارسنجی سمت سرور (Server-Side Validation): این لایه ضروری و غیرقابل چشم‌پوشی است. داده‌ها باید همیشه در سمت سرور اعتبارسنجی شوند، حتی اگر در سمت کلاینت اعتبارسنجی شده باشند. اینجاست که از کتابخانه‌هایی مانند Flask-WTF، Marshmallow یا Pydantic استفاده می‌شود.
3. اعتبارسنجی در لایه داده (Database/ORM Level): پایگاه داده نیز می‌تواند محدودیت‌هایی (constraints) مانند NOT NULL، UNIQUE، CHECK و انواع داده (VARCHAR, INTEGER) را اعمال کند. این یک لایه نهایی از حفاظت را فراهم می‌کند و از ذخیره داده‌های نامعتبر یا ناسازگار جلوگیری می‌نماید، حتی اگر لایه‌های بالایی به دلیل باگ یا سوءاستفاده از کار افتاده باشند. ORMها مانند SQLAlchemy می‌توانند این محدودیت‌ها را به مدل‌های شما نگاشت کنند.

جداسازی منطق اعتبارسنجی

کلاس‌های فرم (Flask-WTF) یا اسکیماها/مدل‌ها (Marshmallow/Pydantic) را به فایل‌های جداگانه منتقل کنید. این کار خوانایی، نگهداری و قابلیت استفاده مجدد کد را افزایش می‌دهد. ویوها باید فقط مسئول فراخوانی و مدیریت نتایج اعتبارسنجی باشند، نه تعریف خود قوانین اعتبارسنجی.

پاک‌سازی و نرمال‌سازی داده‌ها (Sanitization and Normalization)

اعتبارسنجی صرفاً به معنی رد کردن داده‌های نامعتبر نیست؛ بلکه شامل پاک‌سازی و نرمال‌سازی داده‌های معتبر نیز می‌شود:

• Sanitization: حذف یا خنثی کردن کاراکترهای بالقوه خطرناک. به عنوان مثال، هنگام نمایش ورودی کاربر در HTML، همیشه آن را escape کنید تا از XSS جلوگیری شود. Flask و Jinja2 به طور پیش‌فرض این کار را انجام می‌دهند، اما هنگام ذخیره در دیتابیس یا استفاده در جای دیگر باید محتاط باشید.
• Normalization: تبدیل داده‌ها به یک فرم استاندارد. به عنوان مثال، کوتاه کردن فضای خالی اضافی از ابتدا و انتهای رشته‌ها، تبدیل تمام ایمیل‌ها به حروف کوچک، یا فرمت‌بندی شماره تلفن‌ها به یک شیوه ثابت. بسیاری از فیلدهای WTForms یا Marshmallow شامل فیلترهایی برای این کار هستند.

مدیریت انواع مختلف درخواست (GET, POST, PUT, PATCH)

الزامات اعتبارسنجی ممکن است بر اساس نوع درخواست HTTP متفاوت باشد:

• GET: معمولاً پارامترهای کوئری را شامل می‌شود که اغلب برای فیلتر کردن، صفحه‌بندی یا جستجو استفاده می‌شوند. اعتبارسنجی در اینجا ممکن است شامل بررسی نوع (عدد صحیح برای page)، محدوده (page > 0) و مقادیر مجاز (sort_by فقط می‌تواند name یا date باشد) باشد.
• POST: برای ایجاد منابع جدید استفاده می‌شود. همه فیلدهای اجباری برای ایجاد یک منبع جدید باید وجود داشته باشند و اعتبارسنجی شوند.
• PUT: برای جایگزینی کامل یک منبع موجود استفاده می‌شود. معمولاً اعتبارسنجی مشابه POST است، زیرا انتظار می‌رود تمام فیلدها دوباره ارسال شوند.
• PATCH: برای به‌روزرسانی جزئی یک منبع استفاده می‌شود. در اینجا، فیلدها اغلب اختیاری هستند و فقط فیلدهایی که ارسال می‌شوند باید اعتبارسنجی شوند. کتابخانه‌هایی مانند Marshmallow با گزینه‌های partial=True در متد load() این امکان را فراهم می‌کنند. Pydantic نیز از این مفهوم پشتیبانی می‌کند.

اعتبارسنجی شرطی (Conditional Validation)

گاهی اوقات یک فیلد تنها در صورت برقراری یک شرط خاص (مثلاً مقدار یک فیلد دیگر) باید اعتبارسنجی شود. این را می‌توان با منطق سفارشی در متدهای validate() (WTForms) یا @validates_schema / @model_validator (Marshmallow/Pydantic) پیاده‌سازی کرد.

# مثال Pydantic برای اعتبارسنجی شرطی
from pydantic import BaseModel, Field, model_validator
from typing import Optional

class Event(BaseModel):
    event_type: str
    location: Optional[str] = None
    online_link: Optional[str] = None

    @model_validator(mode='after')
    def validate_event_type_fields(self):
        if self.event_type == 'in-person' and not self.location:
            raise ValueError('برای رویداد حضوری، مکان الزامی است.')
        if self.event_type == 'online' and not self.online_link:
            raise ValueError('برای رویداد آنلاین، لینک الزامی است.')
        if self.event_type == 'hybrid' and (not self.location or not self.online_link):
            raise ValueError('برای رویداد ترکیبی، مکان و لینک هر دو الزامی هستند.')
        return self

اعتبارسنجی با دسترسی به پایگاه داده (Database-backed Validation)

برای بررسی منحصر به فرد بودن نام کاربری، ایمیل یا سایر فیلدها، نیاز به کوئری زدن از پایگاه داده دارید. این نوع اعتبارسنجی باید با دقت انجام شود تا از Bottleneck شدن برنامه جلوگیری شود. این را معمولاً در ولیدیتورهای سفارشی یا متدهای validate_<field_name> انجام می‌دهند. توجه داشته باشید که این کوئری‌ها باید در یک Context مناسب (مانند درخواست وب) اجرا شوند.

تست کردن اعتبارسنجی (Testing Validation)

تست‌های واحد (Unit Tests) و تست‌های یکپارچه‌سازی (Integration Tests) قوی برای اطمینان از صحت و کامل بودن منطق اعتبارسنجی ضروری هستند. سناریوهای مختلفی را تست کنید: ورودی‌های معتبر، ورودی‌های نامعتبر (از جمله انواع مختلف خطاها)، ورودی‌های خالی، ورودی‌های بیش از حد طولانی و سناریوهای گوشه‌ای.

بین‌المللی‌سازی پیام‌های خطا (Internationalization of Error Messages)

اگر برنامه شما برای کاربران با زبان‌های مختلف در دسترس است، پیام‌های اعتبارسنجی باید قابل ترجمه باشند. Flask-Babel با Flask-WTF و سایر ابزارها می‌توانند در این زمینه کمک کنند تا پیام‌ها بر اساس زبان کاربر نمایش داده شوند.

استفاده از Data Transfer Objects (DTOs)

برای APIها، به جای استفاده مستقیم از مدل‌های ORM برای اعتبارسنجی ورودی، از DTOها (که معمولاً با Marshmallow Schemas یا Pydantic Models تعریف می‌شوند) استفاده کنید. DTOها به شما اجازه می‌دهند تا داده‌های ورودی را از مدل‌های داخلی برنامه جدا کنید و یک لایه امنیتی و انعطاف‌پذیری اضافه کنید. یک DTO می‌تواند شامل زیرمجموعه‌ای از فیلدهای یک مدل یا فیلدهایی با قوانین اعتبارسنجی متفاوت باشد که برای یک عملیات خاص طراحی شده است.

با رعایت این بهترین روش‌ها، می‌توانید یک سیستم اعتبارسنجی ورودی قوی، ایمن و قابل نگهداری در برنامه‌های Flask خود ایجاد کنید که از برنامه شما در برابر حملات محافظت کرده، یکپارچگی داده‌ها را حفظ کند و تجربه کاربری مثبتی را ارائه دهد.