A `res.send()` vs `res.json()` vs `res.end()`: mikor melyiket használd?

Mindannyian ismerjük azt az érzést, amikor egy Express.js alkalmazás fejlesztése során eljutunk arra a pontra, hogy adatot kell visszaküldenünk a kliensnek. De vajon melyik metódust válasszuk? A res.send(), a res.json(), vagy a res.end() a megfelelő út? Ez a három alapvető Express.js függvény kulcsfontosságú szerepet játszik a HTTP válaszok kezelésében, de sokszor okoz fejtörést, hogy mikor melyikre van szükség. Ne aggódj, nem vagy egyedül ezzel a dilemmával! Ebben az átfogó cikkben részletesen megvizsgáljuk mindhárom metódus működését, különbségeit és optimális felhasználási eseteit, hogy legközelebb magabiztosan dönthess.

A modern webfejlesztés során a backend szerverek feladata nem csupán adatok fogadása, hanem megfelelő formában történő visszaküldése is. Az Node.js és az Express.js keretrendszer hihetetlen rugalmasságot biztosít ehhez, de a rendelkezésre álló eszközök sokfélesége néha zavart okozhat. A kulcs abban rejlik, hogy megértsük az egyes metódusok mögötti filozófiát és azt, hogy milyen automatikus folyamatokat indítanak el a háttérben. Lássuk hát, melyik eszköz mikor a legalkalmasabb!

1. A `res.send()`: A Sokoldalú Mester

A res.send() az Express.js leggyakrabban használt és egyben legrugalmasabb válaszküldő metódusa. Gyakorlatilag ez a „go-to” megoldás, ha nem vagy teljesen biztos abban, hogy pontosan milyen típusú választ szeretnél küldeni. Miért olyan sokoldalú?

Működése és Jellemzői:

Intelligens Tartalomtípus-felismerés: A res.send() megvizsgálja a neki átadott adat típusát, és ennek megfelelően automatikusan beállítja a Content-Type HTTP fejlécet.
- Ha egy String-et adsz át, akkor alapértelmezés szerint text/html-ként küldi el (ha a string HTML-címkéket tartalmaz), vagy text/plain-ként.
- Ha egy Object-et vagy Array-t adsz át, akkor automatikusan JSON formátumba konvertálja, és a Content-Type fejlécet application/json-re állítja.
- Ha egy Buffer-t adsz át, akkor application/octet-stream-ként kezeli.
ETag Generálás: Automatikusan generál egy ETag fejlécet, ami segít a böngészőknek és proxy-knak a cache-elésben, csökkentve a szerver terhelését a jövőbeni kérések során.
Egyszerű Használat: Nincs szükség manuális fejlécbeállításokra a legtöbb esetben, egyszerűen csak átadod az adatot.
Státuszkód: Alapértelmezés szerint 200 OK státuszkódot küld, de ezt könnyedén felülírhatod a res.status(statusCode).send() formában.

Mikor Használd a `res.send()`-et?

A res.send() a tökéletes választás a legtöbb esetben, különösen akkor, ha:

Egyszerű szöveges válaszokat küldesz (pl. „Hello World!”).
HTML tartalommal válaszolsz, például egy egyszerű oldalt renderelsz.
JSON adatokat küldesz vissza, de nem ragaszkodsz ahhoz, hogy explicit módon jelezd, hogy JSON-t küldesz (az Express ezt felismeri helyetted). Ez különösen hasznos gyors prototípusok vagy egyszerű API végpontok esetén.
Buffer-eket szeretnél küldeni (pl. fájlok).

Példák a `res.send()` Használatára:

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

// Egyszerű szöveges válasz
app.get('/text-message', (req, res) => {
    res.send('Ez egy egyszerű szöveges üzenet.');
});

// HTML tartalom küldése
app.get('/welcome', (req, res) => {
    res.send('<h1>Üdvözöllek az oldalamon!</h1><p>Kellemes böngészést!</p>');
});

// JSON adat küldése (Express automatikusan felismeri és konvertálja)
app.get('/user-info', (req, res) => {
    const user = {
        id: 1,
        name: 'Anna',
        email: '[email protected]'
    };
    res.send(user); // Output: {"id":1,"name":"Anna","email":"[email protected]"} with Content-Type: application/json
});

app.listen(3000, () => console.log('Server running on port 3000'));

Előnyök és Hátrányok:

Előnyök: Rendkívül rugalmas, könnyen használható, automatizált fejlécbeállítás, cache-elés támogatás.
Hátrányok: Mivel annyira intelligens, minimális overhead-et jelenthet a tartalomtípus felismerés, de ez a legtöbb esetben elhanyagolható.

2. A `res.json()`: A JSON Válaszok Специалиistája

Míg a res.send() képes JSON adatokat küldeni, a res.json() kifejezetten erre a célra lett kitalálva. Ez a metódus biztosítja, hogy a válaszod mindig érvényes JSON formátumban érkezzen meg, a megfelelő fejléc beállításával.

Működése és Jellemzői:

Explicit JSON Tartalomtípus: Mindig a Content-Type: application/json fejlécet állítja be, függetlenül attól, hogy milyen típusú adatot adtál át neki (természetesen konvertálható formátumban). Ez kritikus fontosságú API fejlesztés esetén, ahol a kliensnek pontosan tudnia kell, milyen adatformátumra számítson.
Automatikus Stringifikálás: Bármilyen JavaScript objektumot vagy tömböt, amit átadsz neki, automatikusan JSON stringgé alakít a JSON.stringify() metódussal. Még a primitív értékeket (pl. szám, boolean) is JSON formába burkolja (pl. res.json(123) -> 123 JSON-ként, res.json(null) -> null JSON-ként).
ETag Generálás: A res.send()-hez hasonlóan, ez is generál ETag fejlécet.
Státuszkód: Alapértelmezés szerint 200 OK státuszkódot küld, de itt is használható a res.status(statusCode).json().

Mikor Használd a `res.json()`-et?

A res.json() a preferált metódus minden olyan esetben, amikor az alkalmazásod egy API szerverként működik, és a kliensek (pl. frontend alkalmazások, mobil appok) JSON formátumban várják az adatokat.

RESTful API-k fejlesztésekor.
Adatok küldése frontend keretrendszerek (pl. React, Angular, Vue) felé.
Mikor biztosítani szeretnéd, hogy a válasz szigorúan JSON legyen, a Content-Type fejléc explicit beállításával.

Példák a `res.json()` Használatára:

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

// Felhasználói adatok küldése JSON formátumban
app.get('/api/users', (req, res) => {
    const users = [
        { id: 1, name: 'Anna', role: 'admin' },
        { id: 2, name: 'Béla', role: 'user' }
    ];
    res.json(users); // Output: [{"id":1,"name":"Anna","role":"admin"},{"id":2,"name":"Béla","role":"user"}] with Content-Type: application/json
});

// Hibaválasz küldése JSON formátumban, státuszkóddal
app.post('/api/create-resource', (req, res) => {
    const success = false; // Feltételezzük, hogy hiba történt
    if (!success) {
        return res.status(400).json({ error: 'Érvénytelen adatok', code: 'INVALID_INPUT' });
    }
    res.status(201).json({ message: 'Erőforrás sikeresen létrehozva' });
});

// Primitív érték küldése JSON-ként
app.get('/api/count', (req, res) => {
    res.json(123); // Output: 123 with Content-Type: application/json
});

app.listen(3000, () => console.log('Server running on port 3000'));

Előnyök és Hátrányok:

Előnyök: Garantáltan JSON formátumú válasz, explicit Content-Type, ideális API-khoz.
Hátrányok: Csak JSON-t küldhet, nem alkalmas más típusú tartalom (pl. HTML, nyers fájlok) küldésére.

3. A `res.end()`: Az Alacsony Szintű Vezérlés

A res.end() az Express.js-ben a legalacsonyabb szintű válaszküldő metódus. Valójában ez a Node.js beépített http.ServerResponse objektumának metódusa, amit az Express is használ. A fő különbség az, hogy a res.end() nem végez semmilyen automatikus fejlécbeállítást vagy tartalomtípus felismerést. Egyszerűen lezárja a válaszfolyamatot.

Működése és Jellemzői:

Folyamat Lezárása: A legfontosabb funkciója, hogy jelzi a szervernek, hogy a válaszfolyamat befejeződött, és további adatot nem fog küldeni.
Nincs Automatikus Fejléc: Nem állítja be a Content-Type fejlécet, az ETag-et vagy bármilyen más HTTP fejlécet. Ha ezekre szükséged van, manuálisan kell beállítanod őket a res.writeHead() vagy res.setHeader() metódusokkal.
Nyers Adat Küldése: Opcionálisan elfogad egy stringet vagy egy Buffer-t, amit közvetlenül elküld a válasz törzseként. Nincs automatikus átalakítás (pl. JSON stringifikálás).
Státuszkód: Ha nem állítasz be státuszkódot manuálisan (pl. res.status(statusCode) vagy res.writeHead()), akkor az alapértelmezett 200 OK-t küldi, ha van tartalma, vagy ha nincs, akkor 204 No Content-et, amennyiben azt explicit módon beállítod a res.status(204)-el.

Mikor Használd a `res.end()`-et?

A res.end()-et ritkábban használjuk közvetlenül Express.js alkalmazásokban, mivel a res.send() és res.json() sok automatikus kényelmi funkciót biztosítanak. Azonban van néhány speciális eset, amikor hasznos lehet:

Nagyon egyszerű, nyers válaszok: Amikor pontosan tudod, milyen típusú adatot küldesz, és manuálisan szeretnéd kezelni a fejlécbeállításokat a maximális kontroll vagy teljesítmény érdekében.
Válasz törzs nélküli válaszok: Például egy 204 No Content státuszkód küldésekor, ami azt jelzi, hogy a kérés sikeres volt, de nincs visszaküldendő tartalom.
Stream-ek kezelése: Fájlok stream-elésekor, vagy amikor a Node.js stream API-jával dolgozol, és a válaszfolyamatot a stream befejezésekor szeretnéd lezárni.
Custom fejléc logika: Ha nagyon specifikus, nem szabványos HTTP fejléceket kell beállítanod, mielőtt lezárod a választ.

Példák a `res.end()` Használatára:

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

// Válasz törzs nélkül, 204 No Content státuszkóddal
app.delete('/api/resource/:id', (req, res) => {
    // Erőforrás törlése a DB-ből...
    res.status(204).end(); // Sikeres törlés, nincs visszaadandó tartalom
});

// Manuálisan beállított fejléc és nyers szöveges válasz
app.get('/raw-text', (req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
    res.end('Ez egy kézzel beállított nyers szöveges válasz.');
});

// Manuálisan beállított fejléc és nyers bináris adat
app.get('/raw-buffer', (req, res) => {
    const buffer = Buffer.from([0xDE, 0xAD, 0xBE, 0xEF]);
    res.writeHead(200, {
        'Content-Type': 'application/octet-stream',
        'Content-Length': buffer.length
    });
    res.end(buffer);
});

app.listen(3000, () => console.log('Server running on port 3000'));

Előnyök és Hátrányok:

Előnyök: Maximális kontroll a válasz felett, minimális overhead, ideális speciális esetekre (pl. stream-ek, 204 válaszok).
Hátrányok: Nincsenek automatikus kényelmi funkciók, minden fejlécet manuálisan kell kezelni, hibalehetőségek a fejléc beállítások elmaradása esetén.

4. Összehasonlítás és Mikor Melyiket Válaszd?

Most, hogy részletesen áttekintettük mindhárom metódust, foglaljuk össze a legfontosabb különbségeket és a döntéshozatali szempontokat:

Jellemző	`res.send()`	`res.json()`	`res.end()`
Cél	Sokoldalú válaszküldés (HTML, szöveg, JSON, bináris)	Exkluzívan JSON válaszok küldése	Alacsony szintű válaszfolyamat lezárása
`Content-Type`	Automatikus felismerés és beállítás	Mindig `application/json`	Nincs automatikus beállítás (manuális szükséges)
Adatkezelés	Intelligens konverzió (pl. objektum -> JSON string)	Objektumok/tömbök -> JSON stringifikálás	Nyers string vagy Buffer küldése (nincs konverzió)
`ETag`	Automatikus generálás	Automatikus generálás	Nincs automatikus generálás
Használat	A legtöbb általános eset, prototípusok	API végpontok, adatátvitel	Speciális esetek (204 válasz, stream-ek, maximális kontroll)
Egyszerűség	Magas	Magas	Alacsony (több manuális lépés)

A Döntési Fa:

JSON adatot szeretnél visszaküldeni, például egy API válaszában?
- Igen: Használd a res.json()-t. Ez a legtisztább és legexplicit módja a JSON válaszok küldésének, és garantálja a megfelelő Content-Type fejlécet.
- Nem: Lépj a következő kérdésre.
Szöveges (akár HTML) tartalmat, vagy bináris adatot (pl. fájlt) szeretnél küldeni, és nem akarsz bajlódni a HTTP fejlécek manuális beállításával?
- Igen: Használd a res.send()-et. Ez intelligensen felismeri a tartalomtípust és elvégzi a szükséges beállításokat helyetted. Ez a leggyakoribb és legkényelmesebb opció a legtöbb nem-JSON válasz esetén.
- Nem: Lépj a következő kérdésre.
Nagyon alacsony szintű kontrollra van szükséged, manuálisan szeretnél minden HTTP fejlécet beállítani, vagy csak le szeretnéd zárni a válaszfolyamatot tartalom nélkül (pl. 204 No Content)?
- Igen: Használd a res.end()-et. Ne feledd, hogy a res.writeHead() vagy res.setHeader() metódusokkal manuálisan kell beállítanod a szükséges fejléceket!
- Nem: Valószínűleg visszatérhetnél az 1. vagy 2. ponthoz, mert a res.send() vagy res.json() egyike megoldja a problémádat.

5. Jó Gyakorlatok és Gyakori Hibák

Mindig küldj választ: Egy Express.js útvonal kezelőjének mindig le kell zárnia a kérést egy válaszküldő metódussal (pl. res.send(), res.json(), res.end(), res.render(), res.redirect()). Ha elfelejted, a kliens időtúllépéssel fog szembesülni, és a kérés „lógva” marad.
Csak egyszer küldj választ: Egy HTTP kérésre csak egyetlen választ lehet küldeni. Soha ne hívj meg két válaszküldő metódust ugyanabban a kérés-válasz ciklusban. Például, ha már küldtél res.send()-et, ne hívj meg utána res.json()-t. Ez hibához vagy váratlan viselkedéshez vezet. Használd a return kulcsszót a válaszküldő metódus előtt, hogy biztosítsd a függvény végrehajtásának leállítását, ha a válasz elküldésre került (pl. return res.status(400).json(...)).
Státuszkódok használata: Mindig állítsd be a megfelelő HTTP státuszkódot. A res.status(statusCode) metódus láncolható a send(), json(), vagy end() elé, hogy pontosan jelezd a kliensnek a kérés eredményét (pl. 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error).
res.end() óvatosan: Csak akkor használd a res.end()-et, ha pontosan tudod, mit csinálsz, és manuálisan kezeltél minden szükséges HTTP fejlécet. A legtöbb esetben a res.send() vagy res.json() jobb és biztonságosabb választás.

Összefoglalás

A res.send(), res.json() és res.end() metódusok mind elengedhetetlen részei az Express.js keretrendszernek, és mindegyiknek megvan a maga helye és szerepe a Node.js backend fejlesztésben. A legfontosabb tanulság, hogy megértsük a különbségeket a mögöttes automatizálásban és abban, hogy melyik metódus milyen fejléceket állít be számunkra.

A res.send() a svájci bicska, ami a legtöbb esetben megállja a helyét. A res.json() a speciális eszköz az API-k és strukturált adatátvitel világában. Végül, a res.end() az a precíziós szerszám, amire akkor van szükség, ha teljes kontrollt akarunk gyakorolni a HTTP válaszfolyamat felett, vagy speciális eseteket kezelünk.

Reméljük, ez az átfogó útmutató segített eloszlatni a bizonytalanságokat, és magabiztosabban fogod használni ezeket a kulcsfontosságú Express.js metódusokat a jövőbeni projektjeid során. Boldog kódolást!