Skip to content

5. Dart 中的 HTTP 函数

Image

5.1. 选择 HTTP 工具

与 JavaScript/TypeScript 提供原生的 [fetch] 函数(在浏览器和 Node.js 中都有)不同,Dart 的标准库没有提供高级客户端([dart:io] 只暴露了一个低级的 [HttpClient],直接使用起来很繁琐)。两个外部包合在一起,所覆盖的范围与 TypeScript 课程中的 [fetch] 和 [axios] 完全相同:

  • [package:http](pub.dev/packages/http),由 Dart 团队自己维护:简单的低级 API,没有全局配置或拦截器——相当于 [fetch] 的角色。
  • [package:dio](pub.dev/packages/dio):全局配置([baseUrl]、[timeout])、拦截器、增强的错误处理([DioException.response])——相当于 [axios] 的角色。

5.2. 税款计算服务器

本章中的所有脚本都以上一章安装的 NestJS 服务器为目标,地址为 [http://localhost:3000/main.php]。在测试下面的脚本之前,请确认 NestJS 服务器正在运行。为使其正常工作,Laragon 工具也必须处于运行状态。

5.2.1. 脚本 [dart_fetch_01]

// dart_fetch_01.dart
// 移植自 fetch-01.ts。
// Dart 中 HTTP 工具的选择:[http] 包(pub.dev/packages/http),
// 由 Dart 团队自己维护,扮演 Node.js/浏览器原生 [fetch] 的
// 角色 - 一个简单的底层 API,没有
// 全局配置或拦截器(与扮演 [axios] 角色的 [dio] 包
// 不同 - 见 dart_dio_01.dart)。
import 'dart:convert';
import 'package:http/http.dart' as http;

// 税款计算服务器的基础 URL(见“安装 NestJS 服务器”
// 一章)
const String baseUrl = 'http://localhost:3000/main.php';

// 初始化会话
Future<dynamic> initSession() async {
  // [与 TypeScript 的区别] [http] 包在请求本身上没有
  // [timeout] 选项:我们通过用 dart:async 的 [.timeout(...)] 扩展
  // 包装 Future 来限制等待时间,
  // 它适用于任何 Future(不仅仅是 HTTP
  // 请求)- 这是比 fetch 的
  // AbortSignal.timeout() 更通用的机制,后者是原生 fetch 特有的。
  final uri = Uri.parse(baseUrl).replace(queryParameters: {
    'action': 'init-session',
    'type': 'json',
  });
  try {
    // 异步请求 - http.get() 返回 Future<http.Response>
    final stopwatch = Stopwatch()..start();
    final response = await http.get(uri).timeout(const Duration(seconds: 2));
    // [response] 是服务器完整的 HTTP 响应(HTTP
    // 头 + 正文)- 我们将其显示出来以查看其结构
    print("http response in Dart (duration=${stopwatch.elapsedMilliseconds}ms) : "
        "statusCode=${response.statusCode}");
    // 我们可以访问 HTTP 头
    print("response headers=${response.headers}");
    // [与 TypeScript 的区别] 与 fetch 不同,fetch 中 response.json()
    // 是单独的异步方法(一个新的 Future),而
    // http.Response 的正文已经
    // 同步地完全可用(response.body,一个 String):http.get() 在返回结果之前
    // 已经等待了 整个正文。因此 jsonDecode() 在这里
    // 不是异步操作。
    final object = jsonDecode(response.body);
    print("json response=$object, type=${object.runtimeType}");
    return object;
  } catch (error) {
    // 我们到这里是因为服务器返回了错误代码,或者
    // 因为 http 客户端抛出了异常(网络不可达、
    // 超时……)
    print("fetch error in Dart=${error.runtimeType}, $error");
    // 我们重新抛出该错误
    rethrow;
  }
}

// main 函数运行异步函数 [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");
  }
}

我们来解读这段代码:

  • 第 30 行:[http.get(uri).timeout(const Duration(seconds: 2))]:[http] 包在请求本身上没有 [timeout] 选项——我们通过 dart:async 的 [.timeout(...)] 方法包装 [Future] 来限制等待时间,该方法适用于任何 [Future],而不仅仅是 HTTP 请求。
  • 第 43 行:[jsonDecode(response.body)]:与 [fetch] 不同,其中 [response.json()] 是一个独立的异步方法,而 [http.Response] 的正文已经完全同步可用([response.body],一个 [String]):[http.get()] 在返回结果之前已经等待了整个正文。

执行结果如下:

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. 脚本 [dart_fetch_02]

// dart_fetch_02.dart
// 移植自 fetch-02.ts:dart_fetch_01.dart 的“精简”版本,没有
// 中间的显示输出。
import 'dart:convert';
import 'package:http/http.dart' as http;

const String baseUrl = 'http://localhost:3000/main.php';

// 初始化会话
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));
  // 以 JSON 格式收到的结果
  return jsonDecode(response.body);
}

// main 函数运行异步函数 [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");
  }
}

我们来解读这段代码:

  • dart_fetch_01.dart 的简洁版本,没有中间输出——结构保持不变:构造 [Uri],调用 [http.get],解码 JSON。

执行结果如下:

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. 脚本 [dart_fetch_03]

// dart_fetch_03.dart
// 移植自 fetch-03.ts:HTTP 请求的最长延迟和手动
// 取消。
import 'package:http/http.dart' as http;

// 税款计算服务器的基础 URL(见 http/README,原课程中
// 历史悠久的 PHP 服务器;这里我们直接指向
// NestJS 服务器 - 见“安装 NestJS 服务器”一章)
const String baseUrl = 'http://localhost:3000/main.php';

// 示例 1:借助 [.timeout(...)] 设置最长延迟的请求 ¶(dart:async 对任意 Future 的扩展 -
// 见 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'))
        // 超过 2 秒后,[.timeout] 以 [TimeoutException] 错误
        // 完成该 Future - 相当于
        // fetch 的 AbortSignal.timeout() 的 Dart 写法
        .timeout(const Duration(seconds: 2));
    print("response = ${response.body}");
  } catch (error) {
    // 如果服务器不存在(在本练习中很可能如此),或者
    // 超过了延迟,[error] 视情况为 [TimeoutException]
    // 或 [SocketException]/[ClientException]
    print("error.runtimeType = ${error.runtimeType}, message = $error");
  }
}

// 示例 2:手动取消请求,例如因为
// 用户改变了主意(例如:他们在搜索
// 字段中重新输入)。
//
// [注意,与 TypeScript 的根本区别] [http] 包没有
// 针对单个请求的取消信号,不像 fetch 的 AbortSignal:唯一的
// 取消方式是整体关闭客户端(http.Client.close()),
// 这会取消该客户端上所有正在进行的请求 - 因此
// 你需要为想要单独取消的请求创建一个专用的客户端,
// 而不是整个应用共享的客户端。
Future<void> manuallyCancellableRequest() async {
  print("--- request cancelled manually ---");
  final client = http.Client();

  // 我们安排在 10 毫秒后进行一次“业务”取消(在真实
  // 应用中,这例如是点击“取消”按钮)
  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) {
    // 在请求进行期间关闭客户端会使其以
    // [ClientException] 失败
    print("error.runtimeType = ${error.runtimeType}, message = $error");
  }
}

Future<void> main() async {
  await requestWithMaximumDelay();
  await manuallyCancellableRequest();
}

我们来解读这段代码:

  • 第 21 行:[.timeout(const Duration(seconds: 2))] 在超过时间限制时,使失败的 [Future] 以 [TimeoutException] 结束——相当于 [fetch] 的 [AbortSignal.timeout()] 在 Dart 中的等价物。
  • 第 35 行:[WARNING, key difference]——[http] 包没有像 [fetch] 的 [AbortController] 那样的针对单个请求的取消信号:唯一的取消方式是整体关闭客户端([http.Client.close()]),这会取消该客户端上所有待处理的请求——因此需要为希望能单独取消的请求创建专用的客户端。

执行结果如下:

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. 脚本 [dart_dio_01]

// dart_dio_01.dart
// 移植自 axios-01.ts 和 axios-02.ts。
// Dart 中 HTTP 工具的选择:[dio] 包(pub.dev/packages/dio)
// 扮演 [axios] 的角色 - 全局配置(baseUrl、timeout)、
// 拦截器、增强的错误处理(error.response,与
// axios 相同):所有更接近 fetch 的 [http] 包
// 留给调用代码处理的事情(见 dart_fetch_01.dart)。
import 'package:dio/dio.dart';

// 一次性配置好的 Dio 实例,被所有
// 调用复用 - 正是 TypeScript 中 "axios.defaults" 的作用
final Dio dio = Dio(BaseOptions(
  baseUrl: 'http://localhost:3000/',
  connectTimeout: const Duration(seconds: 2),
  receiveTimeout: const Duration(seconds: 2),
));

// 初始化会话
Future<dynamic> initSession({required String type}) async {
  try {
    // 异步请求 - dio.get() 直接接受
    // queryParameters,就像 axios.request({params: ...})
    final response = await dio.get('main.php', queryParameters: {
      'action': 'init-session',
      'type': type,
    });
    // 服务器的响应在 [response.data] 中(如果 Content-Type 是 JSON,Dio 已将其
    // 解码为 Map/List),与 axios 中的
    // response.data 完全一样
    return response.data;
  } on DioException catch (error) {
    // 参数 [error] 是一个 [DioException] - 我们将其显示出来
    // 以查看其结构(相当于 axios-01.ts 中被注释掉的
    // "console.log(axios error)")
    if (error.response != null) {
      // 服务器在 HTTP 状态中表明了错误,但
      // 同时也发回了响应:它在 [error.response!.data] 中,
      // 与 axios 中的 [error.response.data] 完全一样
      return error.response!.data;
    } else {
      // 根本没有响应(网络不可达、超时……)- 我们
      // 重新抛出该错误
      rethrow;
    }
  }
}

Future<void> main() async {
  try {
    // 第 1 次尝试,故意无效(type='x' 而不是 'json'),
    // 以观察服务器 - 然后是 dio - 如何表明错误:
    // 服务器仍然会响应(带有业务错误状态),所以
    // error.response.data 确实有内容,与 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 次尝试,已更正(type='json'),与 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");
  }
}

我们来解读这段代码:

  • 第 12–15 行:[Dio(BaseOptions(baseUrl: ..., connectTimeout: ..., receiveTimeout: ...))]:一个一次配置、供所有调用复用的 [Dio] 实例——正是 TypeScript 中 [axios.defaults] 的角色。
  • [response.data]:服务器的响应,如果 [Content-Type] 是 JSON,Dio 已将其解码为 [Map]/[List],与 axios 中的 [response.data] 完全一样。
  • 第 30–31 行:[on DioException catch (error) { if (error.response != null) ... }]:与 Axios 中的 [error.response] 作同样的区分:带有服务器响应的错误(业务错误状态)与没有响应的错误(网络不可达、超时)。

执行结果如下:

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. 脚本 [dart_dio_02]

// dart_dio_02.dart
// 移植自 axios-03.ts:串联两个 HTTP 请求 - init-session,然后
// authenticate-user(一个正文编码为
// x-www-form-urlencoded 的 POST)。
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 {
    // 正文为 x-www-form-urlencoded 的 POST 请求 - 如果在 [Options] 中指定了
    // Content-Type,Dio 会自动
    // 将 Map 编码为 x-www-form-urlencoded,
    // 完全相当于 qs.stringify(...) + 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;
  }
}

// main 函数逐个运行这些异步函数
Future<void> main() async {
  try {
    // init-session
    print("init-session action in progress "
        "---------------------------------------------");
    final response1 = await initSession();
    print("success ---------------------------------------------");
    print("response=$response1");
    // authenticate-user - [注意,与原始 TypeScript
    // 课程中一样] 这次调用从一个新的 HTTP 请求开始,不会
    // 自动共享服务器在
    // 上一步设置的会话 Cookie(在 Node/Dart 端,
    // Dio 和 axios 都不会自动这样做):手动跟踪会话 Cookie 正是
    // dart_dio_03.dart 的主题,它移植自 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");
  }
}

我们来解读这段代码:

  • 第 38 行:[Options(contentType: Headers.formUrlEncodedContentType)]:一旦指定了此 [Content-Type],Dio 会自动将传给 [data] 的 [Map] 编码为 [x-www-form-urlencoded]——相当于 [qs.stringify(...)] 加上手动设置的 Axios 请求头。
  • 此调用是一个新的 HTTP 请求,不会自动共享服务器在上一步中设置的会话 Cookie——无论 Dart 端的 Dio 还是 Node 端的 axios,都不会自动这样做:手动跟踪 Cookie 是下一个脚本的主题。

执行结果如下:

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. 脚本 [dart_dio_03]

// dart_dio_03.dart
// 移植自 axios-04.ts:在两个请求之间手动跟踪会话 Cookie。
import 'package:dio/dio.dart';

final Dio dio = Dio(BaseOptions(
  baseUrl: 'http://localhost:3000/',
  connectTimeout: const Duration(seconds: 2),
  receiveTimeout: const Duration(seconds: 2),
  // 我们禁用 HTTP 状态的默认验证,以便自己
  // 检查错误响应(与 axios 中的 error.response 相同),
  // 而无需总是进入 catch 块
  validateStatus: (_) => true,
));

// 会话 Cookie
const String sessionCookieName = "connect.sid";
String sessionCookie = '';

Future<dynamic> getRemoteData(String path, {
  required String method,
  Map<String, dynamic>? queryParameters,
  Object? data,
  Options? options,
}) async {
  // 对于会话 Cookie - 我们自己把它添加到每个请求的
  // 头中,与 axios-04.ts 完全一样
  final opts = (options ?? Options(method: method)).copyWith(
    method: method,
    headers: {
      ...?options?.headers,
      'Cookie': sessionCookie,
    },
  );
  // 执行 HTTP 请求
  final response = await dio.request(
    path,
    queryParameters: queryParameters,
    data: data,
    options: opts,
  );
  // 如果会话 Cookie 存在,我们就取出它 - response.headers 是
  // Dio 的 [Headers] 对象(不像 axios 中的 response.headers
  // 那样是简单的 Map);response.headers['set-cookie'] 返回 List<String>?
  final setCookie = response.headers['set-cookie'];
  if (setCookie != null) {
    // 我们在这个列表中查找会话 Cookie
    for (final header in setCookie) {
      final result = RegExp('^($sessionCookieName.+?);').firstMatch(header);
      if (result != null) {
        // 我们存储会话 Cookie
        sessionCookie = result.group(1)!;
        break;
      }
    }
  }
  // 服务器的响应在 [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),
  );
}

// main 函数逐个运行这些异步函数
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");
  }
}

我们来解读这段代码:

  • 第 12 行:[validateStatus: (_) => true]:禁用对 HTTP 状态的默认验证,这样您就可以自己检查错误响应,而不必总是通过 [catch] 块——与 axios-04.ts 的选择相同。
  • [response.headers['set-cookie']] 返回 [List<String>?]:与 Axios 中的 [response.headers](一个简单对象)不同,Dio 的 [response.headers] 是专门的 [Headers] 对象,对其索引总是返回一个列表。
  • 第 48 行:[RegExp('^($sessionCookieName.+?);').firstMatch(header)]:会话 Cookie 被手动取出并存储,然后在每个后续请求的 [Cookie] 头中重新插入——与 axios-04.ts 的模式完全相同,只是适配了 Dio 的 API。

执行结果如下:

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. 结论

[package:http] 和 [package:dio] 合在一起覆盖了 [fetch] 和 [axios] 的全部范围:一个贴近协议的低级 API,以及一个具有全局配置和增强错误处理的功能丰富的 API。其特有的差异([timeout] 是针对每个 [Future] 的通用机制而非针对每个请求、缺少单独取消、缺少自动 Cookie 管理)将在下一章的 HTTP 客户端中以具体形式体现出来。