# BaseMVI

**Repository Path**: blesslp/base-mvi

## Basic Information

- **Project Name**: BaseMVI
- **Description**: 安卓compose mvi脚手架,封装了大量提升开发速度的功能,迭代中
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BaseMVI Android 快速开发框架

BaseMVI 是一个面向真实业务开发的 Android 模板项目，目标是把常见基础能力沉淀为可复用模块：MVI 状态管理、统一网络请求、登录态、分页、Compose UI 状态页、模块化导航、主题切换、多语言、图片/权限/媒体/埋点等。

README 只保留快速入口。详细说明请进入 [`docs/`](docs/)。

## 依赖
```agsl
dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
				google()
				mavenCentral()
				mavenLocal() // 本地验证时使用
				maven { url = uri("https://your-maven-repository/repository/releases/") }
			}
}
```

## 发布与本地验证

发布全部 core 模块到 Maven Local：

```bash
./gradlew publishCoreToMavenLocal
```

其他项目添加 `mavenLocal()` 后可引用，例如：

```kotlin
implementation("com.gitee.blesslp.base-mvi:ui:v0.1.3")
```

发布到私服时，通过环境变量或 `~/.gradle/gradle.properties` 提供地址和凭据，再执行 `./gradlew publish`：

```properties
PUBLISH_REPOSITORY_URL=https://your-maven-repository/repository/releases/
PUBLISH_USERNAME=your-username
PUBLISH_PASSWORD=your-password
```

使用 `core:ui` 的 `provider` 需要在消费者模块开启 Compose；Compose runtime 会随 `ui` 的 Maven 元数据自动解析。

```agsl
dependencies {
    implementation("com.gitee.blesslp.base-mvi:mvi:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:ui:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:analytics:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:i18n:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:storage:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:permission:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:network:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:image:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:common:v0.1.3")
    implementation("com.gitee.blesslp.base-mvi:media:v0.1.3")
}
```

## 这个项目解决什么问题

- 新业务模块可以用脚本快速创建，并自动生成 MVI + Hilt + Navigation 基础结构。
- feature 页面不需要层层传递 `NavController` 或 callback，统一使用 `AppNavigator`。
- Repository 统一返回 `Flow<LoadState<T>>`，普通网络与缓存网络只通过策略区分。
- raw API、统一响应壳、业务错误、登录失效、分页等接口场景都有固定写法。
- UI 侧通过 `LoadState`、`PagingState` 和通用 Compose 组件减少重复样板代码。

## 技术栈

| 能力 | 技术 |
|---|---|
| UI | Jetpack Compose、Material3、ViewBinding 基类 |
| 架构 | Kotlin、Coroutine、Flow、MVI |
| 依赖注入 | Hilt |
| 导航 | Navigation Compose + `AppNavigator` |
| 网络 | Retrofit、OkHttp、kotlinx.serialization |
| 本地存储 | MMKV + Store 抽象 |
| 多语言 | `core:i18n` + 资源生成脚本 |
| 构建 | Gradle Kotlin DSL、JDK 17 |

## 模块地图

| 模块 | 职责 | 详细文档 |
|---|---|---|
| `:app` | 应用入口、Hilt 汇总、NavHost、主题/语言入口 | [Architecture](docs/ARCHITECTURE.md) |
| `:core:common` | Dispatcher、日志、Flow 扩展、通用工具 | [Architecture](docs/ARCHITECTURE.md) |
| `:core:mvi` | MVI 契约、ViewModel 基类、请求守卫、加载/分页状态 | [MVI](docs/MVI.md) |
| `:core:network` | Retrofit/OkHttp、ApiFlow、协议解析、登录态、缓存 | [Network](docs/NETWORK.md) |
| `:core:ui` | Compose 基础组件、主题、状态页、导航抽象 | [UI](docs/UI.md)、[Navigation](docs/NAVIGATION.md) |
| `:core:storage` | Store、MMKVStore、MemoryStore | [Architecture](docs/ARCHITECTURE.md) |
| `:core:i18n` | 多语言消息、运行时切换、资源生成 | [I18N](docs/I18N.md) |
| `:feature:sample` | MVI、网络、存储、权限、媒体、埋点等示例 | [Create Feature](docs/CREATE_FEATURE.md) |
| `:feature:gallery` | raw API、分页、详情页、带参导航示例 | [Network Cookbook](docs/cookbook/NETWORK.md) |

## 5 分钟跑起来

### 环境要求

- Android Studio 最新稳定版或兼容版本。
- JDK 17。
- Android SDK：项目当前 `compileSdk = 36`，`minSdk = 23`。

### 本地运行

```bash
./gradlew :app:assembleDebug
```

也可以直接在 Android Studio 中打开项目，选择 `app` configuration 运行。

更多环境、命令与常见启动问题见 [Getting Started](docs/GETTING_STARTED.md)。

## 10 分钟新增一个 feature

```bash
scripts/new_feature.sh --name user
```

脚本会生成：

- `feature/user/build.gradle.kts`
- MVI 的 `State / Intent / Effect / ViewModel`
- `UserRoutes` 与内置 provider 的路由声明
- Hilt `AppRouteGraph` 注册模块

然后按脚本提示把模块接入 `app/build.gradle.kts`：

```kotlin
implementation(project(":feature:user"))
```

也可以使用 Gradle Task：

```bash
./gradlew createFeature -Pname=user
```

完整流程见 [Create Feature](docs/CREATE_FEATURE.md)。

## 10 分钟新增一个 screen

```bash
scripts/new_screen.sh --feature user --screen userDetail
```

脚本会在已有 feature 中生成新的 Compose Route，并提示你到该 feature 的 `Routes.kt` 中补充带 `provider = { ... }` 的 route 声明。

无参数页面使用：

```kotlin
val Detail = route("user/detail") {
    provider = { _ -> UserDetailRoute() }
}
```

单字符串参数页面使用：

```kotlin
val Detail = route("user/detail/{userId}", string("userId")) {
    provider = { args -> UserDetailRoute(userId = args.getString("userId")) }
}
```

更多路由写法见 [Navigation](docs/NAVIGATION.md) 与 [Navigation Cookbook](docs/cookbook/NAVIGATION.md)。

## 最常用能力入口

| 我要做什么 | 看这里 |
|---|---|
| 第一次运行项目 | [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) |
| 理解项目结构与依赖边界 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| 让 AI agent 按架构开发 | [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) |
| 新增 feature / screen | [docs/CREATE_FEATURE.md](docs/CREATE_FEATURE.md) |
| 写 MVI 页面 | [docs/MVI.md](docs/MVI.md) |
| 页面跳转、传参、返回结果 | [docs/cookbook/NAVIGATION.md](docs/cookbook/NAVIGATION.md) |
| 理解导航架构 | [docs/NAVIGATION.md](docs/NAVIGATION.md) |
| 接真实接口 | [docs/cookbook/NETWORK.md](docs/cookbook/NETWORK.md) |
| 理解网络层设计 | [docs/NETWORK.md](docs/NETWORK.md) |
| 接分页接口 | [docs/cookbook/NETWORK.md#8-分页接口](docs/cookbook/NETWORK.md#8-分页接口) |
| 做主题/深色模式 | [docs/UI.md](docs/UI.md) |
| 做多语言 | [docs/I18N.md](docs/I18N.md) |
| 遇到问题 | [docs/FAQ.md](docs/FAQ.md) |
| 长期规划 | [docs/ROADMAP.md](docs/ROADMAP.md) |

## Cookbook

### 导航 Cookbook

[docs/cookbook/NAVIGATION.md](docs/cookbook/NAVIGATION.md) 覆盖：

- 普通跳转
- 带参跳转
- 返回上一页
- 返回到指定页面
- 返回带结果
- 单例跳转
- 清栈跳转
- 登录拦截
- 跨 feature 跳转约定

### 网络 Cookbook

[docs/cookbook/NETWORK.md](docs/cookbook/NETWORK.md) 覆盖：

- raw API：接口直接返回业务数据
- 统一响应壳：`ApiEnvelope<T>`
- 非标准响应壳：`BusinessResponseAdapter`
- 业务错误
- 登录失效
- Token 注入与刷新
- 分页接口
- 网络缓存

## 常用命令

```bash
# 编译 debug 包
./gradlew :app:assembleDebug

# 运行单元测试
./gradlew test

# 创建 feature
./gradlew createFeature -Pname=user

# 创建 screen
./gradlew createScreen -Pfeature=user -Pscreen=userDetail

# 生成/更新多语言资源
./gradlew generateI18n
```


## AI agent 开发入口

如果你要让 AI agent 在本仓库自动开发业务，请先要求它阅读：

1. [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md)：开发流程、分层约束、标准模板、检查清单。
2. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)：模块职责与依赖边界。
3. [docs/MVI.md](docs/MVI.md)、[docs/NAVIGATION.md](docs/NAVIGATION.md)、[docs/NETWORK.md](docs/NETWORK.md)：业务开发三条主线。

推荐提示词：

```text
请先阅读 README.md 和 docs/AGENT_GUIDE.md，再按 BaseMVI 架构新增功能。
要求：Repository 返回 Flow<LoadState<T>>，ViewModel 使用 MVI 归约状态，UI 只消费 State，导航使用 AppNavigator，完成后运行测试/编译并汇报结果。
```

## 最短代码链路

Repository 返回统一网络结果：

```kotlin
class UserRepository @Inject constructor(
    private val api: UserApi,
    private val apiFlow: ApiFlow
) {
    fun users(): Flow<LoadState<List<UserDto>>> {
        return apiFlow.rawFlow { api.getUsers() }
    }
}
```

ViewModel 收集到页面状态：

```kotlin
loadToState(
    request = repository.users(),
    updateState = { newState -> copy(usersState = newState) }
)
```

页面中发起导航：

```kotlin
val appNavigator = LocalAppNavigator.current
appNavigator.navigate(UserRoutes.Detail, userId)
```

## 维护约定

- README 只写上手路径与链接，不再恢复为 API 大全。
- 新增框架能力时，同步更新对应专题文档与 Cookbook。
- 文档示例必须对齐当前源码，不写不存在的方法名或已淘汰写法。
- feature 页面优先依赖 `AppNavigator`，不要把 App 层导航实现泄漏到业务 UI。
- Repository 负责协议接入和 DTO 转换，ViewModel 负责状态归约，UI 只消费 State。