HOWTO · React
在 React 中發出 POST 請求的不同方法
使用 API 對於構建任何 Web 應用程式都是必不可少的。在本文中,我們將探討如何在 React 應用程式中發出 POST 請求。
本頁內容
React 不限定使用哪一種 HTTP 用戶端。新應用程式可以先使用瀏覽器內建的 fetch();若需要更方便的回應與錯誤處理,可選擇 axios;維護既有 jQuery 程式碼時,可沿用 jQuery AJAX;若要管理 mutation 狀態,則可使用 React Query。以下範例都會將相同的示意用戶資料傳送至 https://api.example.test/profiles。這是佔位端點,並非實際服務;請替換成由你控制的 API。
使用 Fetch API
現代瀏覽器內建 fetch(),很適合用來發出簡單的 POST 請求。將方法設為 POST,以 Content-Type 標頭標明 JSON 請求本文,再用 JSON.stringify() 序列化物件。下方函式接受一個 fetch 實作,因此請求建構與回應處理都包含在範例中。範例中的本機回應僅供示範,不會連線至伺服器。
async function createProfile(fetchImpl) {
const response = await fetchImpl('https://api.example.test/profiles', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Sam Lee', role: 'developer' }),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
return response.json();
}
const demoFetch = async (url, options) => ({
ok: true,
json: async () => ({ url, method: options.method, profile: JSON.parse(options.body) }),
});
createProfile(demoFetch).then((result) => console.log(result.profile.name, result.method));
回傳的本文會將提交的用戶資料放在 profile 下,因此最後一行會讀取 result.profile.name。在元件中,可以從表單提交處理函式呼叫相同的請求邏輯,再使用元件狀態顯示結果。解析成功回應的本文之前,請先檢查 response.ok:Fetch 收到 404 或 500 等 HTTP 回應時仍會履行 promise;網路失敗時才會拒絕 promise。伺服器可能不會回傳 JSON 本文,因此只有在 API 契約承諾回應格式為 JSON 時才解析 JSON。這個示範使用記憶體中的回應,不會連線至佔位端點。
使用 Axios
在使用打包工具的應用程式中,請用套件管理器安裝 axios,並從套件匯入。它的 post(url, data) 方法接受 JavaScript 物件,並會將物件序列化為 JSON;成功取得的回應會將伺服器本文放在 response.data。下方瀏覽器範例從 esm.sh 匯入模組,讓範例內容保持完整;此範例僅供說明,尚未在此處執行。
<div id="root"></div>
<script type="module">
import React, { useState } from 'https://esm.sh/react';
import { createRoot } from 'https://esm.sh/react-dom/client';
import axios from 'https://esm.sh/axios';
function ProfileForm() {
const [profile, setProfile] = useState(null);
const [error, setError] = useState('');
async function handleSubmit(event) {
event.preventDefault();
setError('');
try {
const response = await axios.post('https://api.example.test/profiles', {
name: 'Sam Lee',
role: 'developer',
});
setProfile(response.data.profile ?? response.data);
} catch (requestError) {
const message = requestError.response
? `Request failed: ${requestError.response.status}`
: 'Network request failed';
setError(message);
}
}
return React.createElement('form', { onSubmit: handleSubmit },
React.createElement('button', { type: 'submit' }, 'Create profile'),
profile && React.createElement('p', null, `Created ${profile.name}`),
error && React.createElement('p', { role: 'alert' }, error));
}
createRoot(document.getElementById('root')).render(React.createElement(ProfileForm));
</script>
Axios 預設會在 HTTP 狀態碼表示請求未成功時拒絕 promise。處理函式會區分伺服器有回應與完全沒有收到回應的情況,並將結果存入 React 狀態,不會把錯誤當成成功取得的用戶資料回傳。若攔截器、共用設定或回應轉換能簡化大型應用程式,Axios 就很實用。只發出單一請求時,使用 Fetch 則不必額外加入相依套件。
使用 jQuery AJAX
維護已載入 jQuery 的應用程式時,使用 jQuery AJAX 最為實際。在 React 元件中,讓 React 負責渲染,並從 AJAX 回呼更新狀態;避免使用 jQuery 修改由 React 管理的 DOM 節點。下方的瀏覽器與套件範例僅供說明,尚未執行。使用這個元件前,請依照應用程式現有的套件設定加入 jQuery。
<div id="root"></div>
<script type="module">
import React, { useState } from 'https://esm.sh/react';
import { createRoot } from 'https://esm.sh/react-dom/client';
import $ from 'https://esm.sh/jquery';
function ProfileForm() {
const [profile, setProfile] = useState(null);
const [error, setError] = useState('');
function handleSubmit(event) {
event.preventDefault();
setError('');
$.ajax({
url: 'https://api.example.test/profiles',
type: 'POST',
contentType: 'application/json',
dataType: 'json',
data: JSON.stringify({ name: 'Sam Lee', role: 'developer' }),
success: (data) => setProfile(data.profile ?? data),
error: (xhr, status, requestError) => {
setError(xhr.responseJSON?.message || requestError || status);
},
});
}
return React.createElement('form', { onSubmit: handleSubmit },
React.createElement('button', { type: 'submit' }, 'Create profile'),
profile && React.createElement('p', null, `Created ${profile.name}`),
error && React.createElement('p', { role: 'alert' }, error));
}
createRoot(document.getElementById('root')).render(React.createElement(ProfileForm));
</script>
這裡的 contentType 用來描述 JSON 請求本文,而 dataType 則告訴 jQuery 預期的 JSON 回應應如何解析。成功與失敗時的回呼都會更新 React 狀態。這些選項無法保證伺服器會接受請求或回傳約定的格式。開發新的 React 功能時,Fetch 或 Axios 通常更合適,也能避免加入 jQuery 這項額外相依套件。
使用 React Query
如果元件需要共用伺服器狀態行為,或需要清楚呈現待處理、成功與錯誤 UI,React Query 可以將 POST 請求作為 mutation 管理。將網路請求放在 mutation 函式中,由使用者提交表單時觸發,並依照已安裝的程式庫版本呈現狀態。以下是與版本無關的工作流程,並非可直接複製使用的 hook 簽章:提交用戶資料 → 執行 POST mutation → 顯示待處理提示 → 顯示回傳的用戶資料或錯誤。這個概念範例尚未執行;選擇套件名稱、匯入方式、hook 簽章或狀態屬性名稱之前,請先查閱已安裝版本的 React Query 文件。
與讀取資料的 query 相比,mutation 更適合用於會變更伺服器資料的動作。成功後,請依照應用程式的資料流程更新或讓相關快取失效。所有範例都應使用一致的端點與 JSON 資料本文;也不要假設請求成功後所有檢視畫面都會自動更新。
使用 XMLHttpRequest
XMLHttpRequest 是瀏覽器 API,不需使用請求程式庫即可傳送 JSON POST。它與 Fetch 是不同的 API,儘管兩者都是瀏覽器提供的選項。下方的事件驅動瀏覽器範例僅供說明,尚未在指定的執行環境中執行。
<div id="root"></div>
<script type="module">
import React, { useState } from 'https://esm.sh/react';
import { createRoot } from 'https://esm.sh/react-dom/client';
function ProfileForm() {
const [profile, setProfile] = useState(null);
const [error, setError] = useState('');
function handleSubmit(event) {
event.preventDefault();
setProfile(null);
setError('');
const request = new XMLHttpRequest();
request.open('POST', 'https://api.example.test/profiles');
request.setRequestHeader('Content-Type', 'application/json');
request.addEventListener('load', () => {
if (request.status < 200 || request.status >= 300) {
setError(`Request failed: ${request.status}`);
return;
}
try {
const data = JSON.parse(request.responseText);
setProfile(data.profile ?? data);
} catch {
setError('The server response was not valid JSON');
}
});
request.addEventListener('error', () => setError('Network request failed'));
request.send(JSON.stringify({ name: 'Sam Lee', role: 'developer' }));
}
return React.createElement('form', { onSubmit: handleSubmit },
React.createElement('button', { type: 'submit' }, 'Create profile'),
profile && React.createElement('p', null, `Created ${profile.name}`),
error && React.createElement('p', { role: 'alert' }, error));
}
createRoot(document.getElementById('root')).render(React.createElement(ProfileForm));
</script>
load 處理函式會處理 HTTP 回應,因此會在解析本文前檢查狀態碼。error 處理函式則處理網路失敗。兩種情況都會更新 React 狀態;正式環境程式碼也應在元件卸載時中止未完成的請求,或忽略其結果。大多數新程式碼使用 Fetch 會更簡單;若要維護既有相依於 XMLHttpRequest 的程式碼,或需要事件式介面,XMLHttpRequest 仍然適用。
結論
一般的瀏覽器 POST 請求可使用 Fetch;需要用戶端功能時可選擇 Axios;若重視 mutation 狀態與快取協調,則可使用 React Query。既有 jQuery 程式碼可繼續使用 jQuery AJAX;應用程式適合事件式 API 時,也可以選擇 XMLHttpRequest。無論使用哪一種方式,都應依照伺服器 API 設定本文與標頭、檢查回應,並在 React UI 中顯示請求狀態。
常見問題
POST 請求的作用是什麼?
POST 會將資料送至伺服器處理,例如建立資源。提交資料的意義由 API 定義;POST 並不限於更新既有資源。
我應該使用 Fetch 還是 Axios?
現代瀏覽器內建 Fetch,許多請求只用 Fetch 就足夠,但程式碼必須檢查 HTTP 狀態碼,因為 HTTP 錯誤回應不會讓它的 promise 拒絕。Axios 提供一致的回應物件,並預設在 HTTP 狀態碼表示請求未成功時拒絕 promise。請依據應用程式需求與現有相依套件選擇。
我可以在 React 中使用 jQuery 嗎?
可以,尤其是在維護已使用 jQuery 的應用程式時。讓 React 管理它所渲染的 DOM,並透過 AJAX 回呼更新 React 狀態。開發新程式碼時,Fetch 或 Axios 通常更直接合適。
React Query 為 POST 請求增加了什麼?
它會將請求視為 mutation,並協助將待處理、成功與錯誤狀態連結至伺服器狀態管理。其確切 API 取決於已安裝的版本,因此實作細節請參考該版本的文件。
我應該如何處理 POST 錯誤?
請依照伺服器契約檢查 HTTP 狀態碼與回應資料,並提供清楚可見的錯誤狀態。使用 Fetch 時,請檢查 response.ok,因為 HTTP 失敗仍會產生回應。使用 Axios 時,請處理被拒絕的請求,並區分伺服器回應與網路失敗。使用 jQuery 或 XMLHttpRequest 時,請透過其錯誤或網路事件處理失敗,並更新 React 狀態。