快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• build.gradle
• gradle.properties
• gradlew
• app/src/main/AndroidManifest.xml
• app/build.gradle
• lib_room/build.gradle
• mod_demo/build.gradle
• mod_main/build.gradle
• mod_user/build.gradle

SumTea_Android 是一个基于组件化、模块化架构设计的 WanAndroid 客户端，采用 Kotlin 语言结合 Jetpack 组件构建 MVVM 架构模式。该项目集成了协程、Flow、Retrofit、Room 等主流技术栈，并实现了短视频播放功能，适合作为学习大型 Android 项目架构的参考案例 README.md:1-20。

项目简介与环境要求

技术栈概览

项目采用 Kotlin 作为主要开发语言，结合 Jetpack 组件（Navigation、Lifecycle、DataBinding、LiveData、ViewModel）搭建 MVVM 架构。通过组件化和模块化拆分实现解耦，使用 ARouter 实现模块间通信。网络层采用协程 + Flow + Retrofit + OkHttp 组合，数据缓存通过 mmkv 和 Room 数据库管理，视频播放使用谷歌 ExoPlayer 实现 README.md:13-19。

开发环境配置

项目基于 Gradle 7.2.2 版本构建，使用 Kotlin 1.6.10。根目录的 build.gradle 文件定义了项目级插件版本配置 build.gradle:9-14：

groovy
1plugins {
2    id 'com.android.application' version '7.2.2' apply false
3    id 'com.android.library' version '7.2.2' apply false
4    id 'org.jetbrains.kotlin.android' version '1.6.10' apply false
5}

Gradle 配置参数

gradle.properties 文件包含关键的构建配置参数 gradle.properties:9-26：

系统要求

必需环境：

• JDK 8 或更高版本（建议 JDK 11）
• Android Studio Arctic Fox (2020.3.1) 或更高版本
• Android SDK API 31+（根据项目配置）
• Gradle 7.2.2（项目已包含 Gradle Wrapper）

可选依赖：

• Charles 抓包工具（用于网络调试）README.md:95
• Git 版本控制工具

快速运行步骤

克隆项目

通过 Git 克隆项目到本地：

bash
1git clone https://github.com/suming77/SumTea_Android.git
2cd SumTea_Android

导入项目

1. 打开 Android Studio
2. 选择 File -> Open
3. 导航到克隆的项目目录并选择根目录下的 build.gradle 文件
4. 等待 Gradle 同步完成

运行项目

项目提供了两种运行方式：

方式一：直接安装 APK

项目仓库中包含可直接安装的 APK 文件，无需编译即可体验完整功能 README.md:139。

方式二：通过 Android Studio 运行

1. 连接 Android 设备或启动模拟器
2. 在 Android Studio 中点击 Run -> Run 'app' 或使用快捷键 Shift + F10
3. 等待编译安装完成

启动流程验证

应用启动后，首先进入 SplashActivity 启动页，该 Activity 配置为单任务模式并使用独立主题 app/src/main/AndroidManifest.xml:26-37：

xml
1<activity
2    android:name="com.sum.main.ui.SplashActivity"
3    android:launchMode="singleTask"
4    android:theme="@style/SplashAppTheme"
5    android:exported="true">
6    <intent-filter>
7        <action android:name="android.intent.action.MAIN" />
8        <category android:name="android.intent.category.LAUNCHER" />
9    </intent-filter>
10</activity>

启动页完成后跳转至 MainActivity 主界面，该界面同样配置为单任务模式并强制竖屏显示 app/src/main/AndroidManifest.xml:38-43。

项目结构概览

模块化架构设计

项目采用组件化 + 模块化架构，通过分层设计实现高内聚低耦合。整体架构遵循 MVVM 模式，ViewModel 负责数据存储，Repository 负责数据加载，通过 Room 数据库实现数据缓存 README.md:21-24。

正在加载图表渲染器...

核心功能模块

APP 壳工程：包含 Application 类、打包环境配置、签名配置、混淆规则、业务模块集成及 APP 主题配置 README.md:28-30。

mod_main 主模块：包含首页、分类、体系、我的四个 Tab，通过 Navigation 实现管理。首页包含 Banner 轮播图、视频列表、项目文章列表；分类 Tab 包含各网站文章分类内容；体系 Tab 包含知识体系文章分类；我的 Tab 包含个人信息和服务栏 README.md:31-36。

mod_user 用户模块：提供个人设置页面、账户安全、个人信息编辑（头像、姓名、手机号码）、隐私政策条款、版本信息查看、App 更新、缓存清理及用户退出登录功能 README.md:37-43。

mod_login 登录模块：实现登录页面、隐私政策展示、其他登录方式选择及用户注册功能 README.md:44-47。

mod_search 搜索模块：提供搜索页面、用户搜索历史数据及搜索推荐数据功能 README.md:48-51。

mod_video 视频模块：使用 RecyclerView 实现仿抖音短视频列表，保证全局只有一个播放器；通过 ExoPlayer 实现视频播放；包含 RotateNoteView 旋转音乐盒组件 README.md:52-55。

基础库层

lib_framework：包含 Base 基类、扩展函数、Loading 加载框、LogUtil 日志工具、Manager 管理类、TipsToast 吐司工具、Utils 工具类及带删除按钮的 EditText README.md:56-64。

lib_common：提供二次封装的 Banner 组件、常量类、实体 Bean、组件化通信的 provider 和 IService、通用 View README.md:65-70。

lib_network：封装 Api 接口类、错误处理类、Flow 扩展类、网络请求封装、Http 拦截器、BaseViewModel 和 BaseRepository 协程网络请求封装、OkHttp 和 Retrofit 封装 README.md:71-78。

lib_room：Room 数据库相关实现，主要用于视频列表缓存 README.md:87-89。

运行验证

验证应用启动

成功安装后，应用图标将出现在设备启动器中。点击图标启动应用，应看到 Splash 启动页，随后进入主界面。主界面底部显示四个 Tab：首页、分类、体系、我的 README.md:32。

验证核心功能

首页验证：检查 Banner 轮播图是否正常显示，视频列表和项目文章列表是否可正常滑动加载 README.md:33。

网络请求验证：通过 Charles 抓包工具检查网络请求是否正常，API 基地址应为 WanAndroid 官方域名 README.md:95。

视频播放验证：进入视频 Tab，检查短视频列表是否正常加载，点击视频是否能够播放，确保全局只有一个播放器实例 README.md:53-54。

权限检查

应用需要以下权限才能正常运行 app/src/main/AndroidManifest.xml:6-14：

常见问题与排错

Gradle 同步失败

问题：导入项目时 Gradle 同步失败，提示插件版本不兼容。

解决方案：

1. 检查 JDK 版本是否为 8 或更高
2. 确认 Android Studio 版本支持 Gradle 7.2.2
3. 清理 Gradle 缓存：./gradlew clean build.gradle:16-18
4. 删除项目根目录下的 .gradle 文件夹和 .idea 文件夹后重新导入

网络请求失败

问题：应用启动后无法加载数据，网络请求超时或失败。

解决方案：

1. 检查设备网络连接状态
2. 确认应用已获得 INTERNET 权限 app/src/main/AndroidManifest.xml:6
3. 检查网络安全配置 network_security_config app/src/main/AndroidManifest.xml:24
4. 使用 Charles 抓包检查 API 请求是否正常发出 README.md:95

编译错误：Kotlin 版本不匹配

问题：编译时报错 Kotlin 版本与 Gradle 插件版本不兼容。

解决方案： 项目使用 Kotlin 1.6.10 版本 build.gradle:12，确保：

1. Android Studio 中配置的 Kotlin 插件版本与项目一致
2. 检查 gradle.properties 中的 kotlin.code.style=official 配置 gradle.properties:19
3. 如需更新 Kotlin 版本，同步修改 build.gradle 中的版本号

模块间通信失败

问题：使用 ARouter 进行模块间跳转失败。

解决方案：

1. 确认 ARouter 注解正确配置
2. 检查模块间的 IService 接口定义 README.md:69
3. 清理项目后重新编译：Build -> Clean Project 然后 Build -> Rebuild Project

视频播放异常

问题：短视频无法播放或播放卡顿。

解决方案：

1. 检查 ExoPlayer 是否正确初始化 README.md:54
2. 确认视频 URL 可访问
3. 检查 Room 数据库缓存是否正常工作 README.md:89
4. 查看日志输出，定位具体错误信息 README.md:60

下一步建议

完成快速上手后，建议按以下路径深入学习：

架构设计：深入研究 MVVM 架构模式的实现细节，了解 ViewModel 与 Repository 的职责划分，以及 Room 数据库的缓存策略 README.md:23。

Jetpack 组件：学习 Navigation 导航设计、Lifecycle 生命周期机制、ViewModel 配置变更复用原理、LiveData 数据观察机制以及 ViewBinding 与 DataBinding 的使用 README.md:105-118。

Kotlin 协程：掌握协程的概念和原理、挂起函数、Flow 与 Channel 的高级用法，以及协程的底层状态机实现 README.md:120-127。

性能优化：学习应用启动速度优化、内存优化策略、图片和 Bitmap 优化等进阶主题 README.md:129-136。

组件化实践：理解如何通过组件化和模块化实现项目解耦，以及 ARouter 在模块间通信中的应用 README.md:14。