# CancelToken 功能变更日志 / CancelToken Feature Changelog

## [3.3.0] - 2026-01-31

### 🎉 新特性 / New Features

#### CancelToken 支持
- ✅ **配置开关**：在 `generator_config.yaml` 中配置 `generation.api.cancel_token_support: true` 启用
- ✅ **自动添加参数**：启用后，所有 API 方法自动添加 `@CancelRequest() CancelToken? cancelToken` 参数
- ✅ **向后兼容**：默认关闭，不影响现有项目

### 📝 文档 / Documentation
- ✅ 新增 `CANCELTOKEN_USAGE_GUIDE.md` - 使用指南和最佳实践
- ✅ 更新 `generator_config.template.yaml` - 添加配置示例

### 🔧 技术细节 / Technical Details

**修改的文件：**
- `lib/core/config_repository.dart` - 添加 `cancelTokenSupport` 配置解析
- `lib/pipeline/generate/impl/retrofit_api/api_parameters.dart` - 在 `_generateParameters()` 中添加 CancelToken 参数生成逻辑
- `generator_config.template.yaml` - 添加配置项说明

**生成的参数格式：**
```dart
@CancelRequest() CancelToken? cancelToken
```

### 💡 使用场景 / Use Cases

1. **页面离开取消请求** - 避免内存泄漏和不必要的状态更新
2. **用户主动取消** - 如搜索框输入时取消之前的搜索请求
3. **超时控制** - 配合 Timer 实现自定义超时逻辑
4. **批量取消** - 一个 CancelToken 可用于多个请求

---

## 相关资源 / Related Resources

- [Dio CancelToken 文档](https://pub.dev/packages/dio#cancellation)
- [Retrofit CancelRequest 注解](https://pub.dev/packages/retrofit)
- [使用指南](./CANCELTOKEN_USAGE_GUIDE.md)