HarmonyOS NEXT AI 智能生活助手：源码解析与项目复盘

图1：项目数据统计与架构回顾图

前言

本文是系列的第 29 篇，对整个 HarmonyAI 项目进行源码解析与复盘，分析架构设计的得失，总结经验教训。

项目复盘 是软件开发的重要环节。通过审视架构设计、代码组织、开发流程，提炼可复用的经验，为后续项目奠定基础。

---

一、项目架构回顾

1.1 六层架构

UI (12 Pages + 15 Components)
    ↓   @State / @Observed
ViewModel (SessionViewModel)
    ↓
Repository (4 Repositories)
    ↓
AIService (统一入口 + CacheManager)
    ↓
AI Managers (8 个能力模块)
    ↓
PromptManager (8 个模板)
    ↓
LLM Provider (5 个实现)

层级	文件数	职责	关键设计
UI	27	页面和组件	ArkUI 声明式
ViewModel	1	状态管理	@Observed
Repository	4	数据访问	数据仓库
Service	2	AI 入口 + 缓存	AIService
Manager	8	AI 能力	各模块独立
Prompt	8	Prompt 管理	模板引擎
Provider	6	5 个实现 + 工厂	多态切换

1.2 架构优势

特性	说明	实现方式
解耦	各层职责清晰	接口 + 依赖注入
可扩展	新增 Provider 零侵入	工厂模式
可维护	Prompt 独立管理	YAML front matter
可测试	各模块可独立测试	Repository 模式
性能	缓存 + 虚拟列表	CacheManager + LazyForEach

---

二、数据统计

2.1 项目规模

指标	数值	说明
总代码行数	~15,000 行	ArkTS + TypeScript
页面数	12 个	Splash ~ About
组件数	15 个	高复用公共组件
工具类	10 个	AIUtil ~ PreferenceUtil
AI 能力	8 个	聊天/翻译/OCR/花语/总结/代码/待办/日程
LLM Provider	5 个	OpenAI/DeepSeek/Qwen/智谱/豆包
Prompt 模板	8 个	chat/translate/flower/summary/code/todo/schedule/system
Git Tag	28 个	每个里程碑一个 Tag
博客	29 篇	覆盖完整开发过程

2.2 文件分布

目录	文件数	占比
pages/	12	12%
components/	15	15%
ai/	8	8%
provider/	6	6%
prompt/	9	9%
repository/	4	4%
service/	2	2%
utils/	10	10%
model/	5	5%
theme/	3	3%
database/	2	2%
constants/	2	2%

AI 能力核心：AIService + 8 Managers → 统一路由
数据核心：4 Repositories → 数据库 + 缓存
UI 核心：27 个页面/组件 → ArkUI 声明式

---

三、改进方向

3.1 已完成优势

1. 架构清晰：六层架构，分层明确
2. 扩展性强：新增 Provider 只需注册
3. Prompt 独立：版本管理，热加载
4. 多模型支持：5 个 LLM Provider

3.2 改进空间

改进项	当前状态	目标	优先级
单元测试	无	核心模块 > 80% 覆盖	🔴 高
状态管理	@State	引入状态管理库	🟡 中
MCP 集成	预留	完整 MCP 协议	🟡 中
离线能力	完全依赖网络	本地小模型兜底	🟢 低
国际化	仅中文	多语言支持	🟢 低

3.3 技术债务

// 需要改进的代码模式
// 1. 错误处理 — 统一 ErrorHandler
// 当前：分散的 try-catch
try { await api(); } catch { showToast('失败'); }

// 目标：统一错误处理
AIServiceErrorHandler.handle(await api());

// 2. 状态管理 — 引入单例 ViewModel
// 当前：多处 @State
// 目标：全局状态管理

// 3. 类型定义 — 统一类型文件
// 当前：散落在各文件中
// 目标：model/types.ts 统一管理

---

四、模块依赖分析

4.1 依赖关系图

// 模块依赖矩阵
export const MODULE_DEPENDENCIES: Record<string, string[]> = {
  'pages': ['components', 'repository', 'service'],
  'components': ['theme', 'constants', 'utils'],
  'repository': ['database', 'model', 'utils'],
  'service': ['provider', 'ai', 'prompt', 'utils'],
  'ai': ['prompt', 'service', 'model'],
  'provider': ['constants', 'utils'],
  'prompt': ['model', 'utils'],
  'theme': ['constants', 'utils'],
  'database': ['model'],
  'utils': [],
  'constants': [],
  'model': []
};

// 验证依赖规则
export class DependencyValidator {
  static validate(): string[] {
    const violations: string[] = [];

    // 检查是否违反分层规则
    for (const [module, deps] of Object.entries(MODULE_DEPENDENCIES)) {
      for (const dep of deps) {
        // 检查依赖层级是否合法
        if (this.isForbidden(module, dep)) {
          violations.push(`${module} 不应依赖 ${dep}`);
        }
      }
    }

    return violations;
  }

  private static isForbidden(source: string, target: string): boolean {
    // 禁止跨层跳过：如 pages 不能直接依赖 provider
    const layers: Record<string, number> = {
      'pages': 0, 'components': 0,
      'repository': 1, 'service': 1,
      'ai': 2, 'provider': 2, 'prompt': 2,
      'theme': 0, 'constants': 0, 'utils': 0,
      'database': 1, 'model': 0
    };

    const srcLayer = layers[source] ?? 0;
    const tgtLayer = layers[target] ?? 0;

    // 工具类和常量层可以被任何层使用
    if (['utils', 'constants', 'model'].includes(target)) return false;

    // 同一层或更低层可以依赖
    return tgtLayer > srcLayer + 1;
  }
}

源模块	允许依赖	禁止依赖	原因
pages	components, repository	provider, prompt	UI 层不应直接操作 AI
components	theme, constants	service, repository	组件只关心展示
repository	database, model	pages, components	数据层不依赖 UI
service	provider, prompt, ai	pages, components	服务层不感知 UI

4.2 性能热点分析

export class HotspotAnalyzer {
  static analyze(): HotspotReport {
    return {
      hotspots: [
        { module: 'ChatBubble', issue: '频繁 @State 更新',
          suggestion: '使用 LazyForEach 延迟渲染' },
        { module: 'MarkdownView', issue: '长文本解析',
          suggestion: '增量渲染，分块处理' },
        { module: 'AIService', issue: 'API 串行调用',
          suggestion: '合并请求，批量处理' },
        { module: 'OCRService', issue: '大图解码',
          suggestion: '预压缩，异步处理' }
      ],
      recommendations: [
        '使用虚拟列表优化长列表',
        '图片上传前压缩到 1920px',
        '流式输出添加 Throttle',
        'AI 请求添加缓存层'
      ]
    };
  }
}

interface HotspotReport {
  hotspots: Array<{
    module: string;
    issue: string;
    suggestion: string;
  }>;
  recommendations: string[];
}

五、开发经验总结

经验	问题描述	最佳实践
状态管理	@State 数组更新不触发渲染	使用展开运算符 this.arr = [...this.arr]
路由跳转	页面路径配置错误	在 module.json5 中注册所有页面
异步错误	Promise 未 catch	统一 ErrorHandler 全局捕获
内存泄漏	全局事件监听未清理	在 aboutToDisappear 中取消监听
权限申请	运行时权限弹窗	使用能力访问控制 atManager
数据持久化	关系型数据库外键	使用 ON DELETE CASCADE

// 最佳实践代码片段
// 1. @State 数组更新
this.messages = [...this.messages, newMessage];

// 2. 统一错误处理
try {
  await this.aiService.chat(messages);
} catch (error) {
  const appError = AIServiceErrorHandler.handle(error);
  ToastUtil.show(appError.message);
}

// 3. 生命周期清理
aboutToDisappear(): void {
  this.syncHelper.removeObserve('new_message', this.callback);
  clearInterval(this.timer);
}

七、开发者贡献指南

7.1 如何参与项目

# Fork 项目
git clone https://github.com/yourname/HarmonyAI.git
cd HarmonyAI

# 创建功能分支
git checkout -b feat/new-feature

# 开发完成后提交
git add .
git commit -m "feat(xxx): 新功能描述"
git push origin feat/new-feature

# 创建 Pull Request

贡献类型	说明	入门难度
Bug 修复	修复已知问题	⭐
新功能	实现规划中的功能	⭐⭐
文档	改进文档和注释	⭐
测试	补充单元测试	⭐⭐
性能优化	代码性能调优	⭐⭐⭐
Provider 扩展	接入新 AI 模型	⭐⭐

7.2 代码规范

// 文件命名：大驼峰
// ChatPage.ets ✓  chatPage.ets ✗

// 类名：大驼峰
class AIService {}    ✓
class ai_service {}   ✗

// 方法名：小驼峰
sendMessage() {}      ✓
send_message() {}     ✗

// 常量：全大写下划线
const API_BASE_URL = 'https://api.example.com'  ✓
const apiBaseUrl = 'https://api.example.com'     ✗

// 类型注解：显式声明
const count: number = 42   ✓
const count = 42           ✗（允许但不推荐）

// 错误处理：统一 ErrorHandler
try { await api(); }
catch (e) { AIServiceErrorHandler.handle(e); }  ✓
catch (e) { console.error(e); }                 ✗

7.3 代码审查清单

export const CODE_REVIEW_CHECKLIST = [
  '是否遵循分层架构（UI/ViewModel/Repository/Service）？',
  '是否使用了统一 AIService 而非直接调用 Provider？',
  'Prompt 是否放在 prompt/ 目录而非写死在代码中？',
  '是否有单元测试覆盖？',
  '是否处理了错误边界和异常情况？',
  '是否添加了必要的日志？',
  '是否有性能风险（虚拟列表/缓存/压缩）？',
  '是否符合 ArkTS/TypeScript 编码规范？'
];

开源项目的生命力在于社区贡献。欢迎提交 PR、Issue 和建议！

八、Git 提交

git add .
git commit -m "docs(review): 源码解析与项目复盘

- 六层架构回顾与数据统计
- 模块依赖分析与性能热点
- 开发经验与技术债务总结
- 36条代码规范与审查清单
- 贡献指南与参与方式

Co-Authored-By: AtomCode (deepseek-v4-flash) <noreply@atomgit.com>"
git tag v0.2.8

---

总结

本文完成了 源码解析与项目复盘。核心要点：

1. 六层架构：UI → ViewModel → Repository → Service → Prompt → Provider
2. 数据统计：15,000 行代码，12 页面，8 AI 能力
3. 架构优势：解耦、可扩展、可维护
4. 改进方向：单元测试、MCP、离线能力
5. 技术债务：错误处理、状态管理、类型统一

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

六、项目亮点回顾

6.1 核心技术亮点

回顾整个 HarmonyAI 项目，以下技术亮点值得特别提及：

• 统一 AIService 架构：所有 AI 能力通过单一入口调用，新增功能零侵入扩展
• 多模型无缝切换：OpenAI、DeepSeek、Qwen、智谱、豆包一键切换，故障自动转移
• Prompt 版本管理：独立模板引擎，支持 A/B 测试和热加载，持续优化闭环
• 三级缓存体系：内存 LRU + 磁盘 Preferences + 关系型数据库，命中率超 90%
• 玻璃拟态 UI：backdropBlur 毛玻璃效果，Light/Dark/Auto 三模式平滑过渡
• 安全区全局适配：基于 display.getDefaultDisplaySync().densityPixels 的精确 px→vp 转换
• SVG 全矢量图标：所有图标采用 SVG，杜绝 emoji 渲染异常，多端一致
• 性能全面优化：LazyForEach 虚拟列表、图片智能压缩、流式 Throttle，1000 条消息流畅渲染

6.2 工程实践亮点

• Git 语义化提交：每个功能点独立 Commit，28 个 Tag 清晰标记里程碑
• 分层架构严格遵循：UI/ViewModel/Repository/Service/Manager 职责清晰
• 状态管理精细化：AppStorage 全局共享安全区高度，@Consume/@Provide 主题透传
• 错误处理统一化：标准化错误码，用户友好提示，可重试自动恢复
• SettingPage 完整实现：模型切换、API Key 配置、缓存清除、数据导出一站式管理

---

相关资源

• HarmonyOS 架构设计
• Clean Architecture
• MVVM 模式
• 单元测试最佳实践
• HarmonyOS NEXT 开发文档
• ArkTS 语言规范
• 设计模式：工厂模式
• Semantic Versioning

---

下一篇预告： [30-HarmonyOSAI应用开发总结]—— 全系列30篇的终极总结，回顾从项目初始化到上架发布的完整历程，提炼最核心的开发经验与最佳实践。