Às vezes eu vejo utilizarem success
, às vezes eu vejo .done
, para tratar a resposta obtida na requisição.
- Qual eu devo usar?
- Existe alguma diferença entre as duas? Qual?
A mesma coisa para .error
e .fail
.
Utilizo o jQuery 3.2.1.
Conceitualmente eles não são a mesma coisa, mas o resultado produzido é exatamente o mesmo. As funções success
e error
são denominadas callbacks. Por sua vez, as funções done
e fail
são métodos de um Promise.
Diferença entre promise e callback
O resultado é exatamente o mesmo porque o jQuery utiliza os próprios métodos done
e fail
para executar as funções success
e error
. Veja o trecho de código retirado do repositório oficial (linha 662):
// Install callbacks on deferreds
completeDeferred.add( s.complete );
jqXHR.done( s.success );
jqXHR.fail( s.error );
Neste caso, s.success
faz referência ao success
passado em options
, assim como s.error
faz referência a error
.
Qual deles utilizar?
Se você possui apenas uma função success
e error
, não faz diferença. Use qual preferir. Utilizar o done
e fail
são úteis quando você precisa executar múltiplas funções em cada evento:
$.ajax("dominio.com")
.done(fazAlgo1)
.done(fazAlgo2)
.fail(deuErrado1)
.fail(deuErrado2);
Utilizando success
e error
você não consegue atribuir várias callbacks. Existem ainda a callback complete
que é executada sempre, após a execução de success
ou error
. Neste caso, o método semelhante no Promise seria o always
.
Para mais informações, vale ler a documentação oficial citada na outra resposta
Nota: é importante salientar que os métodos
.success
e.error
que a documentação cita como obsoletos não são as callbackssuccess
eerror
. São, na verdade, métodos presentes no Promise em versões antigas do jQuery. As funções callbacks ainda podem ser utilizadas.
Exemplo utilizando callbacks:
Utilizando a função callback success
.
$(() => {
$.ajax({
url: "https://jsonplaceholder.typicode.com/users",
method: "get",
dataType: "json",
success: users => {
$(users).each(i => {
console.log(users[i].name);
});
},
});
});
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
Exemplo utilizando Promise
Utilizando o método done
do objeto Promise retornado por $.ajax
.
$(() => {
const request = $.ajax({
url: "https://jsonplaceholder.typicode.com/users",
method: "get",
dataType: "json"
});
request.done(users => {
$(users).each(i => {
console.log(users[i].name);
});
});
});
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
Exemplo utilizando métodos obsoletos do Promise (OBSOLETO)
Utilizando o método success
do objeto Promise retornado por $.ajax
.
Este método está presente apenas para referência, mas o mesmo está obsoleto desde a versão 1.8 do jQuery e foi removida completamente no jQuery 3. Não utilize-a.
$(() => {
const request = $.ajax({
url: "https://jsonplaceholder.typicode.com/users",
method: "get",
dataType: "json"
});
request.success(users => {
$(users).each(i => {
console.log(users[i].name);
});
});
});
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
Exemplo utilizando fetch
Uma alternativa está em testes no momento chamada fetch
. A função é basicamente o que $.ajax
faz, acredito eu, mas será nativa no navegador, não precisando importar uma biblioteca de terceiros. Uma requisição GET, por exemplo, poderia ser feita assim:
const request = new Request("https://jsonplaceholder.typicode.com/users", {"method": "GET"});
fetch(request).then(response => {
if (response.ok) {
return response.json().then(data => {
data.forEach(user => {
console.log(user.name);
});
});
}
});
Ao meu ver ela será muito melhor de utilizar, não apenas por ser nativa, mas por ser semântica, trabalhando com objetos do tipo Request
, Response
, Headers
, etc. Mas lembrando, ainda está em fase de testes.
Outras leituras
O que são promises (promessas) em javascript?
Como realmente aprender a usar promessas em javascript?
Qual a diferença entre function() {} e () => {}? Por que não funciona o $http.get?
De acordo com a documentação do jQuery, segue abaixo os status
jqXHR.done(function( data, textStatus, jqXHR ){});
Uma alternativa para a opção de retorno de success.
jqXHR.fail(function( jqXHR, textStatus, errorThrown ){});
Uma alternativa para o retorno de erro, o método .fail() substituiu o método .error() que hoje é obsoleto.
jqXHR.always(function( data|jqXHR, textStatus, jqXHR|errorThrown){}); (adicionado em jQuery 1.6)
Uma alternativa para a opção de chamada quando a requisição está completa. O método .always() substituiu o método .complete() que hoje está obsoleto.Caso seja uma solicitação bem-sucedida, os argumentos da função são os mesmos de .done(). Para solicitações que ocorreram erros, os argumentos são iguais aos de .fail().
jqXHR.then(function( data, textStatus, jqXHR ) {}, function( jqXHR, textStatus, errorThrown ){});
Incorpora a funcionalidade dos métodos .done() e .fail(), permitindo (a partir de jQuery 1.8) trabalhar com Promise.
Importante: os retornos de jqXHR.success(), jqXHR.error() e jqXHR.complete() foram removidos a partir da versão 3.0 do jQuery. Você pode usar jqXHR.done(), jqXHR.fail() e jqXHR.always() como alternativa.
.done
sempre é executado, enquanto que.success
só é chamado caso ocorra sucesso. Não sei a distinção entre.fail
e.error
done
efail
estão relacionados ao retorno da função$.ajax
, que é um Promise. Os métodossuccess
eerror
são callbacks executados dentro da própria função.