从这里开始

欢迎参与「魔法纪录复兴计划」服务端开发。本章按深度递进:

• 入门(初级贡献者) — 第一次接触这个仓库?从搭环境、读代码、跑测试,到一个完整的"新增接口"动手示例。
• 深入(资深贡献者) — 要改核心子系统?先读懂多方言存储、协议保真约束、调度器、打包器背后的设计权衡。

你需要先知道的五件事

无论改哪里,这五条贯穿全项目,先记住能少走弯路:

flowchart TB
    A["① 客户端不可信<br/>所有安全判断在服务端"] 
    B["② 单二进制 + 一个数据库<br/>无 Redis/MQ/前端构建"]
    C["③ 一套代码三种数据库<br/>业务用 ? 占位符,方言层改写"]
    D["④ 客户端协议字段<br/>以 Java 源码为唯一真理"]
    E["⑤ 配置即时生效<br/>存 config 表,握手即读"]

1. 客户端不可信 —— 别信任客户端发来的任何字段,都要服务端验证。详见 安全机制。
2. 极简部署 —— 没有 Redis、消息队列、前端构建链。新功能优先用现有的"进程内 + 数据库"模式,别轻易引入外部依赖。
3. 三种数据库 —— 写 SQL 用 ? 占位符,经存储层方言适配 PG/MySQL/SQLite。别写某一种数据库专属的语法。详见 存储层与多方言。
4. 协议保真 —— /client/* 的字段名、嵌套、空值处理对齐客户端 Java 源码,有保真测试守护。改这些前必读 协议保真原则。
5. 配置即时生效 —— 运行配置存数据库 config 表,客户端下次握手即读到。环境变量只承载部署级的东西。

技术栈

层	选型	你需要会
语言	Go 1.25+	Go 基础、标准库 net/http
路由	go-chi v5	看懂 r.Route / r.Use / 中间件
数据库	PG / MySQL / SQLite	SQL 基础;方言差异由存储层封装
前端	React + 浏览器内 Babel	改后台才需要;无构建步骤
测试	Go testing + SQLite 内存库	写表驱动测试

不要求精通全部 —— 改后端接口主要用到 Go + chi + SQL。

典型贡献路径

flowchart LR
    S["搭环境"] --> R["读代码库导览"]
    R --> T["跑通测试"]
    T --> C["改动 + 写测试"]
    C --> V["go vet + go test 全绿"]
    V --> PR["提交 PR"]

1. 开发环境搭建 — 把项目在本地跑起来。
2. 代码库导览 — 知道每个目录在干什么。
3. 运行与编写测试 — 学会跑测试、写测试。
4. 新增一个接口 — 跟着做一遍完整流程。
5. 代码规范 — 提交前对照。

提交前自检

go vet ./...                    # 静态检查
go test ./...                   # 全部测试
go test -race -count=1 ./...    # 竞态检测(CI 会跑,本地最好也跑)

CI 会跑同样的检查 + 交叉编译。三条全绿再提 PR。

资深贡献者:核心子系统

要动这些之前,务必先读对应文档理解设计意图:

子系统	文档	为什么要先读
存储层	多方言抽象	一处改动要同时对三种数据库成立
客户端协议	协议保真原则	一个字段错位真机就崩
调度器	调度器与后台任务	goroutine 生命周期与优雅退出
打包器	离线整包打包器	原子写、流式哈希、retention
发布	发布流程与 CI	版本号自动推进规则

准备好了就从 开发环境搭建 开始。