jQuery AJAX: guia prático de requisições assíncronas, dos exemplos básicos ao tratamento de erros

AJAX permite que uma página se comunique com o servidor sem um recarregamento completo. Com jQuery, a técnica continua útil em projetos existentes, painéis administrativos e aplicações que já dependem da biblioteca. O navegador envia uma requisição HTTP, recebe dados — geralmente JSON — e atualiza apenas a área necessária.

A documentação oficial apresenta $.ajax() como o mecanismo central das requisições Ajax do jQuery. $.get(), $.post(), $.getJSON() e .load() simplificam situações comuns; $.ajax() controla método, cabeçalhos, timeout, formato e erros.

Carregar a versão correta do jQuery

Na preparação deste guia, o projeto indica jQuery 4.0.0 como versão estável. AJAX requer a compilação completa: a versão slim exclui os módulos Ajax e efeitos. Em produção, use o arquivo minificado e, ao carregar de CDN, prefira Subresource Integrity.

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

Primeira requisição com $.ajax()

$.ajax({
  url: "/api/posts",
  method: "GET",
  dataType: "json",
  timeout: 10000
})
.done(function (data) { console.log(data); })
.fail(function (jqXHR, textStatus, errorThrown) {
  console.error("Falha na requisição:", textStatus, errorThrown);
})
.always(function () { console.log("Requisição concluída"); });

url identifica o recurso, method o verbo HTTP e dataType o formato esperado da resposta. O timeout é medido em milissegundos e começa quando $.ajax() é chamado.

jqXHR e processamento assíncrono

$.ajax() retorna um objeto jqXHR que implementa a interface Promise do jQuery. Use .done(), .fail(), .always() e .then(). Os métodos antigos .success(), .error() e .complete() foram removidos no jQuery 3.0.

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

GET, POST e serialização

Quando data é um objeto, o jQuery normalmente o transforma em query string por meio de jQuery.param().

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

Um formulário tradicional pode usar .serialize():

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

Para uma API JSON, serialize o corpo e declare o tipo:

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

contentType descreve o que é enviado; dataType descreve a resposta esperada.

Erros HTTP e mensagens úteis

Uma interface robusta diferencia validação, autenticação, autorização e falhas do servidor. Use statusCode para respostas específicas e .fail() para o caso geral.

$.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("O servidor não respondeu a tempo.");
  else if (jqXHR.status >= 500) showMessage("Erro temporário do servidor.");
});

Carregamento e requisições concorrentes

Desativar temporariamente o botão de envio evita gravações duplicadas. Os eventos globais ajaxStart e ajaxStop podem controlar um indicador geral, mas beforeSend e .always() costumam ser mais claros em cada componente.

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

Em buscas instantâneas, cancele a requisição anterior ou ignore respostas obsoletas; caso contrário, uma resposta lenta pode sobrescrever um resultado mais recente.

CORS, credenciais e segurança

Requisições entre origens são controladas pelas regras CORS do navegador. O servidor deve enviar cabeçalhos adequados; o JavaScript cliente sozinho não corrige uma política CORS. Se o servidor permitir cookies cross-origin, use xhrFields: { withCredentials: true }, com origem explícita e credenciais autorizadas no servidor.

AJAX não substitui a segurança no servidor. Valide entradas e permissões, aplique proteção CSRF quando necessário e não injete HTML não confiável com .html(). Para texto fornecido pelo usuário, prefira .text(). JSONP executa scripts e é uma técnica legada que não deve ser usada com fontes não confiáveis.

Quando usar jQuery AJAX atualmente

Num projeto novo e sem dependências, fetch() costuma ser mais leve. Numa aplicação que já usa jQuery, AJAX fornece uma API coerente e integrada aos formulários. Não adicione jQuery apenas por causa de AJAX; use-o com critério quando já fizer parte da stack.

Checklist final

• Usar a compilação completa, não slim.
• Definir método, formato, timeout e tratamento de erros.
• Diferenciar contentType de dataType.
• Usar .done(), .fail() e .always().
• Gerenciar duplicações e respostas fora de ordem.
• Aplicar autenticação, autorização, CSRF e validação no servidor.
• Mostrar estado de carregamento e mensagens compreensíveis.