跨平台开发 / 系统课时

创建统一 Dio 客户端

创建统一 Dio 客户端

当项目里的每个页面都各自 Dio() 时,baseUrl、超时和请求头很容易出现不一致。本课把这些通用配置收口到一个客户端中,让后续接口只关心路径、参数和业务数据。

学习目标

  • 使用 BaseOptions 集中配置 baseUrl、连接/发送/接收超时和默认 Header。
  • 创建可复用的单一 Dio 实例,避免页面重复初始化网络客户端。
  • 区分适合放在全局配置中的稳定参数与应按请求动态设置的数据。

为什么要统一创建 Dio

Dio 的 BaseOptions 是实例级默认配置。一次请求发出前,它会再与该请求自己的 Options 合并,因此全局配置适合承载所有接口都遵守的规则,而单次请求仍然可以覆盖局部设置。

如果页面 A 使用 10 秒超时、页面 B 使用 30 秒超时,或者不同模块各自拼接服务地址,排查问题时很难确认实际生效配置。统一客户端的价值不是少写几行代码,而是让网络层只有一个明确入口。

创建基础客户端

先在 pubspec.yaml 中加入 Dio 依赖。下面示例使用 Dio 5.x 的 Duration 超时配置形式。

yaml
dependencies:
  flutter:
    sdk: flutter
  dio: ^5.11.1

执行依赖安装后,创建 lib/network/api_client.dart。这里先只放稳定的公共配置,不加入登录令牌等动态数据。

dart
import 'package:dio/dio.dart';

final class ApiClient {
  ApiClient._();

  static final Dio _dio = Dio(
    BaseOptions(
      baseUrl: 'https://api.example.com',
      connectTimeout: const Duration(seconds: 10),
      sendTimeout: const Duration(seconds: 10),
      receiveTimeout: const Duration(seconds: 15),
      headers: const {
        'Accept': 'application/json',
      },
    ),
  );

  static Dio get dio => _dio;
}

void main() {
  final dio = ApiClient.dio;

  // 先验证配置本身,不依赖真实后端即可检查统一入口是否生效。
  print(dio.options.baseUrl);
  print(dio.options.connectTimeout);
  print(dio.options.receiveTimeout);
  print(dio.options.headers['Accept']);
}

预期输出:

text
https://api.example.com
0:00:10.000000
0:00:15.000000
application/json

实际项目中保留 ApiClient,测试入口 main() 可以删除。connectTimeout 控制建立连接等待时间,sendTimeout 控制发送请求数据的等待时间,receiveTimeout 控制接收响应数据的等待时间;它们不应简单理解为“整个请求最多执行多久”。

从业务代码复用客户端

业务接口不再创建新的 Dio,而是直接使用统一实例。下面是片段示例,依赖前面的 ApiClient,并假设后端提供 GET /users/<ID>。

dart
Future<Map<String, dynamic>> fetchUser(String userId) async {
  final response = await ApiClient.dio.get<Map<String, dynamic>>(
    '/users/$userId',
  );

  return response.data ?? <String, dynamic>{};
}

预期结果:

text
请求会发送到 https://api.example.com/users/<ID>。
响应体若能按 JSON 对象解析,则以 Map<String, dynamic> 返回;实际字段由后端接口定义。

这样一来,业务代码只负责接口路径与业务参数。以后修改服务地址、统一超时或增加网络层能力时,不需要逐个页面查找 Dio()。

哪些配置应该放在统一入口

适合集中配置的是稳定且跨接口一致的内容,例如服务地址、基础超时、通用 Accept Header。环境切换时,也应由应用配置决定 baseUrl,而不是散落在业务页面中。

登录令牌、请求追踪 ID、语言等可能随用户或单次请求变化的数据,不适合在初始化时写死。它们可以在请求发生前动态设置;后续需要统一处理鉴权、日志和错误时,再通过拦截器扩展这个客户端。

统一客户端完成后,项目应能做到:搜索业务代码时基本看不到零散的 Dio() 初始化;公共网络配置只需修改一个位置;单个接口仍可通过自己的请求选项覆盖确有必要的局部配置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建统一 Dio 客户端

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通