Çoğu modern web uygulaması her zaman bir sunucuyla konuşur. JavaScript Fetch API bunu yapmanın standart yoludur ve tarayıcılarda ve Node.js 18 ve sonraki sürümlerinde yerleşik olduğundan yüklenecek bir şey yoktur.

Temel kullanım iki satır alır, ancak birçok eğitim burada durur ve gerçek hatalara neden olan kısmı atlar: arıza yönetimi. Bu kılavuzdaki örnekleri Node.js 24 üzerindeki küçük bir yerel sunucuya karşı test ettik ve gösterilen çıktı bu çalıştırmadan geliyor. Koddaki example.com kendi API’nizin yerine geçer. Vaatler sizin için yeniyse, JavaScript vaatlerinin açıklanması ile başlayın.

Getirme API’si nedir?

Fetch, HTTP istekleri yapmak için söze dayalı bir arayüzdür. Eski, geri arama odaklı XMLHttpRequest‘in yerini aldı ve birçok proje artık basit aramalar için bir kitaplık eklemek yerine onu kullanıyor.

Bir GET isteği

Fetch, varsayılan olarak bir GET isteğinde bulunur. İki adım vardır ve her birinin await‘e ihtiyacı vardır: önce yanıt başlıkları gelir ve sonra gövdeyi okursunuz.

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

console.log(user);

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

İki adım mevcuttur çünkü gövde büyük olabilir ve başlıklardan daha geç gelebilir. Bir tarayıcı betiğinde, üst seviye await‘in bir modüle ihtiyacı vardır, dolayısıyla bunu genellikle bir async fonksiyonunun içine yerleştirirsiniz. JavaScript eşzamansız/beklemede kılavuzumuza bakın.

Yanıt nesnesi

Gövdeyi okumadan önce yanıtı inceleyebilirsiniz:

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

// 200 true application/json

Bir gövde yalnızca bir kez okunabilir. json()‘i ikinci kez çağırmak testimizde başarısız oldu:

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

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

Eğer iki kez okumanız gerekiyorsa, önce response.clone()‘i arayın.

Büyük sürpriz: 404 fırlatmıyor

Bu yazıdaki en önemli şey bu. Var olmayan bir kullanıcıdan talepte bulunduk:

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

// 404 false

Hiçbir istisna atılmadı. Getirme söz konusu olduğunda istek işe yaradı: sunucuya ulaşıldı ve sunucu yanıtlandı. Söz, ağ arızasında olduğu gibi yalnızca hiçbir kullanılabilir yanıt gelmediğinde reddedilir. Yani bunun gibi bir kodda gizli bir hata var:

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
}

Her kodun ne anlama geldiğini görmek için HTTP durum kodları yardımcı sayfamıza göz atın.

Yeniden kullanılabilir bir yardımcı

Bu kontrolü her yerde tekrarlamayın. Bir kez sarı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

Artık hem HTTP hataları hem de ağ hataları aynı sonuçla sonuçlanıyor catch. Bu küçük fonksiyon her projede bulunmaya değerdir. Gerçek bir sürüm ayrıca yanıt gövdesinden bir hata mesajı okuyabilir ve ayrıştırılacak JSON’u olmayan bir 204 No Content yanıtını işleyebilir.

POST JSON verileri

İkinci argüman olarak bir seçenekler nesnesini iletin. JSON için iki şeyi kendiniz yapmanız gerekir: verileri bir dizeye dönüştürmek ve başlığı ayarlamak.

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' }

Test sunucumuz, aldığı içerik türünü tekrarlayarak başlığın geldiğini doğruladı. Bu başlığın unutulması, kafa karıştırıcı sunucu hatalarının yaygın bir nedenidir, çünkü birçok çerçeve, JSON’u yalnızca bildirildiğinde ayrıştırır. Bir form veya dosya yüklemek için gövde olarak bir FormData nesnesi iletin ve tarayıcının kendisinin bir sınır değeri eklemesi gerektiğinden Content-Type‘ü ayarlamayın.

Diğer yöntemler ve seçenekler

REST ve diğer API stilleri arasında seçim mi yapıyorsunuz? REST ve GraphQL karşılaştırmamız, getirmenin her birine ne kadar uygun olduğunu gösterir.

Sorgu dizeleri

Özel karakterler bunları bozacağından sorgu dizelerini metni birleştirerek oluşturmayın. URLSearchParams sizin için kodlamayı yönetir:

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' }

Sunucu, alan geri yüklenerek red shoes‘i doğru bir şekilde aldı.

Zaman aşımları ve iptal etme

Siz aksini söylemediğiniz sürece Fetch, yavaş bir sunucuda uzun süre bekleyecektir. AbortSignal.timeout() bir sınır belirler. Test bitiş noktamız 200 milisaniye sınırına rağmen iki saniye sürdü:

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

// TimeoutError

Örneğin bir kullanıcı bir sayfadan ayrıldığında veya yeni bir arama terimi yazdığında manuel olarak iptal etmek için AbortController kullanın:

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

Aynı anda birden fazla isteği çalıştırmak için, tek tek beklemekten çok daha hızlı olan Promise.all‘i kullanın:

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

Her türlü başarısızlık

Koşumuzdaki her başarısızlığın neye benzediğini ve bunları nasıl ayıracağımızı burada bulabilirsiniz:

Bu son sıra üretimde yaygındır. 502 döndüren bir proxy genellikle bir HTML hata sayfası gönderir. Bunu çoğalttık ve res.json() bir SyntaxError attı. Ayrıştırmadan önce response.ok‘ün işaretlenmesi, kafa karıştırıcı bir ayrıştırma hatası yerine gerçek sorunu bildirdiğiniz anlamına gelir.

CORS ve kimlik bilgileri

Bir tarayıcıda, bir kaynaktan diğerine yapılan istek, kaynaklar arası kaynak paylaşımı kuralları olan CORS‘e tabidir. Access-Control-Allow-Origin‘den bahseden bir hata görürseniz, düzeltme sitenize izin vermesi gereken sunucuya aittir. JavaScript’inizde hata yalnızca genel bir TypeError olarak görünüyor, bu nedenle gerçek nedeni öğrenmek için tarayıcı konsoluna bakın. Node.js, CORS’u zorlamadığından, bir komut dosyasında çalışan bir istek tarayıcıda yine de başarısız olabilir.

Tarayıcılar varsayılan olarak çapraz kaynak istekleri üzerine çerez göndermez. İhtiyacınız varsa credentials: "include"‘i ayarlayın ve sunucunun buna izin verdiğinden emin olun. Herkes okuyabileceği için asla gizli API anahtarlarını tarayıcı JavaScript’ine koymayın. Bunları sunucunuzda tutun.

Yaygın hatalar

• İşaretlenmiyor response.ok. Hata yanıtları başarılı olarak değerlendirilir.
• İkinci await. response.json()‘ün unutulması da bir söz verir.
• Unutmak JSON.stringify. Vücudun gönderdiği gibi bir nesneyi iletmek [object Object].
• Content-Type‘yi FormData ile ayarlamak. Bu, sınırı ihlal eder, bu yüzden onu dışarıda bırakın.
• Zaman aşımı yok. Askıya alınan bir istek, sayfanın döndürücüsünün süresiz olarak çalışmasına neden olabilir.
• Boş bir yanıt için JSON ayrıştırılıyor. 204’ün gövdesi yoktur ve json() fırlatır.

Son sözler

Ana kuralını hatırladığınızda, getirme işlemi basittir: Yanıt ile başarı aynı şey değildir. Küçük yardımcıyı projenize kopyalayın, bir zaman aşımı ekleyin ve hata yollarınızı test edin. Bir sonraki adım olarak, bir API’den veri yükleyen, net bir hata mesajı gösteren ve kullanıcının yavaş aramayı iptal etmesine olanak tanıyan küçük bir sayfa oluşturun.

Sık sorulan sorular

Öğrenmeye devam et