oneapp_docs/basic_utils/basic_utils.md

Basic Utils 基础工具模块

模块概述

basic_utils 是 OneApp 基础工具模块群中的核心工具集合，提供了应用开发中常用的基础工具类、辅助方法和通用组件。该模块包含了事件总线、图片处理、分享功能、加密解密、文件上传等丰富的工具功能。

基本信息

• 模块名称: basic_utils
• 版本: 0.0.3
• 描述: 基础工具包
• Flutter 版本: >=2.10.5
• Dart 版本: >=3.0.0 <4.0.08

功能特性

核心功能

1. 事件总线系统

   • 全局事件发布订阅
   • 类型安全的事件传递
   • 事件生命周期管理
   • 异步事件处理

2. 图片处理工具

   • 图片选择和拍照
   • 图片压缩和格式转换
   • 图片裁剪和编辑
   • 图片缓存管理

3. 分享功能集成

   • 社交平台分享
   • 文件分享
   • 链接分享
   • 自定义分享内容

4. 加密解密服务

   • 对称加密算法
   • 非对称加密算法
   • 哈希算法
   • 数字签名

5. 云存储服务

   • 腾讯云COS集成
   • 文件上传下载
   • 断点续传
   • 存储管理

技术架构

目录结构

lib/
├── basic_utils.dart            # 模块入口文件
├── src/                        # 源代码目录
│   ├── event_bus/              # 事件总线
│   ├── image/                  # 图片处理
│   ├── share/                  # 分享功能
│   ├── crypto/                 # 加密解密
│   ├── storage/                # 云存储
│   ├── network/                # 网络工具
│   ├── utils/                  # 通用工具
│   └── models/                 # 数据模型
├── widgets/                    # 通用组件
└── test/                       # 测试文件

依赖关系

核心框架依赖

• basic_modular: ^0.2.3 - 模块化框架
• basic_storage: 0.2.2 - 基础存储
• basic_webview: ^0.2.4 - WebView组件

工具依赖

• event_bus: ^2.0.0 - 事件总线
• shared_preferences: ^2.0.17 - 本地存储
• http: ^1.0.0 - HTTP客户端
• dartz: ^0.10.1 - 函数式编程

功能依赖

• image_picker: ^1.1.2 - 图片选择
• flutter_image_compress: 2.1.0 - 图片压缩
• share_plus: 7.2.1 - 分享功能
• fluwx: ^4.2.5 - 微信SDK
• weibo_kit: ^4.0.0 - 微博SDK

安全依赖

• crypto: any - 加密算法
• encrypt: any - 加密工具
• pointycastle: any - 加密库

云服务依赖

• tencentcloud_cos_sdk_plugin: 1.2.0 - 腾讯云COS

核心模块分析

1. 模块入口 (basic_utils.dart)

功能职责:

• 工具模块统一导出
• 全局配置初始化
• 服务注册管理

2. 事件总线 (src/event_bus/)

功能职责:

• 全局事件发布订阅机制
• 类型安全的事件传递
• 事件过滤和转换
• 内存泄漏防护

主要组件:

• GlobalEventBus - 全局事件总线
• EventSubscription - 事件订阅管理
• TypedEvent - 类型化事件
• EventFilter - 事件过滤器

使用示例:

// 定义事件类型
class UserLoginEvent {
  final String userId;
  final String userName;
  
  UserLoginEvent(this.userId, this.userName);
}

// 发布事件
GlobalEventBus.instance.fire(UserLoginEvent('123', 'John'));

// 订阅事件
final subscription = GlobalEventBus.instance.on<UserLoginEvent>().listen((event) {
  print('User ${event.userName} logged in');
});

// 取消订阅
subscription.cancel();

3. 图片处理 (src/image/)

功能职责:

• 图片选择和拍照功能
• 图片压缩和格式转换
• 图片编辑和处理
• 图片缓存和管理

主要组件:

• ImagePicker - 图片选择器
• ImageCompressor - 图片压缩器
• ImageEditor - 图片编辑器
• ImageCache - 图片缓存管理

使用示例:

class ImageUtils {
  static Future<File?> pickImage({
    ImageSource source = ImageSource.gallery,
    double? maxWidth,
    double? maxHeight,
    int? imageQuality,
  }) async {
    final picker = ImagePicker();
    final XFile? image = await picker.pickImage(
      source: source,
      maxWidth: maxWidth,
      maxHeight: maxHeight,
      imageQuality: imageQuality,
    );
    
    return image != null ? File(image.path) : null;
  }
  
  static Future<File> compressImage(
    File file, {
    int quality = 85,
    int? minWidth,
    int? minHeight,
  }) async {
    final result = await FlutterImageCompress.compressAndGetFile(
      file.absolute.path,
      '${file.parent.path}/compressed_${file.name}',
      quality: quality,
      minWidth: minWidth,
      minHeight: minHeight,
    );
    
    return File(result!.path);
  }
}

4. 分享功能 (src/share/)

功能职责:

• 系统原生分享
• 社交平台分享
• 自定义分享内容
• 分享结果回调

主要组件:

• ShareManager - 分享管理器
• WeChatShare - 微信分享
• WeiboShare - 微博分享
• SystemShare - 系统分享

使用示例:

class ShareUtils {
  static Future<void> shareText(String text) async {
    await Share.share(text);
  }
  
  static Future<void> shareFile(String filePath) async {
    await Share.shareXFiles([XFile(filePath)]);
  }
  
  static Future<void> shareToWeChat({
    required String title,
    required String description,
    String? imageUrl,
    String? webpageUrl,
  }) async {
    final model = WeChatShareWebPageModel(
      webPage: webpageUrl ?? '',
      title: title,
      description: description,
      thumbnail: WeChatImage.network(imageUrl ?? ''),
    );
    
    await fluwx.shareToWeChat(model);
  }
}

5. 加密解密 (src/crypto/)

功能职责:

• 对称加密解密
• 非对称加密解密
• 数字签名验证
• 哈希算法实现

主要组件:

• AESCrypto - AES加密
• RSACrypto - RSA加密
• HashUtils - 哈希工具
• SignatureUtils - 数字签名

使用示例:

class CryptoUtils {
  static String md5Hash(String input) {
    final bytes = utf8.encode(input);
    final digest = md5.convert(bytes);
    return digest.toString();
  }
  
  static String sha256Hash(String input) {
    final bytes = utf8.encode(input);
    final digest = sha256.convert(bytes);
    return digest.toString();
  }
  
  static String aesEncrypt(String plainText, String key) {
    final encrypter = Encrypter(AES(Key.fromBase64(key)));
    final encrypted = encrypter.encrypt(plainText);
    return encrypted.base64;
  }
  
  static String aesDecrypt(String encryptedText, String key) {
    final encrypter = Encrypter(AES(Key.fromBase64(key)));
    final decrypted = encrypter.decrypt64(encryptedText);
    return decrypted;
  }
}

6. 云存储 (src/storage/)

功能职责:

• 腾讯云COS集成
• 文件上传下载
• 断点续传
• 存储空间管理

主要组件:

• COSManager - COS管理器
• FileUploader - 文件上传器
• FileDownloader - 文件下载器
• StorageMonitor - 存储监控

使用示例:

class CloudStorageUtils {
  static Future<String?> uploadFile(
    String filePath, {
    String? objectKey,
    Function(int, int)? onProgress,
  }) async {
    try {
      final result = await TencentCloudCosSdkPlugin.upload(
        filePath,
        objectKey ?? _generateObjectKey(filePath),
        onProgress: onProgress,
      );
      
      return result['url'] as String?;
    } catch (e) {
      print('Upload failed: $e');
      return null;
    }
  }
  
  static Future<bool> downloadFile(
    String url,
    String savePath, {
    Function(int, int)? onProgress,
  }) async {
    try {
      await TencentCloudCosSdkPlugin.download(
        url,
        savePath,
        onProgress: onProgress,
      );
      return true;
    } catch (e) {
      print('Download failed: $e');
      return false;
    }
  }
  
  static String _generateObjectKey(String filePath) {
    final fileName = path.basename(filePath);
    final timestamp = DateTime.now().millisecondsSinceEpoch;
    return 'uploads/$timestamp/$fileName';
  }
}

7. 网络工具 (src/network/)

功能职责:

• HTTP请求封装
• 网络状态检测
• 请求重试机制
• 响应数据处理

主要组件:

• HttpClient - HTTP客户端
• NetworkMonitor - 网络监控
• RequestInterceptor - 请求拦截器
• ResponseHandler - 响应处理器

8. 通用工具 (src/utils/)

功能职责:

• 字符串处理工具
• 日期时间工具
• 数学计算工具
• 格式化工具

主要工具:

• StringUtils - 字符串工具
• DateUtils - 日期工具
• MathUtils - 数学工具
• FormatUtils - 格式化工具

工具方法示例:

class StringUtils {
  static bool isNullOrEmpty(String? str) {
    return str == null || str.isEmpty;
  }
  
  static bool isValidEmail(String email) {
    return RegExp(r'^[^@]+@[^@]+\.[^@]+').hasMatch(email);
  }
  
  static bool isValidPhone(String phone) {
    return RegExp(r'^1[3-9]\d{9}$').hasMatch(phone);
  }
  
  static String maskPhone(String phone) {
    if (phone.length != 11) return phone;
    return '${phone.substring(0, 3)}****${phone.substring(7)}';
  }
}

class DateUtils {
  static String formatDateTime(DateTime dateTime, [String? pattern]) {
    pattern ??= 'yyyy-MM-dd HH:mm:ss';
    return DateFormat(pattern).format(dateTime);
  }
  
  static DateTime? parseDateTime(String dateStr, [String? pattern]) {
    try {
      pattern ??= 'yyyy-MM-dd HH:mm:ss';
      return DateFormat(pattern).parse(dateStr);
    } catch (e) {
      return null;
    }
  }
  
  static bool isToday(DateTime dateTime) {
    final now = DateTime.now();
    return dateTime.year == now.year &&
           dateTime.month == now.month &&
           dateTime.day == now.day;
  }
}

通用组件

Loading组件

class LoadingUtils {
  static OverlayEntry? _overlayEntry;
  
  static void show(BuildContext context, {String? message}) {
    hide(); // 先隐藏之前的
    
    _overlayEntry = OverlayEntry(
      builder: (context) => Material(
        color: Colors.black54,
        child: Center(
          child: Container(
            padding: const EdgeInsets.all(20),
            decoration: BoxDecoration(
              color: Colors.white,
              borderRadius: BorderRadius.circular(8),
            ),
            child: Column(
              mainAxisSize: MainAxisSize.min,
              children: [
                const CircularProgressIndicator(),
                if (message != null) ...[
                  const SizedBox(height: 16),
                  Text(message),
                ],
              ],
            ),
          ),
        ),
      ),
    );
    
    Overlay.of(context).insert(_overlayEntry!);
  }
  
  static void hide() {
    _overlayEntry?.remove();
    _overlayEntry = null;
  }
}

Toast组件

class ToastUtils {
  static void showSuccess(String message) {
    Fluttertoast.showToast(
      msg: message,
      backgroundColor: Colors.green,
      textColor: Colors.white,
      toastLength: Toast.LENGTH_SHORT,
    );
  }
  
  static void showError(String message) {
    Fluttertoast.showToast(
      msg: message,
      backgroundColor: Colors.red,
      textColor: Colors.white,
      toastLength: Toast.LENGTH_SHORT,
    );
  }
  
  static void showInfo(String message) {
    Fluttertoast.showToast(
      msg: message,
      backgroundColor: Colors.blue,
      textColor: Colors.white,
      toastLength: Toast.LENGTH_SHORT,
    );
  }
}

性能优化

内存管理

• 事件订阅管理: 及时取消不需要的事件订阅
• 图片内存优化: 合理控制图片加载和缓存
• 对象池: 复用常用对象减少GC压力
• 弱引用: 使用弱引用避免内存泄漏

网络优化

• 请求缓存: 缓存网络请求结果
• 并发控制: 控制并发请求数量
• 超时重试: 智能超时和重试机制
• 数据压缩: 压缩传输数据

存储优化

• 文件压缩: 压缩存储文件
• 清理策略: 定期清理过期文件
• 分块上传: 大文件分块上传
• 断点续传: 支持上传下载断点续传

安全特性

数据安全

• 敏感数据加密: 敏感信息加密存储
• 传输加密: HTTPS传输保护
• 数据校验: 数据完整性校验
• 防篡改: 数字签名防篡改

隐私保护

• 权限控制: 严格的功能权限控制
• 数据脱敏: 敏感数据脱敏处理
• 本地存储: 安全的本地数据存储
• 清理机制: 数据清理和销毁机制

测试策略

单元测试

• 工具类测试: 各种工具方法测试
• 加密解密测试: 加密算法正确性
• 事件总线测试: 事件发布订阅机制
• 网络工具测试: 网络请求功能

集成测试

• 文件上传测试: 云存储集成测试
• 分享功能测试: 社交分享集成测试
• 图片处理测试: 图片处理流程测试
• 端到端测试: 完整功能流程测试

性能测试

• 内存泄漏测试: 长时间运行检测
• 并发性能测试: 高并发场景测试
• 文件处理测试: 大文件处理性能
• 网络性能测试: 网络请求性能

最佳实践

开发建议

1. 工具复用: 优先使用现有工具方法
2. 异常处理: 完善的异常处理机制
3. 资源管理: 及时释放不需要的资源
4. 性能考虑: 避免不必要的操作开销

使用指南

1. 按需导入: 只导入需要的工具类
2. 配置优化: 合理配置各种参数
3. 错误处理: 妥善处理可能的错误
4. 日志记录: 记录关键操作日志

总结

basic_utils 模块作为 OneApp 的基础工具集合，提供了丰富的开发工具和辅助功能。通过事件总线、图片处理、分享功能、加密解密等核心能力，大大简化了应用开发的复杂性。模块具有良好的性能优化和安全保护机制，能够满足各种开发场景的需求。