跨平台开发 / 系统课时

配置请求头和超时时间

配置请求头和超时时间

本篇介绍如何在 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 或其他约定。

超时时间也不是越长越好。过长会让用户等待明显增加,过短则可能导致正常弱网请求频繁失败。实际项目应结合接口耗时统计和业务重要程度调整。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置请求头和超时时间

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

登录哪都通