Hầu hết các ứng dụng web hiện đại đều liên tục giao tiếp với máy chủ. API tìm nạp JavaScript là cách tiêu chuẩn để thực hiện điều đó và được tích hợp vào trình duyệt cũng như Node.js 18 trở lên nên không cần phải cài đặt.

Việc sử dụng cơ bản cần hai dòng, tuy nhiên nhiều hướng dẫn chỉ dừng lại ở đó và bỏ qua phần gây ra lỗi thực sự: xử lý lỗi. Chúng tôi đã thử nghiệm các ví dụ trong hướng dẫn này trên một máy chủ cục bộ nhỏ trên Node.js 24 và kết quả hiển thị là từ lần chạy đó. example.com trong mã là viết tắt của API của riêng bạn. Nếu lời hứa là điều mới mẻ đối với bạn, hãy bắt đầu với Giải thích về lời hứa JavaScript.

API tìm nạp là gì?

Tìm nạp là giao diện dựa trên lời hứa để thực hiện các yêu cầu HTTP. Nó thay thế cái cũ hơn, dựa trên cuộc gọi lại XMLHttpRequest và nhiều dự án hiện sử dụng nó thay vì thêm thư viện cho các cuộc gọi đơn giản.

Một yêu cầu NHẬN

Fetch thực hiện yêu cầu GET theo mặc định. Có hai bước và mỗi bước cần await: đầu tiên các tiêu đề phản hồi đến và sau đó bạn đọc nội dung.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

Hai bước tồn tại vì phần thân có thể lớn và đến muộn hơn các tiêu đề. Trong tập lệnh trình duyệt, cấp cao nhất await cần một mô-đun, vì vậy bạn thường sẽ đặt mô-đun này bên trong hàm async. Xem Hướng dẫn chờ đợi/không đồng bộ JavaScript của chúng tôi.

Đối tượng phản hồi

Trước khi đọc nội dung, bạn có thể kiểm tra phản hồi:

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Một nội dung chỉ có thể được đọc một lần. Gọi json() lần thứ hai không thành công trong thử nghiệm của chúng tôi:

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Nếu bạn cần đọc nó hai lần, hãy gọi response.clone() trước.

Điều ngạc nhiên lớn: 404 không ném

Đây là điều quan trọng nhất trong bài viết này. Chúng tôi đã yêu cầu một người dùng không tồn tại:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

Không có ngoại lệ nào được ném ra. Về phần tìm nạp, yêu cầu đã hoạt động: máy chủ đã được truy cập và nó đã phản hồi. Lời hứa chỉ từ chối khi không có phản hồi nào có thể sử dụng được, chẳng hạn như lỗi mạng. Vì vậy, mã như thế này có một lỗi ẩn:

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Hãy kiểm tra Bảng tóm tắt mã trạng thái HTTP của chúng tôi để biết ý nghĩa của từng mã.

Một người trợ giúp có thể tái sử dụng

Đừng lặp lại việc kiểm tra đó ở mọi nơi. Bọc nó một lần:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Bây giờ lỗi HTTP và lỗi mạng đều có kết quả giống nhau catch. Chức năng nhỏ này đáng có trong mọi dự án. Phiên bản thực cũng có thể đọc thông báo lỗi từ nội dung phản hồi và xử lý phản hồi 204 No Content, không có JSON để phân tích cú pháp.

ĐĂNG dữ liệu JSON

Truyền một đối tượng tùy chọn làm đối số thứ hai. Đối với JSON, bạn phải tự mình thực hiện hai việc: chuyển đổi dữ liệu thành chuỗi và đặt tiêu đề.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Máy chủ thử nghiệm của chúng tôi phản hồi lại loại nội dung mà nó nhận được, xác nhận rằng tiêu đề đã đến. Việc quên tiêu đề đó là nguyên nhân phổ biến gây ra lỗi máy chủ khó hiểu, vì nhiều khung công tác chỉ phân tích cú pháp JSON khi nó được khai báo. Để tải lên một biểu mẫu hoặc các tệp, hãy chuyển một đối tượng FormData làm nội dung và thực hiện không đặt Content-Type, vì trình duyệt cần tự thêm một giá trị biên.

Các phương pháp và tùy chọn khác

Lựa chọn giữa REST và các kiểu API khác? So sánh của chúng tôi về REST so với GraphQL cho thấy mức độ tìm nạp phù hợp với từng loại.

Chuỗi truy vấn

Không xây dựng chuỗi truy vấn bằng cách nối văn bản vì các ký tự đặc biệt sẽ ngắt chuỗi. URLSearchParams xử lý mã hóa cho bạn:

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

Máy chủ đã nhận được red shoes chính xác và dung lượng đã được khôi phục.

Hết thời gian chờ và hủy

Tìm nạp sẽ đợi rất lâu trên một máy chủ chậm trừ khi bạn thông báo khác. AbortSignal.timeout() đặt ra giới hạn. Điểm cuối thử nghiệm của chúng tôi mất hai giây, so với giới hạn 200 mili giây:

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Để hủy thủ công, chẳng hạn như khi người dùng rời khỏi một trang hoặc nhập cụm từ tìm kiếm mới, hãy sử dụng AbortController:

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Để chạy nhiều yêu cầu cùng một lúc, hãy sử dụng Promise.all, nhanh hơn nhiều so với việc chờ từng yêu cầu một:

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Mọi loại thất bại

Đây là hình ảnh của từng thất bại trong quá trình thực hiện của chúng tôi, cùng với cách phân biệt chúng:

Hàng cuối cùng đó là phổ biến trong sản xuất. Proxy trả về 502 thường gửi trang lỗi HTML. Chúng tôi đã sao chép lại điều này và res.json() đã ném SyntaxError. Kiểm tra response.ok trước khi phân tích cú pháp có nghĩa là bạn báo cáo vấn đề thực sự chứ không phải lỗi phân tích cú pháp khó hiểu.

CORS và thông tin xác thực

Trong trình duyệt, yêu cầu từ nguồn này đến nguồn khác phải tuân theo CORS, quy tắc chia sẻ tài nguyên giữa nhiều nguồn. Nếu bạn thấy lỗi đề cập đến Access-Control-Allow-Origin, thì cách khắc phục thuộc về máy chủ, máy chủ này phải cho phép trang web của bạn. Trong JavaScript của bạn, lỗi chỉ hiển thị dưới dạng lỗi chung TypeError, vì vậy hãy xem bảng điều khiển trình duyệt để biết lý do thực tế. Node.js không thực thi CORS, do đó, một yêu cầu hoạt động trong tập lệnh vẫn có thể bị lỗi trong trình duyệt.

Theo mặc định, trình duyệt không gửi cookie theo yêu cầu có nguồn gốc chéo. Đặt credentials: "include" nếu bạn cần và đảm bảo máy chủ cho phép điều đó. Không bao giờ đặt các khóa API bí mật vào JavaScript của trình duyệt vì bất kỳ ai cũng có thể đọc được chúng. Giữ chúng trên máy chủ của bạn.

Những lỗi thường gặp

• Không kiểm tra response.ok. Phản hồi lỗi được coi là thành công.
• Quên điều thứ hai await. response.json() cũng trả lại một lời hứa.
• Quên JSON.stringify. Truyền một vật khi cơ thể gửi [object Object].
• Đặt Content-Type với FormData. Điều này phá vỡ ranh giới, vì vậy hãy loại bỏ nó.
• Không có thời gian chờ. Yêu cầu bị treo có thể khiến vòng quay của trang chạy vô thời hạn.
• Phân tích cú pháp JSON để có phản hồi trống. A 204 không có nội dung và json() sẽ ném.

Lời kết

Tìm nạp rất đơn giản khi bạn nhớ quy tắc chính của nó: một phản hồi không giống như một thành công. Sao chép trình trợ giúp nhỏ vào dự án của bạn, thêm thời gian chờ và kiểm tra các đường dẫn thất bại của bạn. Bước tiếp theo, hãy xây dựng một trang nhỏ tải dữ liệu từ API, hiển thị thông báo lỗi rõ ràng và cho phép người dùng hủy tìm kiếm chậm.

Câu hỏi thường gặp

Tiếp tục học hỏi