Flutter Dio进阶：使用Flutter Dio拦截器实现高效的API请求管理和身份验证刷新

jcLee952024-02-29 15:36

Flutter笔记 使用Flutter Dio拦截器实现高效的API请求管理和身份验证刷新

【介绍】：在构建现代移动应用程序时，与后端服务的交互是不可避免的。Flutter作为一个流行的跨平台框架，提供了多种方式与后端API进行交互。Dio是一个强大的Dart HTTP客户端，它支持请求拦截、响应拦截、错误处理、全局配置等功能，非常适合用于Flutter应用程序中进行网络请求。本文将深入探讨如何在Flutter中使用Dio的拦截器功能，以实现高效的API请求管理和身份验证刷新。

目 录

  • [1. Dio基础及配置](#1. Dio基础及配置)
    • [1.1 Dio简介](#1.1 Dio简介)
    • [1.2 安装和创建Dio实例](#1.2 安装和创建Dio实例)
      • [1.2.1 如何在Flutter项目中添加Dio依赖](#1.2.1 如何在Flutter项目中添加Dio依赖)
      • [1.2.2 创建和配置Dio实例](#1.2.2 创建和配置Dio实例)
    • [1.3 Dio基本使用](#1.3 Dio基本使用)
      • [1.3.1 GET请求项目中添加Dio依赖](#1.3.1 GET请求项目中添加Dio依赖)
      • [1.3.2 POST请求](#1.3.2 POST请求)
      • [1.3.3 PUT请求](#1.3.3 PUT请求)
      • [1.3.4 DELETE请求](#1.3.4 DELETE请求)
      • [1.3.5 PATCH请求](#1.3.5 PATCH请求)
      • [1.3.6 HEAD请求](#1.3.6 HEAD请求)
      • [1.3.7 HEAD请求](#1.3.7 HEAD请求)
      • [1.3.8 Dio异常处理](#1.3.8 Dio异常处理)
        • [1. 旧版本Dio库（DioError、DioErrorType）](#1. 旧版本Dio库（DioError、DioErrorType）)
        • [2. 新版本Dio库（DioException、DioExceptionType）](#2. 新版本Dio库（DioException、DioExceptionType）)
        • [3. 错误处理建议](#3. 错误处理建议)
  • [2. 深入Dio拦截器](#2. 深入Dio拦截器)
    • [2.1 拦截器概念](#2.1 拦截器概念)
      • [2.1.1 什么是拦截器](#2.1.1 什么是拦截器)
      • [2.1.2 拦截器的作用和应用场景](#2.1.2 拦截器的作用和应用场景)
    • [2.2 配置拦截器](#2.2 配置拦截器)
      • [2.2.1 如何向Dio实例添加拦截器](#2.2.1 如何向Dio实例添加拦截器)
      • [2.2.2 拦截器的基本结构和回调函数](#2.2.2 拦截器的基本结构和回调函数)
    • [2.3 请求拦截器的应用](#2.3 请求拦截器的应用)
      • [2.3.1 动态添加请求头](#2.3.1 动态添加请求头)
      • [2.3.2 请求参数的预处理](#2.3.2 请求参数的预处理)
    • [2.4 响应拦截器的应用](#2.4 响应拦截器的应用)
      • [2.4.1 数据预处理和格式化](#2.4.1 数据预处理和格式化)
      • [2.4.1 根据响应状态进行全局错误处理](#2.4.1 根据响应状态进行全局错误处理)
    • [2.5 错误拦截器的应用](#2.5 错误拦截器的应用)
      • [2.5.1 捕获和处理HTTP错误](#2.5.1 捕获和处理HTTP错误)
      • [2.5.2 自定义错误消息和错误处理逻辑](#2.5.2 自定义错误消息和错误处理逻辑)
  • [3. 实现身份验证刷新机制](#3. 实现身份验证刷新机制)
    • [3.1 身份验证流程概述](#3.1 身份验证流程概述)
      • [3.1.1 访问令牌和刷新令牌的概念](#3.1.1 访问令牌和刷新令牌的概念)
      • [3.1.2 身份验证流程的基本步骤](#3.1.2 身份验证流程的基本步骤)
    • [3.2 使用拦截器处理401错误](#3.2 使用拦截器处理401错误)
      • [3.2.1 检测401错误并触发令牌刷新](#3.2.1 检测401错误并触发令牌刷新)
      • [3.2.2 刷新令牌的实现方法](#3.2.2 刷新令牌的实现方法)
    • [3.3 自动重试原始请求](#3.3 自动重试原始请求)
      • [3.3.1 保存和重试失败的请求](#3.3.1 保存和重试失败的请求)
      • [3.3.2 更新请求头并重新发起请求](#3.3.2 更新请求头并重新发起请求)
    • [3.4 安全存储令牌](#3.4 安全存储令牌)
      • [3.4.1 使用Flutter Secure Storage存储令牌](#3.4.1 使用Flutter Secure Storage存储令牌)
        • [1.安装Flutter Secure Storage](#1.安装Flutter Secure Storage)
        • 2.存储令牌
      • [3.4.2 令牌的安全管理和更新](#3.4.2 令牌的安全管理和更新)
  • [4. 高级应用](#4. 高级应用)
    • [4.1 缓存策略实现](#4.1 缓存策略实现)
      • [4.1.1 使用拦截器实现请求缓存](#4.1.1 使用拦截器实现请求缓存)
      • [4.1.2 缓存策略的设计和应用](#4.1.2 缓存策略的设计和应用)
    • [4.2 日志记录和调试](#4.2 日志记录和调试)
      • [4.2.1 使用拦截器进行日志记录](#4.2.1 使用拦截器进行日志记录)
      • [4.2.2 调试技巧和工具](#4.2.2 调试技巧和工具)
    • [4.3 Dio的扩展和自定义](#4.3 Dio的扩展和自定义)
      • [4.3.1 扩展Dio功能](#4.3.1 扩展Dio功能)
      • [4.3.2 创建自定义拦截器](#4.3.2 创建自定义拦截器)
  • [5. 结论](#5. 结论)

[1. Dio基础及配置](#1. Dio基础及配置)

[1.1 Dio简介](#1.1 Dio简介)

Dio 是一个强大的Dart HTTP 客户端，支持拦截器、全局配置、FormData、请求取消、文件下载、超时等。它的特性包括但不限于：

请求和响应拦截，允许开发者在请求发送前和响应返回后执行特定逻辑。

全局配置，如基础URL、连接超时时间、接收超时时间等，简化了请求的配置。

FormData，方便地处理表单数据和文件上传。

请求取消，提供了取消正在进行的HTTP请求的能力。

错误处理，通过统一的错误处理机制简化了错误管理。

与Flutter 的官方HTTP Client 相比，Dio 提供了更高级的功能，如拦截器和全局配置，这使得它在处理复杂网络请求时更加灵活和强大。相比于其他第三方HTTP客户端库，Dio的特点在于其丰富的功能和良好的文档支持。

[1.2 安装和创建Dio实例](#1.2 安装和创建Dio实例)

[1.2.1 如何在Flutter项目中添加Dio依赖](#1.2.1 如何在Flutter项目中添加Dio依赖)

在pubspec.yaml文件中添加Dio的依赖项：

yaml 复制代码 
dependencies:
 dio: ^5.4.1 # 请检查最新版本

然后运行flutter pub get来安装依赖。

[1.2.2 创建和配置Dio实例](#1.2.2 创建和配置Dio实例)

创建Dio实例并配置基础URL和超时时间：

dart 复制代码 
import 'package:dio/dio.dart';

// 创建一个 Dio 实例
Dio dio = Dio(
  // 配置 Dio 实例的选项
  BaseOptions(
    // 设置请求的基本 URL
    baseUrl: "https://api.example.com",
    // 设置连接超时时间为 5000 毫秒（5 秒）
    connectTimeout: Duration(milliseconds: 5000),
    // 设置接收超时时间为 3000 毫秒（3 秒）
    receiveTimeout: Duration(milliseconds: 3000),
  ),
);

[1.3 Dio基本使用](#1.3 Dio基本使用)

在本节中，我们将详细探讨如何使用Dio 进行网络请求，包并初步介绍Dio中的异常处理和错误处理机制。

[1.3.1 GET请求项目中添加Dio依赖](#1.3.1 GET请求项目中添加Dio依赖)

GET请求通常用于请求服务器发送资源。

dart 复制代码 
try {
  Response response = await dio.get("/user?id=123");
  print(response.data);
} on DioException catch (e) {
  print(e.message);
}

[1.3.2 POST请求](#1.3.2 POST请求)

POST请求通常用于向服务器提交数据。例如：

dart 复制代码 
try {
  Response response = await dio
      .post("/apis/auth/send-code/", data: {"email": "291148484@163.com"});
  print(response.data);
} on DioException catch (e) {
  print(e.message);
}

[1.3.3 PUT请求](#1.3.3 PUT请求)

PUT请求用于更新资源。

dart 复制代码 
try {
  Response response = await dio.put("/user/123", data: {"name": "john doe"});
  print(response.data);
} on DioException catch (e) {
  print(e.message);
}

[1.3.4 DELETE请求](#1.3.4 DELETE请求)

DELETE请求用于删除资源。

dart 复制代码 
try {
  Response response = await dio.delete("/user/123");
  print(response.data);
} on DioException catch (e) {
  print(e.message);
}

[1.3.5 PATCH请求](#1.3.5 PATCH请求)

PATCH请求用于对资源进行部分更新。

dart 复制代码 
try {
  Response response = await dio.patch("/user/123", data: {"name": "johnny"});
  print(response.data);
} on DioException catch (e) {
  print(e.message);
}

[1.3.6 HEAD请求](#1.3.6 HEAD请求)

HEAD请求用于获取资源的元数据，如响应头信息，而不返回响应体。

dart 复制代码 
try {
  Response response = await dio.head("/user/123");
  print(response.headers);
} on DioException catch (e) {
  print(e.message);
}

[1.3.7 HEAD请求](#1.3.7 HEAD请求)

OPTIONS请求用于获取目的资源所支持的通信选项。

dart 复制代码 
try {
  Response response = await dio.options("/user/123");
  print(response.headers);
} on DioException catch (e) {
  print(e.message);
}

[1.3.8 Dio异常处理](#1.3.8 Dio异常处理)

1. 旧版本Dio库（DioError、DioErrorType）

由于新的API更改不久。目前绝大多数已有的项目，如果使用了Dio，几乎都是基于DioError类处理异常。

旧版本的 Dio 中，提供了一个DioError 类来处理异常。DioError 包含了错误的详细信息，如错误类型type、请求信息request、响应信息response等。通过捕获DioError，我们可以根据错误类型进行不同的处理。

dart 复制代码 
try {
  Response response = await dio.get("/user?id=123");
} on DioError catch (e) {
  if (e.type == DioErrorType.connectTimeout) {
    // 连接超时处理
  } else if (e.type == DioErrorType.receiveTimeout) {
    // 响应超时处理
  } else if (e.type == DioErrorType.response) {
    // 服务器响应错误处理
    print(e.response?.statusCode);
  } else {
    // 其他错误处理
  }
}

Dio错误类型主要包括：

  • DioErrorType.cancel：请求取消。

  • DioErrorType.connectTimeout：连接超时。

  • DioErrorType.sendTimeout：发送超时。

  • DioErrorType.receiveTimeout：接收超时。

  • DioErrorType.response：服务器响应错误 ，例如404、500等。

  • DioErrorType.other：其他错误，如无网络连接、请求被拦截器拒绝等。

通过对DioError的处理，我们可以更加灵活地处理网络请求中可能遇到的各种异常情况，从而提高应用的稳定性和用户体验。

2. 新版本Dio库（DioException、DioExceptionType）

新版本的 Dio 库，异常处理的方式有所变化，主要是通过 DioException 类来处理错误，而不再使用 DioError。

DioException 类提供了更详细的错误信息，包括请求选项 requestOptions、响应信息 response、错误类型 type、原始错误对象 error、错误消息 message 等。例如：

dart 复制代码 
try {
  Response response = await dio.get("/user?id=123");
} on DioException catch (e) {
  switch (e.type) {
    case DioExceptionType.connectionTimeout:
      // 连接超时处理
      print('连接超时');
      break;
    case DioExceptionType.sendTimeout:
      // 发送超时处理
      print('发送超时');
      break;
    case DioExceptionType.receiveTimeout:
      // 接收超时处理
      print('接收超时');
      break;
    case DioExceptionType.badResponse:
      // 服务器响应错误处理
      print('服务器响应错误，状态码：${e.response?.statusCode}');
      break;
    case DioExceptionType.cancel:
      // 请求取消处理
      print('请求被取消');
      break;
    case DioExceptionType.connectionError:
      // 连接错误处理
      print('连接错误');
      break;
    case DioExceptionType.unknown:
    default:
      // 其他错误处理
      print('未知错误');
      break;
  }
}

新版本的Dio中的 DioExceptionType 枚举定义以下错误类型：

  • cancel：请求取消。当请求在完成前被取消时，会触发此错误。
  • connectionTimeout：连接超时。发生此错误时，表示客户端在与服务器建立连接时超出指定的时间限制。
  • sendTimeout：发送超时。当请求在发送数据到服务器时超时，会触发此错误。
  • receiveTimeout：接收超时。当等待服务器响应超出设定的时间限制时，会触发此错误。
  • badResponse：服务器响应错误。当服务器的响应状态码不在预期的范围内时，会触发此错误。
  • connectionError：连接错误。当请求由于网络连接问题失败时，会触发此错误。
  • badCertificate：证书验证失败 。这种情况通常发生在 HTTPS 请求中，当服务器的 SSL 证书不被客户端信任时，就会抛出此类型的异常。
  • unknown：未知错误。当发生未预料到的其他错误时，会使用此类型。

这些错误类型相对于旧Dio版本中的错误类型进行了优化，更加清晰。

当遇到 badCertificate 错误时，意味着客户端与服务器之间的安全连接建立失败。这可能是因为服务器使用了自签名证书，或者证书已经过期，或者证书链中有不被信任的证书等原因。

处理 badCertificate 错误的一个方法是提示用户当前连接可能不安全，或者在开发阶段，可以考虑暂时忽略证书验证错误（虽然这不是一个推荐的做法，因为它会降低应用的安全性）。例如：

dart 复制代码 
try {
  Response response = await dio.get("/secure-data");
} on DioException catch (e) {
  if (e.type == DioExceptionType.badCertificate) {
    // 处理证书验证失败
    print('证书验证失败');
  }
  // 其他错误处理...
}
3. 错误处理建议
  • 对于connectionTimeout、sendTimeout、receiveTimeout，可以考虑增加超时时间，或者提示用户检查网络连接。
  • badResponse错误可以用来处理服务器返回的错误状态码，例如404 或 500 等，可以根据不同的状态码给用户不同的提示。
  • cancel类型的错误通常是用户主动取消请求，一般不需要特殊处理。
  • connectionError可能是由于用户的网络环境问题导致的，可以提示用户检查网络连接。
  • 对于unknown类型的错误，可以记录日志供进一步分析，同时给用户一个通用的错误提示。
  • 在生产环境中，处理badCertificate错误的最佳做法是确保服务器使用的是由受信任的证书颁发机构（CA ）签发的有效证书，并且客户端的证书存储包含了这些受信任的CA 证书。这样可以保证客户端与服务器之间的通信是安全的，同时避免了badCertificate错误的发生。

通过以上方式，可以有效地对 Dio 进行异常处理，提升应用的健壮性和用户体验。

[2. 深入Dio拦截器](#2. 深入Dio拦截器)

[2.1 拦截器概念](#2.1 拦截器概念)

[2.1.1 什么是拦截器](#2.1.1 什么是拦截器)

拦截器 是Dio提供的一种强大机制，它允许开发者在请求发送前、响应返回后以及发生错误时介入处理逻辑。

这种机制使得开发者可以在请求的各个阶段执行自定义的操作，例如修改请求头、处理响应数据、统一处理错误等。

[2.1.2 拦截器的作用和应用场景](#2.1.2 拦截器的作用和应用场景)

拦截器的主要作用和应用场景包括：

  • 动态添加请求头：例如，根据不同的请求动态添加Token或其他认证信息。

  • 缓存响应：对特定请求的响应进行缓存，减少服务器负担，加快加载速度。

  • 重试请求：在请求失败时自动重试，提高应用的健壮性。

  • 记录日志：记录请求和响应的详细信息，便于调试和监控。

  • 处理错误：统一处理请求错误，例如，根据错误类型跳转到不同页面或显示不同提示。

[2.2 配置拦截器](#2.2 配置拦截器)

[2.2.1 如何向Dio实例添加拦截器](#2.2.1 如何向Dio实例添加拦截器)

向Dio 实例添加拦截器非常简单，只需使用interceptors.add方法并传入一个InterceptorsWrapper 实例。InterceptorsWrapper 允许你定义onRequest、onResponse和onError三个回调函数，分别对应请求前、响应后和发生错误时的处理逻辑。

dart 复制代码 
dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) {
    // 在请求发送前添加逻辑
    // 例如，添加一个自定义的请求头
    options.headers["Custom-Header"] = "value";
    // 继续执行请求
    return handler.next(options);
  },
  onResponse: (response, handler) {
    // 在响应返回后添加逻辑
    // 例如，打印响应数据
    print(response.data);
    // 继续执行响应
    return handler.next(response);
  },
  onError: (DioException e, handler) {
    // 在发生错误时添加逻辑
    // 例如，根据错误类型显示不同的错误信息
    print(e.message);
    // 继续执行错误处理
    return handler.next(e);
  },
));

[2.2.2 拦截器的基本结构和回调函数](#2.2.2 拦截器的基本结构和回调函数)

InterceptorsWrapper的基本结构包括三个回调函数：

  • onRequest ：在请求发送前调用，可以用于修改请求选项（如URL 、头部 、请求体等）。

  • onResponse：在响应返回后调用，可以用于处理或修改响应数据。

  • onError：在请求发生错误时调用，可以用于统一处理错误。

每个回调函数都接收两个参数：

  • 一个是 请求/响应/错误 对象;
  • 另一个是handler。handler.next方法。用于继续执行 请求/响应/错误 处理流程，也可以使用handler.resolve 和 handler.reject 来直接返回成功或失败的结果。

通过合理利用拦截器，开发者可以在不修改业务逻辑代码的情况下，灵活地实现请求管理和处理的各种需求，极大地提高了代码的可维护性和扩展性。

[2.3 请求拦截器的应用](#2.3 请求拦截器的应用)

请求拦截器在Dio中扮演着至关重要的角色，它允许开发者在请求发送到服务器之前介入，执行一些预处理操作。这些操作包括但不限于动态添加请求头、请求参数的预处理等。

[2.3.1 动态添加请求头](#2.3.1 动态添加请求头)

在实际开发中，我们经常需要向请求中动态添加一些信息，如认证令牌（Token）、应用版本号等。这些信息可能会随着用户的登录状态或应用的更新而变化。使用请求拦截器，我们可以轻松实现这一需求。

dart 复制代码 
dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) async {
    // 动态获取Token
    String token = await getToken(); // 假设getToken是一个异步函数，用于获取存储的Token
    // 如果Token存在，则将其添加到请求头中
    options.headers["Authorization"] = "Bearer $token";
      // 继续执行请求
    return handler.next(options);
  },
));

在上述代码中，getToken函数用于从本地存储或其他来源获取当前用户的认证令牌。如果令牌存在，我们将其添加到请求头的Authorization 字段中。这样，所有通过Dio发出的请求都会自动携带认证令牌，无需在每个请求中手动添加。

[2.3.2 请求参数的预处理](#2.3.2 请求参数的预处理)

除了添加请求头，请求拦截器还可以用于对请求参数进行预处理。例如，我们可能需要对所有请求的参数进行统一的格式化、加密或添加公共参数。

dart 复制代码 
dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) {
    // 添加公共参数
    Map<String, dynamic> commonParams = {"appVersion": "1.0.0", "platform": "iOS"};
    if (options.method.toUpperCase() == "GET") {
      // 对于GET请求，添加到URL的查询参数中
      options.queryParameters.addAll(commonParams);
    } else {
      // 对于POST、PUT等请求，添加到请求体中
      final data = options.data ?? {};
      if (data is Map) {
        data.addAll(commonParams);
        options.data = data;
      }
    }
    // 继续执行请求
    return handler.next(options);
  },
));

在这个例子中，我们向所有请求添加了两个公共参数：appVersion和platform。这些参数根据请求的类型（GET或其他）被添加到查询参数或请求体中。这种方式特别适用于那些需要在每个请求中传递应用信息或用户状态的场景。

通过这两个示例，我们可以看到请求拦截器在实现动态请求头添加和请求参数预处理方面的强大能力。利用这些技术，开发者可以编写更加干净、高效的网络请求代码。

[2.4 响应拦截器的应用](#2.4 响应拦截器的应用)

响应拦截器在处理服务器返回的数据时非常有用。它允许开发者在数据被处理之前，对其进行预处理或格式化，以及根据响应状态进行全局错误处理。

[2.4.1 数据预处理和格式化](#2.4.1 数据预处理和格式化)

在很多情况下，服务器返回的数据可能需要进行一些预处理才能被应用程序使用。例如，你可能需要从响应中提取特定的数据字段，或者将日期字符串转换为DateTime对象。响应拦截器可以在数据被应用程序处理之前，对其进行这样的预处理。

dart 复制代码 
dio.interceptors.add(InterceptorsWrapper(
  onResponse: (response, handler) {
    // 假设服务器返回的数据结构如下：{ "success": true, "data": {...} }
    // 我们只对"data"字段感兴趣
    var responseData = response.data['data'];
    // 对responseData进行进一步处理，例如日期格式化
    // 假设responseData包含一个日期字段"createdAt"，我们将其转换为DateTime对象
    if (responseData.containsKey('createdAt')) {
      responseData['createdAt'] = DateTime.parse(responseData['createdAt']);
    }
    // 更新响应数据
    response.data = responseData;
    // 继续执行响应
    return handler.next(response);
  },
));

在上面的代码中，我们首先从响应数据中提取了data字段，并对其中的createdAt字段进行了日期格式化。然后，我们将处理后的数据重新赋值给response.data，以便应用程序可以使用格式化后的数据。

[2.4.1 根据响应状态进行全局错误处理](#2.4.1 根据响应状态进行全局错误处理)

响应拦截器还可以用于根据响应状态进行全局错误处理。例如，如果服务器返回的状态码表示用户未授权（如401），我们可以自动重定向用户到登录页面。

dart 复制代码 
dio.interceptors.add(InterceptorsWrapper(
  onResponse: (response, handler) {
    // 检查响应状态码
    if (response.statusCode == 401) {
      // 如果用户未授权，则重定向到登录页面
      Navigator.of(context).pushReplacementNamed('/login');
      // 由于我们已经处理了这个错误，我们不希望继续抛出错误
      // 因此，我们可以使用handler.resolve来直接返回一个成功的响应
      return handler.resolve(response);
    }
    // 对于其他状态码，正常继续执行响应
    return handler.next(response);
  },
));

在这个例子中，我们检查了响应的状态码。如果状态码为401 ，表示用户未授权，我们将用户重定向到登录页面，并使用handler.resolve直接返回一个成功的响应，以防止进一步的错误处理。

通过使用响应拦截器进行数据预处理和格式化以及根据响应状态进行全局错误处理，开发者可以编写更加干净、高效的代码，同时提高应用的用户体验。

[2.5 错误拦截器的应用](#2.5 错误拦截器的应用)

在使用Dio 进行网络请求时，处理HTTP错误是不可避免的一部分。Dio提供了错误拦截器，允许开发者在请求发生错误时介入，执行自定义的错误处理逻辑。这不仅可以用于捕获和处理HTTP错误，还可以用于自定义错误消息和逻辑，从而提高应用的健壮性和用户体验。

[2.5.1 捕获和处理HTTP错误](#2.5.1 捕获和处理HTTP错误)

错误拦截器可以捕获由HTTP请求引发的各种错误，包括但不限于网络连接问题、请求超时、服务器错误等。通过对这些错误的捕获和处理，我们可以防止应用崩溃，并向用户提供更友好的错误提示。

dart 复制代码 
  dio.interceptors.add(InterceptorsWrapper(
    onError: (DioException error, handler) {
      // 检查错误类型
      switch (error.type) {
        case DioExceptionType.cancel:
          // 处理连接超时错误
          break;
        case DioExceptionType.sendTimeout:
          // 处理发送超时错误
          break;
        case DioExceptionType.receiveTimeout:
          // 处理接收超时错误
          break;
        case DioExceptionType.badResponse:
          // 处理由服务器返回的错误状态码，如404、500等
          if (error.response?.statusCode == 404) {
            // 处理404错误
          }
          break;
        case DioExceptionType.unknown:
          // 处理其他错误，如无网络连接
          break;
        case DioExceptionType.connectionTimeout:
          // 客户端在与服务器建立连接时超出指定的时间限制
          break;
        case DioExceptionType.badCertificate:
          // 处理服务器的 SSL 证书不被客户端信任
          break;
        case DioExceptionType.connectionError:
          // 处理由于网络连接问题失败
          break;
      }
      // 使用handler.next继续传递错误
      return handler.next(error);
    },
  ));

在上述代码中，我们根据DioError的类型来区分错误，并对不同类型的错误执行不同的处理逻辑。这样可以确保我们对每种错误都有针对性的处理策略，从而提高用户体验。

[2.5.2 自定义错误消息和错误处理逻辑](#2.5.2 自定义错误消息和错误处理逻辑)

除了捕获和处理HTTP错误，错误拦截器还可以用于自定义错误消息和处理逻辑。这意味着我们可以根据错误的类型或错误码，向用户展示更具体、更友好的错误信息。

dart 复制代码 
Future<void> main(List<String> args) async {
  dio.interceptors.add(InterceptorsWrapper(
    onError: (DioException e, handler) {
      String errorMessage = "发生未知错误，请稍后重试";
      if (e.type == DioExceptionType.connectionTimeout) {
        errorMessage = "连接超时，请检查网络连接";
      } else if (e.type == DioExceptionType.receiveTimeout) {
        errorMessage = "服务器响应超时，请稍后重试";
      } else if (e.response?.statusCode == 404) {
        errorMessage = "请求的资源不存在";
      }
      // 显示错误消息
      showToast(errorMessage);
      // 使用handler.next继续传递错误
      return handler.next(e);
    },
  ));
}

在这个例子中，我们根据错误的类型和状态码，设置了不同的错误消息。然后，我们使用showToast函数（假设这是一个用于显示提示消息的函数）向用户展示这些错误消息。这样，用户就可以获得更清晰、更有用的反馈，而不是简单的错误代码或技术性描述。

通过在Dio中使用错误拦截器，开发者可以实现更加精细化的错误处理策略，从而提升应用的稳定性和用户体验。

[3. 实现身份验证刷新机制](#3. 实现身份验证刷新机制)

在现代应用程序中，身份验证是保护用户数据和服务不被未授权访问的关键。大多数应用采用基于令牌的身份验证机制，其中最常见的是使用访问令牌和刷新令牌的组合。本节将详细介绍这一机制的基本概念和实现步骤。

[3.1 身份验证流程概述](#3.1 身份验证流程概述)

[3.1.1 访问令牌和刷新令牌的概念](#3.1.1 访问令牌和刷新令牌的概念)

访问令牌（Access Token）：短期令牌，用于访问受保护的资源。访问令牌有限的有效期通常较短，比如一小时，过期后不能再用于访问资源。

刷新令牌（Refresh Token）：长期令牌，用于在访问令牌过期后获取新的访问令牌。刷新令牌的有效期通常较长，比如一周或更长，但一旦使用就会被替换。

[3.1.2 身份验证流程的基本步骤](#3.1.2 身份验证流程的基本步骤)

  1. 用户登录：用户通过提供用户名和密码登录应用程序。
  2. 发放令牌：身份验证成功后，服务器发放访问令牌和刷新令牌给客户端。
  3. 访问资源：客户端使用访问令牌请求受保护的资源。
  4. 令牌过期：访问令牌过期后，客户端使用刷新令牌请求新的访问令牌。
  5. 刷新访问令牌：服务器验证刷新令牌，如果有效，发放新的访问令牌和刷新令牌。

[3.2 使用拦截器处理401错误](#3.2 使用拦截器处理401错误)

当访问令牌过期时，受保护的资源会返回401 Unauthorized 错误。此时，客户端需要使用刷新令牌获取新的访问令牌。Dio拦截器可以自动处理这一流程。

[3.2.1 检测401错误并触发令牌刷新](#3.2.1 检测401错误并触发令牌刷新)

dart 复制代码 
dio.interceptors.add(InterceptorsWrapper(
  onError: (DioException error, handler) async {
    // 检查是否为401错误
    if (error.response?.statusCode == 401) {
      Dio tokenDio = Dio(); // 创建一个新的Dio实例，避免循环依赖
      try {
        // 使用刷新令牌请求新的访问令牌
        final response = await tokenDio
            .post('https://api.example.com/refresh_token', data: {
          'refreshToken': refreshToken,
        });
        // 保存新的访问令牌和刷新令牌
        accessToken = response.data['accessToken'];
        refreshToken = response.data['refreshToken'];
        // 重试原请求
        final opts = error.requestOptions;
        opts.headers['Authorization'] = 'Bearer $accessToken';
        final cloneReq = await dio.fetch(opts);
        return handler.resolve(cloneReq);
      } catch (e) {
        // 刷新令牌失败，可能需要重新登录
        handler.next(error);
      }
    } else {
      // 其他错误直接传递
      return handler.next(error);
    }
  },
));

[3.2.2 刷新令牌的实现方法](#3.2.2 刷新令牌的实现方法)

上述代码中，当检测到401错误时，我们创建了一个新的Dio实例来请求新的访问令牌。这是因为如果使用相同的Dio实例，可能会导致循环调用拦截器。获取新的访问令牌后，我们更新了请求头，并使用dio.fetch方法重试原请求。

[3.3 自动重试原始请求](#3.3 自动重试原始请求)

在处理身份验证刷新机制时，当访问令牌过期并成功使用刷新令牌获取新的访问令牌后，我们需要重新发起原始请求。这个过程通常涉及到保存失败的请求并在获取新令牌后自动重试这些请求。以下是如何实现这一机制的详细步骤：

[3.3.1 保存和重试失败的请求](#3.3.1 保存和重试失败的请求)

当我们的请求因为401错误（即访问令牌过期）而失败时，我们需要暂时保存这个请求。然后，我们可以在成功刷新访问令牌后，重新发起这个请求。Dio 的DioError对象包含了失败请求的所有信息，包括请求的URL、请求头、请求体等，我们可以使用这些信息来重新构建并发起请求。

dart 复制代码 
// 假设我们有一个用于保存失败请求的队列
List<RequestOptions> requestQueue = [];

dio.interceptors.add(InterceptorsWrapper(
  onError: (DioException error, handler) async {
    if (error.response?.statusCode == 401) {
      RequestOptions options = error.requestOptions;
      requestQueue.add(options); // 保存失败的请求
      // 尝试刷新令牌...
    } else {
      return handler.next(error); // 其他错误直接传递
    }
  },
));

[3.3.2 更新请求头并重新发起请求](#3.3.2 更新请求头并重新发起请求)

在成功刷新访问令牌后，我们需要遍历保存的失败请求队列，更新每个请求的请求头（添加新的访问令牌），然后重新发起这些请求。成功发起请求后，我们应该从队列中移除这些请求。

dart 复制代码 
// 假设refreshToken方法成功获取到了新的访问令牌
String newAccessToken = await refreshToken();

// 遍历失败请求队列，更新请求头并重新发起请求
for (RequestOptions options in requestQueue) {
  // 更新请求头
  options.headers["Authorization"] = "Bearer $newAccessToken";
  try {
    // 使用Dio重新发起请求
    final response = await dio.fetch(options);
    // 处理请求成功的逻辑...
  } catch (e) {
    // 处理请求失败的逻辑...
  }
}

// 清空队列
requestQueue.clear();

通过这种方式，我们可以确保在访问令牌过期后，不仅能够自动刷新令牌，还能够无缝地重试原始请求，为用户提供更加流畅的体验。这种自动重试机制对于维护应用的稳定性和提高用户满意度至关重要。

[3.4 安全存储令牌](#3.4 安全存储令牌)

在移动应用中，安全地存储和管理用户的认证令牌（包括访问令牌和刷新令牌）是至关重要的。不当的令牌存储可能导致安全漏洞，从而使用户数据面临风险。本节将介绍如何使用Flutter Secure Storage来安全地存储令牌，以及如何管理和更新这些令牌。

[3.4.1 使用Flutter Secure Storage存储令牌](#3.4.1 使用Flutter Secure Storage存储令牌)

Flutter Secure Storage 是一个为Flutter 应用提供安全存储功能的插件。它利用了iOS 和Android平台的密钥存储服务来存储敏感数据，如密码、密钥和令牌等。

1.安装Flutter Secure Storage

首先，需要在pubspec.yaml文件中添加flutter_secure_storage依赖：

yaml 复制代码 
dependencies:
  flutter_secure_storage: ^9.0.0 # 请检查最新版本

然后运行flutter pub get来安装依赖。

2.存储令牌

使用Flutter Secure Storage存储令牌非常简单。首先，创建一个FlutterSecureStorage的实例，然后使用write方法存储令牌：

dart 复制代码 
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class TokenStorage {
  final _storage = FlutterSecureStorage();

  Future<void> storeToken(String accessToken, String refreshToken) async {
    await _storage.write(key: 'accessToken', value: accessToken);
    await _storage.write(key: 'refreshToken', value: refreshToken);
  }

  Future<String?> getAccessToken() async {
    return await _storage.read(key: 'accessToken');
  }

  Future<String?> getRefreshToken() async {
    return await _storage.read(key: 'refreshToken');
  }

  Future<void> deleteAllTokens() async {
    await _storage.deleteAll();
  }
}

在上述代码中，我们定义了一个TokenStorage 类，它提供了存储、获取和删除令牌的方法。这些方法通过调用FlutterSecureStorage 的write 、read 和deleteAll方法来实现。

[3.4.2 令牌的安全管理和更新](#3.4.2 令牌的安全管理和更新)

安全地管理和更新令牌是维护应用安全性的关键。以下是一些最佳实践：

定期更新令牌：即使令牌存储在安全的位置，也应定期更新令牌以减少被盗用的风险。可以通过刷新令牌来获取新的访问令牌，并定期更换刷新令牌。

令牌过期处理：应用应能够处理令牌过期的情况。当访问令牌过期时，应使用刷新令牌获取新的访问令牌。如果刷新令牌也失效，应要求用户重新登录。

安全策略更新：随着应用的发展和安全威胁的变化，应定期审查和更新令牌的安全管理策略。

通过遵循这些最佳实践，开发者可以确保应用中的令牌管理既安全又高效，从而保护用户数据免受未授权访问的风险。

[4. 高级应用](#4. 高级应用)

[4.1 缓存策略实现](#4.1 缓存策略实现)

在构建移动应用时，有效的缓存策略可以显著提高应用的性能和用户体验。通过缓存服务器响应，应用可以减少网络请求的数量，加快加载速度，同时减轻服务器的负担。Dio的拦截器功能使得实现自定义缓存策略变得简单而高效。

[4.1.1 使用拦截器实现请求缓存](#4.1.1 使用拦截器实现请求缓存)

要通过Dio实现请求缓存，我们可以利用拦截器在请求发送前查询缓存，并在响应返回后更新缓存。以下是一个简单的实现示例：

dart 复制代码 
class CacheInterceptor extends Interceptor {
  final _cache = <Uri, Response>{};

  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    final response = _cache[options.uri];
    if (response != null) {
      // 如果缓存中存在响应，则直接返回缓存的响应
      handler.resolve(response);
    } else {
      // 否则，继续发送请求
      handler.next(options);
    }
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
    // 将返回的响应存储到缓存中
    _cache[response.requestOptions.uri] = response;
    handler.next(response);
  }
}

在上述代码中，我们创建了一个CacheInterceptor类，它继承自Interceptor。在onRequest方法中，我们检查缓存中是否存在对应的响应。如果存在，我们直接使用handler.resolve方法返回缓存的响应，从而避免了网络请求。在onResponse方法中，我们将返回的响应添加到缓存中，以供后续使用。

[4.1.2 缓存策略的设计和应用](#4.1.2 缓存策略的设计和应用)

在实际应用中，缓存策略的设计需要考虑多个因素，包括但不限于：

  • 缓存有效期：确定缓存多久过期，过期后需要重新请求数据。

  • 缓存大小：限制缓存占用的最大空间，避免消耗过多存储资源。

  • 缓存清理策略 ：当缓存达到最大大小时，选择合适的策略清理旧的缓存项，如LRU（最近最少使用）策略。

  • 数据敏感性：对于敏感数据，可能需要禁用缓存或使用加密存储。

实现高效的缓存策略，不仅可以提升应用性能，还可以在无网络连接的情况下提供部分功能，增强应用的健壮性。开发者应根据应用的具体需求和用户行为，设计合理的缓存策略。

通过在Dio中使用拦截器实现缓存，开发者可以灵活地控制缓存逻辑，从而在不牺牲用户体验的前提下，优化应用的性能和资源使用。

[4.2 日志记录和调试](#4.2 日志记录和调试)

在开发和维护Flutter 应用时，有效的日志记录和调试技巧对于快速定位和解决问题至关重要。Dio的拦截器功能提供了强大的日志记录能力，可以帮助开发者监控网络请求的详细信息，包括请求头、请求体、响应数据、错误信息等。此外，结合一些调试技巧和工具，可以进一步提高开发效率和应用性能。

[4.2.1 使用拦截器进行日志记录](#4.2.1 使用拦截器进行日志记录)

Dio的拦截器可以用于在请求发送前、响应返回后以及发生错误时记录日志。通过自定义拦截器，可以选择性地记录所需的信息，从而实现高度定制的日志系统。

dart 复制代码 
dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) {
    // 记录请求信息
    print("Request to: ${options.uri}");
    print("Headers: ${options.headers}");
    print("Body: ${options.data}");
    return handler.next(options); // 继续执行请求
  },
  onResponse: (response, handler) {
    // 记录响应信息
    print("Response from: ${response.requestOptions.uri}");
    print("Status code: ${response.statusCode}");
    print("Data: ${response.data}");
    return handler.next(response); // 继续执行响应
  },
  onError: (DioException e, handler) {
    // 记录错误信息
    print("Error: ${e.message}");
    print("Error type: ${e.type}");
    return handler.next(e); // 继续执行错误处理
  },
));

在上述代码中，我们为每个请求的发送前、响应返回后和发生错误时添加了日志记录。这样，开发者可以清晰地看到每个请求的详细信息，便于调试和问题定位。

[4.2.2 调试技巧和工具](#4.2.2 调试技巧和工具)

  • 使用Dio的日志拦截器 ：Dio 提供了一个内置的日志拦截器LogInterceptor ，可以方便地记录请求和响应的详细信息。只需简单地将其添加到Dio实例的拦截器列表中即可启用日志记录。
dart 复制代码 
dio.interceptors.add(LogInterceptor(
  requestBody: true,
  responseBody: true,
));

  • 使用Postman或Insomnia进行API测试 ：在开发过程中，使用API 测试工具如Postman 或Insomnia 可以帮助你快速测试和调试API 请求。这些工具提供了友好的界面和强大的功能，使得API的测试和调试变得更加简单高效。

  • 使用Flutter DevTools进行性能分析 ：Flutter DevTools 是一个强大的调试工具集，提供了性能分析、网络请求监控、UI检查等功能。通过使用DevTools，可以更加深入地了解应用的运行状态和性能瓶颈。

  • 利用断点和控制台日志 ：在Flutter IDE （如Visual Studio Code 或Android Studio）中设置断点，可以在代码的特定位置暂停执行，查看变量状态和调用堆栈。此外，利用控制台输出日志信息也是定位问题的有效手段。

通过结合使用Dio 的拦截器功能、API 测试工具、Flutter DevTools 以及IDE的调试功能，开发者可以有效地记录日志、分析性能和定位问题，从而提高开发效率和应用质量。

[4.3 Dio的扩展和自定义](#4.3 Dio的扩展和自定义)

在使用Dio进行网络请求时，有时候我们需要对其进行扩展和自定义以满足特定的需求。Dio的灵活性和强大的拦截器功能使得扩展和自定义变得简单而高效。本节将探讨如何扩展Dio的功能以及如何创建自定义拦截器。

[4.3.1 扩展Dio功能](#4.3.1 扩展Dio功能)

Dio的设计允许开发者通过多种方式扩展其功能，包括但不限于添加自定义拦截器、使用Transformer转换请求/响应数据、以及创建自定义的Dio实例。

使用Transformer转换数据

Dio的Transformer允许你在请求发送到服务器之前以及响应返回到客户端之前对数据进行转换。这对于实现自定义的请求/响应格式化非常有用。

例如，如果你的API需要将请求体以特定格式发送，你可以创建一个自定义的Transformer来实现这一需求：

旧版本的 **DefaultTransformer ** 类已经废弃，取而代之的是 BackgroundTransformer类。

dart 复制代码 
class CustomTransformer extends BackgroundTransformer  {
  @override
  Future<String> transformRequest(RequestOptions options) async {
    // 实现自定义的请求体转换逻辑
    return super.transformRequest(options);
  }

  @override
  Future transformResponse(RequestOptions options, ResponseBody responseBody) {
    // 实现自定义的响应体转换逻辑
    return super.transformResponse(options, responseBody);
  }
}

// 使用自定义的Transformer
dio.transformer = CustomTransformer();

通过覆盖transformRequest和transformResponse方法，你可以在请求发送前和响应返回后对数据进行自定义的处理。

[4.3.2 创建自定义拦截器](#4.3.2 创建自定义拦截器)

自定义拦截器是扩展Dio功能的另一种强大方式。通过创建自定义拦截器，你可以在请求的发送、接收响应、以及处理错误时插入自定义拦截器，你可以在请求的发送、接收响应、以及处理错误时插入自定义逻辑。这对于实现如API认证、请求重试、日志记录等功能非常有用。

以下是创建一个自定义拦截器的示例：

dart 复制代码 
class CustomInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    // 在请求发送前执行的操作
    print("Sending request to ${options.uri}");
    // 可以在这里添加自定义的请求头等
    options.headers["Custom-Header"] = "value";
    super.onRequest(options, handler);
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
    // 在接收响应后执行的操作
    print("Received response from ${response.requestOptions.uri}");
    super.onResponse(response, handler);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    // 在请求失败时执行的操作
    print(
        "Request to ${err.requestOptions.uri} failed with error: ${err.message}");
    super.onError(err, handler);
  }
}

// 将自定义拦截器添加到Dio实例
dio.interceptors.add(CustomInterceptor());

在这个例子中，CustomInterceptor 类继承自Interceptor 。我们覆盖了onRequest 、onResponse 和onError方法来实现在请求发送前、接收响应后以及请求错误时的自定义逻辑。这种方式非常灵活，可以根据你的具体需求来调整。

[5. 结论](#5. 结论)

通通过扩展Dio 的功能和创建自定义拦截器，你可以使Dio 更加强大和灵活，以满足你的特定需求。无论是需要特殊的数据转换、实现复杂的认证流程，还是简单的日志记录，Dio都能通过其灵活的设计来满足这些需求。正确利用这些扩展功能，可以大大提高开发效率，同时使代码更加清晰和易于维护。

相关推荐
一豆羹9 小时前
macOS 环境下 ADB 无线调试连接失败、Protocol Fault 及端口占用的深度排查
flutter
行者969 小时前
OpenHarmony上Flutter粒子效果组件的深度适配与实践
flutter·交互·harmonyos·鸿蒙
行者9612 小时前
Flutter与OpenHarmony深度集成：数据导出组件的实战优化与性能提升
flutter·harmonyos·鸿蒙
小雨下雨的雨12 小时前
Flutter 框架跨平台鸿蒙开发 —— Row & Column 布局之轴线控制艺术
flutter·华为·交互·harmonyos·鸿蒙系统
小雨下雨的雨13 小时前
Flutter 框架跨平台鸿蒙开发 —— Center 控件之完美居中之道
flutter·ui·华为·harmonyos·鸿蒙
小雨下雨的雨13 小时前
Flutter 框架跨平台鸿蒙开发 —— Icon 控件之图标交互美学
flutter·华为·交互·harmonyos·鸿蒙系统
小雨下雨的雨13 小时前
Flutter 框架跨平台鸿蒙开发 —— Placeholder 控件之布局雏形美学
flutter·ui·华为·harmonyos·鸿蒙系统
行者9614 小时前
OpenHarmony Flutter弹出菜单组件深度实践：从基础到高级的完整指南
flutter·harmonyos·鸿蒙
前端不太难14 小时前
Flutter / RN / iOS，在长期维护下的性能差异本质
flutter·ios
小雨下雨的雨15 小时前
Flutter 框架跨平台鸿蒙开发 —— Padding 控件之空间呼吸艺术
flutter·ui·华为·harmonyos·鸿蒙系统
热门推荐
01GitHub 镜像站点02Labelme从安装到标注：零基础完整指南03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04Linux下V2Ray安装配置指南05jdk21下载、安装（Windows、Linux、macOS）06Claude Code 2.1.2 升级报错？别折腾了，一行命令搞定072025-04-03 Latex学习1——本地配置Latex + VScode环境08【踩坑笔记】50系显卡适配的 PyTorch 安装09KGG转MP3工具|非KGM文件|解密音频10UV安装并设置国内源