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

UUID (المُعرّف الفريد الشامل) هو معيار تعريف يُستخدم في تطوير البرمجيات لإنشاء مفاتيح فريدة دون الحاجة إلى إدارة مركزية. توفر مكتبة uuid في JavaScript (Node.js) طريقة بسيطة وموثوقة لتوليد UUID من الإصدارات 1 و3 و4 و5 و7 (في الإصدارات الحديثة). تُعد هذه المكتبة من أشهر المكتبات وأكثرها تحميلاً في نظام Node.js البيئي، حيث تتجاوز تحميلاتها 50 مليون مرة أسبوعياً.

لماذا تحتاجها؟ في التطوير الحديث، تحتاج كل تطبيق تقريباً إلى معرفات فريدة: لسجلات قواعد البيانات، تعريف المستخدمين، الجلسات، الطلبات، الملفات وغيرها. استخدام UUID يمنع التصادم (تطابق المعرفات) حتى في الأنظمة الموزعة حيث تُولد عدة خوادم معرفات في وقت واحد. مثلاً، إذا كان لديك بنية خدمات مصغرة حيث ينشئ كل خدمة سجلات بشكل مستقل، فإن UUID يضمن ألا ينشئ خادمان سجلين بنفس المعرف.

تدعم مكتبة uuid عدة إصدارات من المعيار: v1 (يعتمد على الوقت وعنوان MAC)، v4 (توليد عشوائي)، v7 (طابع زمني + بيانات عشوائية — معيار جديد مُحسّن لقواعد البيانات). الإصدار 4 هو الأكثر شيوعاً لبساطته ودرجة تفرده العالية. يُوصى باستخدام الإصدار 7 للمشاريع الجديدة لأنه يوفر ترتيباً زمنياً طبيعياً، مما يحسن أداء الفهارس في قواعد البيانات.

2. التثبيت

يتم تثبيت مكتبة uuid في مشروع Node.js عبر npm (مدير حزم Node). افتح الطرفية في المجلد الجذري لمشروعك ونفّذ الأمر التالي:

npm install uuid

إذا كنت تستخدم yarn:

yarn add uuid

بعد التثبيت، ستكون المكتبة متاحة للاستيراد في الكود الخاص بك. بالنسبة لمشاريع TypeScript، تتوفر الأنواع (تُثبّت تلقائياً مع الحزمة).

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

أنشئ ملفاً باسم example.js وأضف الكود التالي:

import { v4 as uuidv4 } from 'uuid';

// توليد UUID v4 واحد
const myUUID = uuidv4();
console.log('المُعرّف UUID المُولّد:', myUUID);
// مثال على المخرجات: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

شغّل الملف باستخدام الأمر node example.js. ستظهر قيمة UUID مولّدة في وحدة التحكم. هذا مثال بسيط يوضح الوظيفة الأساسية للمكتبة — توليد معرف واحد.

4. الدوال الأساسية

توفر مكتبة uuid عدة دوال لتوليد UUID من إصدارات مختلفة. دعنا نستعرض كل منها بالتفصيل.

4.1. v1() — UUID الإصدار 1 (المعتمد على الوقت)

التوقيع: v1(options?, buffer?, offset?)

الوصف: يُولّد UUID من الإصدار 1، والذي يتضمن طابعاً زمنياً (فواصل زمنية مقدارها 100 نانوثانية منذ 15 أكتوبر 1582) وعنوان MAC للجهاز. هذا يضمن التفرد عبر الزمان والمكان. لكن استخدام عنوان MAC قد يمثل مشكلة من حيث الخصوصية.

import { v1 as uuidv1 } from 'uuid';

const uuid1 = uuidv1();
console.log('UUID v1:', uuid1);
// مثال: 'c9b1deb4-3b7d-11ec-8d3d-0242ac130003'

// مع خيارات: تعطيل عنوان MAC (استخدام عقدة عشوائية)
const uuid1NoMac = uuidv1({ node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab] });
console.log('UUID v1 بعقدة مخصصة:', uuid1NoMac);

4.2. v4() — UUID الإصدار 4 (عشوائي)

التوقيع: v4(options?, buffer?, offset?)

الوصف: يُولّد UUID عشوائياً بالكامل باستخدام أرقام عشوائية آمنة إحصائياً. هذا هو الإصدار الأكثر استخداماً في التطبيقات الحديثة، خاصة عند عدم الحاجة إلى الترتيب الزمني.

import { v4 as uuidv4 } from 'uuid';

const uuid4 = uuidv4();
console.log('UUID v4:', uuid4);
// مثال: '110ec58a-a0f2-4ac4-8393-c866d813b8d1'

// توليد عدة معرفات في مصفوفة
const uuids = Array.from({ length: 5 }, () => uuidv4());
console.log('5 معرفات UUID v4:', uuids);

4.3. v7() — UUID الإصدار 7 (الطابع الزمني + العشوائية)

التوقيع: v7(options?, buffer?, offset?)

الوصف: يُولّد UUID من الإصدار 7 (متوفر في الإصدارات الحديثة من المكتبة). يجمع بين طابع زمني (بالمللي ثانية) وبيانات عشوائية. هذا الإصدار مثالي لقواعد البيانات لأنه يدعم الترتيب الزمني الطبيعي، مما يحسن أداء فهارس B-Tree.

import { v7 as uuidv7 } from 'uuid';

const uuid7 = uuidv7();
console.log('UUID v7:', uuid7);
// مثال: '018f3e1a-2b7c-7d8e-9f0a-1b2c3d4e5f6a'

// مع خيارات مخصصة
const uuid7Custom = uuidv7({ msecs: new Date('2024-01-01').getTime() });
console.log('UUID v7 بوقت مخصص:', uuid7Custom);