Joi لجافا سكريبت (Node.js): دليل شامل مع أمثلة عملية

مقدمة عن Joi: ما هي ولماذا تحتاجها

Joi هي مكتبة قوية للتحقق من صحة البيانات في بيئة JavaScript (Node.js). تتيح لك وصف مخططات البيانات باستخدام واجهة برمجة تطبيقات بسيطة ومعبرة، ثم التحقق من تطابق الكائنات الحقيقية مع هذه المخططات. تحظى Joi بشعبية خاصة عند تطوير الجزء الخادم من تطبيقات الويب، حيث تحتاج إلى التحقق من صحة الطلبات الواردة والإعدادات والبيانات من النماذج وأي هياكل بيانات أخرى.

الأسباب الرئيسية لاستخدام Joi:

• الأمان: تمنع دخول البيانات غير الصحيحة أو الضارة إلى تطبيقك
• وضوح الكود: مخططات Joi سهلة القراءة والفهم
• المرونة: تدعم الهياكل المتداخلة المعقدة والتحقق الشرطي والقواعد المخصصة
• التكامل: تعمل بشكل ممتاز مع Express وKoa وFastify وأطر العمل الأخرى
• أخطاء مفصلة: توفر رسائل خطأ واضحة تشير إلى الموقع الدقيق للمشكلة

تثبيت Joi

يتم تثبيت Joi في مشروع Node.js عبر npm أو yarn:

# عبر npm
npm install joi

# عبر yarn
yarn add joi

# إذا كنت تستخدم TypeScript، قم بتثبيت الأنواع (اختياري)
npm install @types/joi --save-dev

بعد التثبيت، يمكنك استيراد Joi إلى مشروعك:

const Joi = require('joi');
// أو لوحدات ES:
// import Joi from 'joi';

بداية سريعة: أول مثال للتحقق من الصحة

لنقم بإنشاء مخطط بسيط للتحقق من صحة بيانات المستخدم واختبار عمله:

const Joi = require('joi');

// تعريف مخطط التحقق
const schema = Joi.object({
    username: Joi.string()
        .alphanum()
        .min(3)
        .max(30)
        .required(),
    password: Joi.string()
        .pattern(new RegExp('^[a-zA-Z0-9]{3,30}$')),
    email: Joi.string()
        .email({ minDomainSegments: 2, tlds: { allow: ['com', 'net'] } })
});

// بيانات للتحقق
const userData = {
    username: 'john_doe',
    password: 'myPassword123',
    email: 'john@example.com'
};

// تنفيذ التحقق
const { error, value } = schema.validate(userData);

if (error) {
    console.log('خطأ في التحقق:', error.details);
} else {
    console.log('البيانات صحيحة:', value);
}

في هذا المثال، أنشأنا مخططًا لكائن بثلاثة حقول. تقوم طريقة validate() بإرجاع كائن بخاصيتين: error (إذا وجدت أخطاء) و value (البيانات التي تم التحقق منها).

الطرق الأساسية في Joi

1. Joi.string() — التحقق من النصوص

الوظيفة: تنشئ مدققًا للقيم النصية. توفر العديد من الطرق للتحقق من الطول والتنسيق والمحتوى وخصائص النص الأخرى.

المعاملات: بدون معاملات. تُرجع كائن المدقق الذي يمكن تطبيق سلسلة من الطرق عليه.

مثال:

const schema = Joi.string()
    .min(3)           // الحد الأدنى للطول 3 أحرف
    .max(10)          // الحد الأقصى للطول 10 أحرف
    .alphanum()       // أحرف وأرقام فقط
    .required();      // حقل إجباري

console.log(schema.validate('Hello'));    // { value: 'Hello' }
console.log(schema.validate('Hi'));       // { error: ... } - النص قصير جدًا
console.log(schema.validate('Hello123')); // { value: 'Hello123' }
console.log(schema.validate('Hello!'));   // { error: ... } - يحتوي على رموز خاصة

2. Joi.number() — التحقق من الأرقام

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

المعاملات: بدون معاملات. تدعم سلسلة من الطرق للتخصيص.

مثال:

const schema = Joi.number()
    .integer()       // أعداد صحيحة فقط
    .min(0)