مكتبة validator في Go: دليل شامل

1. ما هي ولماذا تحتاجها

مكتبة validator (الاسم الكامل للحزمة: github.com/go-playground/validator/v10) هي أداة قوية ومرنة للتحقق من صحة الهياكل (structs) والحقول الفردية في لغة Go. تتيح لك تعريف قواعد التحقق بشكل تصريحي (declarative) مباشرة في وسوم (tags) الهياكل، مما يجعل الكود نظيفًا وقابلًا للقراءة وسهل الصيانة. بدلاً من كتابة عشرات الأسطر من التحقق اليدوي (if-else, switch)، تقوم فقط بإضافة وسوم إلى الحقول، وتقوم المكتبة بكل العمل نيابة عنك.

لماذا تحتاجها؟ في أي تطبيق ويب، API، أو خدمة تتعامل مع إدخال المستخدم، من الضروري جدًا التحقق من صحة البيانات قبل معالجتها. بريد إلكتروني غير صحيح، اسم فارغ، عمر سالب، كلمة مرور طويلة جدًا - كل هذا قد يؤدي إلى أخطاء في المنطق، ثغرات أمنية (SQL injection, XSS) أو تعطل الخادم. validator يحل هذه المشكلة بأناقة: تحدد القواعد مرة واحدة، ثم تستدعي دالة واحدة Validate.Struct() التي تتحقق من جميع الحقول تلقائيًا.

تدعم المكتبة العشرات من أدوات التحقق المضمنة (required, min, max, email, url, uuid, oneof, len وغيرها الكثير)، كما تتيح لك إنشاء أدوات تحقق مخصصة خاصة بك. تُستخدم المكتبة بنشاط في بيئات الإنتاج، وتتمتع بأداء ممتاز (بفضل التخزين المؤقت للـ reflection)، ومتوافقة مع الأطر الشهيرة مثل Gin وEcho وFiber. إذا كنت تكتب بلغة Go وتريد تجنب الكود المتكرر (boilerplate)، فهذه المكتبة ضرورية.

2. التثبيت

يتم تثبيت المكتبة بالطريقة القياسية عبر go get. تأكد من أن لديك Go الإصدار 1.18 أو أحدث (يُوصى بـ 1.21+).

go get github.com/go-playground/validator/v10

بعد تنفيذ الأمر، ستتم إضافة الحزمة إلى ملف go.mod الخاص بك. قم باستيرادها في الكود:

import "github.com/go-playground/validator/v10"

3. البداية السريعة - مثال عملي بسيط

لنقم بإنشاء هيكل بسيط لمستخدم والتحقق من حقوله. هذا مثال بسيط يوضح الفكرة الأساسية.

package main

import (
    "fmt"
    "github.com/go-playground/validator/v10"
)

// User — هيكل مع وسوم التحقق
type User struct {
    Name  string `validate:"required,min=2,max=50"`
    Email string `validate:"required,email"`
    Age   int    `validate:"gte=0,lte=150"`
}

func main() {
    // إنشاء كائن المدقق
    validate := validator.New()

    // بيانات اختبارية
    user := User{
        Name:  "أ",               // اسم قصير جدًا
        Email: "invalid-email",   // بريد إلكتروني غير صالح
        Age:   -5,                // عمر سالب
    }

    // تنفيذ التحقق
    err := validate.Struct(user)
    if err != nil {
        // المرور عبر جميع الأخطاء
        for _, err := range err.(validator.ValidationErrors) {
            fmt.Printf("الحقل: %s, الخطأ: %s, القيمة: %v\n",
                err.Field(), err.Tag(), err.Value())
        }
    } else {
        fmt.Println("تم التحقق بنجاح!")
    }
}

مخرجات البرنامج:

الحقل: Name, الخطأ: min, القيمة: أ
الحقل: Email, الخطأ: email, القيمة: invalid-email
الحقل: Age, الخطأ: gte, القيمة: -5

كما ترى، تقوم المكتبة تلقائيًا بالعثور على جميع المخالفات وإرجاع معلومات منظمة عن كل خطأ.

4. أهم الطرق والدوال

فيما يلي 8 طرق ودوال رئيسية في المكتبة. لكل منها التوقيع والوصف ومثال عملي.

4.1. validator.New()

التوقيع: func New() *Validate

الوظيفة: إنشاء كائن مدقق جديد. هذا هو الكائن الرئيسي الذي يتم من خلاله تنفيذ جميع عمليات التحقق. يُوصى بإنشاء كائن واحد للتطبيق بأكمله.