الإقليم ٣ — من http الخام إلى Express: لماذا "إطار"؟

النبذة

في الإقليم ٢ بنيتَ خادم HTTP خاماً بـ http وحده. اشتغل — لكن لمستَ بنفسك كم كلّفك 404 واحدٌ وقراءةُ جسمٍ واحدةٍ وتمييزُ مسار. الآن نواجه السؤال الذي يولد منه كلُّ إطارِ ويب: كيف نروّض هذا التكرار دون أن نخسر فهمَ ما تحته؟ الجواب فكرةٌ واحدةٌ أنيقةٌ — سلسلةٌ من الدوال يمرّ بها كلُّ طلب — سنبنيها بأيدينا حتى يصير Express، حين نفتحه، مألوفاً لا غامضاً. القاعدة المقدّسة هنا: لا تستعمل إطاراً قبل أن تبني نواته، وإلا بقي صندوقاً أسود تثق به بلا فهم.

اللغز المستفزّ

ليش: الفكرة الواحدة — middleware (سلسلة المعالجة)

الجواب: middleware. كلُّ طلبٍ يمرّ عبر سلسلةٍ مرتّبةٍ من الدوال، لكلِّ دالةٍ نفس التوقيع:

code
(req, res, next) => { ... }

كلُّ حلقةٍ في السلسلة تفعل شيئاً بالطلب/الردّ، ثم إمّا:

• تنادي next() لتمرّر التحكّم للحلقة التالية، أو
• تنهي الطلب بـ res.json(...) فلا تنادي next (توقّفت السلسلة)، أو
• تنادي next(err) فتقفز إلى معالِج الأخطاء.

هذا كلّ شيء. لاحظ كم يلتقط هذا التجريدُ الواحد:

ليش هذا التجريد بالذات عبقريّ؟ لأنه قابلٌ للتركيب (composable): تبني سلوكاً معقّداً من دوالٍ صغيرةٍ مستقلّةٍ كلٌّ تفعل شيئاً واحداً، وترتّبها كقطعِ ليغو. وكلٌّ قابلةٌ لإعادة الاستخدام عبر المسارات. وكلٌّ قابلةٌ للاختبار وحدها. هذا هو جوهرُ "الإطار": ليس سحراً، بل عقدُ دالةٍ موحَّدٌ + مُشغِّلٌ يمرّر التحكّم بينها.

كيف: نبني Express المصغّر بأيدينا

قبل الأصل، النواة. هذا tiny-express كاملٌ على http الخام — اقرأه كاشتقاق، ثم ستبني نسختك في اللغز:

js
import http from "node:http";

function createApp() {
  const stack = [];                              // سلسلة الـ middleware/المسارات

  // تسجيل middleware عام (يمرّ به كلُّ طلب)
  function use(fn) { stack.push({ method: null, path: null, fn }); }

  // تسجيل مسارٍ بفعلٍ ومسار
  function route(method, path, fn) { stack.push({ method, path, fn }); }

  // المُشغِّل: يمرّر الطلبَ على السلسلة، حلقةً حلقة، عبر next
  function handle(req, res) {
    let i = 0;
    function next(err) {
      const layer = stack[i++];
      if (!layer) {                               // انتهت السلسلة بلا ردّ
        res.statusCode = err ? 500 : 404;
        return res.end(JSON.stringify({ success: false, message: err ? "error" : "not found" }));
      }
      // طابق الفعل والمسار (null = يطابق الكل = middleware عام)
      const okMethod = !layer.method || layer.method === req.method;
      const params = layer.path ? match(layer.path, req.url) : {};
      const okPath = !layer.path || params !== null;
      if (okMethod && okPath) {
        req.params = params || {};
        try { layer.fn(req, res, next); }         // نادِ الحلقة، ممرّراً next
        catch (e) { next(e); }                    // خطأٌ متزامن → قفزٌ لمعالِج الأخطاء
      } else {
        next(err);                                // لا يطابق → تجاوز للتالي
      }
    }
    next();
  }

  const listen = (port, cb) => http.createServer(handle).listen(port, cb);
  return { use, get: (p, fn) => route("GET", p, fn), post: (p, fn) => route("POST", p, fn), listen };
}

// مطابقة مسارٍ بمعاملاتٍ مثل /users/:id → يلتقط id
function match(pattern, url) {
  const path = url.split("?")[0];
  const pp = pattern.split("/"), up = path.split("/");
  if (pp.length !== up.length) return null;
  const params = {};
  for (let k = 0; k < pp.length; k++) {
    if (pp[k].startsWith(":")) params[pp[k].slice(1)] = decodeURIComponent(up[k]);
    else if (pp[k] !== up[k]) return null;
  }
  return params;
}

ومحلّل JSON كـ middleware — يحلّ بذرة الـ stream من الإقليم ٢:

js
function jsonBody(req, res, next) {
  if (req.method !== "POST" && req.method !== "PUT" && req.method !== "PATCH") return next();
  let body = "";
  req.on("data", (c) => (body += c));            // قطعةً قطعة (streams، الإقليم ٢)
  req.on("end", () => {
    try { req.body = body ? JSON.parse(body) : {}; next(); }
    catch { res.statusCode = 400; res.end(JSON.stringify({ success: false, message: "bad json" })); }
  });
}

استعماله — انظر كم يطابق مشروعك:

js
const app = createApp();
app.use(jsonBody);                                       // قراءة الجسم لكل طلب
app.get("/api/v1/health", (req, res) => json(res, 200, { success: true, data: { status: "ok" } }));
app.post("/api/v1/auth/register", (req, res) => {
  const { username } = req.body;                          // جاهزٌ بفضل jsonBody
  json(res, 201, { success: true, data: { username } });
});
app.get("/api/v1/curricula/:id/sprints", (req, res) =>
  json(res, 200, { success: true, data: { curriculumId: req.params.id } }));  // :id مُلتقَط!
app.listen(3000);

function json(res, code, obj) {
  const s = JSON.stringify(obj);
  res.writeHead(code, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(s) });
  res.end(s);
}

توقّف وتأمّل: بنيتَ للتوّ نواةَ Express. use، الأفعال، :params، next، قفزُ الأخطاء، محلّلُ الجسم — كلّها هنا في خمسين سطراً. Express الحقيقيّ يضيف متانةً وأداءً وميزاتٍ، لكن القلب هو هذا بالضبط. لم يعد صندوقاً أسود.

كيف: من المصغّر إلى Express الحقيقيّ

كلُّ ما بنيته يقابله شيءٌ في Express، بنفس الدلالة:

ts
import express, { Request, Response, NextFunction } from "express";
const app = express();

app.use(express.json());                    // = jsonBody، يضع req.body
app.get("/api/v1/health", (req, res) => res.status(200).json({ success: true, data: { status: "ok" } }));
app.post("/api/v1/auth/register", createUser);

• express.json() = محلّلُ جسمك، أمتنُ وأشمل. res.status(201).json(obj) = دالةُ json يدويّتك، تضبط الرمزَ والترويساتِ والجسم. req.params.id، req.query (ما بعد ?)، req.body — نفس ما ملأته بيدك.
• Request, Response, NextFunction أنواعُ TypeScript (من @types/express، تذكّر الإقليم ٢) تحرس توقيعاتك وقتَ الكتابة وتُمحى وقتَ التشغيل.

الموجِّه (Router): تقسيم السلسلة لوحدات

سلسلةٌ واحدةٌ لكل المسارات تصير فوضى. express.Router() سلسلةٌ فرعيةٌ تركّبها تحت بادئة. هذا ما يفعله مشروعك:

ts
// user.routes.ts — سلسلةٌ فرعيةٌ خاصّةٌ بالمستخدم
const router = express.Router();
router.post("/register", createUser);
export default router;

// app.ts — ركّبها تحت بادئة
app.use("/auth", routes);   // /auth + /register = POST /auth/register

(ملاحظةٌ على مشروعك: app.ts يركّبها تحت /auth بينما عقدُ الـ API يقول /api/v1. هذا أحدُ ما ستملكه وتصلحه — بادئةُ نسخةٍ موحّدة. المنهج جعلك قادراً على رؤيته.)

معالِجُ الأخطاء: الحلقة ذات الأربعة معاملات

middleware بأربعة معاملاتٍ (err, req, res, next) يُنادى فقط حين يُنادى next(err) أو (في Express 5) حين ترفض دالةٌ async. يوضع آخر السلسلة، فيوحّد كلَّ الأخطاء في مظروفٍ ورمزٍ واحد:

ts
app.use((err, req, res, next) => {
  console.error(err);
  res.status(err.status || 500).json({ success: false, message: err.message || "Internal error" });
});

Express 5 يلتقط رفضَ الـ async تلقائياً (يخصّ مشروعك)

مشروعك على Express 5. الفرق العمليّ الأهمّ عن 4: لو رمى معالِجٌ async (رُفض وعدُه)، يلتقطه Express 5 ويمرّره لمعالِج الأخطاء تلقائياً. في Express 4 كان الرفضُ غير المُلتقَط يضيع (أو يُسقط العملية)، فكنت تلفّ كلَّ معالِجٍ بـ try/catch أو بمغلِّف. هذا يبسّط متحكّماتك: ركّز على المنطق، ودع الأخطاء تتدفّق لمعالِجٍ واحد.

ليش: طبقات المتحكّم/الخدمة/المسار (فصل المسؤوليّات)

لاحظ بنية مشروعك: models/User/ فيها user.routes.ts، user.controller.ts، user.service.ts، user.schema.ts. لماذا أربعة ملفّاتٍ لا واحد؟ فصلُ مسؤوليّاتٍ مقصود، كلُّ طبقةٍ تعرف شيئاً واحداً:

• routes: خريطةٌ صرفة — أيُّ فعلٍ+مسارٍ ينادي أيَّ معالِج. لا منطق.
• controller: طبقةُ HTTP — يقرأ req، يستدعي الخدمة، يكتب res بالرمز والمظروف. لا منطقَ عملٍ هنا، فقط ترجمةٌ بين HTTP والمجال.
• service: منطقُ العمل الخالص — لا يعرف شيئاً عن req/res. يأخذ بياناتٍ نظيفة، يتعامل مع قاعدة البيانات (Prisma)، يرجّع نتيجة. قابلٌ للاختبار وحده بلا خادمٍ ولا HTTP.
• schema: عقدُ الإدخال (Zod، الإقليم ٦).

ليش يهمّك لإدارة المشروع؟ لأن الـ HTTP يجب أن يكون قشرةً رقيقة. لو خبّأتَ منطقَ التسجيل داخل req/res، لما استطعتَ اختباره ولا إعادةَ استخدامه (من سطر أوامر، من مهمّةٍ مجدولة...). الفصلُ يجعل كلَّ طبقةٍ مستقلّةً مفهومة. (ملاحظةٌ على الواقع: user.service.ts في مشروعك فارغٌ حالياً، ومنطقُ Prisma موضوعٌ مؤقّتاً في المتحكّم — هذا بالضبط نوعُ القرار الذي تملكه الآن: تنقل منطق prisma.user.create إلى الخدمة، فيبقى المتحكّم قشرةً.)

دورة حياة الطلب كاملةً (اجمع الصورة)

POST /api/v1/auth/register يمرّ بالسلسلة بالترتيب:

كلُّ صندوقٍ دالةٌ في السلسلة. هذا الخطّ هو تدفّق البيانات داخل الخادم الذي وعدتك به الخريطةُ الأم — وسنكمله من المتصفّح إلى Postgres ورجوعاً في الإقليم ٩.

كيف: middleware النظام البيئيّ في مشروعك (كلٌّ حلقةٌ في السلسلة)

تبعيّات مشروعك ليست أسماءً تُحفظ — كلٌّ middleware بدور:

• helmet: يضبط ترويساتِ أمنٍ على كل ردّ (تمنع أصنافاً من الهجمات عبر المتصفّح). حلقةٌ تضيف ترويساتٍ ثم next().
• cors: يقرّر مَن (أيُّ أصلٍ/origin) يحقّ له مناداةُ الـ API من المتصفّح. لماذا تحتاجه؟ واجهتك على localhost:5173 والـ API على localhost:3000 — أصلان مختلفان (المنفذ جزءٌ من الأصل). المتصفّح يمنع الطلبات عبر الأصول افتراضياً (Same-Origin Policy) حمايةً لك؛ cors يضيف ترويساتٍ تقول "أسمحُ لهذا الأصل". (يربط الإقليم ٠: الأصل = بروتوكول+مضيف+منفذ.)
• cookie-parser: يقرأ ترويسة Cookie ويضع req.cookies — خيارٌ لحمل الـ token (الإقليم ٧).
• express-rate-limit: يعدّ طلباتِ عميلٍ في نافذةٍ زمنية ويردّ 429 Too Many Requests عند التجاوز. لماذا على login خصوصاً؟ ضدّ تخمين كلمات المرور (brute force): مهاجمٌ يجرّب آلافَ الكلمات في الثانية؛ الحدُّ يخنقه. درسٌ أمنيٌّ حيّ، ويربط بحدود الموارد ضد DoS التي تعرفها من منهج Docker.

كلُّها — بلا استثناء — دوالٌّ بتوقيع (req, res, next) في السلسلة. حين تستوعب هذا، تتوقّف عن حفظ المكتبات وتبدأ بقراءتها.

اللغز / البناء من الصفر

الخلاصة — أين تتّصل هذه العقدة بالشجرة

الوصلة للواقع (نمط SelfLab)

افتح backend/src/app.ts:

ts
import express from "express";
import routes from "./models/User/user.routes";
const app = express();
app.use(express.json());          // = jsonBody حقّك: يملأ req.body
app.use("/auth", routes);         // يركّب موجِّهَ المستخدم تحت بادئة
export default app;

ثلاثةُ أسطرٍ تقرؤها الآن بثقة: تطبيقٌ = سلسلة؛ express.json() حلقةٌ تحلّل الجسم؛ use("/auth", routes) يركّب سلسلةً فرعية. وفي user.controller.ts، createUser(req, res) هو الحلقةُ الأخيرة — يقرأ req.body، يستدعي المنطق، يكتب res.status(201).json(...). كلُّ ما في الملفّ صار شفّافاً: لا سطرٌ فيه سحر.

ولاحظ ما ينقص (وستضيفه وأنت تملك المشروع): البادئة /api/v1 لا /auth؛ helmet/cors/rate-limit في السلسلة؛ معالِجُ أخطاءٍ موحّد؛ ونقلُ منطقِ Prisma من المتحكّم إلى user.service.ts. صرتَ تراها كلَّها، وتعرف مكانها في السلسلة.