133 lines
3.0 KiB
Markdown
133 lines
3.0 KiB
Markdown
# 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()` 会取消所有使用它的请求
|