# 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` 中启用：

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

---

## 生成效果 / Generated Code

**启用前 / Before:**

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

**启用后 / After:**

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

---

## 使用示例 / Usage Examples

### 基本用法 / Basic Usage

```dart
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

```dart
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

```dart
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

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

---

## 注意事项 / Notes

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