CancelToken 使用指南 / CancelToken Usage Guide

概述 / Overview

CancelToken 是 Dio 提供的请求取消机制。启用此功能后，生成的 API 方法将自动包含可选的 CancelToken? 参数，允许您在请求进行中取消它。

CancelToken is a request cancellation mechanism provided by Dio. When enabled, generated API methods will automatically include an optional CancelToken? parameter, allowing you to cancel requests while they are in progress.

配置 / Configuration

在 generator_config.yaml 中启用：

generation:
  api:
    cancel_token_support: true  # 启用 CancelToken 支持

生成效果 / Generated Code

启用前 / Before:

Future<BaseResult<User>> getUser({
  @Query('id') int? id,
});

启用后 / After:

Future<BaseResult<User>> getUser({
  @Query('id') int? id,
  @CancelRequest() CancelToken? cancelToken,
});

使用示例 / Usage Examples

基本用法 / Basic Usage

final cancelToken = CancelToken();

// 发起请求 / Make request
final future = api.getUser(id: 1, cancelToken: cancelToken);

// 取消请求 / Cancel the request
cancelToken.cancel('用户取消操作');

try {
  final result = await future;
} on DioException catch (e) {
  if (CancelToken.isCancel(e)) {
    print('请求已取消: ${e.message}');
  }
}

页面离开时取消 / Cancel on Page Dispose

class MyPageState extends State<MyPage> {
  final _cancelToken = CancelToken();

  @override
  void dispose() {
    _cancelToken.cancel('页面已关闭');
    super.dispose();
  }

  Future<void> loadData() async {
    try {
      final result = await api.getData(cancelToken: _cancelToken);
      // 处理结果
    } on DioException catch (e) {
      if (!CancelToken.isCancel(e)) {
        // 处理真正的错误
      }
    }
  }
}

GetX Controller 使用 / With GetX Controller

class MyController extends GetxController {
  final _cancelToken = CancelToken();

  @override
  void onClose() {
    _cancelToken.cancel('Controller 已关闭');
    super.onClose();
  }

  Future<void> fetchData() async {
    try {
      final result = await api.getData(cancelToken: _cancelToken);
      // 更新状态
    } on DioException catch (e) {
      if (!CancelToken.isCancel(e)) {
        // 显示错误
      }
    }
  }
}

最佳实践 / Best Practices

每个请求使用独立 Token - 如果需要单独取消某个请求
页面级别共享 Token - 页面离开时取消所有进行中的请求
检查取消状态 - 使用 CancelToken.isCancel(e) 区分取消和真正的错误
及时取消 - 避免不必要的网络请求和资源浪费

注意事项 / Notes

CancelToken 来自 package:dio/dio.dart，无需额外导入
@CancelRequest() 注解来自 package:retrofit/retrofit.dart
取消已完成的请求不会有任何效果
一个 CancelToken 可以用于多个请求，调用 cancel() 会取消所有使用它的请求

3.0 KiB Raw Blame History