likes
comments
collection
share

究极进化版基于 dio 的网络封装库

作者站长头像
站长
· 阅读数 12

本文正在参加「金石计划」

可能是 Flutter 上最强的网络封装框架, 基于dio实现的非侵入式框架(不影响原有功能). 学习成本低、使用简单, 一行代码发起网络请求, 甚至无需初始化。

之前写过两篇关于封装网络库的文章：

距离最早的文章发布时间，已经过去了三年。这期间 dio 已经更新到5.x.x版本了，在使用中也积攒了许多定制需求和优化方案。在确定需求和方案后，修修改改，终于发布了最新最实用的网络请求版本。

欢迎贡献代码/问题

特点

  • 个人使用下来感觉开发效率比目前网络请求库都高：最简单易用
  • 专为 Flutter 而生，支持全平台
  • 遵循设计模式最佳实践，Builder Pattern 全局配置
  • 捕获请求错误，不需要开发者处理
  • 优秀的源码/注释/文档/示例
  • 类似kotlin的语法糖：请求结果when语句判断和密封类

主要功能

  • RESTful API 设计 GET/POST/PUT/HEAH/DELETE/PATCH/DOWNLOAD
  • 可取消请求
  • 异步解析，数据量大不再卡顿
  • 全局错误处理(减少崩溃率)
  • 自定义解析器，支持全局和单个请求
  • 自定义解析方法
  • 配置请求参数
  • 漂亮的日志打印
  • 证书快速配置
  • 代理配置
  • 拦截器配置
  • 友好支持缓存配置
  • 监听上传/下载进度

简单使用

添加依赖：

dependencies:
  flutter_nb_net: ^1.0.0

像 dio 一样使用,无需配置,返回实体类实现BaseNetworkModel，复写fromJson函数即可：

class BannerModel extends BaseNetworkModel<BannerModel> {

  @override
  BannerModel fromJson(Map<String, dynamic> json) {
    return BannerModel.fromJson(json);
  }
  //...
  }

温馨提示：dart实体类可用freezed、json_serializable生成或者JsonToDart插件一键生成。

  /// Get 请求
  void requestGet() async {
    var appResponse = await get<BannerModel, BannerModel>("banner/json",
        decodeType: BannerModel());
    appResponse.when(success: (BannerModel model) {
      var size = model.data?.length;
      debugPrint("成功返回$size条");
    }, failure: (String msg, int code) {
      debugPrint("失败了：msg=$msg/code=$code");
    });
  }

get<BannerModel, BannerModel>这里有两个泛型，前者是接口返回的数据需要序列化的类型，后者是开发关注的类型。比如接口返回一个用户列表，前面泛型就是User类型，后面是List<User>。又或者接口返回的数据包了几层，我们只需要最里面的数据格式，那么前面就是需要序列化的整个数据类型，第二个泛型是最里面的数据类型。另外decodeType也是必须的参数，传入第一个泛型的实例即可。

泛型一样，也可以不写，只传递decodeType即可：

    var appResponse = await get("banner/json",
        decodeType: BannerModel());
    appResponse.when(success: (BannerModel model) {
      var size = model.data?.length;
      debugPrint("成功返回$size条");
    }, failure: (String msg, int code) {
      debugPrint("失败了：msg=$msg/code=$code");
    });

也会遇到需要原始数据的时候，有同学说泛型规定太死了，1.0.0 版本就实现了这个功能，不必写泛型，也不传decodeType，就直接返回原始数据：

    var appResponse = await get("banner/json");
    appResponse.when(success: (dynamic) {
      // var size = model.data?.length;
      debugPrint("成功返回$dynamic");
    }, failure: (String msg, int code) {
      debugPrint("失败了：msg=$msg/code=$code");
    });

配置使用

全局配置

在使用前进行全局配置：

 NetOptions.instance
      // header
      .addHeaders({"aaa": '111'})
      // baseUrl
      .setBaseUrl("https://www.wanandroid.com/")
      // 代理/https
      .setHttpClientAdapter(IOHttpClientAdapter()
        ..onHttpClientCreate = (client) {
          client.findProxy = (uri) {
            return 'PROXY 192.168.20.43:8888';
          };
          client.badCertificateCallback =
              (X509Certificate cert, String host, int port) => true;
          return client;
        })
      // cookie
      .addInterceptor(CookieManager(CookieJar()))
      // dio_http_cache
      .addInterceptor(DioCacheManager(CacheConfig(
        baseUrl: "https://www.wanandroid.com/",
      )).interceptor)
      // dio_cache_interceptor
      .addInterceptor(DioCacheInterceptor(
          options: CacheOptions(
        store: MemCacheStore(),
        policy: CachePolicy.forceCache,
        hitCacheOnErrorExcept: [401, 403],
        maxStale: const Duration(days: 7),
        priority: CachePriority.normal,
        cipher: null,
        keyBuilder: CacheOptions.defaultCacheKeyBuilder,
        allowPostMethod: false,
      )))
       //  全局解析器
      .setHttpDecoder(MyHttpDecoder.getInstance())
       //  超时时间
      .setConnectTimeout(const Duration(milliseconds: 3000))
      // 允许打印log，默认未 true
      .enableLogger(true)
      .create();

如果接口返回的数据格式是统一规范的，配置一个自定义全局解析器即可.setHttpDecoder(MyHttpDecoder.getInstance())：

/// 自定义解码器
class MyHttpDecoder extends NetDecoder {
  /// 单例对象
  static final MyHttpDecoder _instance = MyHttpDecoder._internal();

  /// 内部构造方法，可避免外部暴露构造函数，进行实例化
  MyHttpDecoder._internal();

  /// 工厂构造方法，这里使用命名构造函数方式进行声明
  factory MyHttpDecoder.getInstance() => _instance;

  @override
  K decode<T extends BaseNetworkModel, K>(
      {required Response<dynamic> response, required T decodeType}) {
    var errorCode = response.data['errorCode'];

    /// 请求成功
    if (errorCode == 0) {
      var data = response.data['data'];
      if (data is List) {
        var dataList = List<T>.from(
            data.map((item) => decodeType.fromJson(item)).toList()) as K;
        return dataList;
      } else {
        var model = decodeType.fromJson(data) as K;
        return model;
      }
    } else {
      var errorMsg = response.data['errorMsg'];
      throw NetException(errorMsg, errorCode);
    }
  }
}

如果需要缓存数据，可以使用dio_cache_interceptor、dio_http_cache等 dio 推荐的缓存库。

 // dio_http_cache
      .addInterceptor(DioCacheManager(CacheConfig(
        baseUrl: "https://www.wanandroid.com/",
      )).interceptor)
      // dio_cache_interceptor
      .addInterceptor(DioCacheInterceptor(
          options: CacheOptions(
        store: MemCacheStore(),
        policy: CachePolicy.forceCache,
        hitCacheOnErrorExcept: [401, 403],
        maxStale: const Duration(days: 7),
        priority: CachePriority.normal,
        cipher: null,
        keyBuilder: CacheOptions.defaultCacheKeyBuilder,
        allowPostMethod: false,
      )))

因为dio_http_cache依赖的dio 和json_annotation是旧版本，所以如果使用dio_http_cache`需要解决下依赖冲突：

dependency_overrides:
  dio: ^5.0.3
  json_annotation: ^4.8.0

配置代理和证书：

      .setHttpClientAdapter(IOHttpClientAdapter()
        ..onHttpClientCreate = (client) {
          client.findProxy = (uri) {
            return 'PROXY 192.168.20.43:8888';
          };
          client.badCertificateCallback =
              (X509Certificate cert, String host, int port) => true;
          return client;
        })

配置cookie：

addInterceptor(CookieManager(CookieJar()))

开启 log，默认开启：

.enableLogger(true)

究极进化版基于 dio 的网络封装库

特殊配置

有的接口比较特殊，比如返回的数据格式是特殊的，需要单独解析，此时有两种方法实现，第一种适合多个相同的特殊接口，自定义针对这种数据格式的解析器，在请求时传入即可；第二种适合单独出现的数据格式，通过回调方法在其中自行解析。

解析器httpDecode：

    var appResponse = await get<BannerBean, List<BannerBean>>("banner/json",
        decodeType: BannerBean(), httpDecode: MyHttpDecoder.getInstance());
    appResponse.when(success: (List<BannerBean> model) {
      var size = model.length;
      debugPrint("成功返回$size条");
    }, failure: (String msg, int code) {
      debugPrint("失败了：$msg");
    });

回调converter：

   var appResponse = await get<BannerModel, List<BannerBean>>("banner/json",
        options: buildCacheOptions(const Duration(days: 7)),
        decodeType: BannerModel(), converter: (response) {
      var errorCode = response.data['errorCode'];
      /// 请求成功
      if (errorCode == 0) {
        var data = response.data['data'];
        var dataList = List<BannerBean>.from(
            data.map((item) => BannerBean.fromJson(item)).toList());
        return Result.success(dataList);
      } else {
        var errorMsg = response.data['errorMsg'];
        return Result.failure(msg: errorMsg, code: errorCode);
      }
    });
    appResponse.when(success: (List<BannerBean> model) {
      debugPrint("成功返回${model.length}条");
    }, failure: (String msg, int code) {
      debugPrint("失败了：msg=$msg/code=$code");
    });

名字的由来

一开始这个库的名字是net，这是我第一次在 pub 上发布，不知道库名称不能重合的规则，一直失败：

`xxx@gmail.com` has insufficient permissions to upload new versions to existing package `net`.

说明 pub 上已经有了这个名字的库，改名flutter_net，依然失败：

`xxx@gmail.com` has insufficient permissions to upload new versions to existing package `flutter_net`.

最后改名为flutter_nb_net，终于发布成功了。

国际惯例上源码

pub地址