跨平台开发 / 系统课时
创建统一 Dio 客户端
创建统一 Dio 客户端
当项目里的每个页面都各自 Dio() 时,baseUrl、超时和请求头很容易出现不一致。本课把这些通用配置收口到一个客户端中,让后续接口只关心路径、参数和业务数据。
学习目标
- 使用
BaseOptions集中配置baseUrl、连接/发送/接收超时和默认 Header。 - 创建可复用的单一
Dio实例,避免页面重复初始化网络客户端。 - 区分适合放在全局配置中的稳定参数与应按请求动态设置的数据。
为什么要统一创建 Dio
Dio 的 BaseOptions 是实例级默认配置。一次请求发出前,它会再与该请求自己的 Options 合并,因此全局配置适合承载所有接口都遵守的规则,而单次请求仍然可以覆盖局部设置。
如果页面 A 使用 10 秒超时、页面 B 使用 30 秒超时,或者不同模块各自拼接服务地址,排查问题时很难确认实际生效配置。统一客户端的价值不是少写几行代码,而是让网络层只有一个明确入口。
创建基础客户端
先在 pubspec.yaml 中加入 Dio 依赖。下面示例使用 Dio 5.x 的 Duration 超时配置形式。
dependencies:
flutter:
sdk: flutter
dio: ^5.11.1执行依赖安装后,创建 lib/network/api_client.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']);
}预期输出:
https://api.example.com
0:00:10.000000
0:00:15.000000
application/json实际项目中保留 ApiClient,测试入口 main() 可以删除。connectTimeout 控制建立连接等待时间,sendTimeout 控制发送请求数据的等待时间,receiveTimeout 控制接收响应数据的等待时间;它们不应简单理解为“整个请求最多执行多久”。
从业务代码复用客户端
业务接口不再创建新的 Dio,而是直接使用统一实例。下面是片段示例,依赖前面的 ApiClient,并假设后端提供 GET /users/<ID>。
Future<Map<String, dynamic>> fetchUser(String userId) async {
final response = await ApiClient.dio.get<Map<String, dynamic>>(
'/users/$userId',
);
return response.data ?? <String, dynamic>{};
}预期结果:
请求会发送到 https://api.example.com/users/<ID>。
响应体若能按 JSON 对象解析,则以 Map<String, dynamic> 返回;实际字段由后端接口定义。这样一来,业务代码只负责接口路径与业务参数。以后修改服务地址、统一超时或增加网络层能力时,不需要逐个页面查找 Dio()。
哪些配置应该放在统一入口
适合集中配置的是稳定且跨接口一致的内容,例如服务地址、基础超时、通用 Accept Header。环境切换时,也应由应用配置决定 baseUrl,而不是散落在业务页面中。
登录令牌、请求追踪 ID、语言等可能随用户或单次请求变化的数据,不适合在初始化时写死。它们可以在请求发生前动态设置;后续需要统一处理鉴权、日志和错误时,再通过拦截器扩展这个客户端。
统一客户端完成后,项目应能做到:搜索业务代码时基本看不到零散的 Dio() 初始化;公共网络配置只需修改一个位置;单个接口仍可通过自己的请求选项覆盖确有必要的局部配置。