# learnApp

**Repository Path**: me_angle/learn-app

## Basic Information

- **Project Name**: learnApp
- **Description**: No description available
- **Primary Language**: Kotlin
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# baseapp - Android 组件化 MVVM 敏捷开发脚手架

[![Kotlin](https://img.shields.io/badge/Kotlin-1.8.0-blue.svg)](https://kotlinlang.org)
[![AGP](https://img.shields.io/badge/AGP-8.0.0-green.svg)](https://developer.android.com/studio/releases/gradle-plugin)
[![TheRouter](https://img.shields.io/badge/TheRouter-1.2.2-orange.svg)](https://therouter.cn/)
[![Architecture](https://img.shields.io/badge/Architecture-MVVM%20%2B%20Modularization-purple.svg)](https://developer.android.com/jetpack/guide)

## 📖 项目简介 (Introduction)

**baseapp** 是一个专为 Android 开发者打造的现代化、组件化开发脚手架。
本项目旨在提供一个**架构清晰**、**规范严谨**且**易于扩展**的工程模板。它剥离了复杂的业务逻辑，保留了核心的架构骨架，非常适合作为新项目的启动模板，或用于学习 Android 主流开发技术栈。

### 核心亮点
- **组件化架构**: 采用标准的 `app` + `feature` + `core` 分层设计，模块解耦，支持独立调试（需配置）。
- **TheRouter 路由**: 替换了传统的 ARouter，使用更现代的 [TheRouter](https://therouter.cn/) 进行页面跳转和模块间通信，支持 **KSP** 增量编译，构建速度更快。
- **Jetpack MVVM**: 严格遵循 Google 推荐的 MVVM 模式，利用 `ViewModel` + `LiveData` + `Coroutines` 处理数据流。
- **UI 规范**: 回归经典的 **XML + ViewBinding/DataBinding**，封装了 `BaseActivity`/`BaseFragment`/`BaseAdapter`，极大减少样板代码。
- **网络层封装**: 基于 Retrofit + OkHttp，内置了 **MockInterceptor**，无需后端接口即可跑通完整业务流程，支持离线开发。
- **详细注释**: 核心代码覆盖了详细的中文注释，解释“为什么要这么写”，不仅仅是代码堆砌。

---

## 🛠 技术栈 (Tech Stack)

| 维度 | 技术选型 | 说明 |
| :--- | :--- | :--- |
| **语言** | Kotlin | 100% Kotlin 代码 |
| **构建系统** | Gradle + KSP | 使用 KSP 替代 KAPT 提升编译速度 |
| **架构模式** | MVVM | Model-View-ViewModel |
| **模块化** | Componentization | 业务模块解耦 |
| **路由导航** | **TheRouter** | 阿里/货拉拉技术团队开源的路由框架，支持 AGP8 |
| **UI 视图** | ViewBinding + DataBinding | 安全高效的视图绑定 |
| **异步处理** | Coroutines + Flow | 协程处理异步任务 |
| **网络请求** | Retrofit 2 + OkHttp 3 | 网络栈标准组合 |
| **数据解析** | Gson | JSON 解析 |
| **生命周期** | Lifecycle | 感知组件生命周期 |

---

## 📂 工程结构 (Project Structure)

项目采用清晰的三层架构：

```
baseapp
├── app/                    # [壳工程] 负责应用初始化、多模块打包集成
│   └── MyApplication.kt    # TheRouter 初始化、全局配置
│
├── feature/                # [业务功能层] 按业务划分模块
│   ├── auth/               # 登录注册模块 (LoginActivity, LoginViewModel)
│   └── home/               # 首页模块 (HomeActivity, HomeRepository)
│
├── core/                   # [核心基础层] 通用能力封装
│   ├── common/             # 通用工具、常量、Result<T> 状态封装
│   ├── model/              # 全局数据实体 (User, BaseResponse)
│   ├── network/            # 网络栈 (RetrofitClient, MockInterceptor)
│   └── ui/                 # UI 基础组件 (BaseActivity, BaseViewModel, BaseAdapter)
│
├── build.gradle            # 全局构建配置 (依赖版本管理)
└── settings.gradle         # 模块包含配置
```

---

## 🚀 核心功能与实现细节

### 1. 路由与模块通信 (TheRouter)
本项目使用 **TheRouter**（替代 ARouter）。
- **页面跳转**:
  ```kotlin
  // 定义路径 (RoutePath.kt)
  const val AUTH_LOGIN = "/auth/login"

  // 标记页面
  @Route(path = RoutePath.AUTH_LOGIN)
  class LoginActivity : BaseActivity<...>()

  // 发起跳转
  TheRouter.build(RoutePath.AUTH_LOGIN).navigation()
  ```
- **依赖注入**: 支持跨模块的服务调用（如从 Home 模块获取 User 信息）。

### 2. 网络请求与 Mock 数据
为了方便演示和独立开发，网络层 (`core/network`) 内置了 **MockInterceptor**。
- **机制**: 拦截器会检查请求 URL，如果匹配（如 `/auth/login`），则拦截请求并直接返回本地预定义的 JSON 字符串，模拟真实网络延时（1.5s）。
- **切换真实环境**: 只需在 `RetrofitClient.kt` 中注释掉 `.addInterceptor(mockInterceptor)` 并修改 `BASE_URL` 即可。

### 3. UI 基础封装 (`core/ui`)
- **BaseActivity<VB>**: 利用 Kotlin 泛型反射/委托，自动完成 `ViewBinding` 的 `inflate`，无需手动 `setContentView`。
- **BaseViewModel**: 内置 `isLoading` (Loading状态) 和 `toastMessage` (提示消息) 的 LiveData，配合 BaseActivity 自动处理 Loading 弹窗和 Toast 显示。

---

## 📚 学习指南 (Learning Guide)

如果你是初学者，建议按照以下路径阅读源码：

### 第一阶段：基础稳固 (Core Layer)
1.  **UI 封装**: 阅读 `core/ui/BaseActivity.kt`。
    - *思考*: 如何利用泛型 `<VB : ViewBinding>` 避免每个 Activity 都写重复的绑定代码？
2.  **网络封装**: 阅读 `core/network/RetrofitClient.kt`。
    - *思考*: 单例模式 (`object`) 在这里的好处是什么？Mock 拦截器是如何工作的？

### 第二阶段：业务流转 (Feature Layer)
1.  **MVVM 数据流**: 打开 `feature/auth/LoginActivity.kt` 和 `LoginViewModel.kt`。
    - *观察*: `View` (Activity) 如何通过 `observe` 监听 `ViewModel` 的数据变化？
    - *观察*: `ViewModel` 如何通过 `viewModelScope` 启动协程，处理 `Repository` 返回的 `Result<T>`？
2.  **列表处理**: 打开 `feature/home/HomeActivity.kt` 和 `HomeAdapter.kt`。
    - *学习*: 如何封装 `BaseRecyclerAdapter` 实现通用的列表展示？DataBinding 在 Item 中是如何使用的？

### 第三阶段：组件化实战
1.  **路由集成**: 观察 `app/build.gradle` 和各模块的 `build.gradle`。
    - *学习*: 如何引入 `ksp "cn.therouter:apt:..."`？
    - *实践*: 尝试新建一个 `feature:profile` 模块，并通过 TheRouter 从首页跳转过去。

---

## 🏃‍♂️ 快速开始 (How to Run)

1.  **环境准备**:
    - Android Studio Flamingo 或更高版本 (推荐 Iguana/Jellyfish)。
    - JDK 17 (AGP 8.0+ 要求)。
2.  **克隆项目**:
    ```bash
    git clone https://github.com/your-repo/baseapp.git
    ```
3.  **构建**:
    - 打开 Android Studio，等待 Gradle Sync 完成。
    - 运行 `:app` 模块。
4.  **体验**:
    - 启动后进入登录页，输入任意非空账号密码即可登录。
    - 首页展示 Mock 的列表数据。

---

## 📝 版本记录

- **v1.1.0 (Current)**
  - ⚡ 路由框架调整：ARouter -> **TheRouter**。
  - 🛠 升级构建工具：KAPT -> **KSP**，AGP 8.0。
  - 🐛 修复首页列表 DataBinding 绑定问题。
  - 🎨 补充 UI 资源颜色定义。

- **v1.0.0**
  - 项目初始化，搭建 MVVM + 组件化基础骨架。

---

## 🤝 贡献与反馈
欢迎提交 Issue 或 Pull Request。如果你觉得这个项目对你有帮助，请给一个 ⭐️ Star！