入门 Flutter 的旅程，是从跟着老师的教程一步步摸索开始的。其中最具挑战性的，莫过于环境配置与入门阶段。花费大量时间排查各类报错，反复重装开发环境，在项目前置准备上投入了诸多精力，却也在一次次解决问题中，慢慢摸清了基础配置的逻辑。

接着、我开始深入学习老师们的项目案例。拆解页面构建思路、方法选型与代码规范，在模仿中，逐步解锁 Flutter 的核心逻辑。随着学习的深入，我对 Flutter 的认知也变得清晰。从搭建基础页面框架、填充 UI 组件与交互细节，到最终对接后端 API，每一步都离不开海量资料的查阅与验证，也在反复试错与梳理中实现了稳步成长。

由衷感谢各位老师的悉心指导，也感谢优质的课程资源，让我有机会系统学习 Flutter 这门新技能，不仅充实了自我，更在实践中积累了宝贵的项目经验，为后续的技术探索打下了坚实基础。

以下就是对的这个项目作的一个技术上的总结。

一、项目概览

1.1 基础信息

项目维度	详情说明
项目名称	AtomGit 助手
技术栈	Flutter + 鸿蒙（跨平台开发）
架构模式	分层架构（表示层 / 业务逻辑层 / 数据层）+ MVVM 思想

二、系统架构设计

2.1 分层架构（高内聚、低耦合）

├── Presentation Layer (表示层)
│   ├── pages/          # 页面组件
│   └── widgets/        # 可复用UI组件
├── Business Logic Layer (业务逻辑层)
│   ├── controllers/    # 控制器
│   └── services/       # 业务服务
└── Data Layer (数据层)
    ├── core/           # 核心数据模型和API
    └── persistence/    # 本地持久化

2.2 组织架构

┌─────────────────────────────────────────────────────┐
│                  MaterialApp (根组件)                 │
├─────────────────────────────────────────────────────┤
│                  AuthWrapper (认证包装器)             │
│  ├── 未登录状态 → LoginPage                         │
│  └── 已登录状态 → MainNavigationPage                │
│       ├── HomePage (首页/搜索)                      │
│       ├── RepositoryPage (收藏管理)                  │
│       ├── WorkspacePage (工作空间)                   │
│       └── ProfilePage (个人资料)                     │
└─────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────┐
│                业务逻辑和数据流                       │
├─────────────────────────────────────────────────────┤
│  API请求层 ──┬── GitCodeApiClient (单例)            │
│             ├── 认证中间件                           │
│             └── 网络异常处理                         │
│                                                    │
│  状态管理层 ──┬── PaginationController (分页控制)   │
│             ├── Stream状态流                        │
│             └── 本地状态管理                         │
│                                                    │
│  持久化层 ────┬── SharedPreferences                 │
│             ├── AuthService (认证状态)              │
│             └── PersistenceStorage (用户数据)       │
└─────────────────────────────────────────────────────┘

三、核心技术栈与实现

3.1 基础框架

• UI 体系：基于 Material Design 3 实现响应式布局，适配多屏幕尺寸；
• 导航系统：通过Navigator管理页面栈，结合TabBar/BottomNavigationBar实现局部路由；
• 主题系统：自定义主题色、字体，保证跨平台视觉一致性。

3.2 状态管理方案

采用混合状态管理策略，兼顾轻量性与可维护性：

• 局部状态：通过setState管理页面内独立状态（如加载中 / 空状态）；
• 全局数据流：通过Stream + StreamController实现跨组件状态同步（如分页数据、错误信息）；
• 业务控制器：自定义PaginationController封装分页逻辑，RefreshController管理下拉刷新。

3.3 网络通信

基于http包实现标准化 API 请求流程：

• 单例模式：GitCodeApiClient全局唯一实例，避免重复初始化；
• Token 自动管理：请求前自动读取本地 Token，缺失时触发登录引导；
• 异常统一处理：封装超时、连接失败、状态码（401/500）等异常，返回标准化错误信息。

3.4 本地存储

基于鸿蒙适配版shared_preferences实现安全、隔离的本地数据管理：

• 数据类型：支持列表、字符串等结构化数据存储，自定义 JSON 序列化 / 反序列化；
• 安全保障：Token 加密存储，操作前强制校验登录状态。

四、核心业务流程

4.1 应用启动与认证流程

4.2 分页数据加载流程

4.3 收藏 / 关注操作流程

4.3 api请求认证流程

五、安全与数据管理

5.1 认证安全

• Token 存储：采用鸿蒙沙盒级shared_preferences存储，避免外部访问；
• Token 校验：每次 API 请求前验证 Token 有效性，401 状态时自动触发重新登录；
• 权限控制：未登录状态下禁止收藏 / 关注等操作，强制引导登录。

5.2 数据隔离策略

通过「用户名 + 业务标识」的存储键规则，实现多账号数据完全隔离：

业务场景	存储键示例
收藏仓库列表	zhangsan_starred_repositories
关注用户列表	zhangsan_followed_users

5.3 错误处理机制

构建三级错误处理体系，保证用户体验与系统稳定性：

1. 网络错误：捕获超时、连接失败，展示 “网络异常” 提示；
2. 业务错误：Token 无效、权限不足时，引导用户操作；
3. 数据错误：JSON 解析失败时，返回默认值避免页面崩溃。

六、页面功能详解

页面名称	核心功能	技术亮点
HomePage（搜索页）	仓库 / 用户双 Tab 搜索	实时搜索 + 分页加载 + 错误重试
RepositoryPage	收藏仓库 / 关注用户管理	侧滑删除 + 批量操作 + 本地同步
ProfilePage	个人信息 + 统计数据展示	多状态切换 + 可视化统计卡片
详情页（仓库 / 用户）	详情展示 + 收藏 / 关注操作	数据预加载 + 操作即时反馈

七、页面展示

             

             

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net