# PDDevelopKit

**Repository Path**: pedro-labs/pd-develop-kit

## Basic Information

- **Project Name**: PDDevelopKit
- **Description**: PDDevelopKit：一个专注于开发工具和框架的开源项目，旨在提升开发者效率，支持多平台应用开发，提供丰富的API和组件。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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` 等常用依赖

## 模块文档

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

## 安装

在 `pubspec.yaml` 中添加依赖：

```yaml
dependencies:
  pd_develop_kit: ^0.3.0
```

执行依赖安装：

```bash
fvm flutter pub get
```

## 快速开始

### 1. 初始化网络层

```dart
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. 发起请求

```dart
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. 单次请求覆盖配置

```dart
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. 自定义加解密扩展

```dart
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. 数据层安全转换

```dart
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 表单校验

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

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

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

### 3. 深度比较

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

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

## 示例工程

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

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

运行示例：

```bash
cd example
fvm flutter run
```

## 平台支持

当前支持以下 6 个平台：

- Android
- iOS
- Web
- Windows
- macOS
- Linux

## 权限与配置说明

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

## API 文档

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

```bash
fvm dart doc
```

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