Request Body 是什麼? Request Body(請求主體)是 HTTP 請求在標頭(header)之後附帶的那一段資料,例如註冊表單送出的帳號資料、API 要新增的 JSON、上傳的檔案。第一次接觸多半是在 API 文件看到「請把參數放在 Request Body」,或是用 fetch 送 POST 時不確定該不該設定 Content-Type。本文說明 Request Body 在請求裡的位置、Content-Type 如何決定資料的解讀方式,用 Node.js 看三種常見格式實際送出的原始內容,最後說明 GET 與 DELETE 帶 Body 的規範與限制。
Request Body 是什麼:標頭之後的資料
RFC 9110(HTTP Semantics)把請求裡這段資料稱為 content,定義是「標頭區段之後,依訊息框架劃定的一串位元組」。HTTP/1.1 的 RFC 9112 則說明,請求有沒有 message body,由 Content-Length 或 Transfer-Encoding 標頭表示,而且請求的訊息框架與方法無關:有沒有 Body,不是由 GET 或 POST 這個方法名稱決定。
RFC 9112 規定 HTTP/1.1 訊息由起始行、標頭、一個空行與選用的 message body 組成,請求的起始行格式為「方法、請求目標、協定版本」。所以一個請求大致分成三塊:
| 區塊 | 內容 | 說明 |
|---|---|---|
| 請求行 | POST /api/users HTTP/1.1 | 方法、路徑(含 Query String)與協定版本 |
| 標頭 | Content-Type: application/json | 描述這個請求的資訊,包含 Body 的格式與長度 |
| Body | {"name":"Amy","age":20} | 標頭結束的空行之後的資料;沒有 Body 時這一塊不存在 |
Body 的用途由方法決定。RFC 9110 的例子是:PUT 請求的 content 代表目標資源期望的狀態;POST 請求的 content 代表要由目標資源處理的資訊。資料也可以放在網址的 Query String,兩種位置的差別可前往〈Query String 是什麼?網址查詢字串格式、URL 編碼與常見用途〉觀看;HTTP 各種請求方法的整體介紹,可前往〈淺談 HTTP 請求方法 (HTTP Request Methods):GET、POST、PUT、DELETE 基礎概念與 Fetch 入門〉。
Content-Type 決定 Body 怎麼解讀
Body 只是一串位元組,接收端要靠 Content-Type 才知道該怎麼處理。RFC 9110 §8.3 說明,Content-Type 指出資料的媒體類型,這個類型同時定義資料格式,以及接收端預期的處理方式。送出內容的一方應該帶上 Content-Type;如果沒有,接收端可以假設為 application/octet-stream,也可以自己檢查資料判斷。
Web 開發最常遇到三種:
| Content-Type | Body 長相 | 常見場景 |
|---|---|---|
application/json | {"name":"Amy"} | 前後端分離的 API |
application/x-www-form-urlencoded | user=amy¬e=hello+world | HTML 表單預設格式 |
multipart/form-data | 用 boundary 分隔的多個 part | 含檔案上傳的表單 |
HTML 表單的 method 為 post 時,表單資料就是以請求本文送出;enctype 預設是 application/x-www-form-urlencoded,表單含 type=file 的 <input> 時要改用 multipart/form-data(MDN <form> 說明)。application/x-www-form-urlencoded 的編碼規則與 Query String 相同,空白為什麼是 +,可參考上面那篇 Query String 的說明。表單 GET 與 POST 的使用場景差異,可前往〈HTML Form GET 與 POST 差異比較與常見使用場景解析〉觀看。
multipart/form-data 的結構在 RFC 7578 §4 有規範:Body 由多個以 boundary 分隔的 part 組成,boundary 以 Content-Type 的 boundary 參數提供。
用 Node.js 看三種 Body 的原始內容
下面用 Node.js 內建的 http 建立伺服器,把收到的方法、Content-Type、Content-Length 與原始 Body 印出來,再用 fetch 各送一次。http.IncomingMessage 繼承 stream.Readable,所以請求本文要用串流的方式讀取,這裡用 for await 收集所有片段。
import http from 'node:http';
const server = http.createServer(async (req, res) => {
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
const raw = Buffer.concat(chunks).toString('utf8');
console.log(`[伺服器] ${req.method} ${req.url}`);
console.log(`[伺服器] Content-Type : ${req.headers['content-type'] ?? '(沒有)'}`);
console.log(`[伺服器] Content-Length : ${req.headers['content-length'] ?? '(沒有)'}`);
console.log(`[伺服器] 原始 body : ${JSON.stringify(raw)}`);
res.setHeader('Content-Type', 'application/json');
res.end(JSON.stringify({ method: req.method, bytes: Buffer.byteLength(raw) }));
});
await new Promise((r) => server.listen(0, '127.0.0.1', r));
const base = `http://127.0.0.1:${server.address().port}`;
async function send(title, url, init) {
console.log(`\n--- ${title}`);
const res = await fetch(url, init);
console.log(`[用戶端] 回應 ${res.status}`, await res.text());
}
await send('1. JSON', `${base}/api/users`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Amy', age: 20 }),
});
await send('2. JSON 字串沒有設定 Content-Type', `${base}/api/users`, {
method: 'POST',
body: JSON.stringify({ name: 'Amy' }),
});
await send('3. URLSearchParams', `${base}/login`, {
method: 'POST',
body: new URLSearchParams({ user: 'amy', note: 'hello world' }),
});
const form = new FormData();
form.append('title', '你好');
form.append('file', new Blob(['line1\nline2'], { type: 'text/plain' }), 'a.txt');
await send('4. FormData', `${base}/upload`, { method: 'POST', body: form });
server.close();
輸出(multipart/form-data 的 boundary 每次執行都不同):
--- 1. JSON
[伺服器] POST /api/users
[伺服器] Content-Type : application/json
[伺服器] Content-Length : 23
[伺服器] 原始 body : "{\"name\":\"Amy\",\"age\":20}"
[用戶端] 回應 200 {"method":"POST","bytes":23}
--- 2. JSON 字串沒有設定 Content-Type
[伺服器] POST /api/users
[伺服器] Content-Type : text/plain;charset=UTF-8
[伺服器] Content-Length : 14
[伺服器] 原始 body : "{\"name\":\"Amy\"}"
[用戶端] 回應 200 {"method":"POST","bytes":14}
--- 3. URLSearchParams
[伺服器] POST /login
[伺服器] Content-Type : application/x-www-form-urlencoded;charset=UTF-8
[伺服器] Content-Length : 25
[伺服器] 原始 body : "user=amy¬e=hello+world"
[用戶端] 回應 200 {"method":"POST","bytes":25}
--- 4. FormData
[伺服器] POST /upload
[伺服器] Content-Type : multipart/form-data; boundary=----formdata-undici-061640962066
[伺服器] Content-Length : 268
[伺服器] 原始 body : "------formdata-undici-061640962066\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\n你好\r\n------formdata-undici-061640962066\r\nContent-Disposition: form-data; name=\"file\"; filename=\"a.txt\"\r\nContent-Type: text/plain\r\n\r\nline1\nline2\r\n------formdata-undici-061640962066--"
[用戶端] 回應 200 {"method":"POST","bytes":268}

從輸出可以看到幾件事:
Content-Type是fetch依 Body 的型別自動帶上的。 傳URLSearchParams時是application/x-www-form-urlencoded;charset=UTF-8,傳FormData時是multipart/form-data; boundary=...。WHATWG Fetch Standard 的 extract a body 步驟就是這樣規定的:字串預設為text/plain;charset=UTF-8,URLSearchParams與FormData各有對應的類型。JSON.stringify()的結果是字串,不會自動變成application/json。 第 2 組沒有設定標頭,伺服器收到的是text/plain;charset=UTF-8。如果後端依Content-Type決定要不要解析 JSON,這種請求就可能不會被當成 JSON 處理。送 JSON 時要自己加上'Content-Type': 'application/json'。Content-Length是 Body 的長度。 第 4 組伺服器印出的Content-Length是 268,與伺服器用Buffer.byteLength()算出的位元組數bytes相同;含中文的 Body 以位元組計算,不是字元數。multipart/form-data的 Body 是文字格式的 part 串接。 每個 part 有自己的Content-Disposition(欄位名稱、檔名)與可選的Content-Type,欄位之間以 boundary 隔開。
另外,Content-Type 也會影響跨來源請求:依 MDN 的 CORS 說明,簡單請求的 Content-Type 只允許 application/x-www-form-urlencoded、multipart/form-data、text/plain 三種,其他值(例如 application/json)會觸發 preflight 請求。遇到跨域錯誤時,可前往〈CORS 錯誤是什麼? 如何解決本地端跨域請求 CORS Error〉觀看。
GET 與 POST 的差異:Body 放不放得進去
GET 與 POST 在「資料放哪裡」的慣用差異如下:
| 項目 | GET | POST |
|---|---|---|
| 資料位置 | 網址的 Query String | Request Body |
| 語意 | 取得目標資源目前的 representation | 請求目標資源依自己的語意處理 Body 裡的 representation |
| Body 的規範 | 沒有通用定義的語意 | 用途由資源自行定義,例如表單資料、建立新資源 |
RFC 9110 §9.3.3 對 POST 的用途舉了幾個例子,包含把 HTML 表單欄位這類資料交給資料處理程序、建立尚未識別的新資源。所以常見的 API 設計慣例是查詢條件放 Query String、要新增的資料放 Body。要注意,這是慣例與語意,不是技術上的限制:下一節會看到,Body 能不能送出,在不同工具裡的規則並不一樣。
GET 與 DELETE 帶 Body 會怎樣
RFC 9110 對 GET 與 DELETE 的描述幾乎相同:
- GET(§9.3.1):雖然請求的訊息框架與方法無關,GET 請求裡的 content 沒有通用定義的語意,不能改變請求的意義或目標,部分實作甚至可能因為 request smuggling 的風險而拒絕請求並關閉連線。用戶端不應該產生帶 content 的 GET,除非直接對已經表明支援的 origin server 發送。
- DELETE(§9.3.5):同樣沒有通用定義的語意,用戶端不應該產生帶 content 的 DELETE,除非直接對已經表明支援的 origin server 發送。
規範沒有說「不可能」,而是說「沒有通用語意、不該依賴」。實際行為取決於用戶端函式庫與伺服器,下面用同一個伺服器再看三種情況:
// 接續上一段程式的 server、base 與 send(),在 server.close() 之前執行
await send('5. GET 帶 body(fetch)', `${base}/api/users`, { method: 'GET', body: '{"a":1}' })
.catch((e) => console.log(`[用戶端] ${e.name}: ${e.message}`));
await send('6. DELETE 帶 body(fetch)', `${base}/api/items`, {
method: 'DELETE',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ids: [1, 2, 3] }),
});
console.log('\n--- 7. GET 帶 body(用 node:http 直接送)');
await new Promise((resolve, reject) => {
const r = http.request(`${base}/api/users`, { method: 'GET', headers: { 'Content-Type': 'application/json', 'Content-Length': 7 } }, (res) => {
let t = ''; res.on('data', (d) => (t += d)); res.on('end', () => { console.log(`[用戶端] 回應 ${res.statusCode}`, t); resolve(); });
});
r.on('error', reject);
r.end('{"a":1}');
});
--- 5. GET 帶 body(fetch)
[用戶端] TypeError: Request with GET/HEAD method cannot have body.
--- 6. DELETE 帶 body(fetch)
[伺服器] DELETE /api/items
[伺服器] Content-Type : application/json
[伺服器] Content-Length : 15
[伺服器] 原始 body : "{\"ids\":[1,2,3]}"
[用戶端] 回應 200 {"method":"DELETE","bytes":15}
--- 7. GET 帶 body(用 node:http 直接送)
[伺服器] GET /api/users
[伺服器] Content-Type : application/json
[伺服器] Content-Length : 7
[伺服器] 原始 body : "{\"a\":1}"
[用戶端] 回應 200 {"method":"GET","bytes":7}

fetch不允許 GET 與 HEAD 帶 Body。 WHATWG Fetch Standard 的 Request 建構步驟規定,方法是GET或HEAD又有 body 時要丟出TypeError,所以第 5 組在用戶端就失敗,請求根本沒送出。fetch送 DELETE 帶 Body 沒有被擋。 第 6 組伺服器收得到完整的 JSON。- Node.js 的
http模組可以送出帶 Body 的 GET。 第 7 組伺服器也收得到,這符合「訊息框架與方法無關」的說法;但收得到不代表途中的其他實作也會接受,RFC 提到有些實作會拒絕這類請求。
實務上的做法:需要傳一組條件查詢時,把條件放進 Query String;條件太多或不適合放網址時,改成 POST 並把條件放在 Body。批次刪除怎麼設計、為什麼不建議直接依賴 DELETE 的 Body,可前往〈RESTful API 請求方法怎麼選?HTTP 各方法優缺點比較、冪等性與串接避坑要點〉觀看。
使用 Request Body 的注意事項
送什麼格式就設定對應的 Content-Type
用 fetch 傳 JSON 時,要自己加上 application/json 標頭;傳 FormData 時不要手動設定 Content-Type,讓 fetch 自動產生。Content-Type 裡的 boundary 要和 Body 裡的分隔字串一致(RFC 7578),由 fetch 產生時兩者會成對,手動設定容易對不上。
伺服器要依 Content-Type 解析,並驗證內容
Content-Type 是用戶端自己填的標頭,伺服器不能假設它一定正確,也不能因為 Body 來自自己的前端就信任它。內容的型別與範圍都要驗證;把 Body 的值拼進 SQL 之類的用途,需要另外做防護,可參考〈SQL Injection 防禦:Prepared Statements〉。WAF 怎麼依規則檢查請求內容,可前往〈WAF 是什麼?網頁應用程式防火牆能擋哪些攻擊、和一般防火牆的差別〉觀看。
機密資料不要放在網址
網址會被瀏覽器歷史紀錄與伺服器日誌記錄,所以密碼、Token 這類資料不應放在 Query String,原因與官方規範可前往〈Query String 是什麼?網址查詢字串格式、URL 編碼與常見用途〉觀看。Token 該放在哪裡、各種 Token 的用途,可前往〈Access Token 是什麼?存取權杖的用途,與 Bearer Token、Refresh Token 的差異〉觀看;JWT 的結構,可前往〈JWT 是什麼?JSON Web Token 結構(Header、Payload、Signature)與驗證流程〉觀看。
參考資料與延伸閱讀
- RFC 9110:HTTP Semantics(§6.4 Content、§6.4.1 Content Semantics、§8.3 Content-Type、§9.3.1 GET、§9.3.3 POST、§9.3.5 DELETE)
- RFC 9112:HTTP/1.1(§6 Message Body)
- RFC 7578:Returning Values from Forms: multipart/form-data(§4 Definition of multipart/form-data)
- WHATWG Fetch Standard(Request 建構步驟、extract a body)
- MDN:
<form>元素 - MDN:Cross-Origin Resource Sharing (CORS)
- Node.js v22 文件:HTTP(
http.IncomingMessage) - 站內延伸閱讀:〈Query String 是什麼?網址查詢字串格式、URL 編碼與常見用途〉、〈HTML Form GET 與 POST 差異比較與常見使用場景解析〉、〈RESTful API 請求方法怎麼選?HTTP 各方法優缺點比較、冪等性與串接避坑要點〉、〈CORS 錯誤是什麼? 如何解決本地端跨域請求 CORS Error〉
發佈留言