شرح req.params وreq.query وreq.body في Express

في Express، يحمل req.params قيم المقاطع المسماة في مسار الطلب (/users/:id يعطي req.params.id)، ويحمل req.query سلسلة الاستعلام الواقعة بعد ? (/search?q=node يعطي req.query.q)، ويحمل req.body البيانات المرسلة في جسم الطلب. يُملأ req.params وreq.query في كل طلب، لكن req.body يبقى undefined حتى يقرأه محلل للجسم مثل app.use(express.json()). القيم في params وquery نصوص دائمًا.

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

app.get('/users/:userId/posts', (req, res) => {
    res.json({ params: req.params, query: req.query });
});

app.post('/users/:userId/posts', (req, res) => {
    res.status(201).json({ params: req.params, body: req.body });
});

// GET /users/7/posts?sort=new&limit=2
app.listen(3000);

يجيب الطلب الأول بـ {"params":{"userId":"7"},"query":{"sort":"new","limit":"2"}}. لاحظ علامات الاقتباس: 7 و2 نصان، فحوّلهما بـ Number() قبل إجراء عمليات حسابية أو المقارنة بأرقام. الآن غيّر الطريقة إلى POST، وأبقِ المسار /users/7/posts وأرسل الجسم {"title": "Hello", "draft": true}: الإجابة 201 مع "body":{"title":"Hello","draft":true}، حيث true قيمة منطقية حقيقية لأنها جاءت من JSON.

req.params مقابل req.query مقابل req.body

يمكن أن يحتوي المسار على عدة معاملات، ويصبح كل اسم مفتاحًا في req.params: يعطي /teams/:teamId/members/:memberId المعرّفين كليهما. والشرطة أو النقطة تفصل بينها أيضًا، فيحوّل /flights/:from-:to العنوان /flights/LAX-SFO إلى { from: 'LAX', to: 'SFO' }.

req.query مع المفاتيح المكررة والغائبة

المفتاح الذي يظهر مرتين يصبح مصفوفة، والمفتاح الغائب يكون undefined، فأعطِ الخيارات قيمًا افتراضية:

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

app.get('/products', (req, res) => {
    const page = Number(req.query.page ?? 1);
    const tags = [].concat(req.query.tag ?? []);
    res.json({ page, tags, raw: req.query });
});

// GET /products?tag=red&tag=sale
app.listen(3000);

الإجابة هي {"page":1,"tags":["red","sale"],"raw":{"tag":["red","sale"]}}. أرسل GET /products?tag=red&page=3 فيبقى tags مصفوفة، ["red"]، لأن [].concat() يحوّل النص الواحد أو المصفوفة إلى مصفوفة. يحلل Express 5 سلاسل الاستعلام بالمحلل البسيط في Node، فيعطي ?filter[size]=m المفتاح "filter[size]" لا كائنًا متداخلًا؛ أما Express 4 فكان يجعله متداخلًا.

req.body يحتاج إلى express.json()

يسلّم Node الجسم كتدفق من البايتات. يقرؤه express.json() ويحلله ويضبط req.body، لكن فقط حين يحمل الطلب Content-Type: application/json. أما نماذج HTML فترسل application/x-www-form-urlencoded، التي تحتاج express.urlencoded() بدلًا منه.

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

app.post('/signup', (req, res) => {
    const { email, name } = req.body ?? {};
    if (!email) {
        return res.status(400).json({ error: 'email is required' });
    }
    res.status(201).json({ email, name: name ?? 'anonymous' });
});

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

app.listen(3000);

أرسل POST /signup مع الجسم {"email": "ada@example.com"} فتحصل على 201 مع {"email":"ada@example.com","name":"anonymous"}. وأرسل جسمًا فارغًا فتحصل على 400. الجزء ?? {} مهم: من دونه، يرمي تفكيك undefined الخطأ TypeError مع أي طلب ليس فيه جسم JSON. وللتحقق الحقيقي من الشكل والأنواع، استخدم مكتبة مخططات مثل zod.

req.headers وreq.get()

req.headers كائن فيه كل ترويسات الطلب، بأسماء بأحرف صغيرة. وتقرأ req.get(name) ترويسة واحدة وتتجاهل حالة الأحرف، فتعيد req.get('Content-Type') وreq.get('content-type') القيمة نفسها. وهذه خصائص أخرى ستستخدمها:

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

app.get('/whoami', (req, res) => {
    res.json({
        method: req.method,
        path: req.path,
        originalUrl: req.originalUrl,
        agent: req.get('User-Agent') ?? null,
        token: req.get('authorization') ?? null,
    });
});

// GET /whoami?debug=1
app.listen(3000);

قيمة path هي /whoami وقيمة originalUrl هي /whoami?debug=1. أضف الترويسة Authorization: Bearer abc في شريط الطلب وأرسله مرة أخرى: يصبح token هو "Bearer abc". داخل موجّه مركّب عبر app.use('/api', router)، يفقد req.path البادئة /api بينما يحتفظ بها req.originalUrl (تشرح صفحة التوجيه في Express التركيب).

أخطاء شائعة

قراءة req.body في طلب GET. لا ترسل المتصفحات ومعظم العملاء جسمًا مع GET. ضع خيارات GET في سلسلة الاستعلام.

فحص علامة في الاستعلام على أنها قيمة صحيحة. يعطي ?admin=false النص 'false'، وهو truthy، فيمر if (req.query.admin). قارن النصوص: req.query.admin === 'true'.

إرسال JSON دون الترويسة. العميل الذي يرسل JSON على أنه text/plain يحصل على req.body === undefined. اضبط Content-Type: application/json لدى العميل.