5. As funções HTTP em Dart

5.1. Escolha das ferramentas HTTP
Ao contrário do JavaScript/TypeScript, que fornece uma função [fetch] NATIVA (tanto no navegador quanto no Node.js), o Dart NÃO fornece um cliente de alto nível em sua biblioteca padrão ([dart:io] expõe apenas um [HttpClient] de baixo nível, trabalhoso de usar diretamente). Dois pacotes externos cobrem, juntos, exatamente o mesmo terreno que [fetch] e [axios] no curso de TypeScript:
- [package:http] (pub.dev/packages/http), mantido pela própria equipe do Dart: uma API simples e de baixo nível, sem configuração global nem interceptors —o papel de [fetch].
- [package:dio] (pub.dev/packages/dio): configuração global ([baseUrl], [timeout]), interceptors, tratamento de erros aprimorado ([DioException.response]) —o papel de [axios].
5.2. O servidor de cálculo de imposto
Todos os scripts deste capítulo têm como alvo o servidor NestJS instalado no capítulo anterior, no endereço [http://localhost:3000/main.php]. Antes de testar os scripts a seguir, verifique se o seu servidor NestJS está em execução. Para que ele funcione, a ferramenta Laragon também deve estar em execução.
5.2.1. script [dart_fetch_01]
| // dart_fetch_01.dart
// Porta fetch-01.ts.
// Escolha de ferramentas HTTP no Dart: o pacote [http] (pub.dev/packages/http),
// mantido pela própria equipe do Dart, faz o papel do [fetch] nativo do
// Node.js/navegador - uma API simples e de baixo nível, sem
// configuração global nem interceptors (ao contrário do pacote [dio],
// que faz o papel do [axios] - veja dart_dio_01.dart).
import 'dart:convert';
import 'package:http/http.dart' as http;
// URL base do servidor de cálculo de imposto (veja o capítulo
// "Instalando um servidor NestJS")
const String baseUrl = 'http://localhost:3000/main.php';
// inicialização da sessão
Future<dynamic> initSession() async {
// [diferença com o TypeScript] o pacote [http] não tem opção
// [timeout] na própria requisição: limitamos o tempo de espera
// envolvendo o Future com a extensão [.timeout(...)] de dart:async,
// que funciona em QUALQUER Future (não apenas em requisições
// HTTP) - um mecanismo mais geral que o
// AbortSignal.timeout() do fetch, específico do fetch nativo.
final uri = Uri.parse(baseUrl).replace(queryParameters: {
'action': 'init-session',
'type': 'json',
});
try {
// requisição assíncrona - http.get() retorna um Future<http.Response>
final stopwatch = Stopwatch()..start();
final response = await http.get(uri).timeout(const Duration(seconds: 2));
// [response] é a resposta HTTP completa do servidor (cabeçalhos
// HTTP + corpo) - nós a exibimos para ver sua estrutura
print("http response in Dart (duration=${stopwatch.elapsedMilliseconds}ms) : "
"statusCode=${response.statusCode}");
// podemos acessar os cabeçalhos HTTP
print("response headers=${response.headers}");
// [diferença com o TypeScript] ao contrário do fetch, em que response.json()
// é um método ASSÍNCRONO separado (um novo Future), o corpo do
// http.Response já está totalmente disponível
// DE FORMA SÍNCRONA (response.body, uma String): http.get() já esperou
// todo o corpo antes de retornar seu resultado. jsonDecode() não é, portanto,
// uma operação assíncrona aqui.
final object = jsonDecode(response.body);
print("json response=$object, type=${object.runtimeType}");
return object;
} catch (error) {
// chegamos aqui porque o servidor respondeu com um código de erro, ou
// porque o cliente http lançou uma exceção (rede inacessível,
// timeout excedido...)
print("fetch error in Dart=${error.runtimeType}, $error");
// relançamos o erro
rethrow;
}
}
// a função main executa a função assíncrona [initSession]
Future<void> main() async {
try {
print("HTTP request to the server in progress "
"---------------------------------------------");
final response = await initSession();
print("success ---------------------------------------------");
print("response=$response ${response.runtimeType}");
} catch (error) {
print("error ---------------------------------------------");
print("error=$error");
}
}
|
Vamos comentar este código:
- linha 30: [http.get(uri).timeout(const Duration(seconds: 2))]: o pacote [http] não tem uma opção [timeout] na própria requisição - Limitamos o tempo de espera envolvendo o [Future] com o método [.timeout(...)] de dart:async, que funciona em QUALQUER [Future], não apenas em requisições HTTP.
- Linha 43: [jsonDecode(response.body)]: ao contrário de [fetch], em que [response.json()] é um método ASSÍNCRONO separado, o corpo de uma [http.Response] já está totalmente disponível DE FORMA SÍNCRONA ([response.body], uma [String]): [http.get()] já aguardou o corpo inteiro antes de retornar seu resultado.
O resultado da execução é o seguinte:
| HTTP request to the server in progress ---------------------------------------------
http response in Dart (duration=73ms) : statusCode=200
response headers={x-powered-by: Express, connection: keep-alive, keep-alive: timeout=5, set-cookie: connect.sid=s%3AWxLD5aAAWVIL6pinZyP75L4COQi837LW.NmwJehFDFeCvZ0p6CKHV9ybz9xNUvndTB7TYlKgp7s4; Path=/; HttpOnly; SameSite=Lax, date: Sun, 20 Sep 2026 09:47:30 GMT, content-length: 84, etag: W/"54-sE02l73cr4dRIJSanYxwhuhm21c", content-type: application/json; charset=utf-8}
json response={action: init-session, status: 700, response: session started with type [json]}, type=_Map<String, dynamic>
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]} _Map<String, dynamic>
|
5.2.2. script [dart_fetch_02]
| // dart_fetch_02.dart
// Porta fetch-02.ts: versão "concisa" de dart_fetch_01.dart, sem as
// exibições intermediárias.
import 'dart:convert';
import 'package:http/http.dart' as http;
const String baseUrl = 'http://localhost:3000/main.php';
// inicialização da sessão
Future<dynamic> initSession() async {
final uri = Uri.parse(baseUrl).replace(queryParameters: {
'action': 'init-session',
'type': 'json',
});
final response = await http.get(uri).timeout(const Duration(seconds: 2));
// resultado recebido em jSON
return jsonDecode(response.body);
}
// a função main executa a função assíncrona [initSession]
Future<void> main() async {
try {
print("HTTP request to the server in progress "
"---------------------------------------------");
final response = await initSession();
print("success ---------------------------------------------");
print("response=$response");
} catch (error) {
print("error ---------------------------------------------");
print("error=$error");
}
}
|
Vamos comentar este código:
- Uma versão concisa de dart_fetch_01.dart, sem as saídas intermediárias —a estrutura continua a mesma: construir o [Uri], chamar [http.get], decodificar o JSON.
O resultado da execução é o seguinte:
| HTTP request to the server in progress ---------------------------------------------
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]}
|
5.2.3. script [dart_fetch_03]
| // dart_fetch_03.dart
// Porta fetch-03.ts: tempo máximo de espera e cancelamento manual de uma
// requisição HTTP.
import 'package:http/http.dart' as http;
// URL base do servidor de cálculo de imposto (veja http/README, o
// servidor PHP histórico do curso original; aqui miramos diretamente o
// servidor NestJS - veja o capítulo "Instalando um servidor NestJS")
const String baseUrl = 'http://localhost:3000/main.php';
// exemplo 1: requisição com tempo máximo de espera, graças a [.timeout(...)]
// (extensão de dart:async em qualquer Future - veja dart_fetch_01.dart)
Future<void> requestWithMaximumDelay() async {
print("--- request with .timeout() ---");
try {
final response = await http
.get(Uri.parse('$baseUrl?action=init-session&type=json'))
// após 2 segundos, [.timeout] conclui o Future com um erro
// do tipo [TimeoutException] - o equivalente Dart do
// AbortSignal.timeout() do fetch
.timeout(const Duration(seconds: 2));
print("response = ${response.body}");
} catch (error) {
// se o servidor não existir (caso provável neste exercício), ou se
// o tempo for excedido, [error] é uma [TimeoutException] ou uma
// [SocketException]/[ClientException], conforme o caso
print("error.runtimeType = ${error.runtimeType}, message = $error");
}
}
// exemplo 2: cancelamento manual de uma requisição, por exemplo porque
// o usuário mudou de ideia (ex.: digita de novo em um campo
// de busca).
//
// [AVISO, diferença fundamental com o TypeScript] o pacote [http] não tem sinal de cancelamento
// POR REQUISIÇÃO, como o AbortSignal do fetch: a
// única forma de cancelar é FECHAR O CLIENTE (http.Client.close()) como um
// todo, o que cancela TODAS as requisições em andamento nesse cliente - é
// preciso, portanto, criar um cliente DEDICADO à requisição que se quer poder cancelar
// individualmente, em vez de um cliente compartilhado por toda a aplicação.
Future<void> manuallyCancellableRequest() async {
print("--- request cancelled manually ---");
final client = http.Client();
// agendamos um cancelamento "de negócio" após 10 ms (em uma
// aplicação real, seria por exemplo um clique em um botão "cancelar")
Future.delayed(const Duration(milliseconds: 10), () {
print("manual cancellation triggered");
client.close();
});
try {
final response = await client.get(Uri.parse('$baseUrl?action=init-session&type=json'));
print("response = ${response.body}");
} catch (error) {
// fechar o cliente durante uma requisição em andamento a faz falhar com
// uma [ClientException]
print("error.runtimeType = ${error.runtimeType}, message = $error");
}
}
Future<void> main() async {
await requestWithMaximumDelay();
await manuallyCancellableRequest();
}
|
Vamos analisar este código:
- Linha 21: [.timeout(const Duration(seconds: 2))] completa o [Future] com falha com uma [TimeoutException] quando o limite de tempo é excedido - o equivalente em Dart de [AbortSignal.timeout()] para [fetch].
- Linha 35: [WARNING, key difference]—o pacote [http] NÃO tem sinal de cancelamento POR REQUISIÇÃO como [AbortController] para [fetch]: a única forma de cancelar é FECHAR O CLIENTE ([http.Client.close()]) por inteiro, o que cancela TODAS as requisições pendentes desse cliente—daí a necessidade de criar um cliente DEDICADO para a requisição que se deseja poder cancelar individualmente.
O resultado da execução é o seguinte:
| --- request with .timeout() ---
response = {"action":"init-session","status":700,"response":"session started with type [json]"}
--- request cancelled manually ---
response = {"action":"init-session","status":700,"response":"session started with type [json]"}
manual cancellation triggered
|
5.2.4. script [dart_dio_01]
| // dart_dio_01.dart
// Porta axios-01.ts e axios-02.ts.
// Escolha de ferramentas HTTP no Dart: o pacote [dio] (pub.dev/packages/dio)
// faz o papel do [axios] - configuração global (baseUrl, timeout),
// interceptors, tratamento de erros enriquecido (error.response, como
// no axios): tudo o que o pacote [http], mais próximo do fetch, deixa a cargo do
// código chamador (veja dart_fetch_01.dart).
import 'package:dio/dio.dart';
// uma instância de Dio configurada uma vez por todas, reutilizada por todas
// as chamadas - exatamente o papel de "axios.defaults" em TypeScript
final Dio dio = Dio(BaseOptions(
baseUrl: 'http://localhost:3000/',
connectTimeout: const Duration(seconds: 2),
receiveTimeout: const Duration(seconds: 2),
));
// inicialização da sessão
Future<dynamic> initSession({required String type}) async {
try {
// requisição assíncrona - dio.get() aceita diretamente
// queryParameters, como axios.request({params: ...})
final response = await dio.get('main.php', queryParameters: {
'action': 'init-session',
'type': type,
});
// a resposta do servidor está em [response.data] (já decodificada em
// Map/List pelo Dio se o Content-Type for JSON), exatamente como
// response.data no axios
return response.data;
} on DioException catch (error) {
// o parâmetro [error] é uma [DioException] - nós a exibimos para
// ver sua estrutura (equivalente ao "console.log(axios error)"
// comentado em axios-01.ts)
if (error.response != null) {
// o servidor sinalizou um erro no status HTTP, mas também
// enviou uma resposta: ela está em [error.response!.data],
// exatamente como [error.response.data] no axios
return error.response!.data;
} else {
// nenhuma resposta (rede inacessível, timeout...) -
// relançamos o erro
rethrow;
}
}
}
Future<void> main() async {
try {
// 1ª tentativa, deliberadamente inválida (type='x' em vez de 'json'),
// para observar como o servidor - e depois o dio - sinalizam o erro:
// o servidor responde mesmo assim (com um status de erro de negócio), então
// error.response.data de fato é preenchido, como em axios-01.ts
print("HTTP request (invalid type) to the server in progress "
"---------------------------------------------");
final invalidResponse = await initSession(type: 'x');
print("response=$invalidResponse ${invalidResponse.runtimeType}");
// 2ª tentativa, corrigida (type='json'), como axios-02.ts
print("HTTP request (corrected type) to the server in progress "
"---------------------------------------------");
final response = await initSession(type: 'json');
print("success ---------------------------------------------");
print("response=$response ${response.runtimeType}");
} catch (error) {
print("error ---------------------------------------------");
print("error=$error");
}
}
|
Vamos analisar este código:
- Linhas 12–15: [Dio(BaseOptions(baseUrl: ..., connectTimeout: ..., receiveTimeout: ...))]: uma instância de [Dio] configurada de uma vez por todas e reutilizada em todas as chamadas —exatamente o papel de [axios.defaults] no TypeScript.
- [response.data]: a resposta do servidor, que já foi DECODIFICADA em [Map]/[List] pelo Dio se o [Content-Type] for JSON, exatamente como [response.data] no axios.
- Linhas 30–31: [on DioException catch (error) { if (error.response != null) ... }]: a mesma distinção de [error.response] no Axios entre um erro COM resposta do servidor (status de erro de negócio) e um erro SEM resposta (rede inacessível, timeout).
O resultado da execução é o seguinte:
| HTTP request (invalid type) to the server in progress ---------------------------------------------
response={action: init-session, status: 703, response: invalid parameter type=[x]} _Map<String, dynamic>
HTTP request (corrected type) to the server in progress ---------------------------------------------
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]} _Map<String, dynamic>
|
5.2.5. script [dart_dio_02]
| // dart_dio_02.dart
// Porta axios-03.ts: encadeamento de duas requisições HTTP - init-session e depois
// authenticate-user (um POST com corpo codificado como
// x-www-form-urlencoded).
import 'package:dio/dio.dart';
final Dio dio = Dio(BaseOptions(
baseUrl: 'http://localhost:3000/',
connectTimeout: const Duration(seconds: 2),
receiveTimeout: const Duration(seconds: 2),
));
Future<dynamic> initSession() async {
try {
final response = await dio.get('main.php', queryParameters: {
'action': 'init-session',
'type': 'json',
});
return response.data;
} on DioException catch (error) {
if (error.response != null) {
return error.response!.data;
}
rethrow;
}
}
Future<dynamic> authenticateUser(String user, String password) async {
try {
// requisição POST com corpo x-www-form-urlencoded - o Dio
// codifica automaticamente um Map como x-www-form-urlencoded se o
// Content-Type for especificado nas [Options], exatamente como qs.stringify(...)
// + o cabeçalho manual de axios-03.ts
final response = await dio.post(
'main.php',
queryParameters: {'action': 'authenticate-user'},
data: {'user': user, 'password': password},
options: Options(contentType: Headers.formUrlEncodedContentType),
);
return response.data;
} on DioException catch (error) {
if (error.response != null) {
return error.response!.data;
}
rethrow;
}
}
// a função main executa as funções assíncronas uma a uma
Future<void> main() async {
try {
// init-session
print("init-session action in progress "
"---------------------------------------------");
final response1 = await initSession();
print("success ---------------------------------------------");
print("response=$response1");
// authenticate-user - [NOTA, como no curso TypeScript
// original] esta chamada parte de uma nova requisição HTTP, SEM
// compartilhar automaticamente o cookie de sessão definido pelo servidor na
// etapa anterior (nem o Dio nem o axios fazem isso automaticamente no
// lado Node/Dart): o controle manual do cookie de sessão é justamente o
// tema de dart_dio_03.dart, que porta axios-04.ts.
print("authenticate-user action in progress "
"---------------------------------------------");
final response2 = await authenticateUser('admin', 'admin');
print("success ---------------------------------------------");
print("response=$response2");
} catch (error) {
print("error ---------------------------------------------");
print("error=$error");
}
}
|
Vamos analisar este código:
- linha 38: [Options(contentType: Headers.formUrlEncodedContentType)]: o Dio codifica automaticamente o [Map] passado a [data] em [x-www-form-urlencoded] assim que esse [Content-Type] é especificado - o equivalente a [qs.stringify(...)] combinado com o cabeçalho manual do Axios.
- Esta chamada é uma nova requisição HTTP que NÃO compartilha automaticamente o cookie de sessão definido pelo servidor na etapa anterior—nem o Dio nem o axios fazem isso automaticamente no lado Dart/Node: o rastreamento manual de cookies é o tema do script seguinte.
O resultado da execução é o seguinte:
| init-session action in progress ---------------------------------------------
success ---------------------------------------------
response={action: init-session, status: 700, response: session started with type [json]}
authenticate-user action in progress ---------------------------------------------
success ---------------------------------------------
response={action: authenticate-user, status: 103, response: [no session in progress. Start with action [init-session]]}
|
5.2.6. script [dart_dio_03]
| // dart_dio_03.dart
// Porta axios-04.ts: controle manual do cookie de sessão entre duas requisições.
import 'package:dio/dio.dart';
final Dio dio = Dio(BaseOptions(
baseUrl: 'http://localhost:3000/',
connectTimeout: const Duration(seconds: 2),
receiveTimeout: const Duration(seconds: 2),
// desativamos a validação padrão do status HTTP para poder
// inspecionar nós mesmos uma resposta de erro (como error.response no
// axios), sem passar sistematicamente por um bloco catch
validateStatus: (_) => true,
));
// cookie de sessão
const String sessionCookieName = "connect.sid";
String sessionCookie = '';
Future<dynamic> getRemoteData(String path, {
required String method,
Map<String, dynamic>? queryParameters,
Object? data,
Options? options,
}) async {
// para o cookie de sessão - nós mesmos o adicionamos aos cabeçalhos de
// cada requisição, exatamente como axios-04.ts
final opts = (options ?? Options(method: method)).copyWith(
method: method,
headers: {
...?options?.headers,
'Cookie': sessionCookie,
},
);
// execução da requisição HTTP
final response = await dio.request(
path,
queryParameters: queryParameters,
data: data,
options: opts,
);
// recuperamos o cookie de sessão, se existir - response.headers é um
// objeto [Headers] do Dio (e não um simples Map como response.headers no
// axios); response.headers['set-cookie'] retorna uma List<String>?
final setCookie = response.headers['set-cookie'];
if (setCookie != null) {
// procuramos o cookie de sessão nesta lista
for (final header in setCookie) {
final result = RegExp('^($sessionCookieName.+?);').firstMatch(header);
if (result != null) {
// armazenamos o cookie de sessão
sessionCookie = result.group(1)!;
break;
}
}
}
// a resposta do servidor está em [response.data]
return response.data;
}
Future<dynamic> initSession() {
return getRemoteData(
'main.php',
method: 'GET',
queryParameters: {'action': 'init-session', 'type': 'json'},
);
}
Future<dynamic> authenticateUser(String user, String password) {
return getRemoteData(
'main.php',
method: 'POST',
queryParameters: {'action': 'authenticate-user'},
data: {'user': user, 'password': password},
options: Options(contentType: Headers.formUrlEncodedContentType),
);
}
// a função main executa as funções assíncronas uma a uma
Future<void> main() async {
try {
print("init-session action in progress ----------------");
final response1 = await initSession();
print("success --------------------------");
print("response=$response1");
print("authenticate-user action in progress ---------");
final response2 = await authenticateUser('admin', 'admin');
print("success -------------------");
print("response=$response2");
} catch (error) {
print("error ------------------");
print("error=$error");
}
}
|
Vamos analisar este código:
- Linha 12: [validateStatus: (_) => true]: desativa a validação padrão do status HTTP, para que você possa inspecionar por conta própria uma resposta de erro sem precisar passar sempre por um bloco [catch] —a mesma escolha de axios-04.ts.
- [response.headers['set-cookie']] retorna uma [List<String>?]: ao contrário de [response.headers] no Axios (um simples objeto), [response.headers] do Dio é um objeto [Headers] dedicado, cuja indexação sempre retorna uma lista.
- Linha 48: [RegExp('^($sessionCookieName.+?);').firstMatch(header)]: o cookie de sessão é recuperado e armazenado manualmente e depois reinserido no cabeçalho [Cookie] de cada requisição seguinte —exatamente o mesmo padrão de axios-04.ts, adaptado à API do Dio.
O resultado da execução é o seguinte:
| init-session action in progress ----------------
success --------------------------
response={action: init-session, status: 700, response: session started with type [json]}
authenticate-user action in progress ---------
success -------------------
response={action: authenticate-user, status: 200, response: Authentication successful [admin, admin]}
|
5.2.7. Conclusão
[package:http] e [package:dio] juntos cobrem todo o escopo de [fetch] e [axios]: uma API de baixo nível, próxima do protocolo, e uma API rica em recursos, com configuração global e tratamento de erros aprimorado. As diferenças específicas ([timeout] genérico por [Future] em vez de por requisição, ausência de cancelamento individual, ausência de gerenciamento automático de cookies) aparecerão, de forma concreta, nos clientes HTTP do capítulo seguinte.