HttpAdapter - 基于 http 包的轻量级网络适配器 / Lightweight Network Adapter Based on http Package

author: ZhengZaiHong email: 1096877329@qq.com date: 2026-04-23

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

HttpAdapter 是 RxNet Plus 的轻量级网络适配器，基于 Dart 官方的 http 包实现。 它提供了基础的 HTTP 功能，适合对包大小敏感或不需要高级功能的场景。

HttpAdapter is a lightweight network adapter for RxNet Plus, based on Dart's official http package. It provides basic HTTP functionality, suitable for scenarios sensitive to package size or not requiring advanced features.

============================================================================ 核心特性 / Core Features

1. 轻量级 / Lightweight

   • 基于 Dart 官方 http 包，无额外依赖
   • Based on Dart's official http package, no extra dependencies
   • 包大小更小，适合简单场景
   • Smaller package size, suitable for simple scenarios

2. 基础 HTTP 支持 / Basic HTTP Support

   • 支持所有标准 HTTP 方法
   • Support for all standard HTTP methods
   • 支持请求头和查询参数
   • Support for headers and query parameters
   • 支持 JSON 和文本响应
   • Support for JSON and text responses

3. 拦截器支持 / Interceptor Support

   • 完整的 AdapterInterceptor 支持
   • Full AdapterInterceptor support
   • 与 DioAdapter 相同的拦截器接口
   • Same interceptor interface as DioAdapter

4. 请求取消 / Request Cancellation

   • 支持 RxNet 的 CancelToken
   • Support for RxNet's CancelToken
   • 基于 Completer 的取消机制
   • Completer-based cancellation mechanism

5. 自定义 Client / Custom Client

   • 可以传入自定义的 http.Client
   • Can pass in custom http.Client
   • 支持证书固定等高级配置
   • Support for advanced configurations like certificate pinning

============================================================================ 适用场景 / Use Cases

✅ 适合使用 HttpAdapter 的场景 / Suitable for HttpAdapter:

1. 简单的 REST API 调用 / Simple REST API Calls

   • 基础的 GET/POST 请求
   • Basic GET/POST requests
   • 不需要复杂的拦截器逻辑
   • No need for complex interceptor logic

2. 包大小敏感的应用 / Size-Sensitive Applications

   • 需要减小应用体积
   • Need to reduce app size
   • 不需要 Dio 的高级功能
   • Don't need Dio's advanced features

3. 证书固定 / Certificate Pinning

   • 需要自定义 SSL/TLS 验证
   • Need custom SSL/TLS validation
   • 可以通过自定义 IOClient 实现
   • Can be implemented via custom IOClient

❌ 不适合使用 HttpAdapter 的场景 / Not Suitable for HttpAdapter:

1. 文件上传下载 / File Upload/Download

   • HttpAdapter 不支持进度回调
   • HttpAdapter doesn't support progress callbacks
   • 建议使用 DioAdapter
   • Recommend using DioAdapter

2. 复杂的拦截器需求 / Complex Interceptor Requirements

   • 需要修改请求体或响应体
   • Need to modify request/response body
   • DioAdapter 提供更好的支持
   • DioAdapter provides better support

3. 流式响应 / Streaming Responses

   • HttpAdapter 不支持流式响应
   • HttpAdapter doesn't support streaming responses
   • 建议使用 DioAdapter
   • Recommend using DioAdapter

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

1. 基础使用 / Basic Usage:

final api = RxNet.create();
await api.initNet(
  baseUrl: "https://api.example.com",
  adapter: HttpAdapter(),
);

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

2. 使用自定义 Client / Using Custom Client:

final httpClient = HttpClient();
httpClient.badCertificateCallback = (cert, host, port) {
  // 自定义证书验证逻辑
  // Custom certificate validation logic
  return true;
};

final client = IOClient(httpClient);
final adapter = HttpAdapter(client: client);

await api.initNet(
  baseUrl: "https://api.example.com",
  adapter: adapter,
);

3. 证书固定示例 / Certificate Pinning Example:

IOClient createPinnedClient() {
  final httpClient = HttpClient();
  httpClient.badCertificateCallback = (cert, host, port) {
    // 获取证书指纹并验证
    // Get certificate fingerprint and validate
    final der = cert.der;
    final sha256 = sha256Convert(der);
    const trustedFingerprint = "YOUR_SHA256_FINGERPRINT";
    return sha256 == trustedFingerprint;
  };
  return IOClient(httpClient);
}

final adapter = HttpAdapter(client: createPinnedClient());

4. 添加拦截器 / Adding Interceptors:

final adapter = HttpAdapter();
adapter.addInterceptor(RxNetLogAdapterInterceptor());
adapter.addInterceptor(AuthInterceptor());

await api.initNet(
  baseUrl: "https://api.example.com",
  adapter: adapter,
);

============================================================================ 与 DioAdapter 的对比 / Comparison with DioAdapter

============================================================================ 性能考虑 / Performance Considerations

1. 内存使用 / Memory Usage

   • HttpAdapter 内存占用更小
   • HttpAdapter has smaller memory footprint
   • 适合资源受限的设备
   • Suitable for resource-constrained devices

2. 请求速度 / Request Speed

   • 简单请求性能相当
   • Similar performance for simple requests
   • 复杂场景 DioAdapter 可能更快
   • DioAdapter may be faster in complex scenarios

3. 启动时间 / Startup Time

   • HttpAdapter 启动更快
   • HttpAdapter starts faster
   • 依赖更少，初始化更快
   • Fewer dependencies, faster initialization

============================================================================ 限制和注意事项 / Limitations and Notes

1. 不支持进度回调 / No Progress Callbacks

   • upload() 和 download() 方法的 onProgress 参数无效
   • onProgress parameter in upload() and download() is ineffective
   • 如需进度回调，请使用 DioAdapter
   • Use DioAdapter if progress callbacks are needed

2. 不支持流式响应 / No Streaming Responses

   • ResponseType.stream 会被当作 bytes 处理
   • ResponseType.stream is treated as bytes
   • 大文件下载可能占用较多内存
   • Large file downloads may consume more memory

3. 文件上传限制 / File Upload Limitations

   • 不支持 MultipartFile 类型
   • MultipartFile type not supported
   • 需要手动构建 multipart 请求
   • Need to manually build multipart requests

4. 取消机制 / Cancellation Mechanism

   • 基于 Completer，可能不如 Dio 的取消机制精确
   • Based on Completer, may not be as precise as Dio's mechanism
   • 请求可能已发送但被标记为取消
   • Request may have been sent but marked as cancelled

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

See also / 另见:

• NetworkAdapter for the adapter interface
• DioAdapter for a full-featured alternative
• MockAdapter for testing
• AdapterInterceptor for interceptor implementation

============================================================================ HttpAdapter - http package-based implementation of NetworkAdapter

HttpAdapter - 基于 http 包的 NetworkAdapter 实现

This is a lightweight adapter that uses Dart's official http package. It's suitable for simple scenarios where package size matters.

这是一个使用 Dart 官方 http 包的轻量级适配器。 适合对包大小敏感的简单场景。