当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。
历史 v0.4 变更记录(当前增量见页首 v0.5):原23章继续教授从零完成模拟系统,教学数据不要混用链任务。下一阶段按链模式开发手册创建contracts/与chaintrade/:先解释签名和approve,再把立即成交改为pending,写真实EVM原子交换测试,最后加outbox、raw交易持久化、中间件和钱包恢复。完整逐文件教学仍是模拟版,链增量源码注释/设计提供对应阅读路径。 当前链实现见v0.5架构,操作见开发、测试、部署,证据见本轮报告。
更新:2026-10-12。对应本项目当前 v0.3 架构。主路线使用 Windows + PowerShell + VS Code;Go、React 的代码在 Linux/WSL 也能运行。
这份教程要教你从空目录亲手写出程序,再把它升级到本仓库的完整架构。你会写撮合、资金、单写者运行时、SQLite 持久化、注册登录、管理员、交易页面和测试,最后学习 Windows 运行、容器与云部署。资产是模拟的,没有真实充值提现。
教程分为两个连续阶段:第 1–13 章给出一个可以逐文件输入、编译、操作的教学项目;第 14–23 章在这个基础上升级到当前完整实现。教学代码故意保持较小,进阶章节会明确增加什么、在哪里增加、通过什么用例验收。前半部分的 /api、数据结构、包名与最终项目的 /api/v1 不同,不要把两套文件混着编译。
所有“完整文件”代码块可以复制到指定文件。标为“片段”的内容用于理解或插入已有函数,不能单独运行。每章都先完成验收再继续;不需要第一天懂红黑树或高可用。
阅读导航#
- 1. 先认识你要做的东西
- 2. 安装工具并创建空目录
- 3. 写出第一段 Go 和第一个 HTTP 接口
- 4. 读懂 Go 的基本语法
- 5. 先把交易规则算清楚
- 6. 手写精确金额、订单簿和撮合核心
- 7. 写第一个业务单元测试
- 8. 写单写者运行时与 SQLite 日志
- 9. 写注册、登录、会话和管理员身份
- 10. 写 HTTP 接口和权限校验
- 11. 把后端装配起来
- 12. 从空目录写 React 交易页面
- 13. 操作、测试并重启你的教学项目
- 14. 从教学版升级到完整项目
- 15. 补全订单规则、预算和对象所有权
- 16. 升级日志、增量投影与恢复
- 17. 补全认证、契约和管理员审计
- 18. 写分页、实时行情和待确认请求恢复
- 19. 设计完整测试并读懂性能结果
- 20. 写注释、规范与项目文档
- 21. 运行当前完整项目和 Windows 脚本
- 22. 容器与云服务器部署
- 23. 备份、故障排查与毕业验收
1. 先认识你要做的东西#
1.1 从生活中的交易理解系统#
小王说:“我愿意用每个最多 105 USDT 买 3 个 ETH。”小李说:“我愿意用每个 100 USDT 卖 2 个 ETH。”系统发现二者价格能对上,按既有卖单的 100 成交 2 个,剩下 1 个买单继续等待。USDT 可以先理解成付款单位,ETH 是购买的商品单位。
订单是买卖意愿;成交是已经发生的交换。下单成功并不等于成交成功。一笔订单可以成交多次,也可以没有成交就被撤销。撮合就是按事先约定的规则挑出可以成交的订单。
1.2 前端、后端、数据库各做什么#
| 名词 | 用白话解释 | 本项目的工具 |
|---|---|---|
| 前端 | 浏览器里看到的页面,收集输入和展示结果 | React + TypeScript |
| 后端 | 收到请求、检查身份、处理交易的程序 | Go |
| 数据库 | 程序关闭后仍能保存数据的文件或服务 | SQLite 文件 |
| HTTP | 浏览器和服务之间的请求/响应协议 | Go 标准库 + fetch |
| JSON | 双方约定的数据文本格式 | {"price":"105"} |
| API/接口 | 可以按约定地址调用的一项服务 | POST /api/orders |
| 端口 | 同一机器上区分不同网络服务的编号 | 后端 8080,开发页面 5173 |
| localhost/127.0.0.1 | 当前这台机器 | 教学服务仅本机访问 |
| 进程 | 正在运行的一个程序实例 | 一个交易后端 |
| goroutine | Go 中独立推进的一段工作 | HTTP、写日志、核心、投影 |
GET 常用于读取,POST 常用于提交动作,PATCH 常用于修改某些字段。200 表示 HTTP 成功,400 参数错误,401 未登录,403 无权,503 服务暂时不可用。HTTP 成功、订单成交、资金充足是三个不同概念。
flowchart LR U[浏览器输入] --> H[HTTP:身份和参数检查] H --> J[日志写入 SQLite] J --> E[唯一核心:撮合和资金] E --> V[查询投影 SQLite] V --> U |
1.3 这个项目的主线#
普通用户注册 → 登录 → 获得模拟初始资金 → 下单 → 冻结资金 → 成交或挂单 → 撤单释放余量。管理员可以查看用户、停用用户、增加模拟资金。关掉后端再启动,历史订单和资金应该保留。
以后面试时要能回答:“输入在哪里验身份?什么时候算受理?什么时候落盘?谁能修改资金?浏览器断网时怎么办?”它们比页面颜色更能说明你理解了系统。
2. 安装工具并创建空目录#
2.1 安装与确认#
安装 Go、Node.js、VS Code。Go 以项目 go.mod 的 1.26.9 为准;Node 使用 22 或更高版本。本项目使用纯 Go SQLite 驱动,开发不需要安装 MySQL、Redis、C 编译器或 SQLite 服务。
安装完重新打开 PowerShell。可以在开始菜单搜索“PowerShell”,也可以在 VS Code 的“终端 → 新建终端”中选择 PowerShell。输入下面命令,不复制行首提示符:
go version node --version npm --version |
看到版本号才算安装成功。go 不是内部或外部命令 表示 PATH 没生效;重开终端再检查安装路径。PowerShell 若阻止 npm.ps1,本文所有 npm 命令可改成 npm.cmd,无需修改整台机器的执行策略。
2.2 专门建立练习目录#
下面命令全部在 PowerShell 中执行。路径仅为例子,你可以换成自己的磁盘。新练习目录不要使用现有 web3,避免覆盖完成的项目。
New-Item -ItemType Directory -Force D:\exchange-learn Set-Location D:\exchange-learn Get-Location New-Item -ItemType Directory -Force core,runtime,auth,transport,cmd\server,frontend\src code . |
New-Item 创建目录;Set-Location 切换当前目录;Get-Location 查看你现在在哪。最后一条打开编辑器,若 code 不可用,通过 VS Code 的“打开文件夹”选择这个目录。
Linux/WSL 对应命令是 mkdir -p ~/exchange-learn、cd ~/exchange-learn;后面的 go/npm 大部分一致。别在 Windows 与 WSL 之间共用同一个 node_modules,它包含平台相关程序。
2.3 创建 Go 模块与依赖#
在 D:\exchange-learn 根目录执行:
go mod init exchangelearn go mod edit -go=1.26.9 go get github.com/shopspring/decimal@v1.4.0 go get github.com/emirpasic/gods@v1.18.1 go get github.com/gofrs/flock@v0.12.1 go get golang.org/x/crypto@v0.58.0 go get modernc.org/sqlite@v1.60.1 |
exchangelearn 是你项目的模块名,因此后面才能写 import "exchangelearn/core"。go.mod 记录依赖版本,go.sum 记录校验摘要;两者都保留。go get 下载指定依赖;Go 工具链允许自动下载匹配版本,首次需要联网。若本机设置 GOTOOLCHAIN=local 且版本太旧,使用当前终端 $env:GOTOOLCHAIN="auto" 或安装所需 Go。
依赖为什么选这些:decimal 做精确十进制计算;GoDS 提供红黑树;flock 防止两个进程同时打开同一数据目录;x/crypto 的 bcrypt 存密码摘要;modernc/sqlite 用 Go 操作内嵌数据库。我们不手写密码算法或红黑树。
创建根目录 .gitignore,写入下面完整内容,防止把依赖、数据、产物当源码提交:
/data/ /frontend/node_modules/ /frontend/dist/ /bin/ .env *.tsbuildinfo |
**本章验收:**目录存在,版本命令有效,根目录出现 go.mod 和 go.sum。首次下载失败先检查网络和代理;不要把未下载成功当作代码错误。
3. 写出第一段 Go 和第一个 HTTP 接口#
3.1 第一个程序#
新建 cmd/server/main.go,输入下面完整文件:
package main import "fmt" func main() { fmt.Println("我的模拟交易项目开始了") } |
根目录运行:
go run ./cmd/server
|
它应打印一行文字后退出。package main 表示可执行程序;func main() 是入口;fmt.Println 是标准库打印函数。文件保存后再运行,VS Code 标签页上的小圆点表示还没保存。
3.2 改成一个常驻服务#
用下面完整文件替换同一份 cmd/server/main.go:
package main import ( "encoding/json" "log" "net/http" ) func main() { mux := http.NewServeMux() mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") _ = json.NewEncoder(w).Encode(map[string]string{"status": "ok"}) }) log.Print("打开 http://127.0.0.1:8080/health") if err := http.ListenAndServe("127.0.0.1:8080", mux); err != nil { log.Fatal(err) } } |
运行同一条 go run ./cmd/server。这次窗口不退出,因为它在等请求。打开第二个 PowerShell 窗口执行:
Invoke-RestMethod http://127.0.0.1:8080/health
|
看到 status ok 即完成;浏览器直接打开相同地址会看到 JSON。第一个窗口按 Ctrl+C 停止,然后才能继续覆盖代码。端口被占用意味着旧服务还开着;关闭你自己的旧窗口,别随便结束其他程序。
4. 读懂后面会用到的 Go 基本语法#
不要求背完整 Go 教程,但先能看懂以下对应关系。
| 写法 | 含义 | 为什么项目要用 |
|---|---|---|
type Order struct { ID string } |
把几个字段组成一个类型 | 一张订单有编号、方向、数量 |
o := Order{ID: "1"} |
建一个值并推导变量类型 | 创建订单 |
*Order / &o |
指向某个订单的指针 / 取得地址 | 核心可更新同一个订单 |
[]Order |
可变长度的订单列表,叫 slice | 一页订单或一批变更 |
map[string]*Order |
用字符串找到订单的字典 | 按 ID 快速撤单 |
value, ok := m[key] |
查字典,并判断键是否存在 | 区分未知订单与已有订单 |
func (e *Engine) Apply(...) |
属于 Engine 的方法 | 让引擎处理命令 |
value, err := f() |
返回结果和错误 | 普通错误通过返回处理 |
defer db.Close() |
当前函数返回时再清理 | 正确关闭数据库 |
go f() |
开始一个 goroutine | 外围任务独立运行 |
make(chan T, 64) |
最多缓冲 64 项的消息队列 | 限制等待命令数量 |
ch <- x / x := <-ch |
往队列发送 / 从队列接收 | 按顺序传命令 |
for x := range ch |
依次读取,队列关闭且读完才退出 | 排空工作 |
select |
在多个队列/取消信号之间等待 | 支持超时和拒绝入队 |
`json:"price"` |
JSON 中字段叫什么 | Go 的 Price 对应 price |
_ "modernc.org/sqlite" |
加载驱动的注册动作 | 让 database/sql 认识 sqlite |
值复制不等于深拷贝。b := a 会复制结构体,但里面的指针可能仍指着同一个订单,slice 也可能共享底层数组。后面每次把订单交给 HTTP/投影时要复制,不能让其他 goroutine 改核心对象。
panic 会中断正常控制流,不能用它表示“余额不足”。本教程只在“已提交日志序号断裂”这种内部不变量损坏时使用它;金额错误、权限错误、无流动性都要返回正常结果。
练习:用自己的话说明 map[string]*Order 与 []Order 各适合解决什么问题;再说明 go e.Apply(c) 为什么会破坏单写者。
5. 写代码前,先把交易规则算清楚#
5.1 五条最基础规则#
- 买价越高优先,卖价越低优先;同一价格先到先成交,这叫 FIFO。
- 新来并主动吃已有挂单的叫 taker;已有挂单叫 maker;按 maker 的价格成交。
- 买单冻结
限价 × 数量的 USDT,卖单冻结对应 ETH。 - 成交只交换资产,零手续费演示中不会凭空增加 USDT 或 ETH;只有 CREDIT 注资增加模拟总供给。
- 撤单只释放尚未成交部分;已经成交的部分不能撤回。
GTC 表示未成交部分继续挂单;IOC 表示立即能成交多少成交多少,然后取消剩余部分。教学版先实现 LIMIT GTC,最终版加入 IOC 和带保护价的 MARKET。
5.2 贯穿全篇的算例#
买方开始有 1000 USDT,卖方开始有 10 ETH。先挂卖单 2 ETH @100,然后买方提交 3 ETH @105。
| 时刻 | 买方可用 USDT | 买方冻结 USDT | 买方 ETH | 卖方可用 ETH | 卖方冻结 ETH | 卖方 USDT |
|---|---|---|---|---|---|---|
| 初始 | 1000 | 0 | 0 | 10 | 0 | 0 |
| 卖单挂出 | 1000 | 0 | 0 | 8 | 2 | 0 |
| 买单冻结 315 | 685 | 315 | 0 | 8 | 2 | 0 |
| 按 100 成交 2 | 695 | 105 | 2 | 8 | 0 | 200 |
| 买方撤剩余 1 | 800 | 0 | 2 | 8 | 0 | 200 |
关键步骤:买方本次成交部分原冻结 105×2=210,实际支付 100×2=200,价差 10 立刻回可用余额,余量 1×105=105 仍冻结。
资产守恒:最终 800+200=1000 USDT,2+8=10 ETH。订单守恒:买单 3=成交2+撤销1+余量0。这些式子会成为测试断言。
5.3 为什么金额是字符串#
JSON 写 "price":"0.1",不能先把它变成浮点再转 decimal。常见二进制浮点不能精确表示所有十进制小数。后端 decimal 精确运算;前端保留字符串,避免金额和大序号的精度丢失。价格最多 2 位小数,ETH 数量最多 4 位,乘起来的 USDT 最多 6 位。
输入 1e2、+1、01、0(需要正数时)或超精度值应拒绝,不能偷偷舍入。0.10 与 decimal 输出 0.1 数值相同;最终版在外围规范化后计算幂等摘要。
6. 手写精确金额、订单簿和撮合核心#
6.1 先决定核心可以碰什么#
核心只接收 Command,只做内存运算,返回 Result。它不能读数据库、调用 HTTP、读当前时间、产生随机编号或取得业务锁。这保证同一批历史命令重新执行时,得到相同业务结果。
先看结构,再输入代码,建议按下面顺序分六次写入同一个文件:
- 定义 Command/Order/Balance/Trade/Result/State:明确输入、业务对象、输出。
- 定义 level/ref/saved/Engine 和 New:建立状态容器。
- 写 Parse/d/balance/move/clone:精确金额、资金变更和对象隔离。
- 写 add/remove/best/release:管理订单簿与解冻。
- 写 place:校验→冻结→逐笔撮合→余量挂簿。
- 写 Apply/Snapshot:命令分发、幂等和状态副本。
输入时可先跳过尚未定义的函数产生的编辑器红线;全文件完成后才编译。不要用空函数替代业务后继续后面的章。
6.2 订单簿为什么需要两层结构#
红黑树按价格找档位,档位里用双向链表按到达顺序排订单。树键是 价格×100,例如 105.25 对应整数 10525。验证价格上限和两位小数后,这个转换才安全。
买树取最大价格,卖树取最小价格。BUY 查卖树,SELL 查买树。链表 Front 是最早的 maker;PushBack 将新单排到同价档队尾。active[id] 保存它的链表节点,撤单可以直接删除,不用找遍所有订单。
复杂度中的 P 是“不同价档数”:查档/删空档约 O(log P),同档插入/删除节点 O(1)。教学版 best 每次取树端点;最终版还缓存最优档,常见读取 O(1)。一张大单吃掉 k 张对手单,工作量仍与 k 有关,不能把整笔撮合说成 O(1)。
下面是 core/core.go 的完整文件:
package core import ( "container/list" "fmt" "regexp" "sort" "strconv" "github.com/emirpasic/gods/trees/redblacktree" "github.com/shopspring/decimal" ) // Command 是外部固定好的输入;Seq、Hash 由运行时设置,Account 由会话设置。 type Command struct { Seq int64 `json:"seq"` Hash string `json:"hash"` Account string `json:"account"` Key string `json:"key"` Kind string `json:"kind"` Side string `json:"side,omitempty"` Price string `json:"price,omitempty"` Quantity string `json:"quantity,omitempty"` OrderID string `json:"order_id,omitempty"` Asset string `json:"asset,omitempty"` Amount string `json:"amount,omitempty"` Actor string `json:"actor,omitempty"` Reason string `json:"reason,omitempty"` } type Order struct { ID string `json:"id"` Account string `json:"account"` Side string `json:"side"` Price string `json:"price"` Quantity string `json:"quantity"` Remaining string `json:"remaining"` Filled string `json:"filled"` Canceled string `json:"canceled"` Status string `json:"status"` } type Balance struct { Account string `json:"account"` Asset string `json:"asset"` Available string `json:"available"` Frozen string `json:"frozen"` } type Trade struct { ID string `json:"id"` Maker string `json:"maker"` Taker string `json:"taker"` Price string `json:"price"` Quantity string `json:"quantity"` } // Result 不含所有人的余额;HTTP 可以直接返回它。 type Result struct { ProcessedSeq string `json:"processed_seq"` ResultSeq string `json:"result_seq"` Code string `json:"code,omitempty"` Replayed bool `json:"replayed"` Order *Order `json:"order,omitempty"` Trades []Trade `json:"trades"` } // State 只交给持久化层;公开接口必须按当前会话过滤。 type State struct { Orders []Order `json:"orders"` Balances []Balance `json:"balances"` } type level struct { price decimal.Decimal queue *list.List } type ref struct { order *Order level *level node *list.Element } type saved struct { hash string result Result } type Engine struct { seq int64 bids, asks *redblacktree.Tree active map[string]*ref orders map[string]*Order balances map[string]*Balance dedupe map[string]saved } func New() *Engine { cmp := func(a, b interface{}) int { x, y := a.(int64), b.(int64) if x < y { return -1 } if x > y { return 1 } return 0 } return &Engine{bids: redblacktree.NewWith(cmp), asks: redblacktree.NewWith(cmp), active: map[string]*ref{}, orders: map[string]*Order{}, balances: map[string]*Balance{}, dedupe: map[string]saved{}} } var amountPattern = regexp.MustCompile(`^(0|[1-9][0-9]*)(\.[0-9]+)?$`) // Parse 验证原始文本,绝不把用户输入静默四舍五入。 func Parse(text string, scale int32, max string) (decimal.Decimal, bool) { if len(text) > 32 || !amountPattern.MatchString(text) { return decimal.Zero, false } n, err := decimal.NewFromString(text) return n, err == nil && n.IsPositive() && n.Exponent() >= -scale && n.LessThanOrEqual(decimal.RequireFromString(max)) } // d 仅用于已经验证过的文本;外部输入先调用 Parse。 func d(text string) decimal.Decimal { return decimal.RequireFromString(text) } func (e *Engine) balance(account, asset string) *Balance { key := account + ":" + asset if e.balances[key] == nil { e.balances[key] = &Balance{account, asset, "0", "0"} } return e.balances[key] } // move 的两个增量可正可负;调用者必须先检查足够资金。 func (e *Engine) move(account, asset string, available, frozen decimal.Decimal) { b := e.balance(account, asset) b.Available = d(b.Available).Add(available).String() b.Frozen = d(b.Frozen).Add(frozen).String() } func clone(r Result) Result { if r.Order != nil { o := *r.Order r.Order = &o } r.Trades = append([]Trade{}, r.Trades...) return r } // Apply 只能由启动重放或一个核心 goroutine 调用。 func (e *Engine) Apply(c Command) Result { if c.Seq != e.seq+1 { panic("command sequence gap") } e.seq = c.Seq seq := strconv.FormatInt(c.Seq, 10) r := Result{ProcessedSeq: seq, ResultSeq: seq, Trades: []Trade{}} key := c.Account + ":" + c.Key if old, ok := e.dedupe[key]; ok { if old.hash != c.Hash { r.Code = "IDEMPOTENCY_CONFLICT" return r } r = clone(old.result) r.ProcessedSeq = seq r.Replayed = true r.Trades = []Trade{} // 首次成交不能再次对外作为新成交发布。 return r } switch c.Kind { case "CREDIT": scale, max := int32(6), "1000000000000" if c.Asset == "ETH" { scale, max = 4, "1000000" } n, ok := Parse(c.Amount, scale, max) if !ok || (c.Asset != "ETH" && c.Asset != "USDT") { r.Code = "INVALID_AMOUNT" break } e.move(c.Account, c.Asset, n, decimal.Zero) case "PLACE": e.place(c, &r) case "CANCEL": o := e.orders[c.OrderID] if o == nil { r.Code = "ORDER_NOT_FOUND" break } if o.Account != c.Account { r.Code = "FORBIDDEN" break } item := e.active[o.ID] if item == nil { r.Code = "ORDER_TERMINAL" break } e.release(o, d(o.Remaining)) o.Canceled = d(o.Canceled).Add(d(o.Remaining)).String() o.Remaining = "0" o.Status = "CANCELED" e.remove(item) r.Order = o default: r.Code = "INVALID_COMMAND" } r = clone(r) // 隔离核心订单原件。 e.dedupe[key] = saved{c.Hash, clone(r)} // 再隔离首次结果与返回结果。 return r } func (e *Engine) add(o *Order) { tree := e.bids if o.Side == "SELL" { tree = e.asks } ticks := d(o.Price).Shift(2).IntPart() value, ok := tree.Get(ticks) var l *level if ok { l = value.(*level) } else { l = &level{d(o.Price), list.New()} tree.Put(ticks, l) } e.active[o.ID] = &ref{o, l, l.queue.PushBack(o)} } func (e *Engine) remove(item *ref) { item.level.queue.Remove(item.node) delete(e.active, item.order.ID) if item.level.queue.Len() == 0 { tree := e.bids if item.order.Side == "SELL" { tree = e.asks } tree.Remove(item.level.price.Shift(2).IntPart()) } } func (e *Engine) best(side string) *level { if side == "BUY" { if n := e.asks.Left(); n != nil { return n.Value.(*level) } } if side == "SELL" { if n := e.bids.Right(); n != nil { return n.Value.(*level) } } return nil } func (e *Engine) release(o *Order, q decimal.Decimal) { asset, amount := "ETH", q if o.Side == "BUY" { asset, amount = "USDT", d(o.Price).Mul(q) } e.move(o.Account, asset, amount, amount.Neg()) } func (e *Engine) place(c Command, r *Result) { price, okP := Parse(c.Price, 2, "1000000") quantity, okQ := Parse(c.Quantity, 4, "1000000") if !okP || !okQ || (c.Side != "BUY" && c.Side != "SELL") { r.Code = "INVALID_ORDER" return } // 教学版只有 LIMIT GTC;资金校验必须在任何订单簿变更之前。 asset, needed := "ETH", quantity if c.Side == "BUY" { asset, needed = "USDT", price.Mul(quantity) } if d(e.balance(c.Account, asset).Available).LessThan(needed) { r.Code = "INSUFFICIENT_FUNDS" return } e.move(c.Account, asset, needed.Neg(), needed) o := &Order{ID: strconv.FormatInt(c.Seq, 10), Account: c.Account, Side: c.Side, Price: price.String(), Quantity: quantity.String(), Remaining: quantity.String(), Filled: "0", Canceled: "0", Status: "OPEN"} e.orders[o.ID] = o r.Order = o for d(o.Remaining).IsPositive() { l := e.best(c.Side) if l == nil { break } if c.Side == "BUY" && l.price.GreaterThan(price) { break } if c.Side == "SELL" && l.price.LessThan(price) { break } maker := l.queue.Front().Value.(*Order) if maker.Account == o.Account { // cancel_taker:停止新单,原先自己的挂单保留。 e.release(o, d(o.Remaining)) o.Canceled = o.Remaining o.Remaining = "0" o.Status = "CANCELED" break } q := decimal.Min(d(o.Remaining), d(maker.Remaining)) buyer, seller := o, maker if c.Side == "SELL" { buyer, seller = maker, o } cost := l.price.Mul(q) reserved := d(buyer.Price).Mul(q) e.move(buyer.Account, "USDT", reserved.Sub(cost), reserved.Neg()) e.move(buyer.Account, "ETH", q, decimal.Zero) e.move(seller.Account, "ETH", decimal.Zero, q.Neg()) e.move(seller.Account, "USDT", cost, decimal.Zero) r.Trades = append(r.Trades, Trade{fmt.Sprintf("%d/%d", c.Seq, len(r.Trades)), maker.ID, o.ID, l.price.String(), q.String()}) for _, item := range []*Order{maker, o} { item.Remaining = d(item.Remaining).Sub(q).String() item.Filled = d(item.Filled).Add(q).String() item.Status = "PARTIALLY_FILLED" if item.Remaining == "0" { item.Status = "FILLED" } } if maker.Remaining == "0" { e.remove(e.active[maker.ID]) } } if d(o.Remaining).IsPositive() { e.add(o) } } // Snapshot 复制全部状态,仅为小数据教学。最终项目改用增量投影。 func (e *Engine) Snapshot() State { s := State{Orders: []Order{}, Balances: []Balance{}} for _, o := range e.orders { s.Orders = append(s.Orders, *o) } for _, b := range e.balances { s.Balances = append(s.Balances, *b) } // map 无固定遍历顺序;排序使同一输入产生相同序列化状态。 sort.Slice(s.Orders, func(i, j int) bool { return d(s.Orders[i].ID).LessThan(d(s.Orders[j].ID)) }) sort.Slice(s.Balances, func(i, j int) bool { return s.Balances[i].Account+":"+s.Balances[i].Asset < s.Balances[j].Account+":"+s.Balances[j].Asset }) return s } |
6.3 对着代码走一遍资金算例#
e.place 先 Parse,再检查 buyer 的 Available≥315,之后 move(-315,+315)。循环选到价格100、数量2的 maker,q=min(3,2)=2。四次 move 对应:
| 对象/资产 | AvailableDelta | FrozenDelta | 解释 |
|---|---|---|---|
| 买方 USDT | +10 | -210 | 返价差并消费对应冻结 |
| 买方 ETH | +2 | 0 | 获得商品 |
| 卖方 ETH | 0 | -2 | 交付冻结商品 |
| 卖方 USDT | +200 | 0 | 收取货款 |
maker.Remaining 归零,remove 从活动簿删除;买方余量1还在簿中。撤单时 release 按原价105释放,不按当前行情。Order 原始 Quantity 不变,Filled 与 Canceled 记录去了哪里。
6.4 幂等为什么在核心里#
你点了一次下单,但网络断了,不知道是否成功。若新建另一张单会重复买入;因此重发原 account/key/内容,核心从 dedupe 返回首次结果,禁止再次冻结或成交。
相同 key、不同 Hash 返回冲突。第一次余额不足也会被记住,后来充值后应使用新 key 发新意愿。每次重试仍消费日志 Seq,首次 ResultSeq 不变,本次 ProcessedSeq 增长。
clone 的两次调用很重要:一次隔离核心订单原件与本次输出,另一次隔离首次记忆与输出。撤单后重试下单仍拿到“当时首次下单结果”,最新订单应通过查询获取。
**本章验收:**根目录运行 gofmt -w core 与 go test ./core。暂时显示 [no test files] 仅表示编译通过;下一章才验证业务。最常见错误是 import 路径写成原项目的 web3exchange、字段拼写不一致或漏掉大括号。
7. 写第一个业务单元测试#
测试是让程序自动检查“实际结果是否等于我们事先算出的结果”。测试不需要启动浏览器,也不需要真实数据库;现在只验证 Engine。
创建 core/core_test.go。Go 会自动发现以 _test.go 结尾的文件和 TestXxx 函数。t.Fatal/t.Fatalf 表示失败,不要把计算错误改成“允许一点误差”。
下面是 core/core_test.go 的完整文件:
package core import ( "fmt" "testing" ) func TestTradeAndCancel(t *testing.T) { e := New() var seq int64 apply := func(c Command) Result { seq++ c.Seq = seq // 单元测试固定摘要,真实运行时由 SHA256 计算。 c.Hash = fmt.Sprintf("%s|%s|%s|%s|%s|%s|%s", c.Kind, c.Side, c.Price, c.Quantity, c.OrderID, c.Asset, c.Amount) r := e.Apply(c) if r.Code != "" { t.Fatalf("unexpected code: %s", r.Code) } return r } apply(Command{Account: "buyer", Key: "fund-buyer", Kind: "CREDIT", Asset: "USDT", Amount: "1000"}) apply(Command{Account: "seller", Key: "fund-seller", Kind: "CREDIT", Asset: "ETH", Amount: "10"}) apply(Command{Account: "seller", Key: "sell-001", Kind: "PLACE", Side: "SELL", Price: "100", Quantity: "2"}) buy := Command{Account: "buyer", Key: "buy-0001", Kind: "PLACE", Side: "BUY", Price: "105", Quantity: "3"} first := apply(buy) if first.Order.Remaining != "1" || len(first.Trades) != 1 || first.Trades[0].Price != "100" { t.Fatalf("bad fill: %+v", first) } check := func(account, asset, available, frozen string) { t.Helper() b := e.balance(account, asset) if b.Available != available || b.Frozen != frozen { t.Fatalf("balance %+v", b) } } check("buyer", "USDT", "695", "105") check("buyer", "ETH", "2", "0") check("seller", "USDT", "200", "0") check("seller", "ETH", "8", "0") // 修改返回值,不能修改核心/记忆;也不能改变下一次重试的首次响应。 id := first.Order.ID first.Order.Remaining = "999" again := apply(buy) if !again.Replayed || again.Order.Remaining != "1" || len(again.Trades) != 0 { t.Fatalf("bad dedupe: %+v", again) } canceled := apply(Command{Account: "buyer", Key: "cancel-01", Kind: "CANCEL", OrderID: id}) if canceled.Order.Canceled != "1" || canceled.Order.Remaining != "0" { t.Fatal(canceled) } check("buyer", "USDT", "800", "0") replay := apply(buy) if replay.Order.Remaining != "1" { t.Fatal("first result changed after cancel") } // 1000 USDT 与 10 ETH 的系统总量不因成交/撤单变化。 totalUSDT := d(e.balance("buyer", "USDT").Available).Add(d(e.balance("seller", "USDT").Available)) totalETH := d(e.balance("buyer", "ETH").Available).Add(d(e.balance("seller", "ETH").Available)) if totalUSDT.String() != "1000" || totalETH.String() != "10" { t.Fatal("asset conservation broken") } } func TestParse(t *testing.T) { for _, text := range []string{"0", "-1", "01", "1e2", "1.001"} { if _, ok := Parse(text, 2, "1000000"); ok { t.Fatalf("accepted %s", text) } } if n, ok := Parse("0.10", 2, "1000000"); !ok || n.String() != "0.1" { t.Fatal(n, ok) } } // 相同价格只按入簿顺序决定maker;自成交不挪走原挂单。 func TestFIFOAndSelfTrade(t *testing.T) { e := New() var seq int64 apply := func(c Command) Result { seq++ c.Seq = seq c.Hash = c.Key // 每项测试输入使用独立key,不测试重试摘要。 r := e.Apply(c) if r.Code != "" { t.Fatalf("unexpected code: %s", r.Code) } return r } apply(Command{Account:"seller",Key:"fund-seller",Kind:"CREDIT",Asset:"ETH",Amount:"10"}) apply(Command{Account:"buyer",Key:"fund-buyer",Kind:"CREDIT",Asset:"USDT",Amount:"1000"}) apply(Command{Account:"seller",Key:"fund-quote",Kind:"CREDIT",Asset:"USDT",Amount:"1000"}) first := apply(Command{Account:"seller",Key:"sell-001",Kind:"PLACE",Side:"SELL",Price:"100",Quantity:"1"}) second := apply(Command{Account:"seller",Key:"sell-002",Kind:"PLACE",Side:"SELL",Price:"100",Quantity:"1"}) buy := apply(Command{Account:"buyer",Key:"buy-0001",Kind:"PLACE",Side:"BUY",Price:"100",Quantity:"1"}) if len(buy.Trades)!=1 || buy.Trades[0].Maker!=first.Order.ID { t.Fatalf("FIFO broken: %+v", buy) } ownBuy := apply(Command{Account:"seller",Key:"self-buy",Kind:"PLACE",Side:"BUY",Price:"100",Quantity:"1"}) if ownBuy.Order.Status!="CANCELED" || ownBuy.Order.Canceled!="1" || len(ownBuy.Trades)!=0 { t.Fatalf("self trade was not canceled: %+v", ownBuy) } if e.orders[second.Order.ID].Remaining!="1" || e.active[second.Order.ID]==nil { t.Fatal("existing maker changed by self trade") } b := e.balance("seller","USDT") if b.Available!="1100" || b.Frozen!="0" { t.Fatalf("self trade reserve not released: %+v",b) } } |
根目录执行:
go test -count=1 -v ./core
|
你应该看到 TestTradeAndCancel、TestParse、TestFIFOAndSelfTrade 均 PASS。-count=1 要求重新执行,避免成功缓存。测试刻意修改 first.Order.Remaining 再重试,证明外部对象不能污染核心或首次结果;这比只测返回码更有价值。
动手练习:
- 买单价格从105改为99,应该没有成交;买方冻结297,卖方仍冻结2 ETH。增加独立测试,不改原来的算例。
- 两张同价卖单依次到达,各卖1,买1应先成交最早的 Maker;断言成交 Maker ID,而不只检查数量。
- 第一次余额不足后,用同 key 重试仍拒绝;给新 key 才能表达新的业务意愿。
- 用另一个 Account 撤此买单应 FORBIDDEN,资金与挂单完全不变。
先尝试自己写。最终仓库的 engine_test.go ↗、unit_test.go ↗ 是进阶参考;它们使用完整项目 DTO,不能原样放进 exchangelearn。
8. 写单写者运行时与 SQLite 日志#
8.1 先理解为什么不让 HTTP 直接调用 Apply#
Go 的 HTTP 可以同时处理很多请求。如果每个 handler 都调用 Engine.Apply,多个人会同时读写 map、余额、链表。给它们都上锁会带来复杂的锁顺序;这里将所有输入排队,只有一个 goroutine 拿到核心并修改状态。
单写者是状态所有权规则,不是整个服务只有一个线程。HTTP、密码哈希、数据库读写都在外围。我们采用 LMAX 的单写者思路,通过有界 Go channel 实现,未移植 Disruptor 环形缓冲。
教学版先用下面流程:
Submit → input → writer(SQLite FULL Commit) → durable → 核心 Apply → results → projector(保存完整视图) → 回包 |
最终版回包位置不同:投影 worker 先复制并回包,再做增量批投影。教学版等投影成功后回包,先减少新手对查询滞后的困惑,第16章再正式改变语义。
8.2 SQL 的最低知识#
表像带规则的表格,行是一条记录,列是字段。主键保证编号唯一。INSERT 新增,SELECT 读取,UPDATE 改已有行,DELETE 删除。? 是参数占位,不把用户字符串拼进 SQL。
事务表示几条 SQL 要一起成功:Begin 开始,Commit 提交,Rollback 放弃。SQLite 的 WAL 模式允许读写协作,synchronous=FULL 是本项目的持久化配置。SQLite 自己的 WAL 与 commands 业务日志表是两层不同东西,不要把文件的 -wal 直接当成可重放命令。
journal.db 存确定性输入,views.db 存方便查询的输出;后面 auth.db 存身份。views 可重建,journal/auth 不能随意删。flock 独占整个目录,防止两套内存核心同时解释同一数据。
下面是 runtime/runtime.go 的完整文件:
package runtime import ( "context" "crypto/sha256" "database/sql" "encoding/hex" "encoding/json" "errors" "fmt" "os" "path/filepath" "exchangelearn/core" "github.com/gofrs/flock" _ "modernc.org/sqlite" ) type envelope struct { command core.Command reply chan answer result core.Result state core.State } type answer struct { result core.Result err error } type Runtime struct { journal, views *sql.DB lock *flock.Flock input, durable, results chan envelope done chan struct{} last int64 // 只有日志 writer 修改。 } // OpenDB 只由外围调用;连接限制避免不同连接使用不一致 PRAGMA。 func OpenDB(path string) (*sql.DB, error) { db, err := sql.Open("sqlite", path) if err != nil { return nil, err } db.SetMaxOpenConns(1) for _, stmt := range []string{"PRAGMA journal_mode=WAL", "PRAGMA synchronous=FULL", "PRAGMA foreign_keys=ON", "PRAGMA busy_timeout=5000"} { if _, err = db.Exec(stmt); err != nil { db.Close() return nil, err } } return db, nil } func Open(dir string) (*Runtime, error) { if err := os.MkdirAll(dir, 0700); err != nil { return nil, err } lock := flock.New(filepath.Join(dir, "instance.lock")) ok, err := lock.TryLock() if err != nil { return nil, err } if !ok { return nil, errors.New("data directory already in use") } r := &Runtime{lock: lock, input: make(chan envelope, 64), durable: make(chan envelope, 64), results: make(chan envelope, 64), done: make(chan struct{})} success := false defer func() { if !success { r.closeDB() } }() r.journal, err = OpenDB(filepath.Join(dir, "journal.db")) if err != nil { return nil, err } r.views, err = OpenDB(filepath.Join(dir, "views.db")) if err != nil { return nil, err } if _, err = r.journal.Exec(`CREATE TABLE IF NOT EXISTS commands( seq INTEGER PRIMARY KEY,payload TEXT NOT NULL)`); err != nil { return nil, err } if _, err = r.views.Exec(`CREATE TABLE IF NOT EXISTS projection( id INTEGER PRIMARY KEY CHECK(id=1),seq INTEGER NOT NULL,payload TEXT NOT NULL); CREATE TABLE IF NOT EXISTS results( seq INTEGER PRIMARY KEY,account TEXT NOT NULL,key TEXT NOT NULL,payload TEXT NOT NULL)`); err != nil { return nil, err } // 启动时重放全部输入;教学版清空可重建的 views,不清空 journal/auth。 if _, err = r.views.Exec(`DELETE FROM projection; DELETE FROM results`); err != nil { return nil, err } e := core.New() rows, err := r.journal.Query(`SELECT seq,payload FROM commands ORDER BY seq`) if err != nil { return nil, err } for rows.Next() { var seq int64 var raw string var c core.Command if err = rows.Scan(&seq, &raw); err != nil { break } if err = json.Unmarshal([]byte(raw), &c); err != nil { break } if c.Seq != seq || seq != r.last+1 { err = errors.New("invalid journal sequence") break } result := e.Apply(c) if err = r.project(envelope{command: c, result: result, state: e.Snapshot()}); err != nil { break } r.last = seq } if err == nil { err = rows.Err() } rows.Close() if err != nil { return nil, err } if r.last == 0 { if err = r.project(envelope{state: e.Snapshot()}); err != nil { return nil, err } } go r.write() go r.run(e) go r.consume() success = true return r, nil } func (r *Runtime) Submit(ctx context.Context, c core.Command) (core.Result, error) { // 序号不信任客户端;摘要只包括业务内容,不包括每次重试的日志位置。 c.Seq = 0 c.Hash = "" raw, err := json.Marshal(c) if err != nil { return core.Result{}, err } sum := sha256.Sum256(raw) c.Hash = hex.EncodeToString(sum[:]) msg := envelope{command: c, reply: make(chan answer, 1)} select { case <-ctx.Done(): return core.Result{}, ctx.Err() default: } select { case r.input <- msg: default: return core.Result{}, errors.New("OVERLOADED") } select { case a := <-msg.reply: return a.result, a.err case <-ctx.Done(): return core.Result{}, errors.New("RESULT_UNKNOWN") } } func (r *Runtime) write() { defer close(r.durable) var failed error for msg := range r.input { if failed != nil { msg.reply <- answer{err: failed} continue } if r.last == int64(1<<63-1) { failed = errors.New("sequence exhausted") msg.reply <- answer{err: failed} continue } msg.command.Seq = r.last + 1 raw, err := json.Marshal(msg.command) var tx *sql.Tx if err == nil { tx, err = r.journal.Begin() } if err == nil { _, err = tx.Exec(`INSERT INTO commands(seq,payload) VALUES(?,?)`, msg.command.Seq, string(raw)) if err == nil { err = tx.Commit() } else { tx.Rollback() } } if err != nil { failed = fmt.Errorf("journal unavailable: %w", err) msg.reply <- answer{err: failed} continue } r.last = msg.command.Seq r.durable <- msg // Commit 成功后,才允许修改核心业务状态。 } } func (r *Runtime) run(e *core.Engine) { defer close(r.results) for msg := range r.durable { msg.result = e.Apply(msg.command) msg.state = e.Snapshot() r.results <- msg } } func (r *Runtime) project(msg envelope) error { state, err := json.Marshal(msg.state) if err != nil { return err } result, err := json.Marshal(msg.result) if err != nil { return err } tx, err := r.views.Begin() if err != nil { return err } defer tx.Rollback() if _, err = tx.Exec(`INSERT INTO projection(id,seq,payload) VALUES(1,?,?) ON CONFLICT(id) DO UPDATE SET seq=excluded.seq,payload=excluded.payload`, msg.command.Seq, string(state)); err != nil { return err } if msg.command.Seq > 0 { if _, err = tx.Exec(`INSERT INTO results(seq,account,key,payload) VALUES(?,?,?,?)`, msg.command.Seq, msg.command.Account, msg.command.Key, string(result)); err != nil { return err } } return tx.Commit() } func (r *Runtime) consume() { defer close(r.done) var failed error for msg := range r.results { if failed == nil { failed = r.project(msg) } // 投影失败后继续回未知结果,但停止发布新视图;重启从权威日志重建。 if failed != nil { msg.reply <- answer{err: errors.New("RESULT_UNKNOWN")} } else { msg.reply <- answer{result: msg.result} } } } func (r *Runtime) State(ctx context.Context) (core.State, error) { var raw string var s core.State err := r.views.QueryRowContext(ctx, `SELECT payload FROM projection WHERE id=1`).Scan(&raw) if err != nil { return s, err } err = json.Unmarshal([]byte(raw), &s) return s, err } func (r *Runtime) closeDB() { if r.views != nil { r.views.Close() } if r.journal != nil { r.journal.Close() } if r.lock != nil { r.lock.Unlock() } } // Close 必须在 HTTP Shutdown 等待所有 handler 结束之后调用,不能与 Submit 并发。 func (r *Runtime) Close() { close(r.input); <-r.done; r.closeDB() } |
8.3 按顺序理解五个函数#
- Open:取得目录锁,开库建表,按 Seq 重放历史,再启动三个 worker。未恢复完不监听 HTTP。
- Submit:固定摘要,尝试入有界 input,发送后只等自己的 reply。reply 容量1,客户端不等了也不会堵死回包。
- write:分配连续 Seq,事务 INSERT+Commit,成功才发到 durable。已提交不能因浏览器取消等待就删掉。
- run:唯一持有 Engine;Apply 后得到独立 Snapshot,交给外围 JSON/SQL。
- consume:将视图与结果置于同一事务;状态序号也一起提交。Close 关闭接入后按 channel 方向排空。
客户端取消不等于撤单。一旦入队,其后取消等待仍可能执行,返回 RESULT_UNKNOWN;不能替它生成新 key。日志提交报错也可能是未知提交边界,教学版封住 writer 后续写入并保留原键确认能力。
8.4 教学版有意保留的限制#
每条命令复制/写出整个状态,数据一多会很慢;日志单条提交没有批处理;启动重放会清空并全量重建 views;没有 dataset/版本、防投影故障的完整 fail-fast、全流程 inflight 或关闭超时治理。writer 失败后不再接受新日志,投影失败后返回未知,但教学进程没有最终版完整健康退场机制。
因此它适合小数据学习,不是最终项目的性能实现。**不要为了“优化”将 Snapshot 放到 HTTP goroutine 直接读 Engine。**正确升级是 core 产出增量副本,外围独立维护查询投影。
本章验收:gofmt -w runtime、go test ./... 都通过;还未启动服务器,不应出现业务数据目录。若“undefined core”先检查模块名和 import;SQL 错误先读完整原始报错。
9. 写注册、登录、会话和管理员身份#
9.1 分清四个概念#
注册建立身份;登录验证密码;会话让后续请求知道“是谁”;权限决定“他能做什么”。管理员也是一个用户,区别是后端数据库记录 role=ADMIN,而不是前端传个 role 就能提权。
密码不存明文,也不自己拿普通 SHA256 哈希密码。bcrypt 专门做带盐且有计算成本的密码摘要;SHA256 在这里用于随机会话 token 的索引摘要。浏览器拿随机 token 放 Cookie,数据库只保存其 hash,随机性来自 crypto/rand。
HttpOnly 让页面 JavaScript 不能读取会话 Cookie;CSRF token 则由登录响应返回,后续写操作附在请求头。Origin 校验检查网页来自哪里,CSRF 检查网页是否持有会话配套的写凭证,RBAC 检查账号角色;三者分工不同。
下面是 auth/auth.go 的完整文件:
package auth import ( "context" "crypto/rand" "crypto/sha256" "database/sql" "encoding/hex" "errors" "net/mail" "strings" "time" "golang.org/x/crypto/bcrypt" ) type User struct { ID string `json:"id"` Email string `json:"email"` Role string `json:"role"` Disabled bool `json:"disabled"` } type Store struct{ DB *sql.DB } func New(db *sql.DB) (*Store, error) { _, err := db.Exec(`CREATE TABLE IF NOT EXISTS users( id TEXT PRIMARY KEY,email TEXT NOT NULL UNIQUE,hash TEXT NOT NULL, role TEXT NOT NULL CHECK(role IN ('USER','ADMIN')),disabled INTEGER NOT NULL DEFAULT 0); CREATE TABLE IF NOT EXISTS sessions( hash TEXT PRIMARY KEY,user_id TEXT NOT NULL REFERENCES users(id), csrf TEXT NOT NULL,expires INTEGER NOT NULL)`) return &Store{db}, err } func token() (string, error) { b := make([]byte, 32) _, err := rand.Read(b) return hex.EncodeToString(b), err } func hash(s string) string { n := sha256.Sum256([]byte(s)); return hex.EncodeToString(n[:]) } func email(s string) (string, error) { s = strings.ToLower(strings.TrimSpace(s)) a, err := mail.ParseAddress(s) if err != nil || a.Address != s || !strings.Contains(s, "@") { return "", errors.New("invalid email") } return s, nil } // Create 的 role 来自可信调用者,公开注册 handler 必须固定 USER。 func (s *Store) Create(ctx context.Context, address, password, role string) (User, error) { var u User address, err := email(address) if err != nil { return u, err } if len(password) < 12 || len(password) > 72 { return u, errors.New("password requires 12–72 bytes") } if role != "USER" && role != "ADMIN" { return u, errors.New("invalid role") } digest, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost) if err != nil { return u, err } id, err := token() if err != nil { return u, err } u = User{id, address, role, false} _, err = s.DB.ExecContext(ctx, `INSERT INTO users(id,email,hash,role) VALUES(?,?,?,?)`, id, address, string(digest), role) return u, err } func (s *Store) Bootstrap(ctx context.Context, address, password string) (User, error) { var u User address, err := email(address) if err != nil { return u, err } err = s.DB.QueryRowContext(ctx, `SELECT id,email,role,disabled FROM users WHERE email=?`, address). Scan(&u.ID, &u.Email, &u.Role, &u.Disabled) if err == nil { if u.Role != "ADMIN" || u.Disabled { return u, errors.New("existing account is not an active admin") } return u, nil // 不把原有普通用户提权,不改已有管理员密码。 } if !errors.Is(err, sql.ErrNoRows) { return u, err } return s.Create(ctx, address, password, "ADMIN") } func (s *Store) Login(ctx context.Context, address, password string) (User, error) { var u User var digest string address, err := email(address) if err != nil { return u, errors.New("invalid credentials") } err = s.DB.QueryRowContext(ctx, `SELECT id,email,role,disabled,hash FROM users WHERE email=?`, address). Scan(&u.ID, &u.Email, &u.Role, &u.Disabled, &digest) if err != nil { return u, errors.New("invalid credentials or auth unavailable") } if u.Disabled || bcrypt.CompareHashAndPassword([]byte(digest), []byte(password)) != nil { return User{}, errors.New("invalid credentials") } return u, nil } func (s *Store) NewSession(ctx context.Context, user string) (string, string, error) { t, err := token() if err != nil { return "", "", err } csrf, err := token() if err != nil { return "", "", err } _, err = s.DB.ExecContext(ctx, `INSERT INTO sessions(hash,user_id,csrf,expires) VALUES(?,?,?,?)`, hash(t), user, csrf, time.Now().Add(24*time.Hour).Unix()) return t, csrf, err } func (s *Store) Session(ctx context.Context, t string) (User, string, error) { var u User var csrf string err := s.DB.QueryRowContext(ctx, `SELECT u.id,u.email,u.role,u.disabled,s.csrf FROM sessions s JOIN users u ON u.id=s.user_id WHERE s.hash=? AND s.expires>? AND u.disabled=0`, hash(t), time.Now().Unix()). Scan(&u.ID, &u.Email, &u.Role, &u.Disabled, &csrf) return u, csrf, err } func (s *Store) Logout(ctx context.Context, t string) error { _, err := s.DB.ExecContext(ctx, `DELETE FROM sessions WHERE hash=?`, hash(t)) return err } // Disable 将状态变更与注销所有旧会话放在同一事务。 func (s *Store) Disable(ctx context.Context, id string, disabled bool) error { tx, err := s.DB.BeginTx(ctx, nil) if err != nil { return err } defer tx.Rollback() res, err := tx.ExecContext(ctx, `UPDATE users SET disabled=? WHERE id=? AND role='USER'`, disabled, id) if err != nil { return err } n, err := res.RowsAffected() if err != nil { return err } if n != 1 { return errors.New("user not found or is admin") } if disabled { if _, err = tx.ExecContext(ctx, `DELETE FROM sessions WHERE user_id=?`, id); err != nil { return err } } return tx.Commit() } |
按 Create→Login→NewSession→Session→Disable 理解。Create 只管理身份,不直接改交易余额;资金必须进入 CREDIT 日志。密码长度按 UTF-8 字节算,12–72;中文字符不一定一字一字节。
会话有效期是创建后24小时,不访问续期。Disable 更新用户并删除全部旧会话,在一个事务里完成;重新启用仍需重新登录,不能复活删除的 token。停用不是自动撤单,已存在挂单仍可能成交。
Bootstrap 只能创建新管理员或返回已有管理员,不能把同邮箱普通用户提升权限,也不覆盖已有管理员密码。教学版先使用邮箱管理员与长密码;最终 Windows 指定短密码模式在第21章单独解释。
教学版将部分认证数据库故障合并为认证失败,最终版需区分 401 与 AUTH_UNAVAILABLE,并补认证限流、审计和更完整邮箱校验。创建临时用户测试也会做 bcrypt,测试稍慢不是撮合线程被阻塞。
本章验收:gofmt -w auth、go test ./... 通过。不要输出 digest/Cookie/CSRF 到日志来“检查是否成功”,下一章通过真实登录接口验证。
10. 写 HTTP 接口与权限校验#
10.1 先列清楚接口#
| 教学接口 | 身份要求 | 用途 |
|---|---|---|
| GET /health | 无 | 初步健康检查 |
| POST /api/auth/register、/login | 无;检查 Origin | 注册/登录 |
| GET /api/auth/me | 登录 | 页面刷新恢复身份和CSRF |
| POST /api/auth/logout | 登录+CSRF | 退出当前会话 |
| GET /api/state | 登录 | 仅当前账户的订单/余额 |
| POST /api/orders | 登录+CSRF+幂等键 | 限价GTC |
| POST /api/orders/{id}/cancel | 登录+CSRF+幂等键 | 撤自己的订单 |
| GET /api/admin/users | ADMIN | 用户列表 |
| PATCH /api/admin/users/{id} | ADMIN+CSRF | 停用/启用普通用户 |
| POST /api/admin/credits | ADMIN+CSRF+幂等键 | 正向增加模拟资金 |
GET /api/state 不能把全体用户余额返回出去。即使页面不显示,数据已经发给浏览器就泄露了。核心 RESULT 只带本次必要交易结果;State 是供投影使用的全量内部副本,读取 handler 必须过滤。
新建下面文件。protected 统一做 Cookie/Origin/角色/CSRF 检查,但“订单是否属于当前用户”仍由核心 CANCEL 检查。注册请求体不提供 Role 字段,严格 JSON 解码会拒绝客户端自行塞入未知字段。
下面是 transport/http.go 的完整文件:
package transport import ( "context" "crypto/subtle" "encoding/json" "errors" "io" "net/http" "regexp" "exchangelearn/auth" "exchangelearn/core" rt "exchangelearn/runtime" ) type Server struct { Auth *auth.Store Runtime *rt.Runtime Origin string } func write(w http.ResponseWriter, status int, value any) { w.Header().Set("Content-Type", "application/json") w.WriteHeader(status) _ = json.NewEncoder(w).Encode(value) } func fail(w http.ResponseWriter, status int, message string) { write(w, status, map[string]string{"error": message}) } func read(w http.ResponseWriter, r *http.Request, v any) bool { r.Body = http.MaxBytesReader(w, r.Body, 16<<10) decoder := json.NewDecoder(r.Body) decoder.DisallowUnknownFields() if err := decoder.Decode(v); err != nil { fail(w, 400, "invalid JSON") return false } var extra any if err := decoder.Decode(&extra); !errors.Is(err, io.EOF) { fail(w, 400, "only one JSON value allowed") return false } return true } func (s *Server) origin(w http.ResponseWriter, r *http.Request) bool { if o := r.Header.Get("Origin"); o != "" && o != s.Origin { fail(w, 403, "origin rejected") return false } return true } func (s *Server) protected(admin bool, next func(http.ResponseWriter, *http.Request, auth.User)) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { if !s.origin(w, r) { return } cookie, err := r.Cookie("exchange_session") if err != nil { fail(w, 401, "login required") return } u, csrf, err := s.Auth.Session(r.Context(), cookie.Value) if err != nil { fail(w, 401, "session unavailable") return } if admin && u.Role != "ADMIN" { fail(w, 403, "admin required") return } if r.Method != "GET" && subtle.ConstantTimeCompare([]byte(r.Header.Get("X-CSRF-Token")), []byte(csrf)) != 1 { fail(w, 403, "csrf rejected") return } next(w, r, u) } } // Fund 固定幂等键可修复身份成功但初始化资金中断的情况。 func (s *Server) Fund(ctx context.Context, id string) error { for _, v := range []struct{ asset, amount string }{{"ETH", "10"}, {"USDT", "100000"}} { result, err := s.Runtime.Submit(ctx, core.Command{Account: id, Kind: "CREDIT", Key: "system.initial." + v.asset, Asset: v.asset, Amount: v.amount}) if err != nil { return err } if result.Code != "" { return errors.New(result.Code) } } return nil } func (s *Server) login(register bool) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { if !s.origin(w, r) { return } var body struct { Email string `json:"email"` Password string `json:"password"` } if !read(w, r, &body) { return } var u auth.User var err error if register { u, err = s.Auth.Create(r.Context(), body.Email, body.Password, "USER") } else { u, err = s.Auth.Login(r.Context(), body.Email, body.Password) } if err != nil { fail(w, 400, "registration or login failed") return } if err = s.Fund(r.Context(), u.ID); err != nil { fail(w, 503, "funding incomplete; retry login") return } token, csrf, err := s.Auth.NewSession(r.Context(), u.ID) if err != nil { fail(w, 503, "session unavailable") return } http.SetCookie(w, &http.Cookie{Name: "exchange_session", Value: token, Path: "/", HttpOnly: true, SameSite: http.SameSiteStrictMode, MaxAge: 86400}) write(w, 200, map[string]any{"user": u, "csrf": csrf}) } } var keyPattern = regexp.MustCompile(`^[A-Za-z0-9_.-]{8,128}$`) func key(w http.ResponseWriter, r *http.Request) string { k := r.Header.Get("Idempotency-Key") if !keyPattern.MatchString(k) || len(k) >= 7 && k[:7] == "system." { fail(w, 400, "invalid idempotency key") return "" } return k } func (s *Server) submit(w http.ResponseWriter, r *http.Request, c core.Command) { result, err := s.Runtime.Submit(r.Context(), c) if err != nil { fail(w, 503, "RESULT_UNKNOWN or unavailable; retry original key/body") return } status := 200 if result.Code != "" { status = 422 } write(w, status, result) } func (s *Server) Handler() http.Handler { m := http.NewServeMux() m.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) { write(w, 200, map[string]string{"status": "ok"}) }) m.HandleFunc("POST /api/auth/register", s.login(true)) m.HandleFunc("POST /api/auth/login", s.login(false)) m.HandleFunc("GET /api/auth/me", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) { c, _ := r.Cookie("exchange_session") _, csrf, err := s.Auth.Session(r.Context(), c.Value) if err != nil { fail(w, 503, "auth unavailable") return } write(w, 200, map[string]any{"user": u, "csrf": csrf}) })) m.HandleFunc("POST /api/auth/logout", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) { c, _ := r.Cookie("exchange_session") if err := s.Auth.Logout(r.Context(), c.Value); err != nil { fail(w, 503, "logout failed") return } http.SetCookie(w, &http.Cookie{Name: "exchange_session", Value: "", Path: "/", HttpOnly: true, SameSite: http.SameSiteStrictMode, MaxAge: -1}) write(w, 200, map[string]bool{"ok": true}) })) m.HandleFunc("GET /api/state", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) { state, err := s.Runtime.State(r.Context()) if err != nil { fail(w, 503, "query failed") return } visible := core.State{Orders: []core.Order{}, Balances: []core.Balance{}} for _, o := range state.Orders { if o.Account == u.ID { visible.Orders = append(visible.Orders, o) } } for _, b := range state.Balances { if b.Account == u.ID { visible.Balances = append(visible.Balances, b) } } write(w, 200, visible) })) m.HandleFunc("POST /api/orders", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) { k := key(w, r) if k == "" { return } var body struct { Side string `json:"side"` Price string `json:"price"` Quantity string `json:"quantity"` } if !read(w, r, &body) { return } s.submit(w, r, core.Command{Account: u.ID, Key: k, Kind: "PLACE", Side: body.Side, Price: body.Price, Quantity: body.Quantity}) })) m.HandleFunc("POST /api/orders/{id}/cancel", s.protected(false, func(w http.ResponseWriter, r *http.Request, u auth.User) { k := key(w, r) if k == "" { return } s.submit(w, r, core.Command{Account: u.ID, Key: k, Kind: "CANCEL", OrderID: r.PathValue("id")}) })) m.HandleFunc("GET /api/admin/users", s.protected(true, func(w http.ResponseWriter, r *http.Request, u auth.User) { rows, err := s.Auth.DB.QueryContext(r.Context(), `SELECT id,email,role,disabled FROM users ORDER BY rowid`) if err != nil { fail(w, 503, "query failed") return } defer rows.Close() users := []auth.User{} for rows.Next() { var v auth.User if err = rows.Scan(&v.ID, &v.Email, &v.Role, &v.Disabled); err != nil { fail(w, 503, "query failed") return } users = append(users, v) } if rows.Err() != nil { fail(w, 503, "query failed") return } write(w, 200, users) })) m.HandleFunc("PATCH /api/admin/users/{id}", s.protected(true, func(w http.ResponseWriter, r *http.Request, u auth.User) { var body struct { Disabled *bool `json:"disabled"` } if !read(w, r, &body) { return } if body.Disabled == nil { fail(w, 400, "disabled required") return } if err := s.Auth.Disable(r.Context(), r.PathValue("id"), *body.Disabled); err != nil { fail(w, 400, "update failed") return } write(w, 200, map[string]bool{"ok": true}) })) m.HandleFunc("POST /api/admin/credits", s.protected(true, func(w http.ResponseWriter, r *http.Request, u auth.User) { k := key(w, r) if k == "" { return } var body struct { Account string `json:"account"` Asset string `json:"asset"` Amount string `json:"amount"` Reason string `json:"reason"` } if !read(w, r, &body) { return } var exists int if body.Reason == "" || s.Auth.DB.QueryRowContext(r.Context(), `SELECT 1 FROM users WHERE id=?`, body.Account).Scan(&exists) != nil { fail(w, 400, "target/reason invalid") return } // 操作者、原因也进入摘要和日志;最终版再增加独立执行审计表。 s.submit(w, r, core.Command{Account: body.Account, Key: "admin." + u.ID + "." + k, Kind: "CREDIT", Asset: body.Asset, Amount: body.Amount, Actor: u.ID, Reason: body.Reason}) })) m.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) { fail(w, 404, "route not found") }) m.Handle("/", http.FileServer(http.Dir("frontend/dist"))) return m } |
10.2 初始资金为什么要使用固定键#
注册身份提交后,ETH 注资成功但 USDT 注资失败是可能的,因为 auth、journal 不在一个跨库事务里。不能假装一切原子完成。
Fund 每次使用同一账号的 system.initial.ETH/USDT。登录时再调用:已完成那笔只返回首次结果,未完成那笔补齐。因此不能把 Key 改成每次随机值,否则每次登录都送钱。
管理员注资的目标 Account 与操作者不同,key 加 admin.<操作者ID> 前缀,Actor/Reason 也进入摘要和日志。教学版没有独立执行审计表,最终版要补,让操作原因、执行结果与水位能查询。
10.3 严格输入比“能解析”多一层#
限制16KB请求体,拒绝未知字段,拒绝一段正文含两个JSON。下单 Account 只从会话取得,前端只传 side/price/quantity。幂等键限定字符与长度,system.前缀留给内部初始化。
本地 teaching 的 Cookie 不带 Secure,是因为使用 HTTP。云端 HTTPS 必须启用 Secure,后面最终配置支持此开关。教学 /health 仅表示接口可响应,最终项目分 live 与 ready,并让后台存储故障反映到 ready。
本章验收:gofmt -w transport、go test ./...。先不用手动构造 Cookie;前端会自动管理它,13章集成测试再直接检验 HTTP 权限。
11. 把后端装配起来#
现在替换第3章的 cmd/server/main.go 为下方完整文件。装配顺序是 runtime恢复→auth→管理员初始化→HTTP;启动错误必须退出,不能打印“成功”继续假跑。
下面是 cmd/server/main.go 的完整文件:
package main import ( "context" "errors" "log" "net/http" "os" "os/signal" "path/filepath" "syscall" "time" "exchangelearn/auth" rt "exchangelearn/runtime" "exchangelearn/transport" ) func main() { if err := run(); err != nil { log.Fatal(err) } } func run() error { runtime, err := rt.Open("data") if err != nil { return err } defer runtime.Close() db, err := rt.OpenDB(filepath.Join("data", "auth.db")) if err != nil { return err } defer db.Close() users, err := auth.New(db) if err != nil { return err } server := &transport.Server{Auth: users, Runtime: runtime, Origin: "http://127.0.0.1:5173"} if email := os.Getenv("LEARN_ADMIN_EMAIL"); email != "" { u, err := users.Bootstrap(context.Background(), email, os.Getenv("LEARN_ADMIN_PASSWORD")) if err != nil { return err } if err = server.Fund(context.Background(), u.ID); err != nil { return err } } httpServer := &http.Server{Addr: "127.0.0.1:8080", Handler: server.Handler(), ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second, WriteTimeout: 15 * time.Second} ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() done := make(chan error, 1) go func() { done <- httpServer.ListenAndServe() }() log.Print("backend http://127.0.0.1:8080; frontend http://127.0.0.1:5173") select { case err = <-done: if !errors.Is(err, http.ErrServerClosed) { return err } case <-ctx.Done(): // 教学版先 Shutdown 所有 HTTP handler,再排空 runtime,满足 Close 的前提。 // 超时直接退出进程,不在仍有 handler Submit 时 close(input)。 shutdown, cancel := context.WithTimeout(context.Background(), 20*time.Second) defer cancel() if err = httpServer.Shutdown(shutdown); err != nil { log.Print(err) os.Exit(1) } } return nil } |
根目录 PowerShell 中执行以下命令,演示密码只用于你自己的练习目录:
$env:LEARN_ADMIN_EMAIL="admin@example.com" $env:LEARN_ADMIN_PASSWORD="learn-admin-password" go mod tidy gofmt -w core runtime auth transport cmd go test ./... go run ./cmd/server |
新窗口执行 Invoke-RestMethod http://127.0.0.1:8080/health 应返回 ok。第一次启动出现 data/journal.db、data/views.db、data/auth.db、锁文件及可能的 WAL/SHM。别手工编辑运行中的库。
终端环境变量只影响该终端启动的子程序;重开终端要重新设置。LEARN_ 是教学版参数,最终服务使用 EXCHANGE_,两者不能混用。
关闭时先 Shutdown HTTP,确保没有 handler 再 Submit,才关闭 input 和数据库。这是教学 Close 的明确调用前提。最终版支持并发关闭受理、排空、期限和故障退场,不要把教学版 Close 拷到最终运行时。
练习:关闭再启动后,用同管理员登录,不应得到新ID或重复初始资金;普通账号与订单也保留。管理员同邮箱已存在时新环境密码不会覆盖原密码。
12. 从空目录写 React 交易页面#
12.1 浏览器需要另一套语言和构建工具#
HTML描述页面结构,CSS描述外观,JavaScript描述交互。TypeScript 在 JavaScript 上加编译期类型检查;浏览器最终运行编译后的 JavaScript。React 把页面写成组件,Vite负责开发服务器与打包。Go不会直接执行TSX。
不要用 create-vite@latest 生成不同版本的模板。下面从空 frontend 目录明确创建文件,固定本项目的版本。
下面是 frontend/package.json 的完整文件:
{ "name": "exchangelearn-web", "version": "0.0.1", "private": true, "type": "module", "scripts": { "dev": "vite --host 127.0.0.1", "build": "tsc -b && vite build" }, "dependencies": { "react": "19.1.0", "react-dom": "19.1.0" }, "devDependencies": { "@types/react": "19.1.0", "@types/react-dom": "19.1.1", "@vitejs/plugin-react": "4.4.1", "typescript": "5.8.3", "vite": "6.4.4" } } |
下面是 frontend/tsconfig.json 的完整文件:
{ "compilerOptions": { "target": "ES2022", "lib": ["ES2022", "DOM", "DOM.Iterable"], "module": "ESNext", "moduleResolution": "Bundler", "jsx": "react-jsx", "strict": true, "skipLibCheck": true, "noEmit": true, "allowImportingTsExtensions": true, "esModuleInterop": true }, "include": ["src"] } |
下面是 frontend/vite.config.ts 的完整文件:
// 开发代理统一同源 /api 与 WS,Cookie/CSRF 不依赖跨域配置;生产由 Go 直接提供 dist。 import { defineConfig } from "vite"; import react from "@vitejs/plugin-react"; export default defineConfig({ plugins: [react()], server: { proxy: { "/api": { target: "http://127.0.0.1:8080", ws: true }, "/health": "http://127.0.0.1:8080", }, }, }); |
下面是 frontend/index.html 的完整文件:
<html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>模拟交易练习</title></head><body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body></html> |
下面是 frontend/src/main.tsx 的完整文件:
import React from "react"; import ReactDOM from "react-dom/client"; import App from "./App"; ReactDOM.createRoot(document.getElementById("root")!).render(<React.StrictMode><App /></React.StrictMode>); |
在根目录执行:
npm --prefix frontend install
|
第一次还没有 package-lock.json,所以用 install 创建锁文件。之后复现同版环境用 npm --prefix frontend ci;ci 要求已有且与 package.json 一致的锁文件,会重建 node_modules。不要丢掉 lock 文件,也别每次升级依赖到 latest。
代理的作用:浏览器请求 http://127.0.0.1:5173/api/orders,Vite将它转给8080后端。这样浏览器视角是同源,Cookie不用跨域配置。只在开发存在两个服务,部署时Go直接提供dist。
12.2 先认识组件中的五种写法#
useState保存界面状态,set函数更新后React重新渲染;不是可变全局变量。useEffect在组件挂载/依赖改变时做外部工作,WS和定时器需要返回清理函数。async/await等HTTP返回;等待不会让后端撤销业务。{list.map(...)}把数组转成一组页面元素,每项用稳定id作key。FormData读取表单字段,金额保持 string,不能parseFloat后再提交。
下面页面包含注册、登录、当前资金、下单、撤单、退出、管理员停用与注资。先保证行为正确,最后再增加最终项目的实时行情、分页、GSAP与响应式布局。
下面是 frontend/src/App.tsx 的完整文件:
import { FormEvent, useEffect, useState } from "react"; import "./style.css"; type User = { id: string; email: string; role: string; disabled: boolean }; type Auth = { user: User; csrf: string }; type Order = { id: string; side: string; price: string; remaining: string; status: string }; type State = { orders: Order[]; balances: { asset: string; available: string; frozen: string }[] }; type Pending = { account: string; path: string; key: string; body: unknown }; // 422 是核心已经确定的拒绝;其他异常保留原写请求供确认。 class RequestError extends Error { constructor(message: string, public known: boolean) { super(message); } } async function call<T>(path: string, csrf = "", method = "GET", body?: unknown, key?: string): Promise<T> { const response = await fetch("/api" + path, { method, credentials: "same-origin", headers: { "Content-Type": "application/json", ...(csrf ? { "X-CSRF-Token": csrf } : {}), ...(key ? { "Idempotency-Key": key } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }), }); const data = await response.json(); if (!response.ok) throw new RequestError(data.code || data.error || "请求失败", response.status === 422); return data; } export default function App() { const [auth, setAuth] = useState<Auth | null>(null); const [state, setState] = useState<State>({ orders: [], balances: [] }); const [users, setUsers] = useState<User[]>([]); const [message, setMessage] = useState(""); const [busy, setBusy] = useState(false); const [pending, setPending] = useState<Pending | null>(null); // 教学版不自动信任旧记录:只允许同一账号明确点击确认。 // 完整版 pending.ts 还验证版本、数据集、操作和每个字段。 useEffect(() => { try { const raw = sessionStorage.getItem("learn.pending"); if (raw) { const p = JSON.parse(raw); if (typeof p.account !== "string" || typeof p.path !== "string" || typeof p.key !== "string") throw new Error("待确认记录格式错误"); setPending(p); } } catch { setMessage("待确认记录无法读取,请先核对原订单"); } call<Auth>("/auth/me").then(setAuth).catch(() => {}); }, []); async function refresh(a: Auth) { setState(await call<State>("/state")); if (a.user.role === "ADMIN") setUsers(await call<User[]>("/admin/users")); } useEffect(() => { if (auth) refresh(auth).catch(e => setMessage(String(e))); }, [auth]); async function login(e: FormEvent<HTMLFormElement>) { e.preventDefault(); setBusy(true); const form = new FormData(e.currentTarget); try { const a = await call<Auth>(form.get("mode") === "register" ? "/auth/register" : "/auth/login", "", "POST", { email: String(form.get("email")), password: String(form.get("password")) }); setAuth(a); setMessage("已登录"); } catch (e) { setMessage(String(e)); } finally { setBusy(false); } } async function execute(p: Pending) { if (!auth || p.account !== auth.user.id) throw new Error("请登录原账号确认"); try { await call(p.path, auth.csrf, "POST", p.body, p.key); } catch (e) { if (e instanceof RequestError && e.known) { sessionStorage.removeItem("learn.pending"); setPending(null); } throw e; } sessionStorage.removeItem("learn.pending"); setPending(null); setMessage("操作已确认"); await refresh(auth); } async function write(path: string, body?: unknown) { if (!auth || pending || sessionStorage.getItem("learn.pending")) throw new Error("先确认之前的请求"); const p: Pending = { account: auth.user.id, path, body, key: crypto.randomUUID() }; sessionStorage.setItem("learn.pending", JSON.stringify(p)); // 保存失败就不会发送。 setPending(p); await execute(p); } async function action(fn: () => Promise<void>) { setBusy(true); try { await fn(); } catch (e) { setMessage(String(e)); } finally { setBusy(false); } } function place(e: FormEvent<HTMLFormElement>) { e.preventDefault(); const f = new FormData(e.currentTarget); void action(() => write("/orders", { side: String(f.get("side")), price: String(f.get("price")), quantity: String(f.get("quantity")) })); } function credit(e: FormEvent<HTMLFormElement>) { e.preventDefault(); const f = new FormData(e.currentTarget); void action(() => write("/admin/credits", { account: String(f.get("account")), asset: String(f.get("asset")), amount: String(f.get("amount")), reason: String(f.get("reason")) })); } return <main> <h1>ETH / USDT 模拟交易</h1> <p role="status">{message}</p> {!auth ? <form onSubmit={login}> <input name="email" type="email" placeholder="邮箱" aria-label="邮箱" required /> <input name="password" type="password" placeholder="密码,12–72 字节" aria-label="密码" required /> <select name="mode" aria-label="登录或注册"><option value="login">登录</option><option value="register">注册</option></select> <button disabled={busy}>提交</button> </form> : <> <p>{auth.user.email} · {auth.user.role}</p> <button disabled={busy} onClick={() => void action(async () => { await call("/auth/logout", auth.csrf, "POST"); setAuth(null); setState({ orders: [], balances: [] }); setUsers([]); })}>退出</button> <button disabled={busy} onClick={() => void action(() => refresh(auth))}>刷新</button> {pending && <p>有待确认请求 <button disabled={busy || pending.account !== auth.user.id} onClick={() => void action(() => execute(pending))}>原键确认</button></p>} <h2>资金</h2> {state.balances.map(b => <p key={b.asset}>{b.asset} · 可用 {b.available} · 冻结 {b.frozen}</p>)} <h2>下限价单</h2> <form onSubmit={place}> <select name="side" aria-label="方向"><option>BUY</option><option>SELL</option></select> <input name="price" placeholder="价格" aria-label="价格" required /> <input name="quantity" placeholder="数量" aria-label="数量" required /> <button disabled={busy || !!pending}>下单</button> </form> <table><thead><tr><th>订单</th><th>方向</th><th>价格</th><th>余量</th><th>状态</th><th>操作</th></tr></thead> <tbody>{state.orders.map(o => <tr key={o.id}> <td>{o.id}</td><td>{o.side}</td><td>{o.price}</td><td>{o.remaining}</td><td>{o.status}</td> <td>{o.remaining !== "0" && <button disabled={busy || !!pending} onClick={() => void action(() => write(`/orders/${o.id}/cancel`))}>撤单</button>}</td> </tr>)}</tbody></table> {auth.user.role === "ADMIN" && <> <h2>用户管理</h2> {users.map(u => <p key={u.id}>{u.email} · {u.role} · {u.disabled ? "停用" : "启用"} {u.role === "USER" && <button disabled={busy} onClick={() => void action(async () => { await call(`/admin/users/${u.id}`, auth.csrf, "PATCH", { disabled: !u.disabled }); await refresh(auth); })}>{u.disabled ? "启用" : "停用"}</button>}</p>)} <form onSubmit={credit}> <select name="account" aria-label="目标用户">{users.map(u => <option key={u.id} value={u.id}>{u.email}</option>)}</select> <select name="asset" aria-label="资产"><option>USDT</option><option>ETH</option></select> <input name="amount" placeholder="增加数量" aria-label="增加数量" required /> <input name="reason" placeholder="原因" aria-label="原因" required /> <button disabled={busy || !!pending}>增加模拟资金</button> </form> </>} </>} </main>; } |
下面是 frontend/src/style.css 的完整文件:
/* 使用 Carbon 深色体系基础色;无渐变、无圆角。先保证可用,再扩展动画。 */ :root { color: #f4f4f4; background: #161616; font-family: system-ui, sans-serif; } body { margin: 0; } main { max-width: 1000px; padding: 24px; margin: auto; } h1 { font-size: 24px; } h2 { font-size: 18px; margin-top: 24px; } form { display: flex; gap: 8px; flex-wrap: wrap; margin: 16px 0; } input, select, button { font: inherit; border-radius: 0; padding: 8px; } input, select { background: #262626; color: #f4f4f4; border: 1px solid #8d8d8d; } button { background: #0f62fe; color: white; border: 0; cursor: pointer; margin-right: 8px; } button:disabled { opacity: .5; cursor: default; } :focus-visible { outline: 2px solid white; outline-offset: 2px; } table { width: 100%; border-collapse: collapse; } th, td { border-bottom: 1px solid #525252; text-align: left; padding: 8px; } @media (max-width: 600px) { main { padding: 12px; overflow-x: auto; } input { max-width: 100%; } } |
12.3 为什么这个页面先保存再发下单#
write 创建随机幂等键和固定body,先写 sessionStorage,再调用execute。存储失败直接停止发送。断网/异常保留原请求,用户点击“原键确认”只重发同一个path/key/body,不重新读取表单。
422是教学核心确定拒绝,可以移除本次待确认记录;网络错误、会话失效或5xx不能证明此前没执行,继续保留。若删除存储失败也不能谎称记录已清理。
此教学版本只校验恢复记录的几个字段,未绑定dataset;第18章将其替换为同步校验、固定路径/请求体、数据集/账户/操作隔离的完整pending.ts。现在只用于自己新建的小数据练习,勿把这段简化恢复直接当最终实现。
开发运行(第三个终端,根目录):
npm --prefix frontend run dev
|
浏览器访问 http://127.0.0.1:5173,别把localhost与127.0.0.1交替使用,否则Origin/Cookie可能不一致。后端仍需保持运行。
构建检查:
npm --prefix frontend run build
|
看到 tsc检查成功与Vite生成dist。红线“Cannot find module react”通常是还没安装依赖或打开了错误目录;React 页面白屏先看浏览器F12→Console和Network。
本教学服务Origin固定5173,浏览器交互按5173验收。8080直出dist虽能访问文件,但登录写入会被Origin拒绝;最终项目用配置/请求同源规则处理开发与部署,21章再使用最终服务。不要删Origin校验来掩盖配置错误。
13. 操作、测试并重启你的教学项目#
13.1 做一次真实双用户成交#
保持两个服务都运行。普通浏览器注册 alice@example.com,密码 alice-password-123;另开无痕窗口注册 bob@example.com,密码 bob-password-123。两个普通标签页通常共用Cookie,不算两个独立账号会话。
- Bob以SELL,price=100,quantity=2下单,刷新:ETH可用8、冻结2。
- Alice以BUY,price=105,quantity=3下单:ETH可用12;USDT可用99695、冻结105。
- Bob刷新:ETH可用8、冻结0;USDT可用100200、冻结0。
- Alice撤买单余量:USDT可用99800、冻结0;买单FILLED数量2、CANCELED数量1、余量0(教学页面主要显示余量/状态)。
这里每个注册用户都有10ETH/100000USDT,所以数字与第5章最小单元测试起始资金不同,成交变化相同。查全库总量时要把初始化的管理员也计入,不能只加两个用户然后说资金不守恒。
管理员在第三个独立会话登录admin@example.com,能看到用户,给Alice增加5 USDT后资金为99805。停用Bob,Bob旧Cookie下一次查询应拒绝;再启用,Bob重新登录才能继续。已有挂单不会自动撤掉。
13.2 增加真实HTTP+重启测试#
下面完整测试使用临时目录、真实三库、真实bcrypt、httptest和CookieJar;不会连接你正在运行的服务,也不修改data。
下面是 transport/http_test.go 的完整文件:
package transport import ( "bytes" "context" "encoding/json" "net/http" "net/http/cookiejar" "net/http/httptest" "net/url" "path/filepath" "testing" "exchangelearn/auth" rt "exchangelearn/runtime" ) // 使用真实三库、Cookie 和处理器;每个测试拥有自己的临时数据。 func TestHTTPAndRestart(t *testing.T) { dir := t.TempDir() runtime, err := rt.Open(dir) if err != nil { t.Fatal(err) } db, err := rt.OpenDB(filepath.Join(dir, "auth.db")) if err != nil { t.Fatal(err) } users, err := auth.New(db) if err != nil { t.Fatal(err) } app := &Server{Auth: users, Runtime: runtime, Origin: "http://127.0.0.1:5173"} admin, err := users.Bootstrap(context.Background(), "admin@example.com", "learn-admin-password") if err != nil { t.Fatal(err) } if err = app.Fund(context.Background(), admin.ID); err != nil { t.Fatal(err) } server := httptest.NewServer(app.Handler()) // 清理顺序:先停止 HTTP,再关 auth,最后关 runtime。 t.Cleanup(func() { server.Close() if db != nil { db.Close() } if runtime != nil { runtime.Close() } }) jar, _ := cookiejar.New(nil) client := &http.Client{Jar: jar} request := func(method, path string, body any, csrf, key string, status int) map[string]any { t.Helper() var buf bytes.Buffer if body != nil { if err := json.NewEncoder(&buf).Encode(body); err != nil { t.Fatal(err) } } req, err := http.NewRequest(method, server.URL+path, &buf) if err != nil { t.Fatal(err) } req.Header.Set("Content-Type", "application/json") req.Header.Set("Origin", app.Origin) if csrf != "" { req.Header.Set("X-CSRF-Token", csrf) } if key != "" { req.Header.Set("Idempotency-Key", key) } resp, err := client.Do(req) if err != nil { t.Fatal(err) } defer resp.Body.Close() var result map[string]any if err = json.NewDecoder(resp.Body).Decode(&result); err != nil { t.Fatal(err) } if resp.StatusCode != status { t.Fatalf("%s: %d %+v", path, resp.StatusCode, result) } return result } a := request("POST", "/api/auth/register", map[string]string{"email": "alice@example.com", "password": "alice-password-123"}, "", "", 200) csrf := a["csrf"].(string) request("POST", "/api/orders", map[string]string{"side": "BUY", "price": "105", "quantity": "3"}, "", "buy-0001", 403) body := map[string]string{"side": "BUY", "price": "105", "quantity": "3"} first := request("POST", "/api/orders", body, csrf, "buy-0001", 200) again := request("POST", "/api/orders", body, csrf, "buy-0001", 200) if again["replayed"] != true || again["result_seq"] != first["result_seq"] { t.Fatal(again) } request("GET", "/api/admin/users", nil, "", "", 403) state, err := runtime.State(context.Background()) if err != nil { t.Fatal(err) } // HTTP 已停,才允许 Close;下面验证正常重启而非模拟断电。 server.Close() db.Close() db = nil runtime.Close() runtime = nil runtime, err = rt.Open(dir) if err != nil { t.Fatal(err) } db, err = rt.OpenDB(filepath.Join(dir, "auth.db")) if err != nil { t.Fatal(err) } // Cleanup 闭包读取重赋值后的指针,因此最终清理新 runtime/db。 users, err = auth.New(db) if err != nil { t.Fatal(err) } after, err := runtime.State(context.Background()) if err != nil { t.Fatal(err) } beforeRaw, _ := json.Marshal(state) afterRaw, _ := json.Marshal(after) if !bytes.Equal(beforeRaw, afterRaw) { t.Fatalf("replay mismatch: %s / %s", beforeRaw, afterRaw) } me, _, err := users.Session(context.Background(), jar.Cookies(mustURL(t, server.URL))[0].Value) if err != nil || me.Email != "alice@example.com" { t.Fatal(me, err) } } func mustURL(t *testing.T, raw string) *url.URL { t.Helper() u, err := url.Parse(raw) if err != nil { t.Fatal(err) } return u } |
根目录运行:
go test -count=1 -v ./... go vet ./... |
测试证明:注册资金初始化、缺CSRF被拒绝、原键重复不重复交易、普通用户不能用管理员接口、正常重启全视图一致且身份会话保留。它没有模拟突然断电,也没实际跑浏览器;后面完整项目再做故障窗口和E2E。
测试尾部先停HTTP再关Runtime,符合Close前提。Cleanup闭包读取重赋值后的runtime/db,因此最终清理新实例;不要把它改成绑定旧实例的defer而重复close队列。
13.3 到这里你已经亲手写出什么#
exchange-learn/ go.mod / go.sum / .gitignore core/core.go / core_test.go runtime/runtime.go auth/auth.go transport/http.go / http_test.go cmd/server/main.go frontend/package.json / package-lock.json frontend/tsconfig.json / vite.config.ts / index.html frontend/src/main.tsx / App.tsx / style.css data/ # 运行生成,不是源码 |
别一口气删教学代码再复制完整仓库。先尝试解释每个文件输入/输出,以及一笔单如何流经各层。接下来的章节才逐项改变它们,补齐本项目最终能力。
14. 从教学版升级到完整项目#
14.1 先保存一个可以回退的学习成果#
停掉教学服务,保留 exchange-learn 源码和自己的练习数据。接下来可以另建 exchange-full-learn,从你理解的代码重写完整版。在新目录使用 go mod init web3exchange;最终源码 import 都以 web3exchange 开头。
你已经写出来的算法和规则继续成立,但教学版数据库/路由/日志 JSON 不能直接当最终旧数据升级。教学数据在教学目录保留;完整版使用新的空数据目录。最终所谓“旧 schema=0兼容”指本项目的历史版本,不指这份教学版简化日志。
当某一步卡住,按这一顺序处理:读本章输入/输出→自己实现单个函数→编译→写或运行对应测试→和仓库同名函数对照。参考源码是有中文解释的实现答案,不要求先复制整个仓库再猜它做了什么。
14.2 最终文件应该按什么顺序创建#
| 顺序 | 创建/改写的文件 | 从教学版转过去的东西 | 新增能力 |
|---|---|---|---|
| 1 | backend/types.go、engine.go | core领域对象和算法 | 完整订单规则、增量变更、预算 |
| 2 | backend/store.go | runtime中的OpenDB/投影 | 三库schema、盘口聚合、水位/版本 |
| 3 | backend/runtime.go | 教学Runtime | 批日志、在途额度、fail-fast/关闭 |
| 4 | backend/auth.go、http.go | auth与transport | 严格校验/限流/权限、完整API |
| 5 | api/openapi.json、spec.go | 现有JSON字段 | 契约嵌入/真实响应校验/TS生成 |
| 6 | backend/query.go、admin_query.go、market_query.go | /state查询 | 分页/单笔/按key确认/完整行情 |
| 7 | frontend/src/api.ts、pending.ts、generated/api.ts | call和Pending | 精确契约、恢复作用域 |
| 8 | frontend/src/App.tsx、style.css | 教学界面 | 盘口/分页/水位/实时推送/管理 |
| 9 | backend/maintenance.go、observability.go | 手动看库/日志 | 离线运维、指标、pprof |
| 10 | cmd/server、exchangectl、loadcheck | 教学入口 | 配置/运维CLI/负载工具 |
| 11 | tests、scripts、deploy、Dockerfile | 手工操作 | 自动验收/发布/部署 |
最终仓库把同包后端文件放在 backend,这是当前组织方式;它不是每个文件独立微服务。Go同一package内可以调用未导出的函数,外围cmd只调用导出API。
初期依赖以第2章五项为基础;最终还加入 websocket v1.8.13、kin-openapi v0.133.0,以及前端GSAP、openapi-typescript、Prettier、Playwright。最终版本清单以 go.mod ↗ 和 package.json ↗ 为准,包括间接依赖。不要引入当前不存在的 chi、decimal.js、Prometheus Go SDK,也不要声称生成了Go路由或fetch客户端。
14.3 怎样拆一项改造#
以“新增IOC”为例:先补DTO枚举→验证组合→修改撮合循环结束行为→补资金/数量断言→更新OpenAPI→生成TS→页面选择IOC→浏览器验证→更新设计/测试文档。只改一个下拉框并不算实现。
建议每次只完成表中一行,并保存自己的版本记录。当前工作区没有Git历史,报告不能编造提交号;你在自己的练习目录可 git init 后按里程碑提交,.gitignore 先排除数据/依赖/密码。每次提交写具体行为,例如“IOC余量释放资金”,比“优化架构”清楚。
15. 补全订单规则、预算和对象所有权#
15.1 把领域类型升级到最终DTO#
对照 types.go ↗ 逐项扩充教学类型:
- Command 增加 SchemaVersion、PayloadHash、Timestamp、Type、TIF、ActorID、Reason;资金账户改为 AccountID。
- Order 保留 Quantity/Remaining/Filled/Canceled,增加类型、TIF、撤销原因、创建时刻和内部Seq;JSON字段为 remaining_quantity 等,不沿用教学短名。
- Result 增加 Orders/Balances/Entries 增量副本;这些字段
json:"-",不对HTTP公开。Trades等同样由内部投影消费。 - Balance 在内核仍是文本数值,资金运算转decimal;Entry记每次AvailableDelta/FrozenDelta和原因。
- Snapshot 包含 dataset_id/applied_seq/bids/asks/trades,订单ID和所有序号用字符串。
Seq来自日志writer;Timestamp由Submit外围固定;ID取下单Seq文本,不用rand.Intn或当前时间生成。不保证订单ID连续,因为注资/撤单/拒绝/重试都会消费日志位置。一次命令多次成交用 Seq/成交下标 唯一编号。
写新类型后编译会提示旧字段名;按核心→运行时→HTTP→测试顺序修改,别用多余的兼容字段让两份协议混杂。
15.2 一次只扩一个业务分支#
engine.go ↗ 中的主要方法与教学对应关系:
| 最终方法 | 你已有的基础 | 要补的工作 |
|---|---|---|
| NewEngine | New | 最优档缓存、完整状态容器 |
| balance/move | balance/move | 每笔资金同时记录Entry |
| Apply | Apply | changed订单集、确定性排序、独立余额副本 |
| place | place | 类型/TIF组合、预扫描预算、IOC余量取消 |
| crosses | place价格条件 | 两种方向复用同一价格裁决 |
| opposite/bestOpposite | best | 预扫描树顺序与最优缓存 |
| add/remove | add/remove | 空档更新最优Bid/Ask缓存 |
| release | release | 明确资金原因、原价释放 |
支持的组合是 LIMIT+GTC、LIMIT+IOC、MARKET+IOC。MARKET仍必须有price保护价:BUY允许对手价≤price,SELL允许≥price。没有流动性时正常取消剩余,不panic;部分成交后IOC取消剩余;LIMIT GTC余量留在簿上。自成交取消taker余量,已有maker继续等待。
扩展步骤:先在冻结前验证组合;撮合循环仍按maker价格;循环结束时判断 GTC且不是自成交 才挂余量,其余release并累计Canceled、Remaining归零、记录原因。最终状态CANCELED可以同时Filled>0,页面不能当它“完全没成交”。
15.3 预扫描为什么必须早于冻结#
最终版单命令最多接触1024张可成交maker,活动订单预算100000。单写者若被巨型命令长时间占用,所有后续用户都会等。
正确做法是在任何资金/订单修改前,用和实际撮合相同的价差、自成交与余量停止规则预扫描。一旦超过成交预算,整条命令拒绝且不产生资金副作用。不要先成交1024笔再拒绝第1025笔,否则你需要处理已经发生的部分业务。
步骤可以写成以下片段(省略具体树迭代,完整实现见place):
验证字段与余额 按对手最优价顺序遍历可能成交maker 遇非交叉价格、自成交或余量归零停止 若计数>1024:返回MATCH_LIMIT_EXCEEDED,尚未冻结 检查活动预算 创建订单并冻结 再执行有界撮合 |
这是两次遍历的成本换明确预算。红黑树解决价格索引,但不自动解决单条命令工作量。
15.4 用增量副本替换Snapshot全量复制#
Apply内创建 changed := map[string]*Order{}。下单新单、成交maker、撤单目标都放进去,结束时复制这些Order值到r.Orders,按Seq排序。资金move追加Entry;结束时按受影响 account:asset 去重,复制最新Balance到r.Balances。不要复制全部历史。
Orders/Balances是“变更后的完整值”,Entries是“有符号增量”。投影若把余额完整值再次当增量相加,会翻倍。每次返回Order、首次dedupe记忆的Order各自复制;之后runtime的copyResult再复制所有slice及Order/Error指针,隔离HTTP与还未落库的投影。
不能只靠race检查所有权。单线程环境里外部修改返回指针同样能污染下一次结果,它可能没有并发读写。要明确断言篡改返回对象后原结果/数据库不受影响。
对应最终验收命令(在最终项目根目录,非exchangelearn):
go test -count=1 -v -run 'TestMatchingFIFOAndSettlement|TestIOCAndSelfTrade|TestMatchBudgetRejectsBeforeMutation|TestCoreResultOwnership|TestPricePriorityBothDirections' ./backend
|
练习完成标准:能解释第5章四笔move、自成交规则、首次快照与最新订单差别,并证明非法订单不改变资金。
16. 升级日志、增量投影和恢复#
16.1 先建最终数据库结构#
在 store.go ↗ 依次写openDB→OpenStore→Close→ProjectBatch→applyProjected→Balances/Snapshot。先写建表和读取水位,再实现投影;每个阶段用临时目录做集成测试。
| 库 | 表/元数据 | 是否权威 | 为什么保存 |
|---|---|---|---|
| journal.db | commands、metadata | 是 | 已持久化输入、dataset_id、engine_version等 |
| auth.db | users、sessions、auth_audit | 是 | 身份/密码摘要/权限/会话/认证审计 |
| views.db | orders、balances、levels、trades、ledger、results、credit_audit、progress、projection_metadata | 可派生 | 查询/盘口/首次结果/资金分录/执行审计/可见水位 |
按源码中的DDL创建主键和索引,金额列TEXT。SQL里不做浮点资金运算。新数据目录在外围生成dataset_id并持久化,它用于区分两个独立历史;来自恢复同一套库时保留原dataset,不因每次进程启动换一个。
16.2 先写单条投影,再加批事务#
ProjectBatch先校验命令和结果长度相等,Begin一次事务,依次applyProjected,最后Commit一次。中间任何SQL错整批Rollback,包括progress,不能某几张订单写入而水位只推进一半。
每条applyProjected:
- 查progress;当前命令必须是下一条或已提交前缀,缺口拒绝。
- 对变更订单先读取旧快照,用负旧余量减去旧价档,再加新余量到新档。例:余量3变1,盘口净减2。
- upsert订单,覆盖最新余额;成交与分录按命令序号/下标插入。
- 管理员CREDIT记录操作者/目标/原因/金额/结果码/重试标记,不只记录“请求过”。
- 保存本次Result,推进progress;以上全在同一事务。
已投影前缀不能再累加分录或盘口;旧库补缺资金审计按明确兼容路径做。首次按key查询取最早Result记录,重复envelope有自己ProcessedSeq,不意味着新成交。
测试思路:用临时SQLite trigger使批内第二项失败,断言订单、资金、分录、progress都没部分提交;重开后从journal补齐。这是真实事务测试,比mock出一个nil错误更有价值。
16.3 新运行时的四个阶段#
Runtime ↗ 改为下面顺序。input/durable/results都是有界channel,默认各1024。全流程最多2048个inflight,日志默认最多64条或等1ms聚一批。
sequenceDiagram participant H as HTTP participant W as 日志writer participant E as 唯一核心 participant P as 投影worker H->>W: Submit:占用inflight并入队 W->>W: 批INSERT、FULL Commit W->>E: durable:已提交命令 E->>P: Apply产生增量副本 P-->>H: copyResult后回包 P->>P: 增量批投影Commit P->>P: 释放inflight |
project只收集已就绪结果,最多批大小,不再等待日志的1ms。成功回包保证输入日志已提交并完成核心处理,不保证视图立即可见。所以要加min_seq读取屏障,第18章讲查询。
实现顺序:先由单条writer分配Seq→改同事务批写→Commit后整批发durable→run逐个Apply→project聚已就绪结果→回包前copyResult→ProjectBatch→成功后释放slots。批失败r.fail停止受理并通知监督退出,不能继续使用内存递增后但未提交的Seq。
16.4 in-flight不是HTTP连接数#
slots可看成有2048张通行证,受理命令先拿一张,直到可靠投影完成才归还。HTTP回包、超时或用户断网都不能归还;否则投影慢时客户端可以持续积压后台工作。
Submit入队失败立即归还;入队成功由project负责归还。接入关闭与send/close要协调,最终runtime外围使用锁/原子保护生命周期,核心Engine仍无业务锁。用户提出“去掉锁”是核心状态单写者,不要求外部库、生命周期和指标都完全无锁。
并发请求被拒绝是正常保护,不是丢失已接受命令。排队越长,延迟越大;增加队列长度不等于增加处理速度。
16.5 恢复要同时恢复内存与视图#
最终启动检查目录锁、engine/schema、dataset、日志连续性和投影水位。重放所有历史命令恢复Engine的订单簿/余额/dedupe;视图已提交前缀跳过,落后尾部补投影。即便views已追平,也不能跳过内存重放,因为活动簿和首次结果仍在内存。
未知命令格式、序号缺口、权威损坏、投影超过日志上界都拒绝启动,不删库“修好”。未实现快照,所以历史越大重放越慢;checkpoint只合并SQLite WAL,不截断commands。
Close先停止受理,writer排空并关durable,核心排空并关results,project提交后退出,最后关库。正常关闭先不cancel全部worker,否则已受理任务可能被跳过;超时/故障走明确中止,再靠权威日志恢复。
最终验收:
go test -count=1 -v -run 'TestBackpressureAndCanceledWait|TestProjectionBatchIsAtomic|TestProjectionRollbackAndRecovery|TestRuntimeResponseCannotMutateProjection|TestSequenceExhaustionIsControlled' ./backend
|
精确崩溃窗口的收集/执行在第19章;不要用上述正常测试推断断电耐久性。
17. 补全认证、公开契约和管理员审计#
17.1 完整认证与HTTP接入的新增工作#
对照 auth.go ↗ 与 http.go ↗,将教学版补到以下行为:
| 要加的行为 | 写在哪 | 验证什么 |
|---|---|---|
| 严格邮箱/密码校验、普通注册固定USER | normalizeEmail/validPassword/CreateUser、authAction | 角色伪造、超长/过短、重复邮箱拒绝 |
| 认证入场/限流预算 | allowAuth、authAction | bcrypt在外围且不能无限堆积 |
| 缺会话与认证库故障分开 | Session/protected | 不把库错误都变成401 |
| Cookie Secure/HttpOnly/SameSite及安全响应头 | authAction/Handler | HTTP本地与HTTPS配置分别验证 |
| 停用+删除会话+auth_audit同事务 | SetDisabled | 审计失败整个操作回滚 |
| 初始化资金失败登录可补齐 | EnsureFunding | 同键不重复增发 |
| 管理员注资namespace/ActorID/Reason | credit | 目标账户、操作者、执行结论可解释 |
| 各条管理接口独立RBAC | protected(true,…) | 不能只保护管理首页 |
停用语义必须写清:之后会话被拒绝,旧挂单不自动撤销,已受理命令仍可能完成。这是边界事实,若想“停用立刻取消所有挂单”需新增有顺序的领域命令,不能在auth事务中直接触碰Engine。
17.2 从接口表写OpenAPI#
OpenAPI是一份机器可读的请求/响应说明书。先写info、paths,再在components/schemas复用User、Auth、PlaceOrder、Result、OrderPage等;写清security、状态码、金额/序号为string、枚举、required。对照 api/openapi.json ↗ 作为完整参考。
以下是阅读片段,展示为什么quantity不能写number;完整规格必须按实际DTO/路径建立:
{ "quantity": { "type": "string", "example": "0.0001" }, "price": { "type": "string", "example": "105" }, "processed_seq": { "type": "string", "example": "12" } } |
在 api/spec.go 用go:embed嵌入JSON,HTTP GET /api/v1/openapi.json 返回本次编译的内容。你修改磁盘规格但没重编服务时,老二进制仍返回老版本,因此前后端必须同版。
前端package增加openapi-typescript 7.8.0与Prettier 3.5.3;写api:generate和api:check脚本,使用同版规格。当前项目提供现成 check-api.mjs ↗,生成后格式化再逐字比较。
npm --prefix frontend run api:generate npm --prefix frontend run api:check go test -count=1 -v -run '^TestOpenAPIContractAndRealResponses$' ./backend |
api:check只是生成一致性;真正请求响应由contract_test使用kin-openapi校验。TypeScript的 as/泛型不会在运行时验证JSON,后端仍负责参数/角色校验。当前GoDTO、路由、fetch手写,不能把一份generated/api.ts讲成“整个API自动生成”。
17.3 把前端网络层从App拆出来#
新建 api.ts ↗,从generated/api导出类型,写APIError、api、errorText、unknownResult。请求包含Cookie、CSRF、原key与dataset,12s AbortController只取消客户端等待。response非成功读业务错误;网络/解码失败转换RESULT_UNKNOWN;finally清理计时器。
不要把401/403一律删除pending:原单成功但响应丢失,确认时会话刚过期,401并不能否定原单。先恢复身份再原键确认。泛型 api<Result> 仅帮助编辑器,不自动保证收到的对象符合Result。
最终验收:
go test -count=1 -v -run 'TestAuthValidationRules|TestSessionExpiryAndReenableDoesNotReviveTokens|TestDisableAuditFailureRollsBack|TestEveryAdminRouteEnforcesRBAC|TestAuthStoreFailureIsNotUnauthenticated' ./backend
|
完整角色/会话说明参考 认证设计,手工请求字段参考 接口指南。
18. 写分页、实时行情和待确认请求恢复#
18.1 用min_seq处理写后读#
最终版下单回包时投影可能落后。例如下单Result的processed_seq=”100”,马上查订单时views还在99,这不等于订单丢了。
在http.waitProjection里解析min_seq,用int64检查范围,外围最多等2s,投影progress≥目标时查询,未追上返回503 PROJECTION_LAG。不要锁住Engine等数据库,也别让用户一直无限等。
前端写确认后刷新:
// 插入片段:auth/result已经来自最终版API。 const page = await api<OrderPage>( `/orders?limit=20&min_seq=${encodeURIComponent(result.processed_seq)}`, auth.csrf_token, ); |
订单、余额分别查询并不是同一数据库事务,Promise.all也不把它们变成全局快照。min_seq表示至少看见此水位,不表示恰好历史seq=100的静态状态。
18.2 先写订单游标,再扩用户/成交#
query.go ↗ 定义OrderPage/OrderView/CommandLookup与游标编码解码。第一页读取投影水位,固定新订单创建seq上界;下一页seek“更小的创建seq”,用limit+1判断有没有下一页。SQL再限定当前account或管理员scope。
下面是SQL设计片段,实际列名/游标字段按query.go实现:
SELECT payload FROM orders WHERE account_id = ? AND seq <= ? AND seq < ? ORDER BY seq DESC LIMIT ?; |
第一页before可按实现用无界分支,别为省事硬造一个可能溢出的maxSeq+1。返回items、dataset_id、applied_seq与可选next_cursor,页面先显示20条;API范围1–100。
游标携带dataset、账户/范围、上界与位置,Base64只是编码,既不是加密也不是授权。客户端可以修改它,服务端仍需验格式/数据集/作用域,SQL必须限制账号。翻页期间旧订单仍会成交或撤单,因此固定的是“哪些订单被纳入遍历”,不是每张单的状态。
单笔 /orders/{id} 查询最新视图;/commands/by-key 只返回当前账号的首次结果。found=false可能是投影尚未可见,不能凭它换键重复下单。
扩展顺序:
- 在admin_query.go用用户rowid游标,返回UserPage。
- 在market_query.go用成交rowid游标,返回TradePage;不能只用命令seq翻页,因为一命令能产出多成交,同seq边界会漏。
- 管理审计AUTH/CREDIT来源独立,当前分组分页各有上界,不假装跨库全局时间排序/快照。
- 前端每个列表保存next_cursor,“加载更多”编码原游标,切身份/数据集重置列表和游标。
最终验收:
go test -count=1 -v -run 'TestOrderPaginationBoundaryAndOwnership|TestCommandLookupFirstResultAndLag|TestAdminPaginationAndCreditResults|TestPublicTradesPagination|TestDatasetIdentityUpgradeAndWriteFence' ./backend
|
18.3 写实时行情:先REST,再WS#
行情是公开盘口与近期成交,不发私有余额。Store.Snapshot在同一读事务取得applied_seq、bids/asks、trades。盘口levels由投影增量维护,查行情不能每次扫全订单再排序。
Server.RunSampler每100ms采样20档/最近50笔,各WS连接每100ms tick首次或水位改变发送完整Snapshot,2s写超时断开慢客户端。网络写必须在外围,不能让某浏览器拖住Engine。
实现顺序:公共GET /snapshot→后台采样→coder/websocket接入→来源与连接预算→首次/更新发送→关闭所有流→前端重连。最终代码入口是 http.go ↗ 的RunSampler/stream/CloseStreams。
前端App使用effect创建socket,onmessage解析并按dataset/applied_seq裁决;返回清理函数关闭socket、清掉重连定时器。初次挂载REST一次,此后WS重连等待新快照,退避0.5s逐步到10s。HTTPS使用wss。
**不要用 Number 比序号。**仅同dataset可用BigInt比较;新数据集从低seq开始仍必须接收。完整快照可以跳过中间序号,它不是逐条可靠成交投递,完整成交历史走分页接口。
例如旧数据集A当前seq=500,切到B收到seq=2,应接受B并重置缓存;A内从500收到499才是旧消息。trade近期快照同seq文本ID排序与历史rowid排序不同,不据此判定少了一笔。
18.4 把简化pending升级成可审阅恢复协议#
最终 pending.ts ↗ 的记录至少包含:
// 类型片段:完整hook使用前端Auth并按scope校验。 type PendingAction = { version: 1; dataset: string; account: string; key: string; path: string; body?: unknown; }; |
分别为place/cancel/credit保存,存储key包含dataset/account/scope。restorePending必须验证大小、version、身份、dataset、键字符、固定路径、body对象及每个字段类型。cancel只允许对应数字订单ID路径且没有body;credit的目标账户仍由后端权限验证。
实现顺序:独立纯函数restorePending→单元非法格式测试→usePending同步初始化→begin先保存→发送API→明确结论后clear→页面显示原请求确认。不要用effect延后读取记录,因为页面可能先短暂显示“可下单”,读到旧pending之前又发送新单。
begin返回已保存的原动作,确认不再读表单;clear失败保留记录并显示错误;不按TTL自动清掉未知动作。sessionStorage跨同标签刷新保留,但关闭标签、清存储、换设备没有恢复保证;后端幂等保证业务效果,不是浏览器分布式锁。
dataset变更停止自动确认旧动作,先核对身份/备份/当前数据。退出不删除未知写记录,回到原身份继续确认。管理员注资没有任意目标账号按key查询接口,只能原POST原操作者原内容确认。
18.5 页面完善的实现次序#
最终 App.tsx ↗ 以组件和hook组织:App负责身份/行情/刷新;AuthForm负责登录注册;Book负责盘口;OrderForm负责新单;OrderTable负责订单与撤单;AdminPanel负责用户/订单/审计与注资。当前都在App.tsx,不是多个服务。
先完成auth加载与身份切换取消旧结果;再分页/写后读;然后WS重连/pending;最后样式与动画。异步返回时核对当前身份或请求代次,避免A账号慢响应覆盖B账号列表。
沿用Carbon成熟颜色,平面直角、无渐变、精简文字;金额/seq仍字符串,盘口量条的相对宽度可以Number展示但不参与结算。最终GSAP 3.13.0配@gsap/react 2.1.2,组件作用域和卸载清理、prefers-reduced-motion;不要让动画替代busy/错误状态。
动画可从已有App中的useGSAP读起,先核对作用域、卸载清理和减少动态效果设置,再为新交互补浏览器验收。金额、按钮状态和错误处理不依赖动画完成。
19. 设计完整测试,并读懂性能结果#
19.1 每种测试证明的事情不同#
| 测试 | 是否要真实数据库/服务 | 最重要的断言 |
|---|---|---|
| 核心单元 | 否 | FIFO/价格/资金公式/幂等/边界/所有权 |
| 组件集成 | 真实SQLite/httptest | 事务、权限、投影、水位、游标 |
| 属性测试 | 内存核心 | 每步资产守恒、冻结与挂单一致、索引一致 |
| 崩溃恢复 | 测试子进程/独立服务 | 特定窗口杀进程后重放确定性 |
| 前端单元 | 真实TS源,受控fetch/storage | pending校验、头、异常与未知结果 |
| 浏览器E2E | 真浏览器+后端 | Cookie/CSRF/页面交易/管理/刷新恢复/WS |
| 性能 | 独立环境 | 负载、完成量、拒绝、延迟、最终对账 |
先写“输入—动作—预期”,再写代码。例如“停用审计插入失败”预期用户状态与旧session全保留,因为同事务回滚;“返回指针被调用者修改”预期投影仍是原结果。
19.2 用业务不变量检查一组命令#
遍历所有账户,对每种资产求 Available+Frozen,应等于累计合法CREDIT增加的总供给。无负数;活动买单需USDT冻结等于全部 price×remaining 总和,活动卖单ETH冻结等于remaining总和;每单 Quantity=Remaining+Filled+Canceled;终态Remaining=0。
在 property_test.go ↗ 的TestRandomizedCoreProperties里,固定seed生成合法/非法命令,每一步核对这些式子与树/FIFO/反向索引。固定seed保证失败可重现;生产核心仍没有随机输入。它不是完整参考撮合模型对拍。
钱相等但簿节点重复仍会出错,所以还要查:每个活动订单只出现一次、ref指向同一节点、空价档不存在、最优缓存等于树极值。
19.3 崩溃窗口要实际被测试收集#
提交前、提交后未Apply、Apply后未投影、投影事务中、重放中等窗口,父测试等待明确标记再Kill子进程,重开同目录核对。只“随机杀一次服务”不能证明所有精确窗口。
最终测试文件 crash_recovery_test.go ↗。先确认收集:
go test -list '^TestCrashRecoveryWindows$' ./backend go test -count=1 -v -run '^TestCrashRecoveryWindows$' ./backend |
名称里的Windows指故障窗口,不表示只测微软Windows。Go文件名 _windows_test.go 会被GOOS过滤,Linux可能悄悄漏测;现有文件已更名避免这个坑。helper在没有父进程参数时skip是正常,真正验证看父用例的六个子场景。
Kill进程验证的是进程崩溃,不是真实断电/fsync硬件故障。FULL配置也不能据此推断所有磁盘都绝对可靠。
19.4 分层执行,不一次把所有工具乱开#
以下bash/Python脚本在 Linux/WSL 的最终项目根目录执行;PowerShell直接执行Go/npm即可。Windows的race需要对应C工具链,普通go test不需要;不要把 CGO_ENABLED=0 用于race。
bash scripts/test.sh unit bash scripts/test.sh backend bash scripts/test.sh coverage bash scripts/test.sh fuzz bash scripts/test.sh all |
all顺序执行格式/依赖/Go测试/race/vet/前端单元/契约/构建/故障,再覆盖率、有限fuzz、浏览器。首次浏览器准备:
npx --prefix frontend playwright install chromium python3 scripts/e2e_check.py |
浏览器脚本用自己的临时目录/管理员/随机端口,不重置用户data;无浏览器依赖是准备失败,不写成业务通过。Go测试使用t.TempDir,不拿演示用户目录做损坏/trigger实验。
覆盖率生成HTML后查看未测分支,不能把“80%”当成正确性证明。node内置test的前端用例不等于浏览器测试,也不等于已统计前端行覆盖率。详细操作看 测试手册、用例目录。
19.5 开始做有意义的性能实验#
先单独测Engine,再测FULL日志/投影/恢复,最后测HTTP端到端。核心benchmark不能声称是可靠下单TPS,因为没认证、序列化、磁盘、网络。
最终项目命令(Linux/WSL,独立环境):
go test -run '^$' -bench . -benchmem ./backend CGO_ENABLED=0 go build -trimpath -o bin/loadcheck ./cmd/loadcheck python3 scripts/load_check.py --rates 100,500,1000 --seconds 5 --output /tmp/exchange-tutorial-load.json |
低并发客户端通常发一条等一条,会自然降低压力,掩盖过载。loadcheck按开放到达率产生计划请求,还要记录客户端因自身能力而丢弃的请求、服务拒绝、实际完成与延迟。
读报告时至少说清:硬件/磁盘、Go版本、是否FULL、用户/订单量、交叉成交比例、流量持续时间、成功/拒绝/丢弃、p50/p95/p99及最终对账。p99不是平均值,也不是metrics的max;4000req/s短时历史实验不是当前最大新订单TPS或生产SLA。
单机能力常被最慢阶段限制:核心、FULL磁盘、投影、HTTP/认证、GC。2048是inflight预算,不是每秒2048单。单市场和多市场共享资金分区仍属不同难度;Redis/多写者分区未实现,不把它们写进实测成绩。对应讨论见 详细面试Q&A。
20. 写注释、规范和项目文档#
20.1 学会解释为什么,不只解释语法#
下面是你可以仿照的注释片段:
// release 按订单原价与余量解冻,不按最新成交价解冻。 // 买单剩1 ETH、原价105时释放105 USDT;已成交部分不会释放第二次。 // 调用者必须是唯一核心,保证Frozen与活动挂单对应。 |
比“调用函数,更新金额”有价值。每个模块先说明用途、输入/输出、谁拥有可变状态;关键函数说明执行顺序、边界和失败处理;资金公式给可计算例子。生成文件、依赖不手工注释,业务变更同步更新注释。
前端effect写清启动/清理、身份切换、异步旧响应;测试写触发条件和证明点;脚本注明平台、工作目录、参数、产物、失败退出/清理谁的资源;部署配置注明数据路径和密码规则。
20.2 从你的实现逐步写出这些文档#
| 文档 | 新手可以先写的一页内容 | 最终参考 |
|---|---|---|
| 目标 | 谁使用、模拟资产、订单类型、不做什么 | goal.md ↗ |
| 架构 | 一张调用链、所有权、提交/回包/可见边界 | architecture.md |
| 认证设计 | 注册/会话/权限/停用语义 | auth-design.md |
| 规范 | 金额字符串、错误、单写者、注释、依赖锁 | engineering-standards.md |
| 测试设计 | 业务不变量、权限矩阵、崩溃窗口 | test-design.md |
| 测试记录 | 日期、命令、版本、实际输出、未执行项 | reports中的报告入口 |
| 部署 | 配置/端口/卷/停止/备份/升级 | deployment.md |
| 维护 | 三库、损坏、未知结果、投影重建 | data-lifecycle.md、operations-runbook.md |
| 面试 | 具体问题、方案、公式、测试证据、剩余限制 | interview-guide.md、interview-qa.md |
别先写“支持高并发高可用”再找代码去凑。每项能力关联函数和测试,计划/示例/实测分别标明。代码阅读时按 code-reading-guide.md 的调用链走,而不是按照文件长度从上到下背。
练习:写一个决策记录解释“为什么先日志后核心”,包含问题、候选、决定、代价、验收;再写“为什么全量Snapshot不能放在核心热路径”。
21. 运行当前完整项目与Windows一键脚本#
到这里回到本仓库根目录,不要继续在exchange-learn里输入EXCHANGE参数。
21.1 最方便的Windows路线#
安装Go与Node22+后,文件管理器双击 run-windows.cmd ↗。管理员名 pinkode,密码 2312a132。首次下载/构建后自动打开 http://127.0.0.1:8080;普通用户通过邮箱注册,密码仍12–72字节。
PowerShell可传参数:
# 先进入本仓库,实际路径按你的机器修改。 Set-Location 'D:\codex小项目\go\web3' .\run-windows.cmd -PrepareOnly .\run-windows.cmd -Port 18080 -NoBrowser -DataDir 'D:\exchange-full-demo-data' |
第二条只准备构建,第三条启动独立演示目录并手动打开18080。保持窗口,Ctrl+C停止,下一次重启保留身份/资金/订单;已有管理员不会自动改回指定密码。账号内部邮箱是pinkode@localhost,登录允许pinkode别名。
用户指定密码只有8字节,因此服务显式开启数值回环本地模式,拒绝公网/0.0.0.0和常规管理员邮箱配置混用。它不是普通注册规则被改成8字节,也不用于云/容器。详细说明看 Windows指南。
21.2 如果你想自己手写启动脚本#
先把过程写成明确步骤,再组合CMD/PowerShell,参考 run-windows.ps1 ↗:
- 从脚本路径求根目录,不依赖双击时的当前目录;路径加引号支持中文/空格。
- 检查go/node/npm,固定GOTOOLCHAIN=auto、原生windows与CGO=0。
- 将前端/api复制到bin/windows,Windows npm依赖安装在这个副本;lock摘要变更时ci。
- api:check→前端build→go build exe,任何命令失败立即非零并显示原错误。
- 明确本机Origin/Cookie/资源与独立data-windows,局部进程env,退出恢复原值。
- 启动自己子进程,检查ready与进程状态,成功后才打开浏览器。
- 管理本次进程退出,不自动杀占端口的陌生进程,不删除锁或用户库。
CMD只是双击入口,执行PowerShell脚本并在失败时保留窗口;PowerShell5.1中文脚本用UTF-8 BOM/CRLF。不要把 go run、npm install、打开浏览器三行连一起就叫一键可靠运行。
21.3 最终项目的手动开发运行#
纯Windows根目录(前提frontend/node_modules属于Windows;若此目录已在WSL安装过,使用上面的隔离脚本):
go mod download npm --prefix frontend ci npm --prefix frontend run build $env:EXCHANGE_DATA_DIR="data-manual-learn" $env:EXCHANGE_LISTEN_ADDR="127.0.0.1:8080" go run ./cmd/server |
普通用户可注册,需管理员则首次启动前设置常规EXCHANGE_ADMIN_EMAIL/PASSWORD,密码12–72字节;不要同时设置LOCAL_ADMIN_NAME。常规服务没有默认管理员。
前端开发另开终端 npm --prefix frontend run dev,访问5173,Vite代理/api与WS。部署则直接8080提供构建的dist。final的live/ready路径分别是 /health/live、/health/ready,不是教学 /health。
本机故障:连不上先看终端服务是否仍在、端口、恢复是否完成;登录403核对Origin、CSRF与访问地址;数据锁拒绝说明同一目录已有实例,别删锁文件绕过。
22. 容器和云服务器部署#
22.1 部署是把哪些东西搬过去#
浏览器只需要编译后静态文件,不需要TypeScript/Vite/node_modules;服务器只需要同版Go二进制、前端dist、配置和持久数据路径。构建工具留在构建环境,数据留在持久盘。
前半教学版不直接用于云部署。下面针对完整项目,使用已补齐的Origin/Secure Cookie、健康检查/排空、预算/运维工具。部署步骤是教学命令,不表示本轮真的部署了你的云服务器。
22.2 Docker的几个概念#
镜像是程序/依赖打包模板;容器是正在运行的实例;卷保存容器删掉后仍需要的数据。8080:8080 是宿主端口映射容器端口。容器内127.0.0.1是容器自己,不是宿主。
阅读根 Dockerfile ↗,按以下三段理解:Node阶段用ci构建前端;Go阶段CGO=0构建exchange/exchangectl;运行阶段Debian slim只放产物,以非root UID10001运行。离线Dockerfile.runtime才是scratch,别把两个运行层混着解释。
Compose是用YAML集中写容器、环境、端口、卷、资源。只有一个exchange写者,卷挂/data,根文件系统只读、/tmp tmpfs、stop宽限90s。独立loopback诊断不公开。
安装Docker Desktop并确认Linux containers/daemon可用。完整项目根目录PowerShell执行(密码示例仅本地容器学习):
$env:EXCHANGE_ADMIN_EMAIL="container-admin@example.com" $env:EXCHANGE_ADMIN_PASSWORD="container-learn-password" $env:EXCHANGE_ALLOWED_ORIGIN="http://127.0.0.1:8080" $env:EXCHANGE_COOKIE_SECURE="false" docker compose -f deploy/compose.yaml config --quiet docker compose -f deploy/compose.yaml up -d --build docker compose -f deploy/compose.yaml logs --tail=100 exchange Invoke-RestMethod http://127.0.0.1:8080/health/ready |
先停你自己的本机8080服务或调整映射并同步Origin。打开8080注册/登录,停启动验证数据保留:
docker compose -f deploy/compose.yaml stop exchange docker compose -f deploy/compose.yaml start exchange |
down -v会删除数据卷,正常升级不使用。不能把replicas增加为2却共用/data;这不是单写者分区,目录锁应拒绝。bind mount宿主目录要给UID10001写权限;命名卷按镜像ownership初始化。
若镜像拉取失败先检查daemon/镜像源DNS与网络,别误判业务逻辑失败。本项目曾遇在线基础镜像源DNS失败;历史离线runtime验证不能冒充标准在线构建本次已通过。
22.3 从零准备云服务器#
选择Ubuntu24.04、本地SSD起步,2vCPU/4GiB作为学习预算;资源不代表TPS承诺。创建实例后保存SSH连接方式,安全组只允许你的来源SSH,网页需要80/443;8080/9090不公开。配置域名A记录指向服务器IP,使用Caddy终结HTTPS。
第一次连接:在本机PowerShell运行 ssh <你的用户名>@<实际服务器IP>,以后本节Linux命令在服务器SSH窗口执行。不要把服务器路径当Windows路径。
构建Linux产物最容易在Linux/WSL独立构建目录完成:
go mod download npm --prefix frontend ci npm --prefix frontend run build CGO_ENABLED=0 go build -trimpath -o bin/exchange ./cmd/server CGO_ENABLED=0 go build -trimpath -o bin/exchangectl ./cmd/exchangectl |
服务器架构要匹配,amd64二进制不能直接跑arm64;按目标GOOS/GOARCH构建。完整发布可运行release.sh,但它拒绝覆盖已有同版本产物,使用不含旧bin/releases的独立源码副本,保留历史证据。不要直接拿历史v0.3包当当前源码。
将exchange、exchangectl、前端dist、deploy配置作为一个新版本目录上传。示例本机PowerShell(新建release-local目录并放入这些产物后执行):
scp -r .\release-local deployuser@203.0.113.10:~/exchange-release
|
203.0.113.10是文档示例地址,需替换;上传目录中最终网页目录名设为frontend,不携带node_modules/data/明文密码。若有SHA256SUMS,在服务器先校验。接着SSH服务器:
sudo useradd --system --home /var/lib/exchange --shell /usr/sbin/nologin exchange sudo install -d -o exchange -g exchange -m 0700 /var/lib/exchange /var/backups/exchange sudo install -d -m 0755 /opt/exchange/releases /etc/exchange # 首次部署使用新路径;已有路径时使用另一个版本,别覆盖正在运行目录。 sudo cp -a "$HOME/exchange-release" /opt/exchange/releases/tutorial-20261012 sudo chmod 0755 /opt/exchange/releases/tutorial-20261012/exchange /opt/exchange/releases/tutorial-20261012/exchangectl sudo ln -s /opt/exchange/releases/tutorial-20261012 /opt/exchange/current cd /opt/exchange/current sudo install -m 0600 deploy/exchange.env.example /etc/exchange/exchange.env sudoedit /etc/exchange/exchange.env |
编辑时逐项确认:
EXCHANGE_LISTEN_ADDR=127.0.0.1:8080 EXCHANGE_DATA_DIR=/var/lib/exchange EXCHANGE_FRONTEND_DIR=/opt/exchange/current/frontend EXCHANGE_ADMIN_EMAIL=your-admin@example.com EXCHANGE_ADMIN_PASSWORD=replace-with-your-own-long-password EXCHANGE_ALLOWED_ORIGIN=https://trade.your-domain.example EXCHANGE_COOKIE_SECURE=true EXCHANGE_DIAGNOSTICS_ADDR=127.0.0.1:9090 |
替换邮箱、域名和密码,不用本地pinkode短密码;不启用LOCAL_ADMIN_NAME。EnvironmentFile不是shell脚本,不直接source未知内容。
然后安装服务:
sudo install -m 0644 deploy/exchange.service /etc/systemd/system/exchange.service sudo systemctl daemon-reload sudo systemctl enable --now exchange curl --fail http://127.0.0.1:8080/health/ready sudo journalctl -u exchange -n 100 --no-pager |
systemd负责自启动/故障重启和以exchange用户运行,WorkingDirectory/路径必须对得上。Caddy安装按其平台官方文档,参考 Caddyfile.example ↗ 设置域名及反向代理127.0.0.1:8080,validate成功再启用。证书获取需DNS和公网80/443实际可达。
最终从自己的电脑打开HTTPS域名,真实登录/双用户成交/重启/备份验收,而不是只在服务器curl一次。没域名可用SSH tunnel暂演示,但HTTP时CookieSecure=false与准确Origin需同步,参考 部署手册。
23. 备份、故障排查与毕业验收#
23.1 先写离线工具,再实际练恢复#
maintenance.go ↗ 的实现顺序:OpenExistingStore只打开已有库→InspectStore重放对账→白名单/摘要/同步复制→BackupStore→RestoreBackup→RebuildViews。cmd/exchangectl把它们接成命令行,遇错退出非零。
备份必须停唯一实例且持相同目录锁。checkpoint三库,再固定白名单复制、fsync文件/manifest,记录dataset/engine/水位/数量/表摘要/SHA256。不是运行时随便复制.db;SQLite WAL可能还有新内容。
restore目标必须不存在,验证manifest/摘要再复制到新目录,重放对账通过才考虑切服务。SHA256用于发现字节损坏,不是防攻击签名。坏views可以重建,auth/journal是权威不能当缓存删掉。
rebuild-views先在staging重放/对账,保留坏views/WAL/SHM,再多个rename切换;多个rename不是一个全目录原子操作。普通错误尝试清理自己staging,强杀可能残留,按 数据生命周期 核对,不凭文件名猜测哪个安全。
23.2 在Windows独立目录练一次#
先停止对应服务,构建exe,PowerShell最终根目录:
go build -trimpath -o bin\exchangectl.exe ./cmd/exchangectl .\bin\exchangectl.exe check --data data-windows .\bin\exchangectl.exe backup --data data-windows --backup D:\exchange-backup-20261012 .\bin\exchangectl.exe restore --backup D:\exchange-backup-20261012 --data D:\exchange-restored-20261012 .\run-windows.cmd -Port 18080 -NoBrowser -DataDir D:\exchange-restored-20261012 |
备份和恢复目标必须是新路径;若已经存在,保留旧证据,换个新名字。check会补投影和临时重放对账,不是只读快速检查。恢复启动后核对原身份、资金、订单、dataset和首次结果;原目录仍保留。
云服务器先 sudo systemctl stop exchange,离线工具以exchange用户运行,恢复到新目录、对账再改配置,最后start。容器停服务后用同版exchangectl挂同卷,完整命令在部署手册。卷内备份不抵御整盘损坏,要拷到受限异机位置。
23.3 遇到错误先定位所在层#
| 现象 | 最先看哪里 | 正确动作 |
|---|---|---|
| 编译失败 | 原始错误文件/行号、模块/import | 修字段/路径、装固定依赖,别删报错代码 |
| 网页白屏 | F12 Console、Network、静态dist | 确认同版构建与访问端口 |
| 登录后401 | Cookie、会话期限/停用状态 | 重新登录原身份,保留pending |
| 写入403 | Origin、CSRF、角色 | 修准确配置/身份,不去掉校验 |
| RESULT_UNKNOWN | 原pending与首次按key查询 | 原键原内容确认,禁止新键重下 |
| PROJECTION_LAG | 提交/执行/投影水位与日志 | 等待或修存储,已确认单不是没发生 |
| OVERLOADED | inflight/队列/最慢阶段 | 降流量、测瓶颈,非盲目扩队列 |
| 数据目录锁占用 | 哪个自己实例仍在 | 停旧实例,不能删锁绕过 |
| 坏views | 离线check、journal/auth是否完整 | 保留坏库,离线重建 |
| 权威库损坏 | 备份manifest/对账 | 保留原件、恢复新目录,不跳日志 |
| 云启动失败 | journalctl、权限、二进制架构 | 检查exchange用户可写data与版本 |
本地独立诊断监听127.0.0.1:9090,包含/metrics和标准pprof;业务端口相应路径404。累计count/sum/max不是p99。pprof用来定位CPU/分配/GC瓶颈,不能因方便排错把它公开给所有人。
23.4 给自己做一次毕业验收#
可以不看源码回答并现场证明以下事项,才算真正完成这个手把手项目:
- 从空目录解释工具、模块、依赖、HTTP/JSON并写出health。
- 输入一笔命令,指出日志、核心、回包、投影分别在哪里发生。
- 当场计算3ETH@105对卖2ETH@100的冻结、价差和撤余量。
- 演示FIFO/自成交/IOC、市价保护价、订单与资产守恒。
- 原键重复不重复扣钱,返回对象被修改不污染状态;区分首次Result与最新Order。
- 注册登录与管理员前后端都能使用,普通用户直接访问管理API仍被拒绝。
- 页面刷新/断网后保留原请求;min_seq和dataset处理正确。
- 分页不会漏同一命令多笔成交;WS重连收到新快照并能清理资源。
- 单元/集成/属性/故障/E2E测试各能说明证明点,记录实际执行而非只有文件。
- Windows启动、容器卷、云配置、停机备份恢复能按文档操作。
- 明确当前只有一个核心/一个实例/一个市场,全历史重放与去重增长,无Redis/快照/HA/真实资金。
- 用测试与具体取舍讲项目,不把计划、历史短时负载或未执行云部署说成生产成绩。
不知道一项就回对应章节补一小步,不用重写所有东西。你做出的不是“记住一套架构词”,而是可以亲手修改、测试、解释的完整模拟交易项目。
教程验证说明#
本教程代码的实际检查与适用边界见 2026-10-12 教程验证记录。前半教学代码在隔离目录编译、测试、构建;后半指向最终源码与既有完整测试入口,文档命令不自动代表本轮重跑了所有故障、浏览器、Docker或云服务器。历史报告/发布包继续保留原版本。
从零补上 v0.5 的业务闭环#
先在教程练习目录完成前面的模拟工程,再在本项目独立钱包模式练习以下步骤,不能把教学 journal 与 chain-journal 混用。
- 阅读 chaintrade/index.go:创建 events 和 progress 表;手写一个事务,让 INSERT 事件与 UPDATE 游标一起 Commit。思考 INSERT 报错时为什么不能前进游标,运行 TestIndexTransactionFailure 看真实反例。
- 读取 blockHash 指定的日志。确认深度 2 时 head=10,只记录到 9;从 0 补拉,每轮最多 64 块。比对父块和最后锚点,遇已确认历史变化停下,绝不直接把旧 filled 清零。
- 阅读 tasks.go,给任务加 version。更新条件 WHERE id=? AND version=?;受影响行数不是 1 就拒绝。旧任务时间没记录应显示“未知”,不能用升级时间伪造历史。运行 TestTaskMigrationAndCAS。
- 阅读 history.go:第一页先取 MAX 排序键;后续 WHERE key<=upper AND key<after ORDER BY key DESC LIMIT 26,显示 25 条,额外一条判断下一页。钱包/类型/数据集绑定在 base64 游标内,游标只编码查询,不是身份令牌。运行 TestHistoryBoundaries。
- 打开钱包页面“交易记录”,切换订单/成交/任务/链事件,连接钱包后勾选“仅当前钱包”,从成交打开任务详情;观察 pending 与 CONFIRMED 的区别。
- 设置回环诊断,访问 /check。对账重新跑一个独立 Engine,读快照水位内日志,再比较所有订单,不只最新100条。TestReconciliationDetectsCorruption 故意损坏临时投影,证明能发现问题,但检查不会帮你自动改钱。
- 按 web3-deployment.md 加 Prometheus 和告警,采样失败时看 sample_failed,避免把陈旧 gauge 当健康。教程中的断言是正确性演示,不是公网链 TPS 测量。
在项目根运行 go test -run 'Test(History|TaskMigration|Indexer|IndexTransaction|Reconciliation)' -v ./chaintrade,预期 PASS;临时数据由 Go 测试自动清理。对应实测与局限见 v0.5 报告。