yknetworking

轻量级 Flutter/Dart 网络请求库，基于 dio 5 构建。提供统一的 GET/POST 请求、上传、下载、进度回调、动态头/参、业务数据统一处理、错误回调、全局超时与公共参数配置，以及网络连通性监听能力。

主页与仓库：https://github.com/yykedward/ykflutternetworking

许可证：MIT（见 LICENSE）

特性

统一请求入口与响应封装：YKBaseNetworking.request、YKNetworkingResponse
动态与公共头/参合并，支持每次请求动态生成
业务数据统一处理回调 handleData，可抛出异常中断流程
错误回调与 Loading 显示回调
上传（multipart/form-data）与下载（支持保存到本地）
进度回调（上传/下载/接收）
全局超时、基础地址、公共参数、公共头配置
网络连通性监听 YkNetworkConnectivity（基于 connectivity_plus）

环境与依赖

Dart >=2.15.0 <4.0.0
Flutter
依赖：dio: ^5.5.0，connectivity_plus: ^6.0.5

安装

命令安装：

flutter pub add yknetworking

或在 pubspec.yaml 中添加：

dependencies:
  yknetworking: ^0.1.3

快速开始

初始化全局配置：

import 'package:yknetworking/yk_networking.dart';

void setupNetworking() {
  final config = YKNetworkingConfig.getInstance();
  config.baseUrl = 'https://api.example.com';
  config.timeOut = 30;
  config.receiveTimeout = 30;
  config.commHeader = {'Accept': 'application/json'};
  config.commParams = {'locale': 'zh-CN'};
}

发送请求：

final api = YKNetworking(
  commonHeader: {'Authorization': 'Bearer token'},
  handleData: (req, resp) {
    final data = resp.data;
    if (data is Map && data['code'] != 0) {
      return Exception(data['message'] ?? '业务失败');
    }
    return null;
  },
  errorCallBack: (req, ex) {},
  showLoadingCallBack: (show) {},
);

final r1 = await api.get('/users', params: {'page': 1});
final r2 = await api.post(
  '/login',
  params: {'user': 'a', 'pwd': 'b'},
  contentType: YKNetworkingContentType.applicationJson,
);

上传与下载

上传文件：

final uploadResp = await api.upload(
  '/files',
  '/path/local.png',
  'local.png',
  'image/png',
  'file',
  params: {'dir': 'images'},
  progressCallBack: (sent, total) {},
);

下载文件（保存到本地）：

final downloadResp = await api.download(
  'https://host/file.zip',
  downloadPath: '/tmp/file.zip',
  progressCallBack: (received, total) {},
);

进阶用法

动态头/参：在每次请求前动态生成并合并到公共与局部参数中。

final api = YKNetworking(
  dynamicHeader: (req) async => {'X-Trace-Id': 'trace-id'},
  dynamicParams: (req) async => {'ts': DateTime.now().millisecondsSinceEpoch},
);

业务数据统一处理与错误回调：

final api = YKNetworking(
  handleData: (req, resp) {
    final d = resp.data;
    if (d is Map && d['code'] != 0) {
      return Exception(d['message'] ?? '业务失败');
    }
    return null;
  },
  errorCallBack: (req, ex) {},
);

Loading 显示：

final api = YKNetworking(
  showLoadingCallBack: (show) {},
);
final resp = await api.get('/users', showLoading: true);

绝对 URL：当 path 为完整 http(s) 地址时会覆盖 baseUrl（见实现）。
内容类型：通过 contentType 指定，如 YKNetworkingContentType.applicationJson、multipartFormData 等。

网络连通性监听

await YkNetworkConnectivity.instance.setup();
final didConnect = await YkNetworkConnectivity.instance.check();

在 Flutter 中可结合 ChangeNotifier 订阅 didConnect 状态变化。

API 速查（实现位置）

请求入口：lib/yk_base_networking.dart:11（request）
上传实现：lib/yk_base_networking.dart:111（upload）
下载实现：lib/yk_base_networking.dart:189（download）
配置单例：lib/yk_networking_config.dart:7（YKNetworkingConfig）
请求构造与方法/类型枚举：lib/yk_networking_request.dart:19、lib/yk_networking_request.dart:6、lib/yk_networking_request.dart:12
高层接口（GET/POST/Upload/Download）：lib/yk_networking.dart:41、lib/yk_networking.dart:65、lib/yk_networking.dart:115、lib/yk_networking.dart:147
网络连通性：lib/yk_network_connectivity.dart:6

版本与兼容性

Dart >=2.15.0 <4.0.0
适配 dio 5.x API

开发与测试

运行测试：flutter test
代码规范：参见 analysis_options.yaml

变更日志与许可证

变更日志：见 CHANGELOG.md
许可证：MIT，见 LICENSE

示例项目

使用方式与示例参见本文档代码片段；如需更完整演示，可在你的 Flutter 工程中引入本库并按“快速开始”章节配置后试用。

Libraries

yknetworking package