إنشاء وتشغيل مشروع Koa.js باستخدام ServBay

يُعد ServBay بيئة تطوير ويب محلية متكاملة تدعم macOS وWindows، فهو يجمع العديد من الحزم والأدوات التي يستخدمها المطورون مثل بيئة Node.js وقواعد بيانات متعددة. في هذا الدليل، ستتعلم كيف تستفيد من مزايا ServBay لتأسيس وإدارة مشروعك باستخدام إطار عمل Koa.js بسهولة وسرعة.

ما هو Koa.js؟

Koa.js هو إطار عمل ويب متقدم يعتمد على Node.js وطُوّر من قِبل فريق Express.js. يشتهر ببساطته وأسلوبه التعبيري وميزاته القوية، مما يجعله اختيارًا مثاليًا لبناء تطبيقات الويب وواجهات البرمجة (APIs). يستثمر Koa.js خصائص JavaScript الحديثة، وخاصة بناء الجمل async/await، ليبسّط إدارة العمليات غير المتزامنة وكتابة البرمجيات الوسيطة، ما يجعل الكود أوضح وأسهل في الصيانة.

أهم ميزات Koa.js

• مصمم حول async/await: يعتمد تصميم كوا الأساسي على أسلوب async/await للتحكم الواضح في سير العمليات غير المتزامنة.
• نواة خفيفة الوزن: يحتوي Koa على مكتبة أساسية صغيرة توفر الوظائف الأساسية فقط، ويمكن توسيعها باستخدام البرمجيات الوسيطة (middlewares).
• برمجيات وسيطة قوية: يستخدم آلية البرمجيات الوسيطة المتسلسلة (cascading)، فيضمن مرونة ووضوح معالجة الطلبات.
• مخصص لتطبيقات الويب: يركز على تطوير تطبيقات وخدمات الويب فقط دون وظائف غير ضرورية.

باستخدام Koa.js، يستطيع المطورون بناء خدمات ويب عالية الأداء ويسهل تطويرها وصيانتها.

إنشاء بيئة تطوير Koa.js باستخدام ServBay

يوفر ServBay بيئة جاهزة للعمل لمطوري Node.js، حيث يدمج وقت تشغيل Node.js وخدمات قواعد البيانات الأساسية. بفضل ميزة المواقع (Website) ضمن ServBay، يمكنك إعداد اسم نطاق خاص وشهادة SSL لدخول مشروعك المحلي بـ Koa.js بصورة آمنة وسهلة.

المتطلبات الأساسية

قبل البدء، تأكد من إتمام الخطوات التالية:

1. تثبيت ServBay: زر الموقع الرسمي لـ ServBay وحمّل أحدث نسخة وقم بتثبيتها.
2. تثبيت حزمة Node.js: افتح تطبيق ServBay وادخل إلى إدارة الحزم (Packages)، وتأكد من تثبيت نسخة Node.js المطلوبة. إذا لم تكن مثبتة، اخترها واضغط تثبيت.
3. التعرف على أساسيات استخدام ServBay: تعرف على كيفية تشغيل/إيقاف الخدمات وإدارة المواقع داخل ServBay.

إنشاء مشروع Koa.js

سنستخدم المسار الجذري الذي يوصي به ServBay لحفظ الملفات: /Applications/ServBay/www.

1. تهيئة مجلد المشروع

   افتح تطبيق الطرفية (Terminal)، انتقل إلى المجلد الجذري الخاص بالمواقع في ServBay، ثم أنشئ مجلدًا جديدًا (مثل servbay-koa-app). ادخل إليه وابدأ مشروع Node.js جديد:

   cd /Applications/ServBay/www
   mkdir servbay-koa-app
   cd servbay-koa-app
   npm init -y

   أمر npm init -y ينشئ ملف package.json افتراضي بسرعة.

2. تثبيت Koa.js

   من داخل مجلد المشروع servbay-koa-app، ثبت Koa.js وتعريفاته (في حالة استخدام TypeScript):

   npm install koa
   # إذا كنت تستخدم TypeScript يمكنك تثبيت التعريفات
   # npm install @types/koa --save-dev

3. إنشاء ملف نقطة الدخول للتطبيق

   في مجلد المشروع servbay-koa-app، أنشئ ملفًا باسم app.js وأضف عليه الكود التالي لإنشاء تطبيق Koa بسيط:

   const Koa = require('koa');
   const app = new Koa();
   
   // برمجية وسيطة لتسجيل معلومات الطلب
   app.use(async (ctx, next) => {
     const start = Date.now();
     await next();
     const ms = Date.now() - start;
     console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
   });
   
   // برمجية وسيطة لمعالجة الطلبات على المسار الرئيسي
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // تعيين المنفذ، الأولوية لمتغير البيئة PORT
   const port = process.env.PORT || 3000;
   
   // تشغيل خادم HTTP
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   هذا الكود ينشئ تطبيق Koa ويُضيف برمجيتين وسيطتين: واحدة لتسجيل مدة الطلب، والثانية للرد على الطلبات للمسار / برسالة "Hello from ServBay Koa.js App!"، ويستمع التطبيق للطلبات على المنفذ المحدد في متغير البيئة PORT أو المنفذ 3000 افتراضيًا.

الدخول في وضع التطوير

أثناء التطوير، عادةً ما تقوم بتشغيل تطبيق Koa.js محليًا باستخدام Node.js وتزور الموقع عبر ميزة المواقع (Website) في ServBay.

1. تشغيل خادم Koa.js للتطوير

   افتح الطرفية، انتقل لمجلد المشروع servbay-koa-app، ثم شغّل ملف app.js باستخدام node. لتجنب تعارض المنافذ أو تسهيل إعداد ServBay، يمكنك تحديد منفذ معين مثل 8585:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8585 node app.js

   ستشاهد رسالة مثل Koa.js server running on http://localhost:8585 تعني أن الخادم قد بدأ على المنفذ 8585. اترك النافذة مفتوحة ليظل الخادم يعمل.

2. تهيئة موقع عكس البروكسي في ServBay

   لتتمكن من الدخول إلى تطبيق Koa.js عبر اسم نطاق مخصص، عليك إعداد موقع جديد في ServBay باستخدام عكس البروكسي:

   • افتح تطبيق ServBay.
   • انتقل إلى صفحة المواقع (Website).
   • اضغط زر + في الزاوية لإضافة موقع جديد.
   • أدخل البيانات التالية:
     • الاسم: ServBay Koa.js Dev Site
     • النطاق: servbay-koa-dev.servbay.demo (يُفضل استخدام نطاق ينتهي بـ .servbay.demo ليتم إنشاء شهادة SSL تلقائيًا)
     • النوع: اختر عكس البروكسي (Reverse Proxy)
     • عنوان IP: 127.0.0.1 (يشير إلى العملية المحلية لـ Node.js)
     • المنفذ: 8585 (المنفذ الذي يستمع عليه تطبيق Koa.js)
     • المجلد الجذر: هذا الحقل غير مهم للعكس البروكسي ويمكن تركه فارغًا أو إدخال مسار المشروع /Applications/ServBay/www/servbay-koa-app.
   • احفظ الإعدادات.
   • قد يُطلب منك تطبيق التغييرات، وافق عليها.

   بعد الإعداد، سيقوم ServBay تلقائيًا بتحديث ملف hosts المحلي لربط النطاق servbay-koa-dev.servbay.demo بـ 127.0.0.1. وستتم إعادة توجيه الطلبات القادمة لهذا النطاق إلى منفذ 8585 عبر Caddy أو Nginx. ولأنك تستخدم نطاق .servbay.demo، ستُوقّع ServBay تلقائيًا شهادة SSL ويُثق بها في النظام.

   لمزيد من التفاصيل، راجع قسم إضافة موقع تطوير Node.js في وثائق ServBay (اختر النسخة الإنجليزية).

3. زيارة موقع تطوير Koa.js

   افتح متصفحك، واكتب https://servbay-koa-dev.servbay.demo.

   إذا كانت الإعدادات صحيحة، سترى رسالة "Hello from ServBay Koa.js App!" مما يدل أنك تصل لخادم Koa.js عبر ميزة المواقع في ServBay. بعد تعديل ملف app.js وإعادة تشغيل التطبيق، سيظهر أي تغيير بمجرد تحديث الصفحة.

نشر نسخة الإنتاج (محاكاة)

عند محاكاة بيئة الإنتاج، قد تحتاج لتغيير المنفذ، القيم البيئية أو طريقة التشغيل. ويمكن استخدام إعدادات عكس البروكسي في ServBay بنفس الطريقة.

1. تشغيل تطبيق Koa.js الإنتاجي (محاكاة)

   افتح نافذة طرفية جديدة، أوقف الخادم السابق إذا كان يعمل، ثم ابدأ التطبيق بوضع الإنتاج عبر منفذ مختلف مثلاً 8586 مع الاعتماد على متغير البيئة NODE_ENV:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8586 NODE_ENV=production node app.js

   سيعمل التطبيق على منفذ 8586 محاكيًا بيئة الإنتاج.

2. تهيئة موقع عكس البروكسي لمحاكاة الإنتاج في ServBay

   بنفس الأسلوب، أنشئ موقعًا جديدًا في ServBay لمحاكاة الإنتاج:

   • افتح ServBay، اذهب لصفحة المواقع (Website).
   • اضغط زر + لإضافة موقع جديد.
   • أدخل الإعدادات التالية:
     • الاسم: ServBay Koa.js Prod Site
     • النطاق: servbay-koa-prod.servbay.demo (أو اسم نطاقك الحقيقي، ويمكن طلب شهادة SSL مجانية عبر Let's Encrypt)
     • النوع: عكس البروكسي (Reverse Proxy)
     • عنوان IP: 127.0.0.1
     • المنفذ: 8586
     • المجلد الجذر: فارغ أو أدخل مسار المشروع.
   • احفظ وطبّق التغييرات.

   عند استخدام نطاق .servbay.demo ستتم مواصلة استخدام شهادة ServBay المحلية. وإذا استخدمت النطاق العام الخاص بك، يدعم ServBay كذلك شهادات SSL/TLS المجانية عبر بروتوكول ACME مثل Let's Encrypt. لمزيد من التفاصيل، راجع قسم استخدام SSL لحماية الموقع.

3. زيارة موقع Koa.js الإنتاجي (محاكاة)

   افتح متصفحك وتوجه إلى https://servbay-koa-prod.servbay.demo.

   ستظهر لك نفس الصفحة كما في بيئة التطوير، لكن هذه المرة عبر عكس البروكسي لمنفذ الإنتاج الجديد.

ربط قواعد البيانات

يدمج ServBay عدة قواعد بيانات مشهورة مثل MongoDB، Redis، MariaDB (متوافق مع MySQL)، وPostgreSQL. يمكن ربط مشاريع Koa.js بهذه القواعد بسهولة إذ كلها تعمل محليًا وتُقبل الوصول عبر localhost بإعداداتها الافتراضية.

فيما يلي أمثلة لكيفية ربط قواعد البيانات باستخدام Node.js (تأكد أولاً من تثبيت الحزمة وتفعيل الخدمة عبر الحزم (Packages) في ServBay):

1. ربط MongoDB

   بدايةً ثبّت حزمة Node.js المناسبة مثل mongoose أو mongodb:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # أو npm install mongodb

   ثم أضف كود الاتصال للمشروع:

   // الاتصال بـ MongoDB باستخدام Mongoose
   const mongoose = require('mongoose');
   
   // إعداد اتصال افتراضي بدون مصادقة مع قاعدة بيانات باسم مخصص
   mongoose.connect('mongodb://localhost:27017/servbay-koa-app', {
     useNewUrlParser: true,
     useUnifiedTopology: true
   })
   .then(() => console.log('Connected to MongoDB'))
   .catch(err => console.error('MongoDB connection error:', err));
   
   // ملاحظة: في التطبيق الواقعي غالبًا توضع عملية الاتصال ضمن منطق بدء التطبيق،
   // وتبدأ الاستماع للطلبات بعد نجاح الاتصال.

   MongoDB الافتراضية ضمن ServBay تستمع على المنفذ 27017 وبدون كلمة مرور.

2. ربط Redis

   ثبّت مكتبة Redis:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install redis

   وكود الاتصال:

   // الاتصال بـ Redis عبر مكتبة redis
   const redis = require('redis');
   
   // إنشاء العميل؛ الاتصال افتراضيًا بـ localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // منفذ Redis الافتراضي في ServBay هو 6379
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // بدء الاتصال
   client.connect();
   
   // ملاحظة: في التطبيقات الواقعية يُفضّل انتظار نجاح الاتصال قبل بدء العمليات.
   // وغالبًا تستخدم async/await مع client.connect()

   Redis الافتراضي في ServBay يعمل بدون كلمة مرور على المنفذ 6379.

3. ربط MariaDB (أو MySQL)

   MariaDB متوافقة مع MySQL. ServBay يأتي بها جاهزة.

   ثبت حزمة الاتصال:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # أو npm install mysql2 (الأفضل من ناحية التوافق)

   مثال الاتصال عبر mariadb:

   // الاتصال بـ MariaDB عبر مكتبة mariadb
   const mariadb = require('mariadb');
   
   // كلمة مرور المستخدم root الافتراضية هي 'password'
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // تأكد من إنشاء قاعدة البيانات
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB");
       conn.release(); // إعادة الاتصال إلى الحوض
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // ملاحظة: الحصول على الاتصال يتم بشكل غير متزامن

   مثال باستخدام mysql2 (الموصى به):

   // الاتصال بـ MariaDB/MySQL عبر مكتبة mysql2 بنهج الوعود (Promises)
   const mysql = require('mysql2/promise');
   
   // كلمة مرور root الافتراضية هي 'password'
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // تأكد من إنشاء قاعدة البيانات
     waitForConnections: true,
     connectionLimit: 10,
     queueLimit: 0
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB/MySQL using mysql2");
       conn.release();
     })
     .catch(err => {
       console.error("MariaDB/MySQL connection error:", err);
     });
   
   // ملاحظة: يُفضّل إدارة كلمات المرور عبر متغيرات البيئة وليس داخل الكود.

   MariaDB الافتراضية تعمل على المنفذ 3306 وكلمة مرور root موجودة في واجهة ServBay الإدارية. قد يلزم إنشاء قاعدة البيانات يدويًا من خلال ServBay أو أي أداة مثل TablePlus أو DBeaver.

4. ربط PostgreSQL

   ثبت حزمة الاتصال:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install pg

   كود الاتصال:

   // الاتصال بـ PostgreSQL عبر مكتبة pg
   const { Pool } = require('pg');
   
   // كلمة مرور المستخدم الافتراضي هي 'password'
   const pool = new Pool({
     user: 'user', // المستخدم الافتراضي في ServBay
     host: 'localhost',
     database: 'servbay_koa_app', // تأكد من إنشاء قاعدة البيانات
     password: 'password', // كلمة المرور الافتراضية
     port: 5432, // المنفذ الافتراضي لـ PostgreSQL في ServBay
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release();
   });
   
   // ملاحظة: كلمة المرور تظهر في إعدادات ServBay ويمكن تغييرها.
   // تجنب تخزينها صراحة في الكود للمشاريع الواقعية.

   PostgreSQL الافتراضي يعمل على المنفذ 5432. ستحتاج غالبًا لإنشاء قاعدة البيانات يدويًا وعليك مراجعة ServBay لمعرفة اسم المستخدم وكلمة المرور الأساسيين.

إدارة قواعد البيانات عبر واجهة ServBay

بجانب ربط القواعد برمجيًا، يمكنك استخدام برامج رسومية لإدارتها. معظم القواعد تعمل على 127.0.0.1 أو localhost ويكفي معرفة المنفذ وكلمة المرور الافتراضية من ServBay.

• عرض/تغيير كلمات المرور الافتراضية: عبر تطبيق ServBay، افتح إعدادات قاعدة البيانات (رمز الإعدادات بجانب كل قاعدة)، وابحث عن اسم المستخدم وكلمة المرور وقم بتغييره إذا أردت.
• إنشاء قواعد بيانات/مستخدمين: استخدم أدوات مثل TablePlus، DBeaver، pgAdmin، MongoDB Compass للاتصال والإدارة ومن ثم تنفيذ أوامر SQL أو واجهات رسومية لإنشاء القواعد والمستخدمين والجداول.

ملاحظات هامة

• تعارض المنافذ: تأكد أن المنافذ المستخدمة لتطبيقك (مثل 8585 أو 8586) غير مستخدمة من خدمات أخرى بالنظام.
• حالة ServBay: تحقق من تشغيل تطبيق ServBay وجميع الحزم وقواعد البيانات المطلوبة.
• ملف hosts: يدير ServBay الملف تلقائيًا، ولكن إن واجهت مشاكل تحقق من /etc/hosts وتأكد من وجود السجلات الصحيحة.
• جدار الحماية: تأكد من أن جدار حماية macOS أو أي برنامج خارجي لا يمنع ServBay أو Node.js من الاتصال بالشبكة.
• عرض السجلات: في حال وقوع مشكلة، راجع سجلات ServBay (تجدها غالبًا في تبويب 'السجلات' داخل التطبيق) وسجلات عملية Node.js بالطرفية لتسهيل التشخيص.

الأسئلة الشائعة (FAQ)

• سؤال: لماذا يجب استخدام عكس البروكسي في ServBay للوصول لمشروعي بـ Koa.js؟

  الإجابة: لعكس البروكسي في ServBay عدة مزايا:

  1. محاكاة بيئة الإنتاج: استخدام نطاق مخصص (مثل .servbay.demo أو نطاقك الخاص) يُشابه فعليًا طريقة الوصول الحقيقية للمواقع مباشرة بدلًا من localhost:PORT.
  2. دعم SSL: يهيئ ServBay شهادة SSL تلقائيًا لموقعك المحلي، مما يسمح لك باختبار HTTPS أثناء التطوير.
  3. إدارة موحدة: إمكانية إدارة كل مواقعك المحلية بسهولة من مكان واحد.
  4. إخفاء المنافذ: تصلك الطلبات إلى المنافذ القياسية مثل 80/443، من ثم تُوجه داخليًا لمنافذ Node.js الداخلية.

• سؤال: هل يمكنني الدخول مباشرة للمشروع من خلال localhost:PORT دون استخدام عكس البروكسي؟

  الإجابة: نعم يمكنك ذلك لتطوير واختبار المشروع. لكنك ستخسر ميزات مثل النطاق المخصص، SSL التلقائي وإدارة الموقع والسجلات ترًا. لمحاكاة البيئة الحقيقية يفضل استخدام عكس البروكسي في ServBay.

• سؤال: ما هي كلمة مرور قاعدة البيانات الافتراضية في ServBay وكيف يمكن تغييرها؟

  الإجابة: يمكنك معرفة كلمة المرور الافتراضية عبر واجهة ServBay بالضغط على رموز الإعدادات بجانب كل قاعدة بيانات، ومن ثم تعديل كلمة المرور. لأجل الأمان، ينصح بتغييرها فورًا.

الخلاصة

بعد اتباع هذا الدليل، سيصبح بإمكانك تأسيس واستخدام بيئة تطوير Koa.js بسهولة على macOS عبر ServBay. أنشأنا تطبيق Koa.js بسيط وقمنا بضبط الدخول إليه عبر البروكسي العكسي بالاعتماد على نطاقات مخصصة وSSL. كما استعرضنا ربط قواعد البيانات الأساسية بسهولة وفعالية.

يمنحك ServBay بيئة تطوير متكاملة وسهلة الإدارة، لتركز على البرمجة دون عناء الإعدادات المعقدة، ويرفع من إنتاجيتك كمطور Node.js بوضوح وكفاءة.