# boxes-android

**Repository Path**: sunlunchang/boxes-android

## Basic Information

- **Project Name**: boxes-android
- **Description**: Android开发基础框架
- **Primary Language**: Android
- **License**: MIT
- **Default Branch**: master-4.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2022-04-06
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# boxes-android 4.0

`boxes-android` 是一组可独立引用、支持 Java/Kotlin 的 Android 基础模块。框架采用
Flow-first MVVM、明确 owner 的资源管理、公开 Android/AndroidX API 和按职责拆分的
artifact。

## 基线

- minSdk 23
- compileSdk / targetSdk 37
- JDK/JVM 17
- AGP 9.3.0
- Gradle 9.6.1
- Kotlin 2.4.10（AGP 内置 Kotlin）
- 版本 4.0.1

所有依赖使用精确稳定版。

## 引入

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}
```

推荐按需选模块：

```kotlin
dependencies {
    implementation("com.gitee.sunlunchang.boxes-android:core:4.0.1")
    implementation("com.gitee.sunlunchang.boxes-android:android-util:4.0.1")
    implementation("com.gitee.sunlunchang.boxes-android:design:4.0.1")
}
```

确实需要大多数模块时可使用聚合制品：

```kotlin
implementation(
    "com.gitee.sunlunchang.boxes-android:boxes-android:4.0.1",
)
```

聚合制品不包含可选 `core-databinding`。

## 模块

| Artifact | 职责 | 项目技能 |
| --- | --- | --- |
| `core` | MVVM、Flow/LiveData、ViewBinding 页面、ViewModel 组件 | `boxes-android-core` |
| `core-databinding` | 可选 DataBinding 页面和 ObservableField | `boxes-android-core-databinding` |
| `android-util` | 通用 Java 与 Android 平台工具能力 | `boxes-android-util` |
| `adapter` | BRVAH4、RecyclerView、刷新分页、稳定键选择 | `boxes-android-adapter` |
| `popup` | Alert、Loading、BottomSheet、锚点弹层 | `boxes-android-popup` |
| `storage` | 类型化键值、文件文档、内存/磁盘缓存 | `boxes-android-storage` |
| `or` | Retrofit/OkHttp、结果模型、上传和下载 | `boxes-android-or` |
| `bar-plus` | Toolbar、MenuProvider、ActionProvider、Insets | `boxes-android-bar-plus` |
| `design` | Material 主题、公共资源、颜色和动画 | `boxes-android-design` |
| `boxes-android` | 八个常用模块的聚合 artifact | `boxes-android-all` |

每个技能位于 `.agents/skills/<技能名>`，入口只保留选型、工作流与边界：

- `references/usage.md`：按模块场景提供可直接采用的 Gradle、Manifest、XML、
  Kotlin 和 Java 用法。
- `references/api.md`：按包、资源和职责列出公共入口、关键方法族、生命周期及线程
  语义。
- `boxes-android-util/references/capabilities.md`：机器生成的完整工具能力目录。

## 仓库内部目录

以下目录参与开发和验证，但不是发布给应用的 artifact：

| 目录 | 作用 | 是否发布 |
| --- | --- | --- |
| `app` | 仓库内示例/集成应用，验证模块能在真实 Android Application 中组合 | 否 |
| `build-logic` | Gradle included build，提供 Android、发布、依赖与质量门禁约定插件 | 否 |
| `fixtures/java-consumer` | 直接消费源码模块，验证 Java 能看到并正确调用公共 API | 否 |
| `fixtures/kotlin-consumer` | 直接消费源码模块，验证 Kotlin API、扩展和内置 Kotlin 配置 | 否 |
| `fixtures/published-consumer` | 独立 Gradle 工程，只消费本地 Maven 发布物，验证 AAR、POM 和传递依赖 | 否 |

`build-logic` 会先编译成本次 Gradle 构建使用的插件 JAR，但不会进入任何模块 AAR
或 POM。两个根工程 fixture 会生成临时 Release AAR 作为编译验证结果，但没有应用
`maven-publish`，不会被发布；`published-consumer` 甚至不属于根工程的 `include`，
只由发布验证任务单独启动。

## 架构约定

- `core` 的 `StateFlow` 是持续状态唯一真源，`SharedFlow(replay = 0)` 表达瞬时
  事件；LiveData 是同源投影。
- ViewModel 不持有 Activity、Fragment、View、Binding 或 LifecycleOwner。
- Fragment Binding 和 UI 注册严格绑定 View 生命周期。
- 网络、存储、Popup、Toolbar 等有状态对象由真实 owner 持有和关闭。
- `android-util` 的 Android 无关包不导入平台 API；平台能力显式接收 Context、
  Window、View 或 LifecycleOwner。
- Cache 允许丢失，不能替代可靠持久化。
- 不使用全局可变 Retrofit、Popup、ViewModelStore、EventBus 或隐式 Application
  Provider。

## android-util desugaring

直接或间接使用 `android-util` 的 minSdk 23 消费项目应启用：

```kotlin
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    coreLibraryDesugaring(
        "com.android.tools:desugar_jdk_libs:2.1.5",
    )
}
```

## 本地发布验证

```bash
./gradlew qualityGate
```

门禁检查稳定依赖、模块边界、能力目录、中文注释、Lint、Release AAR、二进制 API、
本地 Maven POM 以及隔离的 Java/Kotlin 消费工程，不执行远程发布。

JitPack 使用仓库根目录 `jitpack.yml` 中的 JDK 17 配置构建 tag。