Flutter 前端代码结构优化

1.1 问题分析

在之前的代码评测中，发现了以下主要问题：

1.2 优化目标

1. 代码仓库结构的进一步优化 - 创建清晰的目录结构
2. 在不影响功能的情况下优化业务逻辑 - 提供更好的使用体验
3. 修复明显 bug 和不合理的地方 - 代码质量提升

关键约束: 仅优化代码结构，不改变任何业务逻辑和功能

2.1 分阶段优化策略

经过分析，决定采用分阶段、低风险的优化策略：

1
Phase 1: 基础设施 - 创建常量和服务层
2
Phase 2: 延后 - AppState 拆分风险太高
3
Phase 3: 缓存优化 - 创建 LRU 缓存
4
Phase 4: 日志系统 - 统一日志管理
5
Phase 5: 代码清理 - 清理冗余代码
6
Phase 6: 集成应用 - 将新组件应用到现有代码

2.2 决策取舍

3.1 Phase 1: 常量管理

1
lib/core/
2
├── constants/           # 新建
3
│   ├── app_constants.dart
4
│   └── storage_keys.dart
5
├── services/
6
│   └── storage_service.dart  # 新建
7
└── utils/
8
    ├── thumbnail_memory_cache.dart  # 新建
9
    ├── simple_lru_cache.dart        # 新建
10
    └── app_logger.dart              # 新建

class AppConstants {
  AppConstants._();  // 私有构造函数，防止实例化
 
  // ===================== 分页 =====================
  static const int messagePageSize = 50;
  static const int filePageSize = 100;
 
  // ===================== 缓存 =====================
  static const int thumbnailMemoryCacheMaxSize = 100;
  static const int imagePreviewCacheMaxSize = 10;
 
  // ===================== 并发 =====================
  static const int defaultUploadConcurrency = 3;
  static const int defaultDownloadConcurrency = 3;
 
  // ===================== 超时 =====================
  static const Duration apiConnectTimeout = Duration(seconds: 3);
  static const Duration healthCheckInterval = Duration(seconds: 15);
  // ...
}

class StorageKeys {
  StorageKeys._();
 
  // 核心配置
  static const String coreMode = 'core_mode';
  static const String coreBaseUrl = 'core_base_url';
 
  // 动态键名生成
  static String videoPosition(String fileId) => 'video_position_$fileId';
}

3.2 Phase 2: StorageService

class StorageService {
  static final StorageService _instance = StorageService._internal();
  factory StorageService() => _instance;
  StorageService._internal();
 
  SharedPreferences? _prefs;
 
  Future<void> init() async {
    _prefs ??= await SharedPreferences.getInstance();
  }
 
  // 类型安全的访问方法
  Future<ThemeMode> getThemeMode() async {
    final value = _prefs?.getString(StorageKeys.themeMode);
    switch (value) {
      case 'light': return ThemeMode.light;
      case 'dark': return ThemeMode.dark;
      default: return ThemeMode.system;
    }
  }
}

设计要点:

• 单例模式，懒加载初始化
• 类型安全的 getter/setter
• 内部处理空值和默认值

3.3 Phase 3: ThumbnailMemoryCache (LRU)

class ThumbnailMemoryCache {
  static final ThumbnailMemoryCache _instance = ThumbnailMemoryCache._internal();
  factory ThumbnailMemoryCache() => _instance;
  ThumbnailMemoryCache._internal();
 
  final Map<String, Uint8List> _cache = {};
  final Set<String> _loading = {};
 
  int get maxSize => AppConstants.thumbnailMemoryCacheMaxSize;
 
  /// 获取缓存（LRU：访问时移到最近位置）
  Uint8List? get(String fileId) {
    final data = _cache[fileId];
    if (data != null) {
      // 移到最近使用位置（先删除再添加）
      _cache.remove(fileId);
      _cache[fileId] = data;
    }
    return data;
  }
 
  /// 添加到缓存（LRU：超过容量时移除最老的）
  void put(String fileId, Uint8List data) {
    _cache.remove(fileId);  // 如果已存在，先移除
 
    // 检查容量，移除最久未使用的项
    while (_cache.length >= maxSize) {
      _cache.remove(_cache.keys.first);
    }
 
    _cache[fileId] = data;
    _loading.remove(fileId);
  }
}

LRU 算法实现:

• 利用 Dart Map 的 LinkedHashMap 特性（默认实现）
• 访问时删除再添加，保持顺序
• 超出容量时，keys.first 是最老的项

3.4 Phase 4: AppLogger

enum LogLevel { debug, info, warning, error }
 
class AppLogger {
  AppLogger._();
 
  static bool _enabled = kDebugMode;  // 仅 debug 模式启用
  static LogLevel _minLevel = LogLevel.debug;
 
  static void d(String tag, String message) {
    _log(LogLevel.debug, tag, message);
  }
 
  static void e(String tag, String message, [Object? error, StackTrace? stackTrace]) {
    _log(LogLevel.error, tag, message);
    if (error != null) debugPrint('  Error: $error');
    if (stackTrace != null) debugPrint('  Stack: $stackTrace');
  }
 
  static void _log(LogLevel level, String tag, String message) {
    if (!_enabled || level.index < _minLevel.index) return;
 
    final prefix = _levelPrefix(level);
    final timestamp = DateTime.now().toIso8601String().substring(11, 23);
    debugPrint('$prefix [$timestamp] [$tag] $message');
  }
}

设计要点:

• 级别过滤，可动态调整
• 时间戳便于追踪
• tag 分类便于筛选

4.1 文件创建顺序

1. lib/core/constants/app_constants.dart (92 行)
2. lib/core/constants/storage_keys.dart (101 行)
3. lib/core/services/storage_service.dart (359 行)
4. lib/core/utils/thumbnail_memory_cache.dart (95 行)
5. lib/core/utils/app_logger.dart (77 行)
6. lib/core/utils/simple_lru_cache.dart (59 行)

4.2 代码替换

// Before
debugPrint('[VideoThumbnail] Error: $e');
 
// After
AppLogger.e('VideoThumbnail', '[VideoThumbnail] Error: $e');

// Before
final Map<String, Uint8List?> _thumbnailCache = {};
final cached = _thumbnailCache[fileId];
_thumbnailCache[fileId] = thumbData;
 
// After
final ThumbnailMemoryCache _thumbnailCache = ThumbnailMemoryCache();
final cached = _thumbnailCache.get(fileId);
_thumbnailCache.put(fileId, thumbData);

// Before (手动 LRU)
static const int _maxCacheSize = 10;
final Map<String, Uint8List> _imageCache = {};
final List<String> _cacheAccessOrder = [];
 
void _addToCache(String id, Uint8List data) {
  _cacheAccessOrder.remove(id);
  _cacheAccessOrder.add(id);
  _imageCache[id] = data;
  while (_cacheAccessOrder.length > _maxCacheSize) {
    final oldestId = _cacheAccessOrder.removeAt(0);
    _imageCache.remove(oldestId);
  }
}
 
// After (使用统一 LRU)
final ThumbnailMemoryCache _imageCache = ThumbnailMemoryCache();
 
void _addToCache(String id, Uint8List data) {
  _imageCache.put(id, data);
}

4.3 冗余 import 清理

清理的 import:

• lib/core/services/file_operation_service.dart - 删除 file_metadata.dart
• lib/main.dart - 删除 api_client.dart
• lib/ui/chat_page.dart - 删除 file_metadata.dart
• lib/ui/file_search_page.dart - 删除 api_client.dart
• lib/ui/files_page.dart - 删除 api_client.dart
• lib/ui/image_preview_page.dart - 删除 file_metadata.dart
• lib/ui/pdf_preview_page.dart - 删除 file_metadata.dart
• lib/ui/text_editor_page.dart - 删除 file_metadata.dart
• lib/ui/unsupported_preview_page.dart - 删除 file_metadata.dart
• lib/ui/video_player_page.dart - 删除 file_metadata.dart

原因: 这些类型已通过 app_state.dart 的 export 导出

4.4 dangling_library_doc_comments 修复

涉及文件:

• lib/core/api/api_client.dart - 删除 library api_client;
• lib/core/models/send_progress.dart - /// 改为 //
• lib/core/models/transfer_types.dart - /// 改为 //
• lib/core/state/transfer_jobs.dart - /// 改为 //
• lib/ui/widgets/chat_exports.dart - /// 改为 //

原因: 文件顶部的 /// 文档注释没有对应的 library 声明，导致 Flutter 分析器警告

5.1 ThumbnailCacheAdapter 实现困难

问题: 尝试创建实现 Map<String, Uint8List?> 接口的适配器，需要实现所有 Map 方法。

复杂度:

• operator []
• operator []=
• containsKey
• forEach
• map
• update
• updateAll
• entries
• 等 20+ 个方法

解决方案: 放弃通用适配器，直接修改使用缓存的组件。

5.2 SendMessage import 误删

问题: 在清理 image_preview_page.dart 的 import 时，误删了 send_message.dart，导致 SendMessage 类型未定义。

症状:

1
Undefined class 'SendMessage'.

解决: 重新添加必要的 import。

教训: 清理 import 时要先检查文件是否使用了该模块中的其他类型。

5.3 PlatformException 类型丢失

问题: 清理 video_thumbnail_service.dart 中的 flutter/foundation.dart import 时，误删了 flutter/services.dart。

症状:

1
The name 'PlatformException' isn't a type and can't be used in an on-catch clause.
2
The name 'MissingPluginException' isn't a type and can't be used in an on-catch clause.

原因: PlatformException 和 MissingPluginException 来自 flutter/services.dart。

解决: 重新添加 flutter/services.dart import。

教训: flutter analyze 的 info 级别提示不一定要修复，有些 import 看似冗余但实际有用。

6.1 新增文件

6.2 修改的文件

6.3 验证结果

$ flutter analyze
Analyzing client...
 
   info - The import of 'package:flutter/foundation.dart' is unnecessary...
   info - The import of '../../core/models/file_metadata.dart' is unnecessary...
   info - The import of '../../core/api/api_client.dart' is unnecessary...
 
3 issues found. (ran in 4.2s)

结果: 只有 info 级别提示，无错误和警告。

7.1 可选优化

• 将现有代码中的 SharedPreferences 调用迁移到 StorageService
• 将 files_page.dart 的缩略图缓存也改为 ThumbnailMemoryCache
• 完成剩余 3 处 info 级别 import 的清理

7.2 延后任务

• AppState 拆分为多个 Provider（需要独立规划）
• 使用 Selector 替代 Consumer 精确订阅（需要评估收益）