跨平台开发 / 系统课时
配置请求头和超时时间
配置请求头和超时时间
本篇介绍如何在 Flutter 网络请求中设置统一请求头和超时策略,让接口调用具备明确的等待边界,避免网络异常时应用长期卡住。
学习目标
- 理解请求头、连接超时和接收超时在网络请求中的作用
- 掌握 Dio 中配置通用 Header 与超时时间的方法
- 能够根据接口场景调整合理的超时策略
理解请求配置的作用
网络请求不仅需要发送地址和参数,还需要携带身份信息、客户端信息或数据格式声明。请求头用于描述这些额外信息,而超时时间用于限制请求等待时间。
在移动应用中,网络环境经常变化。如果没有设置超时,请求可能因为弱网、服务器异常或连接失败一直等待,影响用户体验。因此,客户端通常需要同时配置连接超时、发送超时和接收超时。
使用 Dio 配置 Header 和超时
Dio 提供 BaseOptions 集中管理请求默认配置。通过默认配置设置的 Header 和超时时间,会自动应用到后续请求中。
dart
import 'package:dio/dio.dart';
void main() {
final dio = Dio(
BaseOptions(
baseUrl: 'https://api.example.com',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer <TOKEN>',
},
connectTimeout: const Duration(seconds: 5),
sendTimeout: const Duration(seconds: 5),
receiveTimeout: const Duration(seconds: 10),
),
);
print(dio.options.baseUrl);
}预期输出
text
https://api.example.com这里的 <TOKEN> 表示运行时动态获取的认证信息,实际项目中通常来自登录流程或安全存储,而不是直接写入代码。
区分三种超时场景
Dio 中常见的超时配置分别控制不同阶段:
| 配置 | 作用 | 典型场景 |
|---|---|---|
| connectTimeout | 建立连接等待时间 | DNS、TCP 连接慢 |
| sendTimeout | 上传请求数据等待时间 | 上传文件或大请求体 |
| receiveTimeout | 等待服务器响应时间 | 接口处理慢或弱网 |
普通接口请求通常设置较短的连接超时和适中的响应超时;文件上传等场景则需要根据数据量增加发送时间。
请求级别覆盖配置
全局配置适用于大多数接口,但个别请求可能需要不同策略。例如导出报表接口可能执行时间较长,可以单独覆盖超时参数。
dart
final response = await dio.get(
'/reports/export',
options: Options(
receiveTimeout: const Duration(seconds: 60),
),
);预期结果
text
请求单独使用 60 秒接收超时配置,其他接口仍使用默认配置。常见配置错误
请求头配置完成后,仍需要确认服务端要求的字段名称和格式。例如认证信息通常要求 Authorization,但具体前缀可能是 Bearer 或其他约定。
超时时间也不是越长越好。过长会让用户等待明显增加,过短则可能导致正常弱网请求频繁失败。实际项目应结合接口耗时统计和业务重要程度调整。
按自己的节奏,确认真正理解。