跨平台开发 / 系统课时

用 BaseOptions 管理公共参数

用 BaseOptions 管理公共参数

在 Flutter 项目中,接口地址、超时时间、公共请求头等配置如果分散在每次请求代码里,会导致维护困难。本篇介绍如何使用 Dio 的 BaseOptions 集中管理这些公共参数,让接口访问入口更加统一。

学习目标

  • 理解 Dio BaseOptions 的职责和适用场景
  • 学会创建统一的 Dio 实例并配置公共请求参数
  • 掌握 BaseOptions 与单次请求参数的覆盖关系

BaseOptions 解决什么问题

在使用 Dio 调用接口时,很多请求都会共享相同配置,例如 API 基础地址、连接超时时间、响应超时时间以及公共请求头。如果每个接口都重复填写这些内容,项目规模扩大后容易出现配置不一致。

BaseOptions 是 Dio 提供的基础配置对象,用于初始化 Dio 实例时设置默认行为。创建完成后的 Dio 客户端会自动携带这些配置,请求代码只需要关注接口路径和业务参数。

创建统一 Dio 配置

项目通常会在网络层创建一个单独的 Dio 实例,而不是在每个页面临时创建。

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

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

Future<Response<dynamic>> fetchUser() {
  // 请求只需要填写接口路径
  return dio.get('/users/100');
}

预期结果

text
GET 请求地址自动组合为 https://api.example.com/users/100
请求默认携带 Accept: application/json 请求头
连接和响应超时时间使用 BaseOptions 中的配置

实际项目中,baseUrl、超时时间等值通常来自环境配置,不同环境可以使用不同的接口地址。

公共参数与单次请求参数的关系

BaseOptions 提供默认值,但并不限制单次请求调整。当某个接口需要特殊配置时,可以在请求方法中传入额外选项覆盖默认行为。

例如上传大文件时,可能需要更长的接收超时时间:

dart
final response = await dio.get(
  '/large-file',
  options: Options(
    receiveTimeout: const Duration(seconds: 60),
  ),
);

单次请求中的 Options 优先级高于 Dio 初始化时的 BaseOptions 配置。这样既保持了全局统一,又允许特殊接口拥有独立策略。

常见配置边界

BaseOptions 适合保存稳定的公共规则,例如:

  • 服务端基础地址
  • 默认超时时间
  • 通用请求头
  • 默认响应类型

不适合直接保存用户动态信息,例如登录 Token。Token 会随着登录状态变化,更适合通过拦截器动态注入。

合理划分配置职责,可以避免网络层出现大量条件判断,让接口调用代码保持简单。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 BaseOptions 管理公共参数

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

登录哪都通