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

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

ما هو Koa.js؟

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

أهم ميزات Koa.js

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

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

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

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

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

قبل البدء، تأكد من استيفائك لما يلي:

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

إنشاء مشروع 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. إنشاء ملف المدخل الرئيسي للتطبيق

   أنشئ ملفًا باسم app.js داخل مجلد المشروع وأضف الكود التالي لتطبيق Koa.js بسيط:

   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.

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

خلال التطوير، سنشغل عملية Node.js محلية لتشغيل تطبيق Koa.js، مع الوصول إليه عبر خاصية المواقع (Website) في ServBay.

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

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

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

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

2. إعداد موقع (Website) على ServBay باستخدام عكس البروكسي

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

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

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

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

3. الوصول لموقع تطوير Koa.js

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

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

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

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

1. تشغيل خادم الإنتاج (محاكاة)

   في نافذة طرفية أخرى، أوقف سيرفر التطوير (إن كان لا يزال يعمل)، ثم شغِّل التطبيق بوضع إعدادات الإنتاج والمعلمات المناسبة:

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

   بذلك سيعمل تطبيق Koa.js على المنفذ 8586 بوضع production.

2. إعداد موقع إنتاجي (محاكاة) في ServBay مع عكس بروكسي

   كرِّر الخطوات السابقة مع بعض التعديلات المناسبة للإنتاج:

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

   عند استخدام نطاق .servbay.demo ستحصل تلقائيًا على شهادة SSL. ومع النطاقات العامة يدعم ServBay إصدار شهادات آمنة مجانية عبر Let's Encrypt. راجع حماية الموقع بشهادات SSL لمزيد من التفاصيل.

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

   افتح المتصفح على https://servbay-koa-prod.servbay.demo

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

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

يأتي ServBay مدعّمًا بعدة قواعد بيانات شهيرة مثل MongoDB, Redis, MariaDB (متوافقة مع MySQL)، وPostgreSQL. يمكن للتطبيقات المبنية على Koa.js الربط بهذه القواعد محليًا عبر localhost بشكل مباشر.

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

1. ربط MongoDB

   أولًا، قم بتثبيت مكتبة ربط MongoDB (مثلاً mongoose أو mongodb):

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

   ثم أضف كود الاتصال في app.js أو ملف آخر:

   // استخدام Mongoose للربط مع MongoDB
   const mongoose = require('mongoose');
   
   // افتراضيًا في ServBay: لا حاجة للمصادقة، ويمكنك اختيار اسم قاعدة البيانات
   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 الخاص بـ Node.js:

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

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

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

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

3. ربط MariaDB (أو MySQL)

   MariaDB هي تفرع عن MySQL وتتمتع بتوافقية عالية معه. يوفر ServBay حزمة MariaDB، ويمكنك التعامل معها كما مع MySQL.

   لتثبيت عميل MariaDB:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # أو npm install mysql2 (موصى به لتوافقية أكبر)

   للربط باستخدام mariadb:

   // الربط مع MariaDB باستخدام مكتبة mariadb
   const mariadb = require('mariadb');
   
   // كلمة مرور مستخدم root الافتراضية في ServBay هي '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
   const mysql = require('mysql2/promise');
   
   // كلمة مرور root الافتراضية في ServBay هي '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);
     });
   
   // ملاحظة: كلمة مرور root الافتراضية يمكن معرفتها أو تعديلها من إعدادات ServBay GUI.
   // يُنصح بعدم كتابة كلمة المرور مباشرة في الكود، بل الاستفادة من متغيرات البيئة إلخ.

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

4. ربط PostgreSQL

   لتثبيت عميل PostgreSQL:

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

   وكود الربط كالتالي:

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

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

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

بجانب ربط القواعد عبر الكود، يمكنك إدارة قواعد البيانات الرسومية باستخدام أدوات مثل TablePlus, DBeaver, pgAdmin, MongoDB Compass، إذ يربطون مباشرة بمنافذ localhost الخاصة بـ ServBay وبيانات الدخول كما في الإعدادات.

• عرض/تعديل كلمة المرور الافتراضية: عبر تطبيق ServBay في قسم قواعد البيانات وبالضغط على أيقونة الإعدادات بجانب القاعدة المطلوبة.
• إنشاء قواعد بيانات أو مستخدمين: باستخدام أي من الأدوات المذكورة أو من خلال واجهات الأوامر حسب نوع القاعدة.

ملاحظات هامة

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

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

• س: لماذا أحتاج إلى استخدام عكس البروكسي من ServBay للوصول لمشروعي على Koa.js؟

  ج: لعكس البروكسي (عبر خاصية الموقع في ServBay) عدة مزايا:

  1. محاكاة بيئة الإنتاج: استخدام نطاقات مثل .servbay.demo أو نطاقك بدلًا من localhost:PORT يجعلك أقرب للتجربة الحقيقية.
  2. دعم SSL: يوفر ServBay شهادة SSL تلقائيًا لموقعك المحلي باستخدام CA داخلي أو بالتكامل مع Let's Encrypt.
  3. الإدارة الموحدة: تجمع ServBay كل مواقعك المحلية تحت إدارة واحدة مركزية.
  4. إخفاء المنفذ: يصل المتصفح أو أي مستخدم عبر 80 أو 443 تلقائيًا بينما تُحول الطلبات داخليًا لمنفذ Node.js.

• س: هل يمكنني تجاوز عكس البروكسي والوصول مباشرة عبر localhost:PORT؟

  ج: نعم، فمن الناحية التقنية تستطيع زيارة http://localhost:PORT مباشرة أثناء التطوير. لكن بهذا تفقد إمكانية استخدام النطاقات المخصصة، وميزات SSL التلقائية وإدارة السجلات من خلال ServBay، ما يجعل تجربة التطوير أقل محاكاة لبيئة الإنتاج. الأفضل استخدام عكس البروكسي من ServBay متى أمكن.

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

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

الخلاصة

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

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