Skip to content

5. As funções HTTP em Dart

Image

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:

1
2
3
4
5
6
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:

1
2
3
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:

1
2
3
4
5
--- 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:

1
2
3
4
5
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:

1
2
3
4
5
6
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:

1
2
3
4
5
6
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.