jQuery AJAX : guide pratique des requêtes asynchrones, des bases à la gestion des erreurs

AJAX permet à une page web de communiquer avec un serveur sans rechargement complet. Avec jQuery, cette technique reste utile dans les projets existants, les interfaces d’administration et les applications qui dépendent déjà de la bibliothèque. Le navigateur envoie une requête HTTP, reçoit souvent du JSON et ne met à jour que la zone concernée.

La documentation officielle présente $.ajax() comme le moteur des requêtes Ajax de jQuery. $.get(), $.post(), $.getJSON() et .load() simplifient les cas courants, tandis que $.ajax() contrôle la méthode, les en-têtes, le délai, le format et les erreurs.

Charger la bonne version de jQuery

À la date de rédaction, le projet indique jQuery 4.0.0 comme version stable. AJAX exige la version complète : la version slim exclut les modules Ajax et effets. En production, utilisez le fichier minifié et, depuis un CDN, privilégiez Subresource Integrity.

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

Première requête avec $.ajax()

$.ajax({
  url: "/api/posts",
  method: "GET",
  dataType: "json",
  timeout: 10000
})
.done(function (data) { console.log(data); })
.fail(function (jqXHR, textStatus, errorThrown) {
  console.error("Échec de la requête :", textStatus, errorThrown);
})
.always(function () { console.log("Requête terminée"); });

url désigne la ressource, method le verbe HTTP et dataType le format de réponse attendu. Le délai est exprimé en millisecondes et commence lors de l’appel de $.ajax().

jqXHR et traitement asynchrone

$.ajax() renvoie un objet jqXHR qui implémente l’interface Promise de jQuery. Utilisez .done(), .fail(), .always() et .then(). Les anciennes méthodes .success(), .error() et .complete() ont été supprimées dans jQuery 3.0.

const request = $.ajax({ url: "/api/search", data: { q: "ajax" } });
$("#cancel").on("click", function () { request.abort(); });

GET, POST et sérialisation

Lorsque data est un objet, jQuery le sérialise normalement en chaîne de requête avec jQuery.param().

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

Un formulaire classique peut utiliser .serialize() :

$("#contact-form").on("submit", function (event) {
  event.preventDefault();
  $.post("/api/contact", $(this).serialize())
    .done(function () { $("#message").text("Message envoyé"); })
    .fail(showRequestError);
});

Pour une API JSON, sérialisez le corps et déclarez son type :

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

contentType décrit les données envoyées ; dataType décrit la réponse attendue.

Erreurs HTTP et messages utiles

Une interface robuste distingue validation, authentification, autorisation et panne serveur. Utilisez statusCode pour les réponses précises et .fail() pour le cas général.

$.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("Le serveur n’a pas répondu à temps.");
  else if (jqXHR.status >= 500) showMessage("Erreur temporaire du serveur.");
});

Chargement et requêtes concurrentes

Désactiver temporairement le bouton d’envoi évite les écritures en double. Les événements globaux ajaxStart et ajaxStop peuvent gérer un indicateur général, mais beforeSend et .always() sont souvent plus clairs par composant.

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

Pour une recherche instantanée, annulez la requête précédente ou ignorez les réponses obsolètes afin qu’une réponse lente n’écrase pas le résultat récent.

CORS, identifiants et sécurité

Les requêtes vers une autre origine dépendent des règles CORS du navigateur. Le serveur doit envoyer les bons en-têtes ; JavaScript côté client ne peut pas corriger seul une politique CORS. Si le serveur autorise les cookies cross-origin, utilisez xhrFields: { withCredentials: true }, avec une origine explicite et l’autorisation des identifiants côté serveur.

AJAX ne remplace pas la sécurité serveur. Validez les entrées et les droits, utilisez une protection CSRF lorsque nécessaire et n’insérez jamais du HTML non fiable avec .html(). Pour le texte utilisateur, préférez .text(). JSONP exécute du script et reste une technique ancienne à éviter avec des sources non fiables.

Quand jQuery AJAX reste pertinent

Dans un nouveau projet sans dépendance, fetch() est souvent plus léger. Dans une application qui utilise déjà jQuery, AJAX fournit une API cohérente et bien intégrée aux formulaires. N’ajoutez pas jQuery uniquement pour AJAX, mais exploitez-le correctement lorsqu’il appartient déjà à la pile.

Liste de contrôle

• Utiliser la version complète, pas slim.
• Définir méthode, format, délai et erreurs.
• Distinguer contentType de dataType.
• Utiliser .done(), .fail() et .always().
• Gérer les requêtes en double et les réponses désordonnées.
• Appliquer authentification, autorisation, CSRF et validation sur le serveur.
• Afficher un état de chargement et des messages compréhensibles.