★ FEATURED ARTICLE 【免费下载链接】hammer-editorA simple tool for building stories.项目地址https://gitcode.com/gh_mirrors/ham/hammer-editor点击查看免费下载Hammer 是一款免费开源的跨平台故事编辑器story editor支持 Android、iOS、Windows、macOS 和 Linux。本文带你用最少代码、最快路线拆解它的 Clean 分层架构与 Kotlin Multiplatform 模块结构帮你在第一次打开仓库时就能建立完整地图 一、先认识 Hammer一个数据在你手里的跨平台故事编辑器在拆架构之前先花 30 秒理解这个产品要解决什么问题架构设计才有落脚点离线优先Offline first完全本地运行不依赖网页技术长时间离线写作不丢数据数据透明Transparent Data项目就是人类可读的普通文件与文件夹不锁在云端的黑盒数据库里可选同步可自部署同步服务器也可用 Dropbox、Syncthing 等任意方式同步多端一致手机、平板、桌面端共用同一份业务代码界面按屏幕自适应它的核心写作功能围绕四大模块组织场景Story、百科Encyclopedia人物/地点/事件、笔记Notes、时间线Timeline再加一个能穿透到任意内容的全局搜索。理解了数据透明 多端一致 离线优先这三个产品目标你会发现后文的每个架构决策几乎都能直接对应上。二、Clean 架构总览六层结构依赖只允许向下Hammer 采用的是一套严格约束的 Clean 风格分层。完整规范写在官方文档 docs/ARCHITECTURE.md 中这是全仓库最重要的架构契约。层级从最靠近数据到最靠近界面排列为Data Sources → Foundation → Repositories → Services → Use Cases → ViewModels其中强制主干只有三层Data Source → Repository → ViewModel。Services 和 Use Cases 是可选层只在真实需求出现时才插入官方明确反对预判式建层。层级有状态生命周期必须Data Source 数据源无状态工厂创建每次新实例✅Foundation 基础原语有状态作用域单例固定集合Repository 仓库有状态作用域单例✅Service 服务有状态作用域单例❌ 可选Use Case 用例无状态工厂创建❌ 可选ViewModelComponent—每屏幕一个✅ 本项目把最高层称为ComponentDecompose 组件等价于其他架构里的 ViewModel两个词在文档中通用。Foundation一个固定的三件套Foundation 层不是随便加东西的地方而是全数据层公用的固定有状态基础设施目前只有三个成员IdAllocator— 分配全项目单调递增的实体 IDIdAllocator.ktSyncJournal— 记录等待与服务器对账的脏数据位于 data/sync/GlobalSettingsStore— 应用级与服务器设置GlobalSettingsStore.kt三者构成无向环的 DAGGlobalSettingsStore ← SyncJournal ← IdAllocator这是全仓库中唯一允许有状态组件横向引用同层的地方——正因为集合是手工保持无环的。决策规则该加哪一层官方文档给出了极简判断法值得背下来需要 Use Case只有当存在无状态业务逻辑/组合时才加如果只是把一次调用原样转发给 Repository就别加需要 Service只有当需要跨两个及以上 Repository协调且带共享状态时才加Repository 之间禁止互相引用协调逻辑只能放这里需要 Foundation 原语几乎永远不要。两个 Repository 都需要它不是理由——那是 Service 的职责三、实战拆解一次场景编辑如何穿过各层纸上谈兵不如看真实案例。docs/DESIGN-PATTERNS.md 记录了一次教科书式的分层重构场景编辑域曾经是约 1300 行、捆绑 12 项职责的SceneEditorRepository最终被拆成一个门面 三个仓库SceneEditorService— 组件层唯一入口负责写操作编排在每条命令周围挂上统计、引用索引、同步标记等横切副作用SceneEditorService.ktSceneRepository— 场景树、结构、路径计算、同步哈希纯数据SceneRepository.ktSceneContentRepository— 编辑引擎内存缓冲区、内容防抖管道、临时缓冲区自动保存SceneContentRepository.ktSceneMetadataRepository— 场景与项目元数据的持久化注意一个关键设计Component 层只能透过SceneEditorService这一个门访问场景编辑域调用者永远不需要纠结该注入 repo 还是 service。而 Service、Use Case、同步层仍然可以直接消费下层 Repository——Service → Repository这条边是合法的只有最高层被收口。依赖注入由 Koin 完成约定很简单无状态组件Data Source、Use Case工厂创建有状态组件Repository、Service作用域单例且作用域尽量选窄会话、导航图别一股脑塞进应用级单例。入口模块见 dependencyinjection/。四、Kotlin Multiplatform 模块结构7 个 Gradle 模块各管一摊在 settings.gradle.kts 中可以看到完整的模块清单。这是理解 KMP 结构的第一张地图模块职责关键内容base/最底层共享原语ID 类型、markdown 工具、http、校验、diffcommon/核心业务约 350 个文件数据层六层全家桶 组件层 同步协议composeUi/跨平台 UI约 250 个文件Compose Multiplatform 界面组件android/Android 宿主Activity、Widget、通知desktop/桌面宿主窗口管理、系统快捷键、原生集成server/独立同步服务器Ktor SQLDelight PostgreSQLwear/手表端非 F-Droid 构建Wear Compose 配对界面integrationTests/集成测试端到端场景验证模块之间的依赖方向非常克制base在最底被所有模块依赖common承载几乎全部业务逻辑composeUi消费common的组件各平台模块android/desktop/wear只是薄薄的一层胶水负责启动、权限和平台 API 接入。技术栈版本统一收敛在 gradle/libs.versions.toml 中Kotlin 2.4、Compose Multiplatform、Decompose 3.5组件框架、KoinDI、Ktor、okio 文件系统抽象。服务器模块是独立世界它不复用客户端的 common 代码而是按自己的轻量分层组织——Routes → Repository → Datasource见 server/src/main/数据库层用 SQLDelight 管理 schema 与迁移server/src/main/sqldelight/。五、同一份代码跑五种端源码集Source Set是怎么切分的模块是横向切分KMP 的源码集则是模块内部的纵向切分。以核心模块common为例它的src/目录长这样commonMain— 编译到所有平台的共享代码业务逻辑全在这里desktopMain/androidMain/iosMain/jvmMain— 各平台实现与胶水commonTest/desktopTest/iosTest— 各端测试一个有趣的工程细节因为 mock 库 mockk 尚不支持 Kotlin/Native绝大多数单元测试被放在desktopTest源码集里跑gradlew desktopTest这是 DEVELOPMENT.md 明确说明的取舍。测试还承担了架构守卫的职责例如 PersistedFormatOwnershipTest.kt 强制每种磁盘文件格式只允许一个 Data Source 拥有——历史上两个独立的project_data.toml写入方曾互相擦掉对方字段这条规则就是事故教训固化成的自动化检查。六、给读源码的你核心依赖规则速查官方把最容易踩的坑浓缩成了硬性约束收藏 docs/ARCHITECTURE.md 即可只允许向下依赖任何组件只能引用比它更低的层禁止同层互引No sibling references这是保证依赖图天然无环的关键唯一例外无状态的 Use Case 可以引用其他 Use CaseUse Case 之间用懒注入ProviderT或 lambda无状态不足以防止构造循环ViewModel 永远不直接碰 Data Source必须经过 Repository 或更上层Foundation 原语是下层共享件不是兄弟任何层引用它都算向下一种持久化格式只有一个属主由架构测试强制七、源码导航清单按这个顺序读效率最高最后给出一份最小阅读路径从产品到代码逐层下钻 架构总纲docs/ARCHITECTURE.md 设计模式目录深链导航、场景编辑域 API 等范例docs/DESIGN-PATTERNS.md️ 模块清单与构建入口settings.gradle.kts、gradle/libs.versions.toml 组件层入口屏幕栈与导航components/projectroot/️ 数据层主战场data/30 个领域子包 依赖注入装配dependencyinjection/️ 开发指南与测试哲学DEVELOPMENT.md 构建元数据版本、渠道、发布脚本buildSrc/小结Hammer 的架构精髓可以浓缩为一句话——用只向下依赖的 Clean 分层保证业务代码与平台无关再用 KMP 的源码集切分把这一份业务代码铺到五种操作系统上。读懂common模块里的六层数据流和base/composeUi的边界你就掌握了这个代码库 90% 的脉络。赞分享【免费下载链接】hammer-editorA simple tool for building stories.项目地址https://gitcode.com/gh_mirrors/ham/hammer-editor点击查看免费下载相关推荐一文读懂bRPC高性能RPC框架的核心模块与架构设计全解析一文读懂bRPC高性能RPC框架的核心模块与架构设计全解析 bRPC是百度开源的高性能RPC框架广泛应用于分布式系统中提供高效的远程过程调用能力。本文将深后端RPC框架微服务ChatBotCourse代码结构解析深入理解项目架构与模块设计ChatBotCourse代码结构解析深入理解项目架构与模块设计 ChatBotCourse是一个完整的聊天机器人学习项目通过多个版本的逐步演进帮助开发者示例工程chrome-cli高级功能多窗口管理、演示模式与窗口定位终极指南chrome cli高级功能多窗口管理、演示模式与窗口定位终极指南 想要通过命令行控制Chrome浏览器实现自动化工作流和高效的多窗口管理吗chrome开发工具上一篇Gofile.io 文件下载工具使用指南下一篇Gofile.io文件下载工具使用指南从基础操作到高级技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
