Network Kit Lite：一个基于 SOLID 原则的 Flutter 网络框架架构设计

苦逼的搬砖工2025-08-25 16:37

📖 前言

在移动应用开发中，网络请求是不可或缺的核心功能。一个优秀的网络框架不仅要提供基础的 HTTP 请求能力，更要考虑性能、可维护性、可扩展性等多个维度。本文将详细介绍 Network Kit Lite 的架构设计，展示如何运用 SOLID 原则构建一个高质量的网络框架。

🏗️ 整体架构概览

Network Kit Lite 采用分层架构设计，遵循 SOLID 原则，实现了高内聚、低耦合的模块化结构：

🏗️ 系统架构总览

Network Kit Lite 采用四层架构设计，每层职责明确，遵循 SOLID 原则：

graph TD subgraph "📱 应用层 (Presentation Layer)" A1["📡 API Endpoints
• 统一接口定义
• 请求参数封装
• 路由管理"] A2["📦 Response Wrappers
• 数据包装器
• 类型安全转换
• 业务数据提取"] A3["⚠️ Error Handling
• 异常分类处理
• 国际化错误消息
• 用户友好提示"] end subgraph "🧠 业务逻辑层 (Business Logic Layer)" B1["💾 Cache Manager
• 多级缓存策略
• 缓存过期管理
• 批量操作优化"] B2["🔄 Retry Logic
• 智能重试机制
• 错误类型判断
• 指数退避算法"] B3["📊 Network Monitor
• 性能统计分析
• 请求历史记录
• 实时监控报告"] end subgraph "⚙️ 基础设施层 (Infrastructure Layer)" C1["🌐 Dio Client
• HTTP 客户端
• 连接池管理
• 配置管理"] C2["🔗 Interceptors
• 请求拦截器
• 响应处理链
• 中间件系统"] C3["💿 Storage Impl
• 存储抽象实现
• 多存储策略
• 数据持久化"] end subgraph "💾 数据层 (Data Layer)" D1["🗄️ Cache Storage
• 内存缓存
• SQLite 数据库
• 文件缓存"] D2["🌐 Network Connectivity
• 网络状态检测
• 连接类型识别
• 状态变化监听"] D3["📁 File System
• 文件系统操作
• 路径管理
• 权限处理"] end A1 -.-> B1 A2 -.-> B2 A3 -.-> B3 B1 -.-> C1 B2 -.-> C2 B3 -.-> C3 C1 -.-> D1 C2 -.-> D2 C3 -.-> D3

📱 应用层 (Presentation Layer)

📡 API Endpoints

  • 统一接口定义
  • 请求参数封装
  • 路由管理

📦 Response Wrappers

  • 数据包装器
  • 类型安全转换
  • 业务数据提取

⚠️ Error Handling

  • 异常分类处理
  • 国际化错误消息
  • 用户友好提示

🧠 业务逻辑层 (Business Logic Layer)

💾 Cache Manager

  • 多级缓存策略
  • 缓存过期管理
  • 批量操作优化

🔄 Retry Logic

  • 智能重试机制
  • 错误类型判断
  • 指数退避算法

📊 Network Monitoring

  • 性能统计分析
  • 请求历史记录
  • 实时监控报告

⚙️ 基础设施层 (Infrastructure Layer)

🌐 Dio Client

  • HTTP 客户端
  • 连接池管理
  • 配置管理

🔗 Interceptors

  • 请求拦截器
  • 响应处理链
  • 中间件系统

💿 Storage Implementations

  • 存储抽象实现
  • 多存储策略
  • 数据持久化

💾 数据层 (Data Layer)

🗄️ Cache Storage

  • 内存缓存
  • SQLite 数据库
  • 文件缓存

🌐 Network Connectivity

  • 网络状态检测
  • 连接类型识别
  • 状态变化监听

📁 File System

  • 文件系统操作
  • 路径管理
  • 权限处理

📋 架构层次详细说明

层级 组件 职责 设计模式
应用层 API Endpoints 统一接口定义、请求参数封装 工厂模式
Response Wrappers 数据包装器、类型安全转换 包装器模式
Error Handling 异常分类处理、国际化错误消息 策略模式
业务逻辑层 Cache Manager 多级缓存策略、过期管理 策略模式
Retry Logic 智能重试机制、错误判断 状态模式
Network Monitor 性能统计、实时监控 观察者模式
基础设施层 Dio Client HTTP 客户端、连接池管理 单例模式
Interceptors 请求拦截器、中间件系统 责任链模式
Storage Impl 存储抽象实现、多存储策略 适配器模式
数据层 Cache Storage 内存缓存、数据库存储 策略模式
Network Connectivity 网络状态检测、状态监听 观察者模式
File System 文件系统操作、路径管理 外观模式

🔄 网络请求流程

flowchart TD A["📱 应用发起请求"] --> B["📡 API 端点处理"] B --> C["🔗 拦截器链处理"] C --> D{"💾 缓存检查"} D -->|命中| E["📦 返回缓存数据"] D -->|未命中| F["🌐 网络请求"] F --> G["📊 监控记录"] G --> H{"⚠️ 错误检查"} H -->|有错误| I["🔄 重试逻辑"] I --> F H -->|成功| J["📦 响应包装"] J --> K["💾 缓存保存"] K --> L["📱 返回应用"] E --> L style A fill:#e1f5fe style E fill:#e8f5e8 style F fill:#fff3e0 style I fill:#ffebee style L fill:#e1f5fe

📱 应用发起请求 ↓ 📡 API 端点处理 ↓ 🔗 拦截器链处理 ↓ 💾 缓存检查

  • 如果命中缓存 → 直接返回缓存数据
  • 如果未命中 → 继续网络请求 ↓ 🌐 网络请求 ↓ 📊 监控记录 ↓ ⚠️ 错误检查
  • 如果有错误 → 重试逻辑 → 重新网络请求
  • 如果成功 → 响应包装 ↓ 📦 响应包装 ↓ 💾 缓存保存 ↓ 📱 返回应用

🔧 核心组件关系

graph TB subgraph "🔧 核心组件" Dio["🌐 DioClient
• 单例模式
• 统一入口
• 全局管理"] Cache["💾 CacheManager
• 缓存策略
• 过期管理
• 批量操作"] Monitor["📊 NetworkMonitor
• 性能统计
• 实时监控
• 历史记录"] Retry["🔄 RetryInterceptor
• 智能重试
• 错误处理
• 指数退避"] end subgraph "💿 存储实现" Memory["💾 MemoryCache
• 内存存储
• 快速访问
• 临时缓存"] File["📁 FileCache
• 文件存储
• 持久化
• 大文件支持"] SQLite["🗄️ SQLiteCache
• 数据库存储
• 结构化数据
• 复杂查询"] LRU["🔄 LRUCache
• LRU算法
• 容量控制
• 自动清理"] end subgraph "🌐 网络层" Connect["📡 NetworkConnectivity
• 网络检测
• 状态监听
• 类型识别"] Config["⚙️ HttpConfig
• 配置管理
• 参数设置
• 环境切换"] Interceptors["🔗 Interceptors
• 拦截器链
• 中间件
• 请求处理"] end Dio -.-> Cache Dio -.-> Monitor Dio -.-> Retry Dio -.-> Interceptors Cache -.-> Memory Cache -.-> File Cache -.-> SQLite Cache -.-> LRU Interceptors -.-> Connect Interceptors -.-> Config style Dio fill:#e3f2fd style Cache fill:#e8f5e8 style Monitor fill:#fce4ec style Retry fill:#fff8e1 style Memory fill:#fff3e0 style File fill:#f3e5f5 style SQLite fill:#e1f5fe style LRU fill:#f1f8e9

🌐 DioClient (单例模式)

  • 统一入口，管理所有网络请求

💾 CacheManager

  • 管理缓存策略和过期
  • 支持多种存储方式：
    • 💾 MemoryCache (内存存储)
    • 📁 FileCache (文件存储)
    • 🗄️ SQLiteCache (数据库存储)
    • 🔄 LRUCache (LRU 算法)

📊 NetworkMonitor

  • 性能统计和实时监控
  • 与 📡 NetworkConnectivity 配合

🔄 RetryInterceptor

  • 智能重试机制
  • 与 ⚙️ HttpConfig 配置配合

🎯 设计模式应用

设计模式 应用场景 实现组件 优势
单例模式 全局网络客户端 DioClient 统一管理、资源复用
策略模式 缓存策略选择 CacheManager 灵活切换、易于扩展
责任链模式 拦截器处理链 Interceptors 解耦处理逻辑
观察者模式 网络状态监听 NetworkConnectivity 实时响应状态变化
工厂模式 API 端点创建 APIEndpoints 统一创建接口
适配器模式 存储实现适配 Storage Implementations 兼容不同存储方式
包装器模式 响应数据包装 ResponseWrappers 统一数据格式
状态模式 重试状态管理 RetryLogic 清晰的状态转换

🎯 核心设计原则

1. 单一职责原则 (SRP)

每个类都有明确的单一职责，避免功能混杂：

dart 复制代码 
/// 缓存管理器 - 只负责缓存逻辑
class CacheManager {
  Future<void> save(String key, dynamic data, {Duration? duration});
  Future<dynamic> get(String key);
  Future<void> clear();
}

/// 网络监控器 - 只负责性能监控
class NetworkMonitor {
  void recordRequest(RequestPerformance performance);
  NetworkStats getStats();
  List<RequestPerformance> getHistory();
}

/// 重试拦截器 - 只负责重试逻辑
class RetryInterceptor extends Interceptor {
  @override
  void onError(DioException err, ErrorInterceptorHandler handler);
}

2. 开放封闭原则 (OCP)

通过抽象接口和策略模式实现扩展性：

dart 复制代码 
/// 缓存存储抽象接口
abstract class CacheStorage {
  Future<void> init();
  Future<void> save(String key, Map<String, dynamic> data);
  Future<Map<String, dynamic>?> get(String key);
  Future<void> clear();
}

/// 具体实现可以轻松扩展
class MemoryCache implements CacheStorage { /* ... */ }
class FileCache implements CacheStorage { /* ... */ }
class SqliteCache implements CacheStorage { /* ... */ }
class LruCache implements CacheStorage { /* ... */ }

3. 里氏替换原则 (LSP)

所有缓存实现都可以无缝替换：

dart 复制代码 
class CacheManager {
  final CacheStorage _storage; // 依赖抽象

  CacheManager(this._storage); // 通过构造函数注入

  // 无论传入哪种实现，都能正常工作
  Future<void> save(String key, dynamic data) async {
    await _storage.save(key, data.toJson());
  }
}

4. 接口隔离原则 (ISP)

将大接口拆分为多个专用接口：

dart 复制代码 
/// 网络连接检测接口
abstract class NetworkConnectivity {
  Future<NetworkConnectivityStatus> checkConnectivity();
  Stream<NetworkConnectivityStatus> get onConnectivityChanged;
}

/// 缓存操作接口
abstract class CacheOperations {
  Future<void> save(String key, dynamic data);
  Future<dynamic> get(String key);
}

/// 性能监控接口
abstract class PerformanceMonitoring {
  void recordRequest(RequestPerformance performance);
  NetworkStats getStats();
}

5. 依赖倒置原则 (DIP)

高层模块不依赖低层模块，都依赖抽象：

dart 复制代码 
/// 高层模块：DioClient
class DioClient {
  final CacheManager _cacheManager;
  final NetworkMonitor _monitor;
  final List<Interceptor> _interceptors;

  // 依赖抽象，不依赖具体实现
  DioClient({
    required CacheManager cacheManager,
    required NetworkMonitor monitor,
    List<Interceptor>? interceptors,
  }) : _cacheManager = cacheManager,
       _monitor = monitor,
       _interceptors = interceptors ?? [];
}

🔧 核心模块设计

1. DioClient - 网络客户端核心

DioClient 是整个框架的核心，采用单例模式，负责协调各个模块：

dart 复制代码 
class DioClient {
  static final DioClient _instance = DioClient._internal();
  factory DioClient() => _instance;
  DioClient._internal();

  late Dio _dio;
  late final CacheManager _cacheManager;
  late final NetworkMonitor _monitor;
  late final NetworkConnectivity _connectivity;

  /// 初始化方法 - 配置所有依赖
  Future<void> init({
    required String baseUrl,
    Duration? connectTimeout,
    Duration? receiveTimeout,
    int maxRetries = 3,
    bool enableCache = false,
    CacheType cacheType = CacheType.memory,
    bool enableLogging = false,
    bool enableMonitoring = false,
  }) async {
    // 1. 初始化网络连接检测
    await _initializeNetworkConnectivity();

    // 2. 初始化缓存管理器
    if (enableCache) {
      await _initializeCacheManager(cacheType);
    }

    // 3. 初始化性能监控
    if (enableMonitoring) {
      _initializeMonitoring();
    }

    // 4. 配置 Dio 实例
    _configureDio(baseUrl, connectTimeout, receiveTimeout);

    // 5. 添加拦截器
    _addInterceptors(maxRetries, enableLogging);
  }
}

设计亮点：

  • 采用建造者模式进行初始化配置
  • 支持条件性功能启用（缓存、监控、日志）
  • 通过依赖注入实现模块解耦

2. 缓存系统 - 多级缓存架构

缓存系统采用策略模式和装饰器模式，支持多种缓存策略：

dart 复制代码 
/// 缓存策略枚举
enum CacheType {
  memory,   // 内存缓存
  file,     // 文件缓存
  sqlite,   // SQLite 缓存
  lru,      // LRU 缓存
}

/// 缓存管理器 - 统一缓存接口
class CacheManager {
  final CacheStorage _storage;
  final Duration _cleanupInterval;
  final int _maxCacheSize;

  /// 智能缓存策略
  Future<dynamic> get(String key) async {
    // 1. 检查缓存是否过期
    if (_isExpired(key)) {
      await _remove(key);
      return null;
    }

    // 2. 更新访问统计
    await _updateAccessStats(key);

    // 3. 返回缓存数据
    return await _storage.get(key);
  }

  /// 批量操作优化
  Future<void> saveBatch(Map<String, dynamic> data) async {
    final operations = data.entries.map((entry) =>
      CacheOperation.save(entry.key, entry.value)
    ).toList();

    await _processBatchOperations(operations);
  }
}

设计亮点：

  • 支持多种缓存策略，可灵活切换
  • 智能过期检查和自动清理
  • 批量操作优化性能
  • 访问统计支持 LRU 算法

3. 拦截器系统 - 可插拔的中间件

拦截器系统采用责任链模式，支持灵活的功能组合：

dart 复制代码 
/// 基础拦截器抽象
abstract class BaseInterceptor extends Interceptor {
  final String name;
  final bool enabled;

  BaseInterceptor({required this.name, this.enabled = true});

  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    if (!enabled) {
      handler.next(options);
      return;
    }
    _processRequest(options, handler);
  }

  void _processRequest(RequestOptions options, RequestInterceptorHandler handler);
}

/// 缓存拦截器
class CacheInterceptor extends BaseInterceptor {
  final CacheManager _cacheManager;

  @override
  void _processRequest(RequestOptions options, RequestInterceptorHandler handler) {
    // 只缓存 GET 请求
    if (options.method == 'GET') {
      final cached = _cacheManager.get(_generateCacheKey(options));
      if (cached != null) {
        // 返回缓存数据
        handler.resolve(Response(data: cached));
        return;
      }
    }
    handler.next(options);
  }
}

/// 重试拦截器
class RetryInterceptor extends BaseInterceptor {
  final int maxRetries;
  final Duration retryDelay;

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    if (_shouldRetry(err) && _retryCount < maxRetries) {
      _scheduleRetry(err, handler);
    } else {
      handler.next(err);
    }
  }
}

设计亮点：

  • 可插拔的拦截器设计
  • 支持条件性启用/禁用
  • 智能重试策略
  • 缓存与网络请求无缝集成

4. 网络监控系统 - 性能分析

网络监控系统采用观察者模式，实时收集性能数据：

dart 复制代码 
/// 网络监控器
class NetworkMonitor {
  final Queue<RequestPerformance> _requestHistory;
  final Map<String, RequestPerformance> _activeRequests;
  final StreamController<NetworkStats> _statsController;

  /// 记录请求开始
  void recordRequestStart(String requestId, String url, String method) {
    final performance = RequestPerformance(
      url: url,
      method: method,
      startTime: DateTime.now(),
    );
    _activeRequests[requestId] = performance;
  }

  /// 记录请求完成
  void recordRequestEnd(String requestId, int? statusCode, String? error) {
    final performance = _activeRequests.remove(requestId);
    if (performance != null) {
      performance.endTime = DateTime.now();
      performance.statusCode = statusCode;
      performance.error = error;

      _requestHistory.add(performance);
      _updateStats();
    }
  }

  /// 获取性能统计
  NetworkStats getStats() {
    final total = _requestHistory.length;
    final successful = _requestHistory.where((r) => r.isSuccess).length;
    final failed = total - successful;
    final avgTime = _requestHistory.map((r) => r.duration).average;

    return NetworkStats(
      totalRequests: total,
      successfulRequests: successful,
      failedRequests: failed,
      averageResponseTime: avgTime,
      successRate: total > 0 ? successful / total : 0.0,
      // ... 其他统计信息
    );
  }
}

设计亮点：

  • 实时性能监控
  • 详细的请求统计
  • 支持性能报告导出
  • 内存友好的历史记录管理

🚀 性能优化策略

1. 连接池管理

dart 复制代码 
class ConnectionPool {
  final int maxConnections;
  final Duration connectionTimeout;
  final Map<String, HttpClient> _connections = {};

  Future<HttpClient> getConnection(String host) async {
    if (_connections.containsKey(host)) {
      return _connections[host]!;
    }

    if (_connections.length >= maxConnections) {
      await _cleanupIdleConnections();
    }

    final client = HttpClient();
    _connections[host] = client;
    return client;
  }
}

2. 请求去重

dart 复制代码 
class RequestDeduplicator {
  final Map<String, Completer<dynamic>> _pendingRequests = {};

  Future<T> deduplicate<T>(String key, Future<T> Function() request) async {
    if (_pendingRequests.containsKey(key)) {
      return await _pendingRequests[key]!.future as T;
    }

    final completer = Completer<T>();
    _pendingRequests[key] = completer;

    try {
      final result = await request();
      completer.complete(result);
      return result;
    } catch (e) {
      completer.completeError(e);
      rethrow;
    } finally {
      _pendingRequests.remove(key);
    }
  }
}

3. 智能缓存策略

dart 复制代码 
class SmartCacheStrategy {
  /// 根据网络状态调整缓存策略
  CachePolicy getCachePolicy(NetworkConnectivityStatus status) {
    switch (status) {
      case NetworkConnectivityStatus.none:
        return CachePolicy.onlyCache; // 离线时只使用缓存
      case NetworkConnectivityStatus.mobile:
        return CachePolicy.cacheFirst; // 移动网络优先缓存
      case NetworkConnectivityStatus.wifi:
        return CachePolicy.networkFirst; // WiFi 优先网络
      default:
        return CachePolicy.networkFirst;
    }
  }
}

🧪 测试策略

1. 单元测试

dart 复制代码 
class CacheManagerTest {
  late CacheManager cacheManager;
  late MockCacheStorage mockStorage;

  setUp(() {
    mockStorage = MockCacheStorage();
    cacheManager = CacheManager(mockStorage);
  });

  test('should save data successfully', () async {
    // Arrange
    const key = 'test_key';
    const data = {'name': 'test'};
    when(mockStorage.save(key, any)).thenAnswer((_) async {});

    // Act
    await cacheManager.save(key, data);

    // Assert
    verify(mockStorage.save(key, any)).called(1);
  });
}

2. 集成测试

dart 复制代码 
class DioClientIntegrationTest {
  late DioClient dioClient;

  setUpAll(() async {
    dioClient = DioClient();
    await dioClient.init(
      baseUrl: 'https://httpbin.org',
      enableCache: true,
      enableMonitoring: true,
    );
  });

  test('should handle successful request with cache', () async {
    // 第一次请求
    final response1 = await dioClient.execute(
      APIEndpoint.get('/get'),
    );

    // 第二次请求应该从缓存获取
    final response2 = await dioClient.execute(
      APIEndpoint.get('/get'),
    );

    expect(response1.data, equals(response2.data));
  });
}

📊 性能基准测试

通过基准测试验证框架性能：

dart 复制代码 
class PerformanceBenchmark {
  static Future<void> runBenchmarks() async {
    final dioClient = DioClient();
    await dioClient.init(baseUrl: 'https://httpbin.org');

    // 并发请求测试
    final stopwatch = Stopwatch()..start();
    final futures = List.generate(100, (index) =>
      dioClient.execute(APIEndpoint.get('/delay/1'))
    );
    await Future.wait(futures);
    stopwatch.stop();

    print('并发 100 个请求耗时: ${stopwatch.elapsedMilliseconds}ms');

    // 缓存性能测试
    final cacheStopwatch = Stopwatch()..start();
    for (int i = 0; i < 1000; i++) {
      await dioClient.execute(APIEndpoint.get('/get'));
    }
    cacheStopwatch.stop();

    print('缓存请求 1000 次耗时: ${cacheStopwatch.elapsedMilliseconds}ms');
  }
}

🔮 未来扩展计划

1. 插件化架构

dart 复制代码 
/// 插件接口
abstract class NetworkPlugin {
  String get name;
  void onRequest(RequestOptions options);
  void onResponse(Response response);
  void onError(DioException error);
}

/// 插件管理器
class PluginManager {
  final List<NetworkPlugin> _plugins = [];

  void registerPlugin(NetworkPlugin plugin) {
    _plugins.add(plugin);
  }

  void onRequest(RequestOptions options) {
    for (final plugin in _plugins) {
      plugin.onRequest(options);
    }
  }
}

2. 自适应优化

dart 复制代码 
class AdaptiveOptimizer {
  /// 根据网络状况自动调整策略
  void adaptToNetworkConditions(NetworkStats stats) {
    if (stats.averageResponseTime > 5000) {
      // 网络较慢，增加缓存时间
      _increaseCacheDuration();
    }

    if (stats.successRate < 0.8) {
      // 成功率较低，增加重试次数
      _increaseRetryCount();
    }
  }
}

📝 总结

Network Kit Lite 通过严格遵循 SOLID 原则，实现了：

  1. 高内聚低耦合：每个模块职责明确，相互独立
  2. 易于扩展：通过抽象接口和策略模式支持功能扩展
  3. 高性能：多级缓存、连接池、请求去重等优化策略
  4. 可维护性：清晰的架构分层和模块化设计
  5. 可测试性：完善的单元测试和集成测试覆盖

这种架构设计不仅满足了当前的需求，更为未来的功能扩展和性能优化奠定了坚实的基础。通过持续的重构和优化，Network Kit Lite 将成为一个更加成熟和强大的网络框架。

作者： [Allen] 项目地址： [github.com/1989allen12...] 版本： v1.0.0

如果您觉得这篇文章对您有帮助，欢迎点赞、收藏和分享！

相关推荐
火柴就是我17 小时前
flutter 之真手势冲突处理
android·flutter
Speed12317 小时前
`mockito` 的核心“打桩”规则
flutter·dart
法的空间17 小时前
Flutter JsonToDart 支持 JsonSchema
android·flutter·ios
恋猫de小郭17 小时前
Android 将强制应用使用主题图标，你怎么看？
android·前端·flutter
玲珑Felone18 小时前
从flutter源码看其渲染机制
android·flutter
ALLIN2 天前
Flutter 三种方式实现页面切换后保持原页面状态
flutter
Dabei2 天前
Flutter 国际化
flutter
Dabei2 天前
Flutter MQTT 通信文档
flutter
Dabei2 天前
Flutter 中实现 TCP 通信
flutter
孤鸿玉2 天前
ios flutter_echarts 不在当前屏幕 白屏修复
flutter
热门推荐
01GitHub 镜像站点02UV 工具安装与国内镜像源配置指南03Claude Code 平替：OpenAI发布 Codex CLI ，GPT-5 国内直接使用04UV安装并设置国内源0546个Nano-banana 精选提示词，持续更新中06A股预测还能更准？开源大模型Kronos带你跑通预测+回测全流程07conda中设置镜像地址（附所有可换的地址）08KGG转MP3工具|非KGM文件|解密音频09保姆级教程：手把手教你用Dify实现完美多轮对话（附Chatflow和提示词）10突破百度网盘的下载限速，两种方法教会你【超详细】