Fetch API ב-JavaScript: בקשות, JSON וטיפול בשגיאות

Fetch הוא לקוח HTTP מבוסס promises

fetch מובנה בדפדפנים וב-Node מודרני. נותנים לו URL, והוא מחזיר Promise שמתממש לאובייקט Response. זה כל ה-API בבסיסו:

fetch("https://jsonplaceholder.typicode.com/todos/1")
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(err => console.error("נכשל:", err));

יש שתי קריאות .then כי יש שני שלבים אסינכרוניים: קודם מגיעות הכותרות של התגובה (עם זה ה-promise הראשון מתממש), ואחר כך הגוף נקרא ומפוענח (response.json() הוא בעצמו promise). הגוף לא מורד עד שמבקשים אותו.

אותו תהליך עם async/await נקרא כמו קוד רגיל מלמעלה למטה:

async function loadTodo() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
    const data = await response.json();
    console.log(data);
}

loadTodo();

שני await, שתי נקודות השהיה. אותה עבודה, סדר קריאה ברור יותר.

אובייקט ה-Response

מה שמקבלים בחזרה הוא לא הגוף, אלא אובייקט Response עם מטא-דאטה ומתודות לקריאת הגוף בצורות שונות:

async function inspect() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");

    console.log(response.status);       // 200
    console.log(response.ok);           // true for 200-299
    console.log(response.headers.get("content-type"));

    const data = await response.json();
    console.log(data.title);
}

inspect();

אפשר לקרוא את הגוף עם .json(), .text(), .blob(), .arrayBuffer() או .formData(). כל אחת מהן מחזירה promise. אפשר לקרוא את הגוף רק פעם אחת: קראו ל-.json() פעמיים על אותה תגובה, והקריאה השנייה תזרוק שגיאה.

המלכודת הגדולה: שגיאות HTTP לא גורמות לדחייה

זה מכשיל כמעט כל מי שחדש ב-fetch. תגובת 404 או 500 היא לא דחייה. ה-promise מתממש כרגיל, עם response.ok === false. fetch נדחה רק כשהבקשה עצמה לא הצליחה להסתיים: כשל DNS, אין רשת, חסימת CORS.

המשמעות היא ש-fetch נאיבי ימסור לכם בשמחה דף שגיאה ויקרוס מאוחר יותר ב-.json():

async function buggy() {
    // This URL returns 404, but fetch resolves anyway.
    const response = await fetch("https://jsonplaceholder.typicode.com/nope/999");
    const data = await response.json();    // might explode or return garbage
    console.log(data);
}

buggy();

התיקון הוא לבדוק בעצמכם את response.ok ולזרוק שגיאה אם השרת החזיר סטטוס שגיאה:

async function loadTodo(id) {
    const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);

    if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
}

loadTodo(1).then(console.log).catch(err => console.error(err.message));

התרגלו לכתוב את בלוק ה-if (!response.ok) הזה. הוא שייך לכל wrapper של fetch שתכתבו.

שליחת בקשת POST

GET הוא ברירת המחדל. לכל דבר אחר, העבירו ארגומנט שני, אובייקט אפשרויות:

async function createPost() {
    const response = await fetch("https://jsonplaceholder.typicode.com/posts", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            title: "hello",
            body: "from fetch",
            userId: 1
        })
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    console.log(data);
}

createPost();

שלושה דברים ששווה לשים לב אליהם:

• ברירת המחדל של method היא "GET". הגדירו אותו במפורש ל-POST, PUT, DELETE, PATCH.
• body מקבל מחרוזת (או FormData, Blob וכו'): fetch לא יסרלז אובייקטים בשבילכם. ה-JSON.stringify(...) באחריותכם.
• הכותרת Content-Type אומרת לשרת איך לפענח את הגוף. תשכחו אותה, ורוב השרתים יתייחסו לגוף כטקסט רגיל.

Headers, query strings ואפשרויות נוספות

Headers הם פשוט אובייקט (או מופע של Headers). את ה-query string בונים בעצמכם, בדרך כלל עם URLSearchParams:

async function search(query, token) {
    const params = new URLSearchParams({ q: query, limit: "10" });
    const url = `https://api.example.com/search?${params}`;

    const response = await fetch(url, {
        headers: {
            "Authorization": `Bearer ${token}`,
            "Accept": "application/json"
        }
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
}

URLSearchParams מטפל בקידוד בשבילכם: רווחים, סימני &, יוניקוד. ככה לא תקבלו כתובות שבורות כשבקלט יש תווים שצריך לקודד.

אפשרויות נוספות שתראו בקוד אמיתי: credentials: "include" כדי לשלוח cookies בין מקורות, cache: "no-store" כדי לעקוף את מטמון ה-HTTP, ו-mode: "cors" (בדרך כלל ברירת המחדל) כדי לשלוט בהתנהגות CORS.

ביטול בקשה עם AbortController

לפעמים רוצים לוותר: המשתמש הקליד חיפוש חדש, או שהבקשה לוקחת יותר מדי זמן. AbortController הוא המנגנון לזה:

async function loadWithTimeout(url, ms) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), ms);

    try {
        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
    } finally {
        clearTimeout(timeout);
    }
}

loadWithTimeout("https://jsonplaceholder.typicode.com/todos/1", 3000)
    .then(console.log)
    .catch(err => console.error(err.name, err.message));

controller.abort() גורם ל-promise של fetch להידחות עם DOMException שה-name שלו הוא "AbortError". בלוק ה-finally מנקה את ה-timeout, כדי שבקשה מוצלחת לא תשאיר טיימר תלוי.

את התבנית הזו, fetch ועוד timeout ועוד ניקוי, שווה לעטוף בפונקציית עזר ולהשתמש בה בכל מקום.

Wrapper לשימוש חוזר

מחברים את הכול ומקבלים פונקציית עזר קטנה שמטפלת בקוד החוזר פעם אחת:

async function apiRequest(url, options = {}) {
    const response = await fetch(url, {
        headers: { "Content-Type": "application/json", ...options.headers },
        ...options
    });

    if (!response.ok) {
        const text = await response.text();
        throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
    }

    if (response.status === 204) return null;   // No Content
    return response.json();
}

apiRequest("https://jsonplaceholder.typicode.com/todos/1")
    .then(console.log)
    .catch(err => console.error(err.message));

מקום אחד לשנות headers, מקום אחד לטפל בשגיאות, מקום אחד להתמודד עם תגובות ריקות. כל אפליקציה שאינה טריוויאלית מגיעה בסוף למשהו כזה.

הבא בתור: טיפול בשגיאות בקוד אסינכרוני

fetch הוא אחד המקומות הנפוצים ביותר שבהם צצות שגיאות אסינכרוניות, ובדיקת response.ok היא רק חלק אחד מהפאזל. העמוד הבא עוסק בטיפול בשגיאות ב-promises וב-async/await: לאן שגיאות הולכות, איך תופסים אותן, והמלכודות שנותנות להן לחמוק בשקט.