5. Dart 中的 HTTP 函数

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]
我们来解读这段代码:
- 第 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()] 在返回结果之前已经等待了整个正文。
执行结果如下:
5.2.2. 脚本 [dart_fetch_02]
我们来解读这段代码:
- dart_fetch_01.dart 的简洁版本,没有中间输出——结构保持不变:构造 [Uri],调用 [http.get],解码 JSON。
执行结果如下:
5.2.3. 脚本 [dart_fetch_03]
我们来解读这段代码:
- 第 21 行:[.timeout(const Duration(seconds: 2))] 在超过时间限制时,使失败的 [Future] 以 [TimeoutException] 结束——相当于 [fetch] 的 [AbortSignal.timeout()] 在 Dart 中的等价物。
- 第 35 行:[WARNING, key difference]——[http] 包没有像 [fetch] 的 [AbortController] 那样的针对单个请求的取消信号:唯一的取消方式是整体关闭客户端([http.Client.close()]),这会取消该客户端上所有待处理的请求——因此需要为希望能单独取消的请求创建专用的客户端。
执行结果如下:
5.2.4. 脚本 [dart_dio_01]
我们来解读这段代码:
- 第 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] 作同样的区分:带有服务器响应的错误(业务错误状态)与没有响应的错误(网络不可达、超时)。
执行结果如下:
5.2.5. 脚本 [dart_dio_02]
我们来解读这段代码:
- 第 38 行:[Options(contentType: Headers.formUrlEncodedContentType)]:一旦指定了此 [Content-Type],Dio 会自动将传给 [data] 的 [Map] 编码为 [x-www-form-urlencoded]——相当于 [qs.stringify(...)] 加上手动设置的 Axios 请求头。
- 此调用是一个新的 HTTP 请求,不会自动共享服务器在上一步中设置的会话 Cookie——无论 Dart 端的 Dio 还是 Node 端的 axios,都不会自动这样做:手动跟踪 Cookie 是下一个脚本的主题。
执行结果如下:
5.2.6. 脚本 [dart_dio_03]
我们来解读这段代码:
- 第 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。
执行结果如下:
5.2.7. 结论
[package:http] 和 [package:dio] 合在一起覆盖了 [fetch] 和 [axios] 的全部范围:一个贴近协议的低级 API,以及一个具有全局配置和增强错误处理的功能丰富的 API。其特有的差异([timeout] 是针对每个 [Future] 的通用机制而非针对每个请求、缺少单独取消、缺少自动 Cookie 管理)将在下一章的 HTTP 客户端中以具体形式体现出来。