jQuery AJAX: guida pratica alle richieste asincrone, dagli esempi base alla gestione degli errori

AJAX consente a una pagina web di comunicare con il server senza eseguire un ricaricamento completo. Con jQuery questa tecnica resta utile nei progetti esistenti, nei pannelli amministrativi e nelle applicazioni che già dipendono dalla libreria. Il termine indica un modello di comunicazione asincrona: il browser invia una richiesta HTTP, riceve dati — spesso JSON — e aggiorna solo la parte interessata dell’interfaccia.

La documentazione ufficiale conferma che $.ajax() è il motore alla base delle richieste AJAX di jQuery. I metodi abbreviati $.get(), $.post(), $.getJSON() e .load() coprono i casi più semplici, mentre $.ajax() permette di controllare metodo, intestazioni, timeout, formato dei dati e gestione degli errori.

Caricare la versione corretta di jQuery

Al momento della preparazione di questa guida la versione stabile indicata dal progetto è jQuery 4.0.0. Per usare AJAX serve la build completa: la build slim esclude esplicitamente i moduli AJAX ed effetti. In produzione conviene utilizzare il file compresso, preferibilmente con Subresource Integrity quando viene caricato da CDN.

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>

La prima richiesta con $.ajax()

Una richiesta GET che recupera un elenco di articoli può essere scritta così:

$.ajax({
  url: "/api/posts",
  method: "GET",
  dataType: "json",
  timeout: 10000
})
.done(function (data) {
  console.log(data);
})
.fail(function (jqXHR, textStatus, errorThrown) {
  console.error("Richiesta fallita:", textStatus, errorThrown);
})
.always(function () {
  console.log("Richiesta terminata");
});

url identifica la risorsa, method il verbo HTTP e dataType il formato atteso della risposta. Il valore json chiede a jQuery di interpretare la risposta come JSON. Il timeout è espresso in millisecondi e decorre dal momento in cui viene chiamato $.ajax().

jqXHR e gestione asincrona

$.ajax() restituisce un oggetto jqXHR, compatibile con l’interfaccia Promise di jQuery. I metodi consigliati sono .done(), .fail(), .always() e .then(). I vecchi metodi .success(), .error() e .complete() sono stati rimossi da jQuery 3.0 e non devono comparire nel nuovo codice.

Conservare il riferimento consente anche di annullare una richiesta non più necessaria:

const request = $.ajax({ url: "/api/search", data: { q: "ajax" } });

$("#cancel").on("click", function () {
  request.abort();
});

GET, POST e serializzazione dei dati

Se data è un oggetto, jQuery lo serializza normalmente in una query string tramite jQuery.param(). Per una ricerca GET è sufficiente:

$.get("/api/search", { q: "jquery", page: 1 })
  .done(function (results) {
    renderResults(results);
  });

Per inviare un form tradizionale si può usare .serialize():

$("#contact-form").on("submit", function (event) {
  event.preventDefault();

  $.post("/api/contact", $(this).serialize())
    .done(function () {
      $("#message").text("Messaggio inviato");
    })
    .fail(showRequestError);
});

Quando l’API accetta JSON, bisogna serializzare manualmente il corpo e dichiararne il tipo:

$.ajax({
  url: "/api/users",
  method: "POST",
  contentType: "application/json; charset=UTF-8",
  dataType: "json",
  data: JSON.stringify({ name: "Ada", role: "editor" })
});

contentType descrive ciò che viene inviato; dataType descrive ciò che ci si aspetta di ricevere. Confondere i due parametri è una causa frequente di errori.

Errori HTTP e messaggi utili

Un’interfaccia robusta distingue gli errori di validazione, autenticazione, autorizzazione e server. statusCode permette di associare funzioni a codici specifici, mentre .fail() gestisce il caso generale.

$.ajax({
  url: "/api/profile",
  method: "PUT",
  contentType: "application/json",
  data: JSON.stringify(profile),
  statusCode: {
    401: function () { window.location.href = "/login"; },
    422: function (jqXHR) { showValidationErrors(jqXHR.responseJSON); }
  }
}).fail(function (jqXHR, textStatus) {
  if (textStatus === "timeout") {
    showMessage("Il server non ha risposto in tempo.");
  } else if (jqXHR.status >= 500) {
    showMessage("Errore temporaneo del server.");
  }
});

Indicatori di caricamento e richieste concorrenti

Disabilitare temporaneamente il pulsante di invio evita doppi salvataggi. Gli eventi globali ajaxStart e ajaxStop possono controllare uno spinner generale, ma per componenti indipendenti è spesso più chiaro aggiornare lo stato in beforeSend e .always().

const $button = $("#save");

$.ajax({
  url: "/api/settings",
  method: "POST",
  data: $("#settings").serialize(),
  beforeSend: function () { $button.prop("disabled", true); }
}).always(function () {
  $button.prop("disabled", false);
});

Nelle ricerche istantanee conviene annullare la richiesta precedente o ignorare le risposte obsolete. In caso contrario una risposta lenta può sovrascrivere il risultato di una richiesta più recente.

CORS, credenziali e sicurezza

Le richieste verso un’origine diversa sono regolate dal CORS del browser. Il server deve inviare intestazioni compatibili; non è possibile “risolvere” CORS soltanto dal JavaScript client. Se il server autorizza cookie cross-origin, jQuery può impostare xhrFields: { withCredentials: true }, ma il server deve indicare un’origine esplicita e consentire le credenziali.

AJAX non sostituisce la sicurezza lato server. Validare sempre input e autorizzazioni, proteggere le richieste che modificano dati con token CSRF quando l’architettura lo richiede e non inserire HTML non affidabile con .html(). Per aggiornare testo proveniente dall’utente, usare .text(). JSONP esegue codice tramite uno script ed è una tecnica legacy: non va usata con sorgenti non fidate.

Quando usare jQuery AJAX oggi

Per un nuovo progetto senza dipendenze, l’API nativa fetch() è spesso la scelta più leggera. In un’applicazione che usa già jQuery, però, AJAX offre un’API coerente, integrazione con i form e una gestione collaudata del ciclo di vita delle richieste. La scelta migliore è evitare di aggiungere jQuery soltanto per AJAX, ma sfruttarlo con criterio dove è già parte dello stack.

Checklist finale

• Usare la build completa di jQuery, non la slim.
• Definire metodo, formato, timeout e gestione degli errori.
• Distinguere contentType da dataType.
• Usare .done(), .fail() e .always().
• Gestire richieste duplicate e risposte fuori ordine.
• Applicare autenticazione, autorizzazione, CSRF e validazione sul server.
• Mostrare all’utente uno stato di caricamento e messaggi comprensibili.

Con queste regole, jQuery AJAX rimane uno strumento affidabile per modernizzare interfacce esistenti senza riscrivere l’intera applicazione.