GameBoosterProject 开发文档

GameBoosterProject 开发文档

1. 项目目标

当前项目已完成基础架构搭建，采用 MVVM 模式，并封装了基于 Android 原生能力的网络请求框架（HttpURLConnection），用于后续业务快速扩展。

---

2. 架构设计

采用经典分层架构：presentation -> domain -> data -> core。

2.1 presentation（表现层）

• 负责 UI 展示与用户交互（Jetpack Compose）。
• 通过ViewModel管理页面状态，避免将业务逻辑写入 UI。
• 当前示例：
  • HomeScreen.kt
  • HomeViewModel.kt
  • HomeUiState.kt
  • TodoUserMessageMapper.kt

2.2 domain（领域层）

• 定义核心业务模型与业务规则。
• 不依赖 Android 具体实现，便于测试与复用。
• 当前示例：
  • Todo.kt（领域实体）
  • TodoRepository.kt（仓库接口）
  • GetTodoUseCase.kt（业务用例）

2.3 data（数据层）

• 负责远程/本地数据的获取与转换。
• 实现domain层定义的仓库接口。
• 当前示例：
  • TodoDao.kt（本地缓存查询接口）
  • AppDatabase.kt（Room 数据库入口）
  • TodoEntity.kt（本地缓存实体）
  • TodoLocalMapper.kt（本地/远端模型映射）
  • TodoApiService.kt（远程接口封装）
  • TodoRemoteDataSource.kt（远端数据源抽象）
  • TodoDto.kt（数据传输对象）
  • TodoRepositoryImpl.kt（仓库实现）

2.4 core（基础能力层）

• 提供通用能力：网络、依赖注入、通用模型。
• 当前示例：
  • HttpClient.kt（原生网络请求封装）
  • HttpRequest.kt（单次请求快照、HttpInterceptor、HttpLogger声明）
  • NetworkResult.kt（统一结果模型）
  • NetworkException.kt（统一异常模型）
  • ServiceLocator.kt（轻量依赖注入）

---

3. MVVM 调用链路

页面点击请求后的完整链路如下：

1. HomeScreen触发加载、重试或切换编号事件
2. HomeViewModel.loadTodo()
3. 调用GetTodoUseCase
4. 调用TodoRepository接口
5. TodoRepositoryImpl先请求远端数据源，再决定写入/读取 Room 缓存
6. TodoApiService使用HttpClient发起网络请求
7. 成功时写入 Room；失败时尝试回退本地缓存
8. 返回NetworkResult给 ViewModel
9. ViewModel 更新HomeUiState，UI 自动响应渲染

---

4. 原生网络框架说明

4.1 设计目标

• 不依赖 Retrofit/OkHttp，采用系统原生HttpURLConnection。
• 统一网络成功/失败模型，减少业务层try-catch嵌套。
• 支持协程与 IO 线程切换，避免阻塞主线程。

4.2 核心能力

• HTTP 方法：get/post/put/delete/patch；带 body 的方法支持可选请求体与bodyContentType（默认application/json; charset=UTF-8）。
• Query / Header：各方法支持queryParams: Map<String, String>?与headers: Map<String, String>?；URL 已含?时用&追加参数，且保证#fragment不被破坏。
• 连接头顺序（与HttpURLConnection设置顺序一致）：先Accept: application/json，若有请求体再Content-Type，最后应用业务headers（可覆盖前述默认值）。
• 拦截器：构造HttpClient时传入List<HttpInterceptor>；请求前将调用参数收拢为HttpRequest，经各拦截器依次intercept后再真正发起连接，便于注入 Token、公共 Query 等。
• 调试日志：可选HttpLogger；若注入，会打印合并后的请求信息与响应（敏感头Authorization、Cookie打码；响应体过长时截断）。ServiceLocator在Debug构建（BuildConfig.DEBUG）下默认注入基于android.util.Log的实现。