BuildRequest<T> class

author: ZhengZaiHong email: [e-mail] date: 2025-08-12 describe: BuildRequest - 网络请求构建器 / Network Request Builder

============================================================================ 类说明 / 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.

============================================================================ 使用示例 / 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

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

Constructors

BuildRequest(HttpMethod _httpMethod, RxNet _rxNet)

Properties

checkNetWork ↔ CheckNetWork?

getter/setter pair

hashCode → int

The hash code for this object.

no setter, inherited

onResponse ↔ dynamic Function(AdapterResponse response)?

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

addHeaders(Map<String, dynamic> headers) → BuildRequest<T>

asFormData() → BuildRequest<T>

使用FormData格式发送（multipart/form-data）

asJson() → BuildRequest<T>

使用JSON格式发送（application/json）

asUrlEncoded() → BuildRequest<T>

使用URL编码格式发送（application/x-www-form-urlencoded）

breakPointDownload({required String savePath, ProgressCallback? onReceiveProgress, Success? success, Failure? failure, Completed? completed, dynamic cancelCallback()?}) → void

断点下载

breakPointUpload({required String filePath, ProgressCallback? onSendProgress, Success? success, Failure? failure, Completed? completed, dynamic cancelCallback()?, int? start}) → void

断点上传

download({required String savePath, ProgressCallback? onReceiveProgress, Success? success, Failure? failure, Completed? completed}) → void

下载文件（回调版本，保留向后兼容）

downloadFile({required String savePath, ProgressCallback? onReceiveProgress}) → Future<RxResult<String>>

下载文件（Future 版本，支持 async/await）

execute({Success<T>? success, Failure? failure, Completed? completed}) → void

使用回调的方式

executeStream() → Stream<RxResult<T>>

Stream方式（支持轮询）

getCancelToken() → CancelToken?

getContentLength(AdapterResponse response) → Future<String?>

获取内容长度（兼容方法）

getParams(ParamCallback callBack) → BuildRequest<T>

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

removeNullValueKeys() → BuildRequest<T>

request() → Future<RxResult<T>>

async/await方式

setBodyParam(String key, dynamic value) → BuildRequest<T>

设置Body参数（用于POST/PUT/PATCH）

setBodyParams(Map<String, dynamic> params) → BuildRequest<T>

批量设置Body参数

setBodyType(RequestBodyType type) → BuildRequest<T>

设置请求体类型

setCacheInvalidationTime(int millisecond) → BuildRequest<T>

setCacheMode(CacheMode cacheMode) → BuildRequest<T>

setCancelToken(dynamic cancelToken) → BuildRequest<T>

设置取消令牌，支持两种方式：

setCheckNetwork(CheckNetWork checkNetWork) → BuildRequest<T>

setConnectTimeout(Duration timeout) → BuildRequest<T>

setContentType(String type) → BuildRequest<T>

setEnableGlobalHeader(bool enable) → BuildRequest<T>

setHeader(String key, dynamic value) → BuildRequest<T>

setIgnoreCacheKey(String key) → BuildRequest<T>

setIgnoreCacheKeys(List<String> keys) → BuildRequest<T>

setJsonConvert(JsonTransformation convert) → BuildRequest<T>

setLoop(bool loop, {Duration? interval}) → BuildRequest<T>

setPath(String? path) → BuildRequest<T>

setPathParam(String key, dynamic value) → BuildRequest<T>

设置路径参数（用于RESTful风格） 例如：setPathParam("id", "123") 会将 /user/{id} 替换为 /user/123

setPathParams(Map<String, dynamic> params) → BuildRequest<T>

批量设置路径参数

setQueryParam(String key, dynamic value) → BuildRequest<T>

设置查询参数（拼接在URL后） 例如：setQueryParam("page", 1) 会生成 ?page=1

setQueryParams(Map<String, dynamic> params) → BuildRequest<T>

批量设置查询参数

setRawBody(dynamic body) → BuildRequest<T>

设置原始Body数据（用于自定义body）

setReceiveTimeout(Duration timeout) → BuildRequest<T>

setRequestIgnoreCacheTime(bool ignoreCache) → BuildRequest<T>

setResponseCallBack(dynamic responseCallBack(AdapterResponse response)) → BuildRequest<T>

setResponseType(ResponseType type) → BuildRequest<T>

setRetryCount(int count, {Duration? interval}) → BuildRequest<T>

setRetryPolicy(RetryPolicy policy) → BuildRequest<T>

设置高级重试策略（支持指数退避、抖动等）

setSendTimeout(Duration timeout) → BuildRequest<T>

toString() → String

A string representation of this object.

inherited

upload({ProgressCallback? onSendProgress, Success? success, Failure? failure, Completed? completed}) → void

上传文件（回调版本，保留向后兼容）

uploadFile({ProgressCallback? onSendProgress}) → Future<RxResult<T>>

Operators

operator ==(Object other) → bool

The equality operator.

inherited