Web3 交易系统
开发与源码

从零手写 Go + React 模拟交易系统:新手手把手教程

当前基线:模拟 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. 先认识你要做的东西#

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 五条最基础规则#

  1. 买价越高优先,卖价越低优先;同一价格先到先成交,这叫 FIFO。
  2. 新来并主动吃已有挂单的叫 taker;已有挂单叫 maker;按 maker 的价格成交。
  3. 买单冻结 限价 × 数量 的 USDT,卖单冻结对应 ETH。
  4. 成交只交换资产,零手续费演示中不会凭空增加 USDT 或 ETH;只有 CREDIT 注资增加模拟总供给。
  5. 撤单只释放尚未成交部分;已经成交的部分不能撤回。

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、读当前时间、产生随机编号或取得业务锁。这保证同一批历史命令重新执行时,得到相同业务结果。

先看结构,再输入代码,建议按下面顺序分六次写入同一个文件:

  1. 定义 Command/Order/Balance/Trade/Result/State:明确输入、业务对象、输出。
  2. 定义 level/ref/saved/Engine 和 New:建立状态容器。
  3. 写 Parse/d/balance/move/clone:精确金额、资金变更和对象隔离。
  4. 写 add/remove/best/release:管理订单簿与解冻。
  5. 写 place:校验→冻结→逐笔撮合→余量挂簿。
  6. 写 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 的完整文件:

<!doctype 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,不算两个独立账号会话。

  1. Bob以SELL,price=100,quantity=2下单,刷新:ETH可用8、冻结2。
  2. Alice以BUY,price=105,quantity=3下单:ETH可用12;USDT可用99695、冻结105。
  3. Bob刷新:ETH可用8、冻结0;USDT可用100200、冻结0。
  4. 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:

  1. 查progress;当前命令必须是下一条或已提交前缀,缺口拒绝。
  2. 对变更订单先读取旧快照,用负旧余量减去旧价档,再加新余量到新档。例:余量3变1,盘口净减2。
  3. upsert订单,覆盖最新余额;成交与分录按命令序号/下标插入。
  4. 管理员CREDIT记录操作者/目标/原因/金额/结果码/重试标记,不只记录“请求过”。
  5. 保存本次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可能是投影尚未可见,不能凭它换键重复下单。

扩展顺序:

  1. 在admin_query.go用用户rowid游标,返回UserPage。
  2. 在market_query.go用成交rowid游标,返回TradePage;不能只用命令seq翻页,因为一命令能产出多成交,同seq边界会漏。
  3. 管理审计AUTH/CREDIT来源独立,当前分组分页各有上界,不假装跨库全局时间排序/快照。
  4. 前端每个列表保存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 ↗:

  1. 从脚本路径求根目录,不依赖双击时的当前目录;路径加引号支持中文/空格。
  2. 检查go/node/npm,固定GOTOOLCHAIN=auto、原生windows与CGO=0。
  3. 将前端/api复制到bin/windows,Windows npm依赖安装在这个副本;lock摘要变更时ci。
  4. api:check→前端build→go build exe,任何命令失败立即非零并显示原错误。
  5. 明确本机Origin/Cookie/资源与独立data-windows,局部进程env,退出恢复原值。
  6. 启动自己子进程,检查ready与进程状态,成功后才打开浏览器。
  7. 管理本次进程退出,不自动杀占端口的陌生进程,不删除锁或用户库。

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 给自己做一次毕业验收#

可以不看源码回答并现场证明以下事项,才算真正完成这个手把手项目:

  1. 从空目录解释工具、模块、依赖、HTTP/JSON并写出health。
  2. 输入一笔命令,指出日志、核心、回包、投影分别在哪里发生。
  3. 当场计算3ETH@105对卖2ETH@100的冻结、价差和撤余量。
  4. 演示FIFO/自成交/IOC、市价保护价、订单与资产守恒。
  5. 原键重复不重复扣钱,返回对象被修改不污染状态;区分首次Result与最新Order。
  6. 注册登录与管理员前后端都能使用,普通用户直接访问管理API仍被拒绝。
  7. 页面刷新/断网后保留原请求;min_seq和dataset处理正确。
  8. 分页不会漏同一命令多笔成交;WS重连收到新快照并能清理资源。
  9. 单元/集成/属性/故障/E2E测试各能说明证明点,记录实际执行而非只有文件。
  10. Windows启动、容器卷、云配置、停机备份恢复能按文档操作。
  11. 明确当前只有一个核心/一个实例/一个市场,全历史重放与去重增长,无Redis/快照/HA/真实资金。
  12. 用测试与具体取舍讲项目,不把计划、历史短时负载或未执行云部署说成生产成绩。

不知道一项就回对应章节补一小步,不用重写所有东西。你做出的不是“记住一套架构词”,而是可以亲手修改、测试、解释的完整模拟交易项目。

教程验证说明#

本教程代码的实际检查与适用边界见 2026-10-12 教程验证记录。前半教学代码在隔离目录编译、测试、构建;后半指向最终源码与既有完整测试入口,文档命令不自动代表本轮重跑了所有故障、浏览器、Docker或云服务器。历史报告/发布包继续保留原版本。

从零补上 v0.5 的业务闭环#

先在教程练习目录完成前面的模拟工程,再在本项目独立钱包模式练习以下步骤,不能把教学 journal 与 chain-journal 混用。

  1. 阅读 chaintrade/index.go:创建 events 和 progress 表;手写一个事务,让 INSERT 事件与 UPDATE 游标一起 Commit。思考 INSERT 报错时为什么不能前进游标,运行 TestIndexTransactionFailure 看真实反例。
  2. 读取 blockHash 指定的日志。确认深度 2 时 head=10,只记录到 9;从 0 补拉,每轮最多 64 块。比对父块和最后锚点,遇已确认历史变化停下,绝不直接把旧 filled 清零。
  3. 阅读 tasks.go,给任务加 version。更新条件 WHERE id=? AND version=?;受影响行数不是 1 就拒绝。旧任务时间没记录应显示“未知”,不能用升级时间伪造历史。运行 TestTaskMigrationAndCAS。
  4. 阅读 history.go:第一页先取 MAX 排序键;后续 WHERE key<=upper AND key<after ORDER BY key DESC LIMIT 26,显示 25 条,额外一条判断下一页。钱包/类型/数据集绑定在 base64 游标内,游标只编码查询,不是身份令牌。运行 TestHistoryBoundaries。
  5. 打开钱包页面“交易记录”,切换订单/成交/任务/链事件,连接钱包后勾选“仅当前钱包”,从成交打开任务详情;观察 pending 与 CONFIRMED 的区别。
  6. 设置回环诊断,访问 /check。对账重新跑一个独立 Engine,读快照水位内日志,再比较所有订单,不只最新100条。TestReconciliationDetectsCorruption 故意损坏临时投影,证明能发现问题,但检查不会帮你自动改钱。
  7. 按 web3-deployment.md 加 Prometheus 和告警,采样失败时看 sample_failed,避免把陈旧 gauge 当健康。教程中的断言是正确性演示,不是公网链 TPS 测量。

在项目根运行 go test -run 'Test(History|TaskMigration|Indexer|IndexTransaction|Reconciliation)' -v ./chaintrade,预期 PASS;临时数据由 Go 测试自动清理。对应实测与局限见 v0.5 报告。

— 本篇阅读完毕 —
来源:Web3 交易系统 / docs / 03-development/from-zero-tutorial.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭