0040 1.0 收尾:目录分层、统一的事务工具与按读者组织的文档
- 状态:已接受(2026-11-09)
- 相关:ADR 0002(模块化单体)、0026–0028(事务规则)、设计文档 04 §3.3
背景
1.0 之前做一次整理,目标是让新贡献者能快速看懂代码,让玩家和站长能快速找到要看的文档。整理前的问题:
internal/下 33 个包平铺,业务模块、基础设施和进程级的包混在一起,看目录看不出分层。- 事务辅助函数
withTx在 9 个包里各有一份,写法不完全一样(有的总用errors.Join包一层,有的原样返回),而且都没有在回调 panic 时回滚:panic 被 HTTP 服务器恢复后,事务一直占着连接和锁。SQLite 只有一个写者,此后整个站点的写入都会等待并失败。 - 按字节截断字符串的函数有三份,
sameJSON、cmpOr各有重复。 - 几个大文件职责混杂:
texture/manage.go(894 行:衣柜、编辑删除、加锁、文件清理)、account/service.go(700 行:安装、登录、注册、会话)、cli/root.go(所有命令)。 - README 有 276 行,大段重复文档站的部署说明;文档站"开始使用"一栏把玩家操作、站长设置、实现细节和 Blessing Skin 缺陷编号写在同一页,玩家要翻过设置键才能找到"怎么上传"。
决策
目录分层
internal/
app cli config gateway launcher daemon backup 进程级:装配、命令行、入口、运维
httpapi HTTP 层
hook 扩展总线(将来的插件接入点)
modules/ 业务模块
account audit captcha cdn mail notify oauth player render report
score settings sitesettings social stats texture theme yggdrasil
platform/ 与业务无关的基础设施
db dbtest migrate datalock fsperm httpx realip validate
pubsub jobs storage logging secrets buildinfo registry clip
importer/bs contract tools/
依赖方向是 cli → app → httpapi → modules → platform,platform 不导入任何业务包。captcha 和 mail 声明了自己的站点设置,所以归入 modules。命名沿用设计文档 04 §3.3 的 modules 与 platform。
迁移只改导入路径,不改包名和代码。buildinfo 移到 internal/platform/buildinfo,Dockerfile 和打包脚本里的 -ldflags -X 随之更新。
统一的事务工具
所有事务都用 db.WithTx(ctx, client, fn):
fn返回 nil 时提交;返回错误时回滚,并原样返回这个错误(调用方用==比较哨兵错误),只有回滚本身也失败时才用errors.Join合并;fnpanic 时先回滚再继续 panic。
internal/platform/db/tx_test.go 覆盖这三种情况,并在三种数据库上验证 panic 之后还能写入(旧写法在 SQLite 上超时)。统一过程中,测试还抓到了把 errors.Join 写法推广到所有包会破坏 err != ErrNotFound 这类比较的问题,最终采用上面的语义。
其它清理
platform/clip提供Bytes(按字节、不切断字符)和Runes(按字符),替换四份截断函数;sameJSON导出为settings.SameJSON;cmpOr换成标准库cmp.Or。- 拆分大文件,只移动声明、不改逻辑(用工具按声明搬移,并逐行比对搬移前后的代码):
texture拆成closet.go、edit.go、locks.go、upkeep.go;account拆出setup.go、login.go、register.go、session.go;cli拆成serve.go、maintain.go、site.go、info.go。 httpapi的管理接口文件统一加admin_前缀,新增doc.go列出每个文件负责的接口。app.OpenCore改为先建Core、出错时统一调用Close:原来每个出错分支各自关闭数据库,并且出错时 hook 总线的 goroutine 不会退出。新增Core.APIDeps,替换run.go里那行很长的依赖列表。
文档按读者组织
- 文档站分成玩家指南(
players/:账号、皮肤与披风、角色、在游戏里使用)、站长指南(deployment/与admin/:快速开始、部署、配置文件、站点设置、注册登录与邮件、后台管理、外观、第三方登录、外置登录与游戏接口、备份、迁移)和开发(development/:环境、架构、接口,以及插件与主题)。 - 玩家文档只讲怎么做,不出现设置键和实现细节;站长文档给出设置键和命令;Blessing Skin 缺陷编号(C03、S05 等)和实现说明不再出现在使用文档里,留在设计文档和 ADR 中。
- 站点设置速查表按
skinloom settings get的输出逐项核对,覆盖全部 80 个设置。 - README 只保留介绍、功能、快速开始和按读者分的入口;部署细节交给文档站,发布流程移到 CONTRIBUTING。
备选方案
- 把
httpapi按领域拆成子包:处理函数共用的请求上下文、错误映射和权限检查都得导出,换来的只是目录层级。改为文件前缀加doc.go索引。 - 业务目录叫
internal/domain:设计文档一直用modules,沿用以减少概念。 - 旧文档地址加重定向:需要新增插件依赖。部署类页面保留了
deployment/路径(发行包 README 链接的地址不变),旧的getting-started/*只在开发日志里被引用过,已改为新地址。
影响
- 导入路径变化:自行用
-ldflags -X …/internal/buildinfo.Version构建的脚本要改为…/internal/platform/buildinfo.Version。 - 文档站
/docs/getting-started/*地址不再存在。 - 已有的 ADR 与开发日志保留当时的路径,作为历史记录不改写。