Middleware في Express: كيف تعمل next() مع أمثلة

الـ middleware في Express دالة بالتوقيع (req, res, next) تعمل بين لحظة وصول الطلب ولحظة إرسال الاستجابة. يمكن لكل middleware أن يقرأ req وres أو يغيّرهما، أو ينهي الطلب بإرسال استجابة، أو يستدعي next() ليسلّم الطلب إلى الدالة التالية في الصف. يضيف app.use(fn) middleware لكل طلب، ويشغّل Express كل شيء بالترتيب الذي سجّلته به.

const express = require('express');
const app = express();

function logger(req, res, next) {
    req.startedAt = Date.now();
    console.log('1. logger:', req.method, req.url);
    next();
}

app.use(logger);

app.use((req, res, next) => {
    console.log('2. second middleware');
    next();
});

app.get('/', (req, res) => {
    console.log('3. route handler');
    res.json({ ok: true, tookMs: Date.now() - req.startedAt });
});

app.listen(3000);

تسجّل وحدة التحكم الخطوات الثلاث بالترتيب مع كل طلب، ويقرأ المسار req.startedAt، وهي خاصية أضافها المسجّل. أرسل GET /missing: يسجّل الـ middleware الاثنان مع ذلك، لأن app.use() يطابق كل مسار، ثم يجيب Express بـ 404 لأنه لم يطابق أي مسار.

نسيان next()

الـ middleware الذي لا يرسل استجابة ولا يستدعي next() يترك الطلب معلّقًا. ينتظر العميل حتى تنقضي المهلة، ولا يظهر شيء في السجلات، وهذا يجعله من أخطاء الـ middleware الشائعة. احذف next(); من logger في المثال السابق وأرسل GET / مرة أخرى: لن يحصل الطلب على إجابة أبدًا.

القاعدة بسيطة: كل مسار تنفيذ داخل الـ middleware ينتهي بواحد بالضبط من هذه:

• next() للمتابعة،
• next(err) للقفز إلى معالج الأخطاء (راجع معالجة الأخطاء في Express)،
• استجابة مثل res.json() أو res.status(401).send().

استدعاء next() بعد إرسال استجابة خطأ أيضًا. يحاول المعالج التالي إرسال استجابة ثانية فيرمي Express الخطأ ERR_HTTP_HEADERS_SENT. اكتب return res.status(401).json(...) لتتوقف الدالة عندها.

فحص مصادقة يوقف الطلب

الـ middleware الذي يرفض طلبًا يرسل الاستجابة بنفسه ولا يستدعي next() أبدًا. مرّره كوسيط إضافي إلى مسار لتحمي ذلك المسار وحده:

const express = require('express');
const app = express();

function requireApiKey(req, res, next) {
    if (req.get('x-api-key') !== 'secret123') {
        return res.status(401).json({ error: 'Missing or wrong API key' });
    }
    req.client = 'reporting-app';
    next();
}

app.get('/public', (req, res) => {
    res.json({ message: 'Anyone can read this' });
});

app.get('/admin/stats', requireApiKey, (req, res) => {
    res.json({ users: 42, caller: req.client });
});

// GET /admin/stats
app.listen(3000);

يحصل الطلب الأول على 401 مع {"error":"Missing or wrong API key"}. أضف الترويسة x-api-key: secret123 في شريط الطلب وأرسله مرة أخرى: الإجابة الآن {"users":42,"caller":"reporting-app"}. ولا يشغّل /public الفحص أبدًا.

أين يعمل الـ middleware

الترتيب جزء من المعنى. المسجّل المسجَّل بعد المسارات لا يسجّل أبدًا الطلبات التي أجابتها تلك المسارات، لأن المسار الذي يرسل استجابة لا يستدعي next(). سجّل الـ middleware العام للتطبيق، مثل التسجيل وتحليل الجسم وCORS، أولًا، ثم المسارات، ثم معالجي 404 والأخطاء.

الـ middleware المدمج

يأتي Express مع بعض دوال الـ middleware التي تضيفها بـ app.use(). محللات الجسم تملأ req.body؛ ومن دونها يكون undefined.

const express = require('express');
const app = express();

app.use(express.json());
app.use(express.urlencoded());

app.get('/', (req, res) => {
    res.send('Send POST /echo with a body');
});

app.post('/echo', (req, res) => {
    res.json({ type: req.get('content-type'), body: req.body });
});

app.listen(3000);

أرسل POST /echo مع الجسم {"name": "Ada"} فتتضمن الإجابة "body":{"name":"Ada"}. احذف سطر express.json() وأرسله مرة أخرى، فيختفي body من الإجابة: req.body هو undefined، وJSON.stringify يحذف القيم غير المعرّفة. الحزم مثل cors وhelmet وmorgan هي middleware أيضًا: تثبّتها بـ npm install وتمررها إلى app.use() بالطريقة نفسها. تغطي صفحة express.static تقديم الملفات.

أخطاء شائعة

استدعاء الـ middleware بدلًا من تمريره. يشغّل app.use(logger()) الدالة logger مرة واحدة عند بدء التشغيل ويسجّل القيمة التي تعيدها. اكتب app.use(logger). (لـ express.json() أقواس لأنها تعيد دالة middleware.)

إضافة محلل الجسم بعد المسارات. تعمل المسارات أولًا فترى req.body على أنه undefined.

توقّع أن app.use('/admin', fn) يطابق مسارًا واحدًا. يعمل أيضًا مع /admin/users وكل مسار آخر تحت /admin، ومع كل طريقة. لحماية مسار واحد، مرّر الـ middleware إلى app.get('/admin', fn, handler).