跳到主要内容

第 31 期 · 1.0 收尾:整理代码与文档

· 阅读需 5 分钟

1.0 之前的一次大扫除,这期没有新功能:

  • 后端目录分了层,一眼能看出哪些是业务、哪些是基础设施;
  • 九份各写各的事务辅助函数合成一份,顺手修掉一个会让 SQLite 站点卡死的问题;
  • 文档按玩家、站长、开发者重新组织,README 从 276 行减到不到 80 行。

接下来是前端优化,然后是 1.x 与 2.0。

目录分层(ADR 0040)​

以前 internal/ 下 33 个包平铺。现在:

  • internal/modules/:账号、材质、角色、积分、举报、外置登录等 18 个业务模块;
  • internal/platform/:数据库、任务队列、存储、日志等基础设施,不认识任何业务;
  • 顶层只剩进程级的包:装配、命令行、网关、前端启动器、系统服务、备份,以及 HTTP 层和扩展总线。

依赖方向是 cli → app → httpapi → modules → platform。这次只改了导入路径,没有改代码逻辑。

几个太长的文件也拆开了。texture/manage.go 有 894 行,衣柜、编辑删除、加锁、文件清理都在里面,现在分成四个文件;account/service.go 和 cli/root.go 也一样。拆分用一个小工具按声明搬移,然后逐行比对搬移前后的代码,确认一个字都没改。

一个藏得很深的问题​

withTx 在九个包里各复制了一份,写法还不完全一样。统一的时候发现,这九份都没有处理回调 panic 的情况:

  • 处理函数里的 panic 会被 HTTP 服务器恢复,请求返回 500;
  • 但事务没人回滚,一直占着数据库连接和锁;
  • SQLite 只有一个写者,之后站点的所有写入都在等这个永远不会结束的事务,最后超时失败,只能重启。

按 TDD 的做法,先写测试:在三种数据库上制造一次 panic,再写一笔。旧写法在 SQLite 上等了 10 秒超时,确认问题存在;db.WithTx 加上 panic 回滚后测试通过。

统一的过程中,测试还拦住了一个回归。一开始统一成的版本无论如何都用 errors.Join 把错误包一层,结果 player 的测试失败了:调用方写的是 err != ErrNotFound,被包过的错误对不上。最后定下的语义是原样返回回调的错误,只有回滚本身也失败时才合并。

文档​

  • 文档站分成三块:
    • 玩家指南:只讲怎么做(注册、上传、换皮肤、在启动器里登录),不出现设置键;
    • 站长指南:部署、配置文件、站点设置、后台管理、迁移;
    • 开发:环境、架构、接口。
  • 站点设置速查表照着 skinloom settings get 的输出逐项核对,全部 80 个设置都在。
  • 使用文档里去掉了 Blessing Skin 缺陷编号和实现细节。它们对开发者有用,但对玩家和站长是干扰,现在留在设计文档和 ADR 里。
  • README 只留介绍、快速开始和文档入口,部署细节都在文档站。

终端日志(ADR 0041)​

以前终端里每行都以 time=2026-11-09T15:39:33.541+08:00 level=INFO msg= 开头,级别没有颜色。新站点首次启动先刷 11 行迁移记录,安装链接埋在中间。现在:

16:03:29 INFO [migrate] database migrated applied=11 version=20261030040409
16:03:29 NOTE SkinLoom is running url=http://localhost:17546/ database=sqlite
16:03:29 WARN unknown keys in config file (typo?); they are ignored keys=[log.levle]
16:03:29 NOTE first run: open this one-time link to create the administrator account url=…
16:03:30 INFO [web] ✓ Ready in 897ms
  • 级别带颜色:错误红、警告黄,站点地址和安装链接用新的 NOTE 级别,绿色加粗,log.level = warn 时也会显示。
  • 日志文件、Docker、systemd 拿到的仍是完整时间戳的 key=value,grep setup 照常可用。
  • 前端每个请求一行的记录降到 debug;Next.js 打印的内部端口地址不再转发,免得有人去访问它。

调试时踩了一个坑:用 FORCE_COLOR 测试彩色输出时,这个变量也传给了 Next.js,它自己的颜色码让请求行认不出来,还会混进日志文件。现在先去掉子进程输出里的颜色码,再分级、上色。

验证​

  • go vet、staticcheck、govulncheck 无告警;
  • 全部测试在 SQLite 和本地 PostgreSQL 上通过,生成的 OpenAPI 文档没有变化;
  • 在本机启动完整站点,手动走了一遍主要流程;
  • 文档站构建通过,站内链接全部有效。

MySQL 本地没有环境,交给 CI。