Web3 交易系统
开发与源码

代码阅读与注释指南

v0.6 发售调用链:FlashSale.sol 条款/验签 → flashsale/types.go 单位 → store.go 库存与资格事务 → auth.go/http.go 钱包会话 → middleware.go 与 messaging/rabbitmq.go 发布确认/消费 ack → processing.go 签名任务 → chain.go 索引/安全回收 → SaleApp.tsx 页面恢复。操作见手动验收,协议见发售架构。

本轮已在 29 个源码、测试与配置文件中补充详细中文注释,并核对有效代码未变,见注释完善记录。建议按下列顺序沿源码阅读:

阅读入口 注释重点
类型与金额 ↗、库存事务 ↗ 份数/lot/原子额、库存守恒、行锁、请求键与钱包限购、提交成功点
钱包认证 ↗、HTTP ↗ 登录签名、一次性挑战、Cookie/CSRF/Origin、资格归属、准入与限流
RabbitMQ ↗、分发 ↗ 持久队列、confirm、手动 ack、重连、重投与坏消息隔离
后台调度 ↗、状态事务 ↗ 签名固定正文、迟到任务、inbox、成交与回收的原子状态迁移
链读取 ↗、合约 ↗ 同 hash 证据、确认深度、深重组冻结、防重放、付款与交付回滚
活动页 ↗、接口 ↗ 页面状态与链事实的区别、过期倒计时、上下文代数、刷新恢复、金额精度
一键启动 ↗、集成验收 ↗ 新链/新库隔离、只清理自有进程、故障触发方式和各断言的证明点

当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。

历史 v0.4 变更记录(当前增量见页首 v0.5):新增阅读顺序:chaintrade/types.go单位与EIP712→engine.go数量状态→store.go三阶段日志流水线→tasks.go专用PG会话锁→middleware.go缓存/至少一次→chain.go原交易/receipt/锚点→http.go→cmd/web3server/main.go→Web3App.tsx→contracts/src/Settlement.sol。 当前链实现见v0.5架构,操作见开发、测试、部署,证据见本轮报告。

更新:2026-10-11。适用于目前已实现的 Go + SQLite + React 单市场模拟交易系统。用户要求“完善代码的注释,越全越好”,已写入 goal.md ↗ 和开发规范第 8 节。新增功能必须同步说明状态所有权、算法原因、失败边界和验证证据。

1. 从哪里开始#

文件 阅读重点
doc.go ↗ 模块边界、完整流水线、权威数据与可重建数据
types.go ↗ 命令/订单/结果/分录字段,金额与 ID 字符串,输入精度限制
engine.go ↗ 纯内存核心、幂等、红黑树与 FIFO、资金冻结结算、最优价缓存
runtime.go ↗ 三阶段唯一写者、批提交屏障、有界资源、未知结果、关闭与重放
query.go ↗ 页内一致投影水位、seek 游标、单笔/首次结果查询
api 契约 ↗、前端 API ↗、请求恢复 ↗ 生成类型、未知请求、sessionStorage/数据集边界
store.go ↗ 数据目录锁、三库边界、版本拒绝、原子投影、行情聚合与查询
auth.go ↗、http.go ↗ 密码/会话、RBAC/CSRF/Origin、认证初始化、交易接口、WS
main.go ↗ 配置、启动顺序、管理员 bootstrap、监督与退出
App.tsx ↗ 真 API、异步状态、水位、未知请求确认、组件、动画清理
核心测试 ↗、集成测试 ↗ 每个场景证明的性质、故障注入方式与边界
浏览器测试 ↗、崩溃脚本 ↗ 多身份真实成交、停用、子进程 SIGKILL 恢复
容器配置 ↗、systemd ↗ 非 root、持久卷、只读文件系统、优雅关闭

注释提供阅读背景;判断能力是否交付时仍需对照实际代码、测试完善报告和测试设计。计划中的快照、分区、Redis、Go 路由/完整 fetch 客户端生成和完整监控告警平台不能当作已实现;目前已有独立 loopback metrics/pprof;v0.2 TS 类型生成/订单分页/请求恢复见设计。

2. 用一个订单理解状态所有权#

  1. Server.protected 从 Cookie 查会话,确认角色/CSRF,得到可信的用户 ID。place 不接受客户端 account_id,将金额规范为 decimal 字符串。
  2. Runtime.Submit 取得在途额度,生成业务摘要和时间,把命令交给 input。外部 HTTP 超时只能停止等待,不能撤销已受理的命令。
  3. Runtime.write 独占日志序号,将最多 64 条或等待 1ms 收到的请求在 SQLite FULL 事务中提交。只有成功提交的命令才发布到 durable。
  4. Runtime.run 独占 Engine.Apply。它检查连续序号及幂等,校验资金,预扫描成交工作量,冻结资产,执行价格时间优先撮合。
  5. Apply 拷贝本次订单/余额变化和首次响应,不能把核心可变指针交给 HTTP/投影。后续成交不改变先前返回的订单快照。
  6. Runtime.project 合并已就绪结果(不等待 1ms),先用 copyResult 隔离响应与投影的指针/切片并回包,再将订单、余额、成交、分录、价档及水位整批 FULL 提交到 views.db。投影完成后才归还在途额度。
  7. 前端拿 processed_seq 请求 min_seq,查询投影追上后再显示新余额。随后轮询继续携带最大已知水位,并忽略旧身份及晚到请求的结果。
可变资源 唯一写入/协调方 外围能否直接访问核心原件
核心树、链表、活动索引、订单、余额、去重 启动重放;随后只有 Runtime.run 不能
日志序号、commands 表 Runtime.write 查询读取日志可以,不能并发分配业务序号
查询投影 Runtime.project;启动时由恢复流程补齐 HTTP 读投影,不读核心
认证状态 外围认证 SQL,独立连接/事务 不进入核心
共享行情快照 RunSampler 整体发布,外围 RWMutex 协调 WS 只读已发布快照
接入关闭标记、限流表 外围锁 不构成核心业务锁

这套实现采用 LMAX 单写者思想和 Go 有界 channel,未实现 Disruptor 环形缓冲区,也未实现集群多写者。

3. 手算资金变化#

假设买方初始有 100000 USDT,提交买 3 ETH、限价 105;卖方有两个各 1 ETH、卖价 100 的 maker:

步骤 买方可用 USDT 买方冻结 USDT 说明
初始 100000 0 测试准备通过 CREDIT 进入日志
冻结 99685 315 105 × 3
成交 2 ETH 99695 105 解扣冻结 210,实际支付 200,返价差 10
撤剩余 1 ETH 99800 0 释放原限价 × 余量 = 105

成交后买方 ETH 增 2,卖方 ETH 减 2、USDT 增 200。零手续费下每种资产的全账户 Available + Frozen 总和守恒,只有 CREDIT 会增发模拟资产。

数量始终满足 Quantity = Remaining + Filled + Canceled;冻结 ETH 等于账户所有活动卖单余量之和,冻结 USDT 等于所有活动买单 Price × Remaining 之和。测试每条命令后独立重算这些性质。

4. 撮合算法为什么这样写#

  • 价档用红黑树维护有序 ticks;同价订单用双向链表 FIFO。订单 ID 到链表节点的索引让同档撤单不需要线性扫描。
  • 买最优档取最高价,卖最优档取最低价。缓存使每次找最优对手档为 O(1),新档定位和删除空档仍有 O(log P) 成本;删除最优空档时从树更新缓存。
  • 正式变更资金前预扫描最多 1024 个可能成交 maker。否则成交一半才超限,会引入复杂的业务回滚。预扫描和撮合使用相同价格/自成交停止条件。
  • 成交采用 maker 价格;MARKET 必须给保护价且 IOC。无流动性时产生零成交的 CANCELED 订单,有部分流动性时成交后取消余量,不保证全额成交。
  • 自成交使用 cancel_taker:保留自己的 maker,取消当前订单余量;不会越过自身 maker 去吃后面的挂单。
  • Apply 中排序的仅是本命令改变的订单,目的是消除 map 输出顺序差异;订单簿没有每次查询全量排序。

5. 失败和恢复应怎样理解#

边界 当前行为 不应误解为
入队之前容量不足 明确拒绝,未执行 已成交但查询没到
入队之后等待超时/断网 原键原内容重试,结果可能已执行 可以换新键再下同单
日志提交失败 不发布对应命令到核心,停止流水线 跳过失败序号继续撮合
投影失败 核心结果可能已回包,进程停机,日志恢复可补投影 成功回包表示所有查询立即可见
内部序号不连续/panic 外围监督停机,不继续执行受损核心 普通余额不足也应 panic
程序关闭 先取消后台采样/关闭 WS,再停止 runtime 受理并排空、等待 HTTP 关闭与采样退出,最后关数据库 先关数据库再等待后台任务
引擎版本不兼容 拒绝并释放启动过程中资源/数据锁 自动清空旧库启动
SIGKILL 验证 六窗口覆盖日志提交前后、Apply 后、回包前、投影事务内与恢复中;另有回包后 SIGKILL 脚本 完成真实断电或全部磁盘故障验证

重启时保留 journal.db 与 auth.db,从日志头恢复内存核心与去重,重放仍逐条 Apply,ProjectBatch 跳过已应用前缀并补齐后缀;旧库资金审计可在前缀额外补写。views.db 可以在停止所有实例后重建,不能按同样方式删除 auth.db。没有快照时,日志、去重、恢复成本随历史增长。

6. 认证及前端注释的重点#

密码采用 bcrypt 慢哈希(12–72 UTF-8 字节),随机会话使用 SHA256 摘要落库(24h)。两者不同,不能因为会话可直接摘要就把密码改成 SHA256。Cookie 为 HttpOnly/SameSite Strict,HTTPS 配置 Secure;CSRF token 仅保存在页面内存。

公开注册固定 USER;管理员由环境配置 bootstrap,已有 USER 不自动提升、已有 ADMIN 不改密码。停用会撤销会话,但不原子撤销已有挂单,也不取消已经受理命令。注资走核心日志,不能直接改查询余额。

前端金额输入不经过 Number。盘口深度条使用 Number 只绘制比例;金额原文、下单输入和余额继续保留字符串。序号比较采用 BigInt。WS 重连退避至 10s,收到完整快照仅接受不倒退水位;当前通过 dataset_id 区分新数据集,并接受它的低序号;初始 HTTP 不能覆盖已收到 WS。

未知下单/撤单/注资保存原幂等键和原请求,锁定下单/注资表单直至确认;v0.2 在发送前写 sessionStorage,同标签页刷新或重登录该身份可恢复,关闭标签/清存储后没有恢复保证。存储故障会阻止发送,不把浏览器存储称为服务端耐久日志。账号作为私有组件 key,避免把前一身份的待确认请求复用到另一账号。

GSAP 限定组件 scope,只动画 transform/opacity,支持 reduced-motion。定时器、WS、matchMedia/context 在卸载时清理。注释说明这些规则的原因,不把“调用了 hook”本身当作资源清理证明。

7. 后续审阅检查#

修改业务时同时检查:核心所有权是否泄漏、日志能否重放、资金公式是否守恒、错误是否在变更前可拒绝、幂等结果是否稳定、投影水位是否原子推进、前端是否把未知执行当失败、资源是否有上限和关闭路径。

注释应说明真实保证及代价,避免重复赋值、过期叙述和未经测试的性能数字。Go 使用 gofmt,前端提供 npm run format / npm run format:check;注释仅在实际实现或相关证据改变时更新。

8. v0.3 扩展阅读路径#

  1. runtime.go 的 schema/seq/hash 检查与已投影前缀跳过:不要误以为跳过投影就是跳过恢复核心。
  2. store.go 的 ProjectBatch/applyProjected:整批提交,第二条失败首条也回滚,提交后才释放额度。
  3. admin_query.go/market_query.go:同秒用户使用 rowid,多笔同 seq 成交也用 rowid seek;审计两个来源各自上界。
  4. maintenance.go 与 cmd/exchangectl:同目录 flock,正规文件/manifest 校验,独立重放逐表摘要,坏投影保留与 staging。
  5. observability.go:只发布外围原子副本/时长,标准 pprof 独立回环监听;字段数量由唯一核心调用者读取后发布。
  6. cmd/loadcheck 和 scripts/load_check.py:固定工作者与有界客户端积压、计划至完成延迟、拒绝/丢弃/对账;发生器瓶颈与服务瓶颈分开。
  7. crash_recovery_test/runtime_test/maintenance_test/property_test:精确窗口、整批事务回滚、额度生命周期、恢复/对账、固定 seed 守恒与静态依赖边界。

本轮测试入口与证明点补充见测试手册、用例目录。engine_boundary_test 验证首次幂等记忆不能共享返回 Order 指针;runtime_boundary_test 占用唯一投影连接验证 copyResult 将响应与投影切片分离。前端 tests/unit 执行真实 api/pending TS 源码,React hook 的 DOM 行为仍由浏览器验证。

新增代码继续充分中文注释,解释用途、字段、顺序、边界和例子;对应设计见v0.3,实际证据见报告。

9. 配套使用与维护阅读#

先用接口使用指南走一遍登录—下单—原键确认—min_seq 查询;再用数据生命周期区分三库、备份和投影重建。异常时按故障排查手册检查进程、认证、投影与磁盘。

本次注释审阅记录见文档与注释报告。它记录文档纠偏与行为不变检查,旧测试源码摘要属于旧历史快照,不应在注释更新后继续宣称与当前文件逐字相同。

Windows 本地运行代码路径#

CMD 入口 ↗ → PowerShell 构建与生命周期 ↗ → server.localAdminConfig 回环检查 → BootstrapLocalAdmin → authAction 的配置别名映射 → 真实会话/RBAC。CreateUser/BootstrapAdmin 的常规 12 字节下限保留,本地模式只有可信初始化允许 8 字节。注册仍邮箱输入,登录允许文本别名;契约分别为 Credentials/LoginCredentials。使用与验证见Windows 指南。

v0.5 阅读路线#

先读 history.go(上界与钱包游标),再 tasks.go(schema 迁移和版本 CAS),index.go(连续块与事务),reconcile.go(固定投影水位重放),observability.go(无核心依赖的指标),最后 Web3History.tsx(取消旧读取、筛选重置、详情)。production_test.go 给出每条恢复边界的实际反例。

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