BuildRequest - 网络请求构建器 / Network Request Builder

author: zhengzaihong email: 1096877329@qq.com date: 2025-08-12

============================================================================ 类说明 / Class Description

BuildRequest 是 RxNet Plus 的核心请求构建器，提供流畅的 API 来配置和执行网络请求。 它将请求配置与 RxNet 主类分离，使代码更加清晰和易于维护。

BuildRequest is the core request builder of RxNet Plus, providing a fluent API to configure and execute network requests. It separates request configuration from the main RxNet class, making the code clearer and easier to maintain.

============================================================================ 版本历史 / Version History

📦 Version 0.6.0 (2026-04-20) - 适配器架构支持 / Adapter Architecture Support

🎯 核心变更 / Core Changes:

1. 适配器集成 / Adapter Integration

   • 重构为使用 NetworkAdapter 接口
   • Refactored to use NetworkAdapter interface
   • 支持多种网络库（Dio、http、自定义）
   • Support for multiple network libraries (Dio, http, custom)

2. 统一的取消令牌 / Unified Cancel Token

   • 使用 RxNet 的 CancelToken 替代 Dio 的 CancelToken
   • Use RxNet's CancelToken instead of Dio's CancelToken
   • 跨适配器的取消支持
   • Cross-adapter cancellation support

3. 改进的拦截器支持 / Improved Interceptor Support

   • 拦截器通过适配器执行
   • Interceptors executed through adapters
   • 支持请求、响应、错误拦截
   • Support for request, response, and error interception

📦 Version 0.5.0 (2025-10-03) - API 优化 / API Optimization

🎯 核心改进 / Core Improvements:

1. 参数类型明确化 / Explicit Parameter Types

   • 引入 RequestBodyType 枚举
   • Introduced RequestBodyType enum
   • 分离路径参数、查询参数、Body 参数
   • Separated path params, query params, and body params

2. RESTful 自动检测 / RESTful Auto-Detection

   • 自动识别路径中的 {placeholder}
   • Automatically recognize {placeholder} in paths
   • 无需手动调用 setRestfulUrl(true)
   • No need to manually call setRestfulUrl(true)

3. 请求体类型清晰化 / Clear Request Body Types

   • asJson() - JSON 格式
   • asFormData() - FormData 格式
   • asUrlEncoded() - URL 编码格式

4. 改进的缓存键生成 / Improved Cache Key Generation

   • 更智能的缓存键生成逻辑
   • Smarter cache key generation logic
   • 支持忽略特定参数
   • Support for ignoring specific parameters

5. 统一的错误处理 / Unified Error Handling

   • 标准化的异常类型
   • Standardized exception types
   • 更清晰的错误信息
   • Clearer error messages

📦 Version 0.4.x - 初始版本 / Initial Version

• 基础请求功能 / Basic request functionality
• 缓存支持 / Cache support
• 重试和轮询 / Retry and polling
• JSON 转换 / JSON conversion

============================================================================ 使用示例 / Usage Examples

1. 基础 GET 请求 / Basic GET Request:

final result = await RxNet.get()
  .setPath("/api/users")
  .request();

2. RESTful 请求 / RESTful Request:

final result = await RxNet.get()
  .setPath("/api/users/{id}/posts")
  .setPathParam("id", "123")
  .setQueryParam("page", 1)
  .request();

3. POST JSON 数据 / POST JSON Data:

final result = await RxNet.post()
  .setPath("/api/user")
  .setBodyParams({"name": "John", "age": 25})
  .asJson()
  .request();

4. 文件上传 / File Upload:

final file = await MultipartFile.fromFile("path/to/file.jpg");
final result = await RxNet.post()
  .setPath("/api/upload")
  .setBodyParam("file", file)
  .asFormData()
  .request();

5. 带缓存的请求 / Request with Cache:

final result = await RxNet.get()
  .setPath("/api/data")
  .setCacheMode(CacheMode.FIRST_USE_CACHE_THEN_REQUEST)
  .setCacheInvalidationTime(60000) // 60 seconds
  .request();

6. 带重试的请求 / Request with Retry:

final result = await RxNet.get()
  .setPath("/api/data")
  .setRetryCount(3, interval: Duration(seconds: 2))
  .request();

7. 取消请求 / Cancel Request:

final cancelToken = CancelToken();

RxNet.get()
  .setPath("/api/data")
  .setCancelToken(cancelToken)
  .request();

// Later...
cancelToken.cancel("User cancelled");

============================================================================ 参数类型说明 / Parameter Types

1. 路径参数 / Path Parameters (setPathParam/setPathParams)

   • 用于 RESTful URL 中的占位符替换
   • Used for placeholder replacement in RESTful URLs
   • 例如：/users/{id} -> /users/123
   • Example: /users/{id} -> /users/123

2. 查询参数 / Query Parameters (setQueryParam/setQueryParams)

   • 拼接在 URL 后面的参数
   • Parameters appended to the URL
   • 例如：/users?page=1&size=20
   • Example: /users?page=1&size=20

3. Body 参数 / Body Parameters (setBodyParam/setBodyParams)

   • POST/PUT/PATCH 请求的请求体参数
   • Request body parameters for POST/PUT/PATCH
   • 根据 bodyType 决定编码方式
   • Encoding method determined by bodyType

4. 原始 Body / Raw Body (setRawBody)

   • 自定义的原始请求体数据
   • Custom raw request body data
   • 优先级高于 bodyParams
   • Takes precedence over bodyParams

============================================================================ 请求体类型 / Request Body Types

• RequestBodyType.auto - 自动判断（默认）/ Auto-detect (default)
• RequestBodyType.json - JSON 格式 / JSON format
• RequestBodyType.formData - FormData 格式 / FormData format
• RequestBodyType.urlEncoded - URL 编码 / URL-encoded
• RequestBodyType.query - 查询参数 / Query parameters

============================================================================ 缓存模式 / Cache Modes

• ONLY_REQUEST - 仅请求网络 / Network only
• FIRST_USE_CACHE_THEN_REQUEST - 先缓存后网络 / Cache first, then network
• REQUEST_FAILED_READ_CACHE - 请求失败读缓存 / Read cache on failure
• CACHE_EMPTY_OR_EXPIRED_THEN_REQUEST - 缓存为空或过期时请求 / Request when cache is empty or expired
• ONLY_CACHE - 仅读缓存 / Cache only

============================================================================ 注意事项 / Notes

1. BuildRequest 实例是一次性的，每次请求都会创建新实例 BuildRequest instances are disposable, a new instance is created for each request

2. 参数设置方法可以链式调用 Parameter setting methods can be chained

3. 请求执行后，BuildRequest 实例不应被重用 After request execution, BuildRequest instances should not be reused

4. 缓存功能在 Web 平台不可用 Cache functionality is not available on Web platform

============================================================================