Repository navigation
代码优化:提升安全性、性能和可维护性 #86
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,222 @@ | ||
| # 代码优化说明 | ||
|
|
||
| 本次优化基于代码审查,按照优先级实施了以下改进: | ||
|
|
||
| ## 🔴 高优先级优化 | ||
|
|
||
| ### 1. API Key 加密存储(安全性) | ||
|
|
||
| **问题**: API Key 以明文形式存储在配置文件中,存在安全风险。 | ||
|
|
||
| **解决方案**: | ||
| - 引入 `flutter_secure_storage: ^10.3.1` 依赖 | ||
| - 创建 `SecureStorageService` 类用于加密存储敏感信息 | ||
| - 使用平台原生加密能力(Android KeyStore / iOS Keychain) | ||
|
|
||
| **文件**: | ||
| - `lib/core/services/secure_storage_service.dart` | ||
|
|
||
| **使用示例**: | ||
| ```dart | ||
| final storage = SecureStorageService(); | ||
| await storage.saveApiKey('provider-id', 'sk-xxx'); | ||
| final apiKey = await storage.readApiKey('provider-id'); | ||
| ``` | ||
|
|
||
| ### 2. 错误处理改进(用户体验) | ||
|
|
||
| **问题**: 返回 `null` 时丢失错误信息,用户无法知道失败原因。 | ||
|
|
||
| **解决方案**: | ||
| - 创建 `AiResult<T>` 类型,使用 Sealed Classes 实现 Result 模式 | ||
| - 明确区分 `AiSuccess` 和 `AiFailure` 状态 | ||
| - 保留错误码和错误信息供上层处理 | ||
|
|
||
| **文件**: | ||
| - `lib/core/models/ai_result.dart` | ||
|
|
||
| **使用示例**: | ||
| ```dart | ||
| final result = await generateStructuredNote(...); | ||
| result.fold( | ||
| onSuccess: (data) => print('成功: $data'), | ||
| onFailure: (error, code) => print('失败: $error (code: $code)'), | ||
| ); | ||
| ``` | ||
|
|
||
| ### 3. 路径安全验证(安全性) | ||
|
|
||
| **问题**: 文件写入操作缺少路径验证,可能存在路径遍历漏洞。 | ||
|
|
||
| **解决方案**: | ||
| - 创建 `PathValidator` 工具类 | ||
| - 验证文件扩展名、防止路径遍历攻击 | ||
| - 在 `NoteService` 的读写操作中添加安全检查 | ||
|
|
||
| **文件**: | ||
| - `lib/core/utils/path_validator.dart` | ||
| - 更新 `lib/core/services/note_service.dart` | ||
|
|
||
| **安全功能**: | ||
| - ✅ 路径遍历检测(`../` 等) | ||
| - ✅ 文件扩展名白名单验证 | ||
| - ✅ 路径规范化检查 | ||
| - ✅ 危险字符过滤 | ||
|
|
||
| ## 🟡 中优先级优化 | ||
|
|
||
| ### 4. 文件 I/O 性能优化 | ||
|
|
||
| **问题**: `listMarkdownFiles` 方法串行读取文件,在文件较多时性能差。 | ||
|
|
||
| **解决方案**: | ||
| - 使用 `Future.wait()` 并行读取所有文件 | ||
| - 减少总耗时,提升用户体验 | ||
|
|
||
| **改进位置**: | ||
| - `lib/core/services/note_service.dart` 中的 `listMarkdownFiles` 方法 | ||
|
|
||
| **性能对比**: | ||
| ``` | ||
| 串行: 10 个文件 × 50ms = 500ms | ||
| 并行: max(50ms) ≈ 50ms (提升 10 倍) | ||
| ``` | ||
|
|
||
| ### 5. Service 层抽象化 | ||
|
|
||
| **问题**: Service 类都是具体实现,难以测试和替换。 | ||
|
|
||
| **解决方案**: | ||
| - 定义 `INoteService` 接口 | ||
| - `NoteService` 实现该接口 | ||
| - 便于编写 Mock 进行单元测试 | ||
|
|
||
| **文件**: | ||
| - `lib/core/services/note_service_interface.dart` | ||
| - 更新 `lib/core/services/note_service.dart` | ||
|
|
||
| ### 6. 消除魔法字符串 | ||
|
|
||
| **问题**: 模型配置键名散落在代码各处,易出错且难维护。 | ||
|
|
||
| **解决方案**: | ||
| - 创建 `ModelKeys` 常量类统一管理 | ||
| - 所有模型键通过常量引用 | ||
|
|
||
| **文件**: | ||
| - `lib/core/constants/model_keys.dart` | ||
|
|
||
| **使用方式**: | ||
| ```dart | ||
| // 之前 | ||
| config.defaultModels['intelligentGenerationModel'] | ||
|
|
||
| // 之后 | ||
| config.defaultModels[ModelKeys.intelligentGeneration] | ||
| ``` | ||
|
|
||
| ## 🟢 低优先级优化(后续) | ||
|
|
||
| 以下优化项规划在后续迭代中实施: | ||
|
|
||
| - [ ] 依赖注入统一管理(引入 get_it) | ||
| - [ ] 状态管理方案(Riverpod) | ||
| - [ ] 单元测试覆盖 | ||
| - [ ] 图片压缩优化 | ||
| - [ ] 注释标准化 | ||
| - [ ] CI/CD 流程完善 | ||
|
|
||
| ## 📊 优化效果预期 | ||
|
|
||
| | 维度 | 改进 | | ||
| |------|------| | ||
| | **安全性** | ⭐⭐⭐⭐⭐ API Key 加密 + 路径验证 | | ||
| | **可维护性** | ⭐⭐⭐⭐ 接口抽象 + 常量管理 | | ||
| | **用户体验** | ⭐⭐⭐⭐ 错误信息明确 | | ||
| | **性能** | ⭐⭐⭐ 文件并行读取 | | ||
|
|
||
| ## 📝 迁移指南 | ||
|
|
||
| ### 现有代码兼容性 | ||
|
|
||
| 所有优化都采用**非破坏性**方式: | ||
| - ✅ 新增文件,不删除旧代码 | ||
| - ✅ `NoteService` 实现保持向后兼容 | ||
| - ✅ 新功能通过新接口暴露 | ||
|
|
||
| ### 使用新特性的建议步骤 | ||
|
|
||
| 1. **逐步迁移 API Key 存储** | ||
| ```dart | ||
| // 从配置文件迁移到安全存储 | ||
| final storage = SecureStorageService(); | ||
| for (var provider in config.providers) { | ||
| await storage.saveApiKey(provider.id, provider.apiKey); | ||
| } | ||
| ``` | ||
|
|
||
| 2. **采用 Result 模式处理错误** | ||
| ```dart | ||
| // 在新代码中使用 AiResult | ||
| AiResult<String> generateReport() async { | ||
| try { | ||
| final result = await service.generate(); | ||
| return AiSuccess(result); | ||
| } catch (e) { | ||
| return AiFailure(error: e.toString()); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 3. **测试时使用接口** | ||
| ```dart | ||
| // 编写单元测试 | ||
| class MockNoteService implements INoteService { | ||
| @override | ||
| Future<List<NoteFile>> listMarkdownFiles(...) async { | ||
| return [/* mock data */]; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## 🔧 技术细节 | ||
|
|
||
| ### 依赖变更 | ||
| ```yaml | ||
| # pubspec.yaml | ||
| dependencies: | ||
| flutter_secure_storage: ^10.3.1 # 新增 | ||
| flutter_rust_bridge: ^2.12.0 # 放宽版本限制 | ||
| ``` | ||
|
|
||
| ### 代码统计 | ||
| - 新增文件: 5 个 | ||
| - 修改文件: 2 个 | ||
| - 新增代码行数: ~400 行 | ||
| - 破坏性变更: 0 | ||
|
|
||
| ## ⚠️ 注意事项 | ||
|
|
||
| 1. **flutter_secure_storage 权限** | ||
| - Android 需要 `minSdkVersion >= 18` | ||
| - iOS 需要 Keychain 访问权限(已默认包含) | ||
|
|
||
| 2. **路径验证的影响** | ||
| - 非 `.md` 文件的读写会抛出异常 | ||
| - 包含 `..` 的路径会被拒绝 | ||
| - 确保所有路径操作都在预期目录内 | ||
|
|
||
| 3. **并行 I/O 的考虑** | ||
| - 大量文件(100+)时可能需要限制并发数 | ||
| - 建议后续添加分批处理逻辑 | ||
|
|
||
| ## 📚 参考资料 | ||
|
|
||
| - [Flutter Secure Storage](https://pub.dev/packages/flutter_secure_storage) | ||
| - [Dart Result Pattern](https://dart.dev/language/pattern-types#sealed-types) | ||
| - [OWASP Path Traversal](https://owasp.org/www-community/attacks/Path_Traversal) | ||
|
|
||
| --- | ||
|
|
||
| **优化完成时间**: 2026-07-15 | ||
| **优化作者**: Claude (Kiro AI Development Environment) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| /// 模型配置键常量 | ||
| /// | ||
| /// 统一管理所有模型配置的键名,避免字符串散落在代码中 | ||
| class ModelKeys { | ||
| ModelKeys._(); | ||
|
|
||
| /// 智能生成模型(用于日报生成、结构化笔记等) | ||
| static const String intelligentGeneration = 'intelligentGenerationModel'; | ||
|
|
||
| /// 回忆书模型(用于历史记录检索和对话) | ||
| static const String memoryBook = 'memoryBookModel'; | ||
|
|
||
| /// 编辑补全模型(用于 Markdown 编辑时的 AI 补全) | ||
| static const String editCompletion = 'editCompletionModel'; | ||
|
|
||
| /// 所有支持的模型键列表 | ||
| static const List<String> allKeys = [ | ||
| intelligentGeneration, | ||
| memoryBook, | ||
| editCompletion, | ||
| ]; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| /// AI 操作结果的统一封装 | ||
| /// | ||
| /// 使用 Result 模式替代返回 null,明确区分成功和失败情况 | ||
| sealed class AiResult<T> { | ||
| const AiResult(); | ||
|
|
||
| /// 操作成功 | ||
| bool get isSuccess => this is AiSuccess<T>; | ||
|
|
||
| /// 操作失败 | ||
| bool get isFailure => this is AiFailure<T>; | ||
|
|
||
| /// 获取成功结果(如果失败则返回 null) | ||
| T? get dataOrNull => switch (this) { | ||
| AiSuccess(data: final data) => data, | ||
| AiFailure() => null, | ||
| }; | ||
|
|
||
| /// 获取错误信息(如果成功则返回 null) | ||
| String? get errorOrNull => switch (this) { | ||
| AiSuccess() => null, | ||
| AiFailure(error: final error) => error, | ||
| }; | ||
|
|
||
| /// 转换成功结果 | ||
| AiResult<R> map<R>(R Function(T data) transform) { | ||
| return switch (this) { | ||
| AiSuccess(data: final data) => AiSuccess(transform(data)), | ||
| AiFailure(error: final error, code: final code) => | ||
| AiFailure(error: error, code: code), | ||
| }; | ||
| } | ||
|
|
||
| /// 处理结果 | ||
| R fold<R>({ | ||
| required R Function(T data) onSuccess, | ||
| required R Function(String error, String? code) onFailure, | ||
| }) { | ||
| return switch (this) { | ||
| AiSuccess(data: final data) => onSuccess(data), | ||
| AiFailure(error: final error, code: final code) => onFailure(error, code), | ||
| }; | ||
| } | ||
| } | ||
|
|
||
| /// 成功结果 | ||
| final class AiSuccess<T> extends AiResult<T> { | ||
| const AiSuccess(this.data); | ||
|
|
||
| final T data; | ||
|
|
||
| @override | ||
| String toString() => 'AiSuccess(data: $data)'; | ||
|
|
||
| @override | ||
| bool operator ==(Object other) => | ||
| identical(this, other) || | ||
| other is AiSuccess<T> && | ||
| runtimeType == other.runtimeType && | ||
| data == other.data; | ||
|
|
||
| @override | ||
| int get hashCode => data.hashCode; | ||
| } | ||
|
|
||
| /// 失败结果 | ||
| final class AiFailure<T> extends AiResult<T> { | ||
| const AiFailure({ | ||
| required this.error, | ||
| this.code, | ||
| }); | ||
|
|
||
| /// 错误信息 | ||
| final String error; | ||
|
|
||
| /// 错误代码(可选) | ||
| final String? code; | ||
|
|
||
| @override | ||
| String toString() => 'AiFailure(error: $error, code: $code)'; | ||
|
|
||
| @override | ||
| bool operator ==(Object other) => | ||
| identical(this, other) || | ||
| other is AiFailure<T> && | ||
| runtimeType == other.runtimeType && | ||
| error == other.error && | ||
| code == other.code; | ||
|
|
||
| @override | ||
| int get hashCode => Object.hash(error, code); | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
这个文档建议本地gitignore了
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ok