# ykflutternetworking

**Repository Path**: Edwrard/ykflutternetworking

## Basic Information

- **Project Name**: ykflutternetworking
- **Description**: Flutter 的网络请求库（基于dio进行封装）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-12-25
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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
```

**快速开始**
- 初始化全局配置：
```dart
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'};
}
```
- 发送请求：
```dart
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,
);
```

**上传与下载**
- 上传文件：
```dart
final uploadResp = await api.upload(
  '/files',
  '/path/local.png',
  'local.png',
  'image/png',
  'file',
  params: {'dir': 'images'},
  progressCallBack: (sent, total) {},
);
```
- 下载文件（保存到本地）：
```dart
final downloadResp = await api.download(
  'https://host/file.zip',
  downloadPath: '/tmp/file.zip',
  progressCallBack: (received, total) {},
);
```

**进阶用法**
- 动态头/参：在每次请求前动态生成并合并到公共与局部参数中。
```dart
final api = YKNetworking(
  dynamicHeader: (req) async => {'X-Trace-Id': 'trace-id'},
  dynamicParams: (req) async => {'ts': DateTime.now().millisecondsSinceEpoch},
);
```
- 业务数据统一处理与错误回调：
```dart
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 显示：
```dart
final api = YKNetworking(
  showLoadingCallBack: (show) {},
);
final resp = await api.get('/users', showLoading: true);
```
- 绝对 URL：当 `path` 为完整 `http(s)` 地址时会覆盖 `baseUrl`（见实现）。
- 内容类型：通过 `contentType` 指定，如 `YKNetworkingContentType.applicationJson`、`multipartFormData` 等。

**网络连通性监听**
```dart
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 工程中引入本库并按“快速开始”章节配置后试用。