fragmject：一个为 Kotlin 与 Compose 初学者准备的完整上手项目

为什么存在这个项目

fragmject 的诞生源于一个具体痛点：Kotlin 初学者学习时，书籍和视频偏重知识点讲解，缺少完整的项目实操。而开源项目往往业务复杂、封装层层，不适合直接上手。作者因此创建了这个项目，目标是用官方推荐的写法，实现一个功能完备、符合主流市场标准的应用。它面向的是那些已经知道 Kotlin 语法、但不知道如何组织一个真实 Android 项目的人。项目刻意避免复杂业务和多余封装，所有代码都尽量贴近 Android Developer 官方文档的风格。

技术栈与架构：MVVM/MVI 混合，多模块组织

项目采用 Kotlin 2.4.x 与 Compose，架构上混合使用 MVVM 和 MVI，模块划分为 core、feature 和 app 三层。app 是壳工程，包含唯一 Activity（WanActivity.kt）、Application（WanApplication.kt，作为 Hilt 入口）以及导航图（WanNavGraph.kt）。core 模块存放设计系统等公共部分，feature 模块承载具体功能。依赖注入使用 Hilt，数据库使用 Room 3，网络层是 Retrofit 和 OkHttp，构建系统采用 Gradle Kotlin DSL、Version Catalog 和 Convention Plugins。这种结构对初学者来说，既能看到实际项目的模块划分，又不至于陷入过度抽象。

大屏自适应：WindowSizeClass 与 List-Detail 同屏

项目基于 material3-window-size-class 实现了完整的自适应布局。布局策略根据窗口宽度分为三档：Compact（小于 600dp）使用底部导航栏 NavigationBar，详情全屏推入；Medium（600 到 840dp）使用左侧导航 NavigationDrawerItem 加 Surface，详情仍全屏推入；Expanded（大于等于 840dp，常见于平板横屏或桌面）使用常驻侧栏 PermanentNavigationDrawer，并且点击列表项时不再全屏跳转，而是在右侧面板渲染详情。这个右侧面板称为 DetailPane，它承载 WebScreen、UserScreen、SettingScreen 等页面。实现上，LocalWindowSizeClass.kt 通过 CompositionLocal 注入窗口大小类，WanNavGraph.kt 在 Expanded 模式下拦截 NavKey 并将其传递给 DetailPane，MainScreen.kt 负责三态布局分发和 DetailPane 路由。使用方式很直接：读取 LocalWindowSizeClass.current，然后根据 widthSizeClass 分支到不同布局。这个设计对学习大屏适配很有参考价值。

导航：Navigation 3 的类型安全与同屏切换

项目采用 Navigation 3，这是 Android 新推出的导航库，支持类型安全导航。WanNavGraph.kt 定义了导航图，在 Expanded 模式下，点击文章、用户主页、设置等条目时，不是启动新的目的地，而是将 NavKey 传递给 DetailPane，实现列表与详情的同屏显示。mermaid 图展示了数据流：列表（占 50% 宽度）指向 DetailPane（占 50%），DetailPane 再根据内容渲染 WebScreen、UserScreen 或 SettingScreen。这种模式避免了传统导航中频繁的页面切换，也减少了状态丢失。初学者可以从中理解 Navigation 3 的核心概念，比如 NavBackStack 和 NavDisplay。不过，Navigation 3 在 2021 年还比较新，API 可能与当前稳定版有差异，阅读时需要留意版本。

刻意少用第三方库：自己实现，学习更多

项目 README 明确解释了为什么很少依赖其他库。作者日常开发推荐使用 Hilt、Paging 等库，认为它们能提高效率和减少 bug。但对初学者来说，过早依赖第三方库有两个危害：一是增加学习负担，第三方库用起来简单但底层复杂，阅读源码容易打击积极性；二是造成基础薄弱，初学者容易把第三方库能力当成自己的能力，脱离库后开发能力下降。因此，fragmject 尽量自己实现常见功能，比如 SharedFlowBus，一个用 30 行代码实现的消息总线，基于 SharedFlow 实现普通消息和粘性消息的发送与订阅。还有字节码插桩的 library-plugin，用于替换目标字段或方法，作者写有隐私合规相关的文章。这种取舍是双刃剑：一方面能让学习者深入理解底层机制，另一方面也意味着代码可能不如成熟库健壮，比如 SharedFlowBus 的 tryEmit 可能丢失消息，需要使用者自己评估。

运行与构建：环境要求与版本目录

要运行 fragmject，你需要先更新 Android Studio，README 提到可能需要梯子。项目使用 Gradle Kotlin DSL 和 Version Catalog，版本信息集中在 gradle/libs.versions.toml。如果你遇到构建问题，可以自行配置 AGP 和 Compose 版本以适应你的环境。项目还提供了迁移到版本目录的官方文档链接。下载体验方面，仓库有一个 APK 链接（wan-release-1.6.0-free.apk），但注意这个版本号与仓库最新 release v1.1.0 不一致，可能是历史产物，实际以 release 为准。项目默认分支是 master，最近一次推送是 2021 年 8 月 15 日，之后没有更新，这意味着依赖版本较老。如果你使用新版 Android Studio，可能需要手动升级 AGP 和 Compose 编译器。

维护状态与升级成本

fragmject 的最近一次 release 是 v1.1.0，发布于 2021 年 8 月 15 日，之后仓库没有新的推送。项目未被归档，但处于停滞状态。这意味着它不会跟随 Android 生态的更新，比如 Kotlin 2.4.x 可能已经不是当前版本，Navigation 3 的 API 也可能发生变化。对于学习项目来说，这不一定是个问题，因为核心概念仍然有效。但如果你想把它作为新项目的基础，需要自行承担升级依赖的成本。许可证是 Apache-2.0，允许自由使用和修改，只要保留版权声明。

替代方案：官方示例与第三方模板

与 fragmject 类似的资源包括 Android 官方的 Now in Android 示例应用，它同样使用 Kotlin、Compose、Hilt、Room 等，但代码更贴近生产实践，而且持续维护。另一个替代是各类 Compose 教程项目，比如 Jetpack Compose 官方示例仓库。区别在于：fragmject 刻意减少第三方库，而 Now in Android 则大量使用 Paging、DataStore 等成熟库。fragmject 适合想理解底层实现的初学者，而 Now in Android 适合想学习生产级架构的开发者。如果你需要最新的 API 和最佳实践，官方示例是更好的选择。

编辑结论

fragmject 适合那些已经掌握 Kotlin 基础语法、但缺乏完整项目经验的开发者。它适合用来理解 Compose 声明式 UI、Navigation 3 的类型安全导航、WindowSizeClass 自适应布局，以及 MVVM/MVI 架构在真实项目中的组织方式。如果你希望学习官方推荐的写法，并且愿意接受代码中可能存在的非最优实现，那么这个项目值得阅读。不适合的人群包括：需要直接用于生产项目的开发者，因为项目自 2021 年 8 月后未再更新，依赖版本停留在 Kotlin 2.4.x 与 Navigation 3 的早期阶段，可能与当前 Android Studio 和 AGP 存在兼容问题。另外，如果你希望学习第三方库的封装技巧，这个项目反而刻意回避了这一点。开始之前，请先确认你的 Android Studio 版本能够构建该项目，必要时参考 libs.versions.toml 自行调整 AGP 和 Compose 版本。最后，注意项目中的 SharedFlowBus 和字节码插桩示例，它们展示了自定义实现，但你需要自行评估其健壮性。

官方来源

1. Official README
2. Project repository
3. Release notes