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

星月赶路人
1,017 阅读9分钟

前言

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

整体架构概览

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

系统架构总览

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

graph TD
    subgraph " 应用层 (Presentation Layer)"
        A1[" API Endpoints<br/>• 统一接口定义<br/>• 请求参数封装<br/>• 路由管理"]
        A2[" Response Wrappers<br/>• 数据包装器<br/>• 类型安全转换<br/>• 业务数据提取"]
        A3[" Error Handling<br/>• 异常分类处理<br/>• 国际化错误消息<br/>• 用户友好提示"]
    end

    subgraph " 业务逻辑层 (Business Logic Layer)"
        B1[" Cache Manager<br/>• 多级缓存策略<br/>• 缓存过期管理<br/>• 批量操作优化"]
        B2[" Retry Logic<br/>• 智能重试机制<br/>• 错误类型判断<br/>• 指数退避算法"]
        B3[" Network Monitor<br/>• 性能统计分析<br/>• 请求历史记录<br/>• 实时监控报告"]
    end

    subgraph " 基础设施层 (Infrastructure Layer)"
        C1[" Dio Client<br/>• HTTP 客户端<br/>• 连接池管理<br/>• 配置管理"]
        C2[" Interceptors<br/>• 请求拦截器<br/>• 响应处理链<br/>• 中间件系统"]
        C3[" Storage Impl<br/>• 存储抽象实现<br/>• 多存储策略<br/>• 数据持久化"]
    end

    subgraph " 数据层 (Data Layer)"
        D1[" Cache Storage<br/>• 内存缓存<br/>• SQLite 数据库<br/>• 文件缓存"]
        D2[" Network Connectivity<br/>• 网络状态检测<br/>• 连接类型识别<br/>• 状态变化监听"]
        D3[" File System<br/>• 文件系统操作<br/>• 路径管理<br/>• 权限处理"]
    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 ClientHTTP 客户端、连接池管理单例模式
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<br/>• 单例模式<br/>• 统一入口<br/>• 全局管理"]
        Cache[" CacheManager<br/>• 缓存策略<br/>• 过期管理<br/>• 批量操作"]
        Monitor[" NetworkMonitor<br/>• 性能统计<br/>• 实时监控<br/>• 历史记录"]
        Retry[" RetryInterceptor<br/>• 智能重试<br/>• 错误处理<br/>• 指数退避"]
    end

    subgraph " 存储实现"
        Memory[" MemoryCache<br/>• 内存存储<br/>• 快速访问<br/>• 临时缓存"]
        File[" FileCache<br/>• 文件存储<br/>• 持久化<br/>• 大文件支持"]
        SQLite[" SQLiteCache<br/>• 数据库存储<br/>• 结构化数据<br/>• 复杂查询"]
        LRU[" LRUCache<br/>• LRU算法<br/>• 容量控制<br/>• 自动清理"]
    end

    subgraph " 网络层"
        Connect[" NetworkConnectivity<br/>• 网络检测<br/>• 状态监听<br/>• 类型识别"]
        Config[" HttpConfig<br/>• 配置管理<br/>• 参数设置<br/>• 环境切换"]
        Interceptors[" Interceptors<br/>• 拦截器链<br/>• 中间件<br/>• 请求处理"]
    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)

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

/// 缓存管理器 - 只负责缓存逻辑
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)

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

/// 缓存存储抽象接口
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)

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

class CacheManager {
  final CacheStorage _storage; // 依赖抽象

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

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

4. 接口隔离原则 (ISP)

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

/// 网络连接检测接口
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)

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

/// 高层模块：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 是整个框架的核心，采用单例模式，负责协调各个模块：

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. 缓存系统 - 多级缓存架构

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

/// 缓存策略枚举
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. 拦截器系统 - 可插拔的中间件

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

/// 基础拦截器抽象
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. 网络监控系统 - 性能分析

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

/// 网络监控器
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. 连接池管理

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. 请求去重

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. 智能缓存策略

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. 单元测试

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. 集成测试

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));
  });
}

性能基准测试

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

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. 插件化架构

/// 插件接口
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. 自适应优化

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

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

avatar
文章
阅读
粉丝