التوجيه في Express وexpress.Router: المسارات والمعاملات

يربط التوجيه في Express طريقة HTTP ومسارًا بدالة معالجة: يجيب app.get('/users', handler) على طلبات GET إلى /users، وتفعل app.post() وapp.put() وapp.delete() الشيء نفسه مع الطرق الأخرى. المقطع الذي يبدأ بنقطتين، كما في /users/:id، هو معامل مسار تصل قيمته إلى req.params. ولإبقاء تطبيق متنامٍ منظمًا، ضع المسارات المترابطة في express.Router() وركّبه تحت بادئة عبر app.use('/api', router).

const express = require('express');
const app = express();
app.use(express.json());

const users = [
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Linus' },
];
let nextId = 3;

app.get('/users', (req, res) => {
    res.json(users);
});

// GET /users/2
app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) return res.status(404).json({ error: 'User not found' });
    res.json(user);
});

app.post('/users', (req, res) => {
    const user = { id: nextId++, name: req.body.name };
    users.push(user);
    res.status(201).json(user);
});

app.delete('/users/:id', (req, res) => {
    const index = users.findIndex((u) => u.id === Number(req.params.id));
    if (index === -1) return res.status(404).json({ error: 'User not found' });
    users.splice(index, 1);
    res.status(204).end();
});

app.listen(3000);

يجيب GET /users/2 بـ {"id":2,"name":"Linus"}. معاملات المسار نصوص دائمًا، ولهذا يقارن المعالج بـ Number(req.params.id). أرسل POST /users مع الجسم {"name": "Grace"} لتحصل على 201، ثم DELETE /users/1 وGET /users لترى القائمة تتغير.

express.Router() مع بادئة

الموجّه تطبيق مصغّر له مساراته وmiddleware خاص به. مساراته نسبية: المسار المكتوب /:id داخل موجّه مركّب على /api/books يجيب على /api/books/:id. في مشروع حقيقي يكون كل موجّه في ملفه الخاص وينتهي بـ module.exports = router.

const express = require('express');

// routes/books.js
const books = express.Router();
const list = [{ id: 1, title: 'Dune' }];

books.get('/', (req, res) => {
    res.json(list);
});

books
    .route('/:id')
    .get((req, res) => {
        res.json(list.find((b) => b.id === Number(req.params.id)) ?? null);
    })
    .put((req, res) => {
        res.json({ updated: req.params.id });
    })
    .delete((req, res) => {
        res.json({ deleted: req.params.id });
    });

// server.js
const app = express();
app.use('/api/books', books);

// GET /api/books/1
app.listen(3000);

يعيد GET /api/books/1 القيمة {"id":1,"title":"Dune"}. يكتب router.route('/:id') المسار مرة واحدة ويسلسل معالجًا لكل طريقة؛ أرسل PUT /api/books/1 فتحصل على {"updated":"1"}. غيّر مسار التركيب إلى /v2/books فيجيب الموجّه نفسه هناك بدلًا من ذلك.

ترتيب المسارات: أول تطابق يفوز

يجرّب Express المسارات بالترتيب الذي سجّلتها به ويتوقف عند أول مسار يرسل استجابة. مسار المعامل يلتقط أي شيء في موضعه، فالمسار الثابت المسجّل بعده لا يُبلغ أبدًا:

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

app.get('/users/:id', (req, res) => {
    res.json({ route: '/users/:id', id: req.params.id });
});

app.get('/users/new', (req, res) => {
    res.json({ route: '/users/new' });
});

// Runs only when no route above answered.
app.use((req, res) => {
    res.status(404).json({ error: `Cannot ${req.method} ${req.path}` });
});

// GET /users/new
app.listen(3000);

يجيب GET /users/new بـ {"route":"/users/:id","id":"new"}: سُجّل مسار المعامل أولًا فأخذ الطلب. انقل مسار /users/new فوق /users/:id وشغّل من جديد لتحصل على {"route":"/users/new"}. ثم أرسل GET /books لتصل إلى معالج 404 في الأسفل.

معالج 404

يجيب Express على الطلب غير المطابق بصفحة HTML خاصة به، Cannot GET /books. أما في واجهة API فتريد عادة JSON، فأضف app.use() دون مسار كآخر مسار تمامًا، كما في المثال السابق. لا يعمل إلا حين تكون كل المسارات قبله قد مرّرت الطلب. الأخطاء التي ترميها المعالجات حالة مختلفة لها معالج خاص بأربعة وسائط، تغطيه صفحة معالجة الأخطاء في Express.

صيغة المسارات في Express 5

غيّر Express 5 صيغة المسارات، ومعظم المقتطفات على الإنترنت مكتوبة لـ Express 4:

النجمة * المجردة أو ? بعد معامل ترمي TypeError عند تسجيل المسار، فلا يبدأ التطبيق.

أخطاء شائعة

تسجيل معالج 404 أولًا. يطابق app.use() دون مسار كل شيء، فيحصل كل طلب على 404. أبقِه في الأسفل.

نسيان أن البادئة تُحذف. داخل موجّه مركّب على /api، لا يتضمن req.path البادئة /api. استخدم req.originalUrl حين تحتاج المسار الكامل.

مقارنة معامل برقم. req.params.id === 1 خاطئة دائمًا لأن req.params.id هو النص '1'.