pd_develop_kit #

跨平台 Flutter 开发工具包插件，聚合网络抽象层、数据安全转换、表单校验、深度比较、扩展能力与常用 UI 依赖，并通过统一导出入口对外提供能力。

特性概览 #

• 网络层：统一返回 BaseResponse<T>，不向业务层抛出网络异常、服务端异常或映射异常
• 传输抽象：通过 PDTransport 抽象底层传输实现，默认内置 dio 适配，但业务 API 不暴露 dio 类型
• 灵活配置：支持 PDNetworkConfig 全局配置与 PDRequestConfig 单次请求覆盖
• 加解密扩展：支持可插拔 PDRequestEncoder / PDResponseDecoder，可扩展 AES 等加解密流程
• 长连接支持：提供完整的 WebSocket 长连接方案，支持系统栈优先、自动降级、心跳、重连等
• 工具类：提供 PDTypeSafe、PDPhoneValidator、PDPasswordValidator、PDDeepComparator、PDTimerManager 等常用工具
• 扩展能力：常用 Dart/Flutter 扩展方法，如 num.adapt、String.color 等
• 响应式布局：提供 PDResponsiveBuilder、PDResponsiveGrid 等适配多端的布局组件
• 统一导出：内置导出 global_event_bus、pd_load_state、pd_cooldown、pd_log、random_toolkit 等常用依赖

模块文档 #

• 网络层：HTTP 网络请求、配置管理、加解密流程
• 长连接：WebSocket 长连接、系统栈优先、重连/心跳策略
• 工具类：PDTypeSafe、校验工具、深度比较、定时器管理
• 扩展能力：num.adapt、颜色转换、日期格式化等
• UI 组件与响应式布局：响应式构建器、网格布局等

安装 #

在 pubspec.yaml 中添加依赖：

dependencies:
  pd_develop_kit: ^0.3.0

执行依赖安装：

fvm flutter pub get

快速开始 #

1. 初始化网络层 #

import 'package:pd_develop_kit/pd_develop_kit.dart';

void initNetwork() {
  PDNetwork.configure(
    config: const PDNetworkConfig(
      baseUrl: 'https://api.example.com',
      headers: <String, dynamic>{
        'Accept': 'application/json',
      },
      enableLog: true,
      defaultErrorMessage: '请求失败，请稍后重试。',
    ),
  );
}

2. 发起请求 #

final PDApiClient client = PDNetwork.client;

final BaseResponse<Map<String, dynamic>> response =
    await client.get<Map<String, dynamic>>('/user/profile');

if (response.isSuccess) {
  final Map<String, dynamic>? data = response.data;
  print('用户信息: $data');
} else {
  print('code=${response.code}, msg=${response.msg}');
}

3. 单次请求覆盖配置 #

final BaseResponse<Map<String, dynamic>> response =
    await client.get<Map<String, dynamic>>(
  '/demo/success',
  requestConfig: const PDRequestConfig(
    baseUrl: 'https://override.example.com',
    headers: <String, dynamic>{'X-From': 'requestConfig'},
    enableLog: true,
  ),
);

4. 自定义加解密扩展 #

final BaseResponse<Map<String, dynamic>> response =
    await client.post<Map<String, dynamic>>(
  '/secure/demo',
  data: <String, dynamic>{'name': 'Pedro'},
  requestConfig: PDRequestConfig(
    requestEncoder: PDAesRequestEncoder(
      encrypt: (plain) => 'ENC:$plain',
      bodyCipherField: 'cipherText',
    ),
    responseDecoder: PDAesResponseDecoder(
      decrypt: (cipher) => cipher.replaceFirst('ENC:', ''),
      mode: PDDecryptMode.dataFieldOnly,
    ),
  ),
);

常用工具 #

1. 数据层安全转换 #

final int id = PDTypeSafe.ofInt(json['id'], defaultValue: 0);
final bool enabled = PDTypeSafe.ofBool(json['enabled'], defaultValue: false);
final Map<String, dynamic> payload = PDTypeSafe.ofJsonMap(json['data']);
final List<String> tags = PDTypeSafe.ofList<String>(json['tags']);

2. UI 表单校验 #

final String? phoneError = PDPhoneValidator.validateCNPhone(inputPhone);

final PDPasswordValidationResult passwordResult =
    const PDPasswordValidator().validate(inputPassword);

if (!passwordResult.isValid) {
  print(passwordResult.errorMessage);
}

3. 深度比较 #

final PDComparisonResult result = const PDDeepComparator().compare(a, b);

if (!result.isEqual) {
  print(result.description);
  print(result.differencePaths);
}

示例工程 #

示例工程位于 example/，包含以下演示内容：

• 平台通道能力调用
• 网络层成功、业务失败、服务端失败、超时、映射异常等场景
• PDRequestConfig 单次覆盖能力
• PDAesRequestEncoder / PDAesResponseDecoder 的模拟加解密示例

运行示例：

cd example
fvm flutter run

平台支持 #

当前支持以下 6 个平台：

• Android
• iOS
• Web
• Windows
• macOS
• Linux

权限与配置说明 #

• 插件本身不强制申请系统权限
• 若使用网络能力，Android 端需确保已声明 android.permission.INTERNET
• 若接入自定义加密方案，请自行保证密钥管理、密文传输和服务端协议一致
• 网络层不会将异常直接抛到业务层，请统一从 BaseResponse 的 code、msg、data、rawData 中读取结果

API 文档 #

本仓库使用以下命令生成 API 文档：

fvm dart doc

生成结果默认位于 doc/api/，本地可直接打开 doc/api/index.html 查看。