Web3 交易系统
系统架构

交易撮合演示项目架构设计

本页主体为模拟 v0.3 架构;全项目 v0.6 现状见开发进度,既有链协议背景见v0.5,已实现业务见限量发售与秒杀。发售的 PG 库存事务独立于无 SQL 的撮合核心;交易和发售的消息传输均已改用 RabbitMQ。

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

历史 v0.4 新增独立单写者、pending/finalized 数量状态、可靠 outbox、Redis/PG/Kafka 及 Settlement,见旧报告。链模式成功回包须等本地投影,不能套用模拟回包先于投影语义;固定预算、FIFO 简化、链事实轮询与深重组边界保留。当前消息传输以页首 v0.6 为准。

模拟架构历史修订号:0.6(不是应用 v0.6,模拟 API 仍为 0.3.0);实现基线为模拟 v0.3,主体更新于 2026-10-11,适用范围于 2026-11-02 核对。

用户已授权开发并新增注册/登录/管理员要求。实际认证与权限见认证设计;本页早期演示账户描述被新要求覆盖。当前代码集中在 backend 包;v0.2 增加 api 契约/生成 TS、订单分页/单笔/按键查询、dataset_id 与浏览器请求恢复,见增量设计。v0.3 完成分页/公共成交历史/离线管理 CLI/指标/性能与故障证据,见完成设计。快照与分区属于可选演进;Go 自动路由生成暂不采用,契约以生成 TS/真实响应校验保证。

用户追加充分注释要求,已纳入 goal.md/开发规范并落实 Go、前端、测试、脚本和部署配置。现有实现阅读见代码阅读指南,实际验证见报告。当前执行细节以 v0.3 增量设计和公开契约为准;下方快照/生产扩展保留独立范围。

测试完善落实响应所有权:核心 Order、首次幂等记忆、对外 Result.Order 三者独立;外围在回包前复制 Result 的指针/切片,使调用者与异步投影各持自己的数据。测试接口/用例/执行清单见测试手册、本轮报告,其中同时更正上一版 Linux 精确窗口漏收集的问题。

1. 目标与范围#

面向大三学生的 Go 后端面试项目:能够讲清楚价格时间优先、金额精度、状态一致性、单线程业务模型、持久化与恢复,并用真实接口和故障实验提供证据。原项目仅作为问题分析与业务参考,重新组织实现,不继承其链上转账和共享指针结构。

遵循用户补充的 LMAX 思路:所有可变业务状态由一个核心 goroutine 独占;HTTP、WebSocket、序列化、磁盘、数据库、日志与监控输出均在外围执行。 撮合核心不使用 mutex/RWMutex,不访问网络和文件,不依赖当前时间和随机数。

第一版交付 后续扩展 本轮边界
Go 撮合引擎、精确金额、限价 GTC/IOC、市价 IOC、撤单、模拟账户、日志重放、REST、实时行情、注册/登录/管理员前后端、测试与部署文档、充分注释 快照加速、批量撮合优化、按市场分片、独立数据库或消息总线、链上充值提现 本地/容器、短时容量/恢复和精确进程崩溃窗口已验证;云/真实断电需外部环境

默认交易对 ETH/USDT;当前代码只开放一个市场,业务由一个核心管理。现货为模拟资产,已支持注册/登录和管理员,使用数据库会话 Cookie;模拟模式不接钱包;独立链模式已接EOA签单与测试代币原子结算,真实托管/出入金未实现。

2. 架构总览#

flowchart LR
    UI[React 演示页面] --> API[HTTP 接入与严格校验]
    API --> IQ[有界接入队列]
    IQ --> JW[日志写入 goroutine\n定序与批量提交]
    JW --> JD[(journal.db\nSQLite WAL / FULL)]
    JW --> DQ[仅已持久化命令队列]
    DQ --> CORE[单 goroutine 核心\n账户 / 订单簿 / 撮合 / 幂等]
    CORE --> OQ[有界结果队列]
    OQ --> PROJ[投影 goroutine\n先回包,再投影提交]
    PROJ --> ACK[HTTP 结果回传]
    ACK --> API
    PROJ --> VD[(views.db\n订单 / 成交 / 账户 / 进度)]
    VD --> READ[REST 查询]
    READ --> UI
    VD --> HUB[外围行情采样 / WebSocket]
    HUB --> UI

三个 SQLite 文件职责不同:journal.db 的业务命令表是恢复的权威来源;views.db 是可以重建的查询投影;auth.db 是身份与会话权威,不能按投影方式删除。SQLite 的物理 WAL 用于原子提交和崩溃恢复,业务命令表用于应用重放;物理 WAL 的 checkpoint 不会删除业务命令历史。

当前 writer/core/projector 三阶段,回包和投影由外围 projector 顺序完成,未另建独立 ResultDispatcher。

不依赖 RabbitMQ、Redis、微服务或自制无锁环形缓冲区。先使用 Go 有界 channel 构成流水线。channel 和数据库底层可能使用同步机制;“去掉锁”准确指核心状态不需要业务锁,不声称整个运行时无锁。一个 goroutine 是一个逻辑写入者,不等于固定在某个 OS 线程或 CPU 核;不设置全局 GOMAXPROCS=1,不默认使用 runtime.LockOSThread。

2.1 组件职责与状态所有权#

组件 所有权与职责 禁止事项
HTTP 接入 请求字节、参数校验、请求关联、接入限额 读取或修改核心订单指针
JournalWriter 命令序号、编码、输入日志事务、持久化水位 撮合、冻结资金、忽略提交错误
Engine 所有订单簿、账户、幂等结果、最后处理序号 SQL、文件、网络、日志输出、时钟、随机数
回包阶段(当前合并在 Projector) 接收不可变结果,回传响应,继续提交投影 丢弃成交或订单结果以缓解压力
Projector 按序更新查询表和 applied_seq 用最终一致查询表做资金校验
HTTP 查询 订单/用户/审计/成交有界分页、min_seq、行情一致读事务 用旧投影余额裁定交易;宣称独立订单/余额请求为同一瞬间
WebSocketHub 采样投影、编码和发包、连接生命周期 在核心线程执行编码或 socket write
Supervisor 生命周期、异常停止、恢复及外围观测 核心发生内部错误后继续处理后续命令

跨组件发送的命令和结果按不可变值处理;结果含 ID、金额值、状态和事件;Result.Order 允许指向脱离核心原件的副本,不共享核心可变 *Order、链表节点或树指针。发送后禁止改写任何共享 slice backing array 或 map。第一版优先显式复制;确认基准后才考虑受控对象池。

3. 命令流水线与持久化屏障#

3.1 处理顺序#

  1. HTTP 在外围限制 body 大小,解析十进制字符串,验证账户/市场格式和字段组合。无效语法请求直接返回,不进入日志。
  2. 取得有界在途额度并放入接入队列。排队容量不足返回 503 OVERLOADED,尚未受理的请求没有业务效果。
  3. Submit 在外围设置 Timestamp、schema_version 与业务摘要;JournalWriter 单独读取队列,按读取顺序赋予全局连续 seq。接收时间仅展示,不参与 FIFO,未保存名为 received_at 的字段。
  4. JournalWriter 将一批带序号命令写入 commands 表的一个 SQLite 事务,使用 WAL 模式和 synchronous=FULL 提交。默认上限 64 条或等待 1ms(可配置),仅日志主动等待聚批;投影只合并已就绪结果。
  5. 只有提交成功的命令才按序发送到核心队列。提交失败或结果不确定时停止接入和核心推进,由恢复过程核对日志;不能猜测事务成功,也不能跳过序号。
  6. Engine 消费命令,完成状态相关校验、幂等、资金冻结、撮合/撤单/释放,生成一个完整 Result。
  7. 结果分发到可靠投影队列并回传 HTTP。这里成功意味着命令已持久化且核心已处理完成,不意味着所有查询表和浏览器已同步。
  8. Projector 对一个或一批连续结果开启事务,原子更新订单、成交、资金分录、余额及 applied_seq。外围行情线程读取投影并推送全量小型快照。

持久化屏障只控制命令何时可进入核心。核心本身没有等待磁盘 API,但受到流水线吞吐与背压限制;不能把纯内存 benchmark 当成完整请求吞吐。

3.2 Go 核心接口示意#

// Apply 已实现;ExportSnapshot 为可选 P8 接口示意,尚未实现。
type Engine interface {
    Apply(command Command) Result
    ExportSnapshot() Snapshot // 仅核心持有者调用,返回脱离核心的值
}

Apply 不接收请求 context,不执行外部调用。业务拒绝编码为有类型的结果,例如 INSUFFICIENT_BALANCE,不会 panic。外部取消 HTTP 请求仅取消等待,不撤销已经受理的命令。

外围事件循环通过 channel 顺序调用 Apply;核心处理函数本身可直接在测试中运行。实现上拆开业务计算和结果传递,不在业务方法中隐藏阻塞 IO。

3.3 队列和背压#

当前 input/durable/results 三队列默认各 1024、在途额度 2048、batch 64/1ms;队列/在途/批大小/等待可配置,见运行手册。body 16KiB、match 1024、活动订单 100000 固定预算。预算不是吞吐承诺;投影合并已就绪结果同事务 FULL 提交。

队列限制条数;HTTP 限制 body 16KiB,核心限制单命令撮合工作量。内部 Go Submit 是可信调用边界,不额外提供通用命令字节上限校验,禁止无限 goroutine、无限结果缓存和无限等待。在途额度从接入前取得,直到该命令的投影提交后才释放;不能因 HTTP 已回包或断开就提前释放可靠工作额度。日志/核心/投影失败由监督停止接入,重启后依据持久化水位恢复,不沿用旧进程的内存额度。

匹配笔数超过上限时,在任何状态变更前用只读预扫描返回 MATCH_LIMIT_EXCEEDED,不允许执行半笔命令后失败。预扫描与执行都在同一个核心调用内,没有中间命令插入。

投影队列是可靠通道,满时结果分发停顿,最终停止核心消费并触发接入背压。已持久化命令继续由日志保障,不能丢弃订单事件。网络等待者断开不会阻塞可靠事件通路;请求关联表和响应 channel 在外围受控清理。

行情为可重建数据:慢客户端只保留最新完整行情快照或断开重连,不积压逐笔动画消息。公平性、超时和拒绝计数在外围观测。

4. 金额与市场规则#

所有业务金额使用 shopspring/decimal,从 NewFromString 构造。HTTP 金额字段和持久化金额都是字符串,不走 float64;前端输入保留字符串,目前不引入 decimal.js 或做结算预估;后续需要预估时选用经过验证的十进制库,服务器为最终裁决者。

默认市场配置:

项目 第一版规则
市场 ETH-USDT
最小价格变动 0.01 USDT
最小数量变动 0.0001 ETH
价格范围 大于零且不超过 1000000000000
数量范围 大于零且不超过 1000000
内部 USDT 精度 6 位,能够精确存储该市场 price × quantity 的所有结果
ETH 精度 4 位
手续费 首版为零;引入费用前设计费用账户和舍入规则

输入限定普通十进制形式,禁止指数、NaN、Infinity;限制字符串长度与小数位数,拒绝超精度,不静默四舍五入。价格必须是 tick 的整数倍,数量必须是 step 的整数倍。

价档键为经过精确整除和范围检查的 int64 price_ticks,此值仅用于索引与排序。价档中的价格、数量和资金仍为 decimal。这样 "1.0"、"1.00" 进入同一价档,也避免以包含内部指针的 decimal 值当 map key。新市场的精度必须保证成交计价能被资金精度精确容纳,不得热修改已存在日志的精度元数据。

VWAP 当前未实现;后续展示计算候选为 sum(price × quantity) / sum(quantity),只在展示边界按指定精度舍入;不使用 VWAP 参与结算。

5. 订单簿与撮合#

5.1 数据结构与复杂度#

每个市场维护两个价档红黑树,复用 GoDS 稳定版红黑树;价档内部使用标准库 container/list 保证 FIFO,map[OrderID]OrderRef 保存活动订单对应的价档和节点。买盘最大价、卖盘最小价维护为核心私有缓存,价档增删时更新。

操作 预期复杂度 说明
读取最佳买/卖价 O(1) 缓存有效最佳价档
创建/删除价档 O(log P) P 为价档数,复用红黑树
挂入已有价档 O(log P) 查询 + O(1) 入队 可按实测决定是否补价档 map
撤销订单节点 O(1) 查索引与删节点 最后一单导致删价档时另加 O(log P)
吃掉 M 笔订单、移除 L 个价档 O(M + L log P) 不包含金额运算成本及安全预扫描
获取前 K 档 O(log P + K) 遍历 不每次 sort 全部价档

不把同价订单用随机时间排序;FIFO 由日志命令序号确定。订单索引只包含活动订单;终态摘要和幂等结果由专门结构保存,历史成交通过投影分页读取。

5.2 业务规则#

限价买单匹配 ask <= limit_price,限价卖单匹配 bid >= limit_price,均优先最佳价格,再同价 FIFO。成交价取 resting maker 价格。例如卖盘 100 × 2,买入限价 105 × 3,成交 100 × 2,剩余 1 在 105 挂单。

订单类型 规则 剩余处理
LIMIT / GTC 到限价范围内立即撮合 剩余按本次受理序号挂单
LIMIT / IOC 到限价范围内立即撮合 剩余取消,释放冻结
MARKET / IOC 必须提供保护价格;买单不高于保护价,卖单不低于保护价 剩余取消,永不挂单

市价单流动性不足但能够部分成交时,返回成交数量和取消余量;无任何可成交对手时仍返回正常订单响应,状态 CANCELED、零成交,cancel_reason 为 NO_LIQUIDITY 或 PRICE_PROTECTION,无冻结残留。接口不使用 panic 表达流动性不足。

自成交采用 cancel_taker:预扫描在价格时间顺序中遇到本账户订单,则停止继续扫盘;此前遇到的其他账户订单允许成交,taker 剩余以 SELF_TRADE_PREVENTED 取消,不跳过同价 maker,也不改变 resting maker。

5.3 生命周期#

OPEN → PARTIALLY_FILLED → FILLED;活动单可转 CANCELED。即时单部分成交后取消仍记为 CANCELED,并保存非零 filled_quantity 和 cancel_reason;校验失败为 REJECTED。完全成交后撤单返回 409 ORDER_TERMINAL,不存在返回 404 ORDER_NOT_FOUND。同一幂等撤单重试返回首次结果,新幂等键重复撤单返回 ORDER_TERMINAL。

订单保存 original/remaining/filled/canceled 数量,始终满足:

original_quantity = remaining_quantity + filled_quantity + canceled_quantity。

一个命令完成后不能保留交叉挂单:有效 GTC 买盘最佳价应低于卖盘最佳价。同账户相遇的 taker 取消策略也避免交叉簿。

6. 模拟账户与结算#

只做订单簿而不约束余额会允许无限买卖,因此首版包含最小模拟资金闭环。注册先提交用户到 auth.db,再用 CREDIT 初始化 ETH/USDT;初始化也进命令日志,固定幂等键避免重复启动/登录注资。身份与资金初始化不在跨库事务里,登录会重试补齐中断步骤;详细边界见认证设计。

账户按 (account_id, asset) 保存 available 和 frozen:

  • 限价买单冻结 limit_price × original_quantity;市价买单冻结 protection_price × original_quantity。采取最坏成本资金检查,资金不足直接拒绝,不按可见深度临时放宽额度。
  • 卖单冻结 original_quantity ETH;买卖双方均不得出现负余额。
  • 成交时买方冻结减少 reservation_price × fill_quantity,卖方冻结减少 ETH 成交数量;买方可用 ETH 增加成交数量,卖方可用 USDT 增加 maker_price × fill_quantity。
  • 买方将 (reservation_price - maker_price) × fill_quantity 退到可用 USDT。卖出 taker 的价格不参与买方 reservation,买方 reservation 按买方订单本身计算。
  • 撤单/IOC 余量/自成交阻止时释放余量对应冻结。校验或预扫描拒绝时不产生冻结和成交。

以 price=105、quantity=3 的买单为例,初始冻结 315;在 100 成交 2 后,消耗冻结 210,卖方收到 200,买方释放 10,剩余冻结 105。

核心先验证,再一次性完成命令的业务变更,外部只能看到完整结果。资金变化输出成不可变的账户分录,使用稳定 (command_seq, entry_index) ID。每笔成交每种资产的全账户变化相加为零;冻结/释放为同一账户可用和冻结的转移。初始化外部注入使用明确的发行源账户或供应记录,不伪装成交易收入。

7. 序号、ID 与幂等#

JournalWriter 是全局定序者,序号在事务内连续写入 commands;持久化高水位来自已提交日志末尾,未另设日志进度表,重启恢复后从该位置继续。第一版使用有符号 64 位正序号并在耗尽前拒绝,避免 SQLite 整数边界问题。

新订单 ID 取首次有效下单命令的 command_seq,允许因为撤单、拒绝或查询以外的命令产生间隙。成交 ID 使用 (command_seq, match_index);HTTP 的 ID 和序号都编码为字符串,避免 JS 安全整数限制。时间仅用于展示与外围延迟测量,不决定排序。

写接口要求 Idempotency-Key,业务幂等键为 (account_id, key),同账户不同写接口也共享键域。外围计算规范化业务载荷摘要,忽略服务器接收时间和本次序号;价格 1.0 与 1.00 规范化后相同。核心第一次处理保存载荷摘要与完整业务结果;相同键、相同内容返回首次结果,相同键、不同内容返回 409 IDEMPOTENCY_CONFLICT。

并发重试可以被记录成多条输入命令,但不会创建多笔订单或冻结两次。每条输入仍产生自己的“处理完成”投影 envelope 以推进序号;重复结果引用首次订单及业务序号。响应区分 processed_seq(本次 envelope)与 result_seq(首次业务结果)。业务拒绝也被幂等记住,余额改变后希望再试需使用新键。

第一版核心保留全部幂等摘要/结果和必要终态摘要,内存随命令量增长,明确作为演示数据量限制和压测观测项;不偷偷设置过期时间破坏重试保证。长期运行的有界去重方案需设计调用期限和持久化查验,列入后续 ADR。

HTTP 在日志提交后超时,表示客户端不知道结果,不表示命令撤销。504 RESULT_UNKNOWN 或网络断开后以相同键、相同内容重试;已经入队的请求若在提交前连接断开,也可能继续被受理。前端不自动换键重复下单。

8. 持久化模型、查询与恢复#

8.1 实际数据表#

文件 / 表 实际内容
journal / metadata、commands engine_version=1、dataset_id;seq 与 JSON payload(schema/摘要/时间)
auth / users、sessions、auth_audit 身份/密码摘要、会话 token 摘要/CSRF/期限、状态审计
views / orders、balances、levels 订单、精确资产、按 ticks 聚合价档
views / trades、ledger、results 确定性成交 ID、(seq,idx) 分录、每个 envelope 结果
views / progress、credit_audit、projection_metadata 单行水位、管理资金执行结论、可幂等迁移标记

价格排序、分页依赖 price_ticks、序号和复合索引;禁止 SQLite 把金额 TEXT cast 成 REAL 后参与结算。数据库包含变更版本,DDL 由外围迁移执行。

输入日志和投影各自仅一个写入者,当前每库最多一条连接,读写竞争连接;每条新连接设置相应 foreign_keys、busy_timeout、synchronous 等连接级配置。选用实际内嵌 SQLite 已修复 WAL-reset 问题的驱动版本;至少 3.51.3 或官方修复回移版本,记录运行时 sqlite_version()。

8.2 查询一致性#

行情/订单/成交/命令结果从 views 只读事务取得数据及 applied_seq;余额仍返回数组,不与订单请求构成同瞬间快照;用户/认证审计来自 auth。下单返回 processed_seq=120 而查询只有 applied_seq=118,这是明确可观测的投影滞后。

查询可带 min_seq=120。外围最多等待 2s,超时返回 503 PROJECTION_LAG(当前响应不含水位),不返回冒充最新的数据。该机制满足“下单后读到自己的写入”,不让查询线程触碰核心。账户是否能下单只由核心余额裁定。

8.3 重启恢复#

  1. 启动时先不开放写接口,执行迁移、元数据和 SQLite 完整性检查;只允许一个应用实例占用同一数据目录,由成熟文件锁库完成外围进程互斥。
  2. 读取输入日志,从 1 起依次向新建核心重放,不再生成新序号和时间,不调用 HTTP/链上服务,也不发送历史业务响应。
  3. Projector 读取自己的 applied_seq=N。重放结果中 seq<=N 不再应用,seq>N 按序应用;如果投影缺失,从零重建。业务结果的可选摘要用于回归比对。
  4. 检查最后核心序号、日志高水位和投影水位一致,验证订单簿、数量与资金不变量后开放 readiness 和接入。

不要求日志和投影做跨数据库事务:投影允许落后而不能超前,缺失部分可由已提交输入重算。去重效果及拒绝结果同样由确定性重放恢复。输入日志不能从查询投影反推重建。

8.4 故障窗口#

故障点 恢复行为
命令尚未提交日志 不保证受理;事务未提交内容由 SQLite 回滚,相同幂等键可重试
日志提交成功,尚未撮合 重启重放一次业务效果
撮合后未回包 重放恢复业务与幂等结果;客户端同键重试返回首次结果
核心完成,投影未提交 重放补齐未应用 envelope
投影事务中途崩溃 表更新及水位一起提交或一起回滚
投影损坏或缺失 备份损坏文件供诊断,停止服务,从输入日志重建
输入日志损坏、提交状态不确定 停止写入,保留原始文件,完整性检查和备份恢复;不自行截尾或跳过交易

FULL 提交的耐久性依赖本地文件系统和存储对同步写的正确实现;本地磁盘损坏仍需备份。kill -9 只能验证进程崩溃窗口,不能声称完成真实断电验证。

8.5 快照(第二阶段)#

第一版保留全部输入,从头重放提供最小可靠闭环。达到恢复耗时目标后再实现快照:核心在两个完整命令之间导出不含共享引用的状态副本,外围编码与持久化;副本包含最后处理序号、市场配置、活动订单及 FIFO、账户、幂等和终态摘要。

外围快照文件包含版本、序号和校验摘要,完成写入、fsync、原子重命名和父目录同步后才发布 manifest。快照失败保留上一个快照并继续保留日志。首版快照不删除输入历史;未来压缩需同时证明恢复、幂等、审计和备份覆盖。复制可能暂停核心,必须记录暂停时长,不能宣称快照完全无成本。

9. REST 与 WebSocket 契约草案#

v0.3 契约以 api/openapi.json 为源,生成 TS 并以 kin-openapi 校验真实响应;Go DTO/ServeMux/fetch 保留手写。表中业务路由均已实现;metrics 位于独立 loopback 诊断监听,业务监听返回 404。用户/审计也已分页,详见完成设计。

路由 用途
GET /api/v1/markets 市场精度与规则
POST /api/v1/orders 下单,必须有幂等键
POST /api/v1/orders/{id}/cancel 撤单,Cookie 会话账户与幂等键
GET /api/v1/orders 当前会话账户订单页,limit/cursor/min_seq
GET /api/v1/orders/{id} 单笔订单及当前投影水位
GET /api/v1/balances 当前会话账户余额
GET /api/v1/markets/{symbol}/book?depth=20 聚合价档,限制 depth
GET /api/v1/markets/{symbol}/trades?limit=50 成交,限制 limit、稳定游标
GET /api/v1/commands/by-key?key=... 当前会话账户首次投影结果;found=false 不证明未受理
GET /api/v1/stream WebSocket 全量行情快照
GET /health/live、GET /health/ready 进程和恢复就绪状态
GET /metrics 独立 loopback 诊断端口,业务端口返回 404

下单示例:

POST /api/v1/orders
Idempotency-Key: demo-a-buy-001
X-CSRF-Token: <登录返回的csrf_token>
Cookie: exchange_session=<会话凭证>
Content-Type: application/json

{"market":"ETH-USDT","side":"BUY","type":"LIMIT","time_in_force":"GTC","price":"2500.00","quantity":"0.1000"}

响应的 order 对象含 id、状态、数量分解,另含 processed_seq、result_seq 和 replayed。新建订单返回 201,幂等重试返回 200;即时部分成交并取消属于已成功处理的订单响应。统一错误 envelope:

{"error":{"code":"INSUFFICIENT_BALANCE","message":"USDT 可用余额不足"},"processed_seq":"120","result_seq":"120","replayed":false}

语法错误 400,未登录 401,权限/CSRF/Origin 拒绝 403,核心业务拒绝含资源预算为 422,幂等/终态/数据集冲突 409,不存在 404,认证频率限制 429,接入/WS 容量与投影故障为 503,受理后等待超时 504;恢复完成前尚未监听,不能假称恢复期一直能返回 503。日志前错误没有业务序号。当前空买卖盘以 bids:[]、asks:[] 表示,不返回伪造的零价订单。

撤单先通过服务端会话认证,再由核心检查订单归属,避免误撤其他账户;两层保证各司其职。

外围采样器每 100ms 从一个投影读事务生成 Snapshot,字段直接为 dataset_id、applied_seq、前 20 档和最近 50 笔成交,没有额外 type/market 包装。连接通过定时 tick 读取最新采样快照,首次发送及水位变化时发送;前端首次挂载另外请求 HTTP snapshot,WS 重连等待最新 tick,不保证立即 REST 拉取。快照序号允许跳跃,客户端在同 dataset_id 丢弃旧快照,新 dataset_id 接受低序号;不设计增量 delta 的连续性协议,也不承诺浏览器收齐每笔成交,当前订单 REST 已支持游标,成交历史/用户/审计分页已完成。采样器整体替换最新快照,各连接不积压逐笔事件;网络写超时 2s 后断开。快照内同 seq 成交按文本 ID 排序,完整成交历史另用 rowid 游标,不能假称文本 ID 是数字下标倒序。

10. 前端设计与联调#

React + TypeScript + Vite;gsap + @gsap/react,按 frontend-design、gsap-core、gsap-performance、gsap-react 技能约束落地。用户要求中的 gzap-skills 按 GSAP 动画技能理解。

使用已建立的 IBM Carbon White 配色,直接引用既有 token:背景 White #ffffff、分区 Gray 10 #f4f4f4、边线 Gray 30 #c6c6c6、正文 Gray 100 #161616、操作 Blue 60 #0f62fe、错误 Red 60 #da1e28、成功 Green 60 #198038。颜色服务操作与交易状态,不另创调色板。后续对具体文字/底色组合检查对比度,买卖含文字标识,不只靠红绿颜色。

禁止渐变和圆角方框,所有控件与面板 border-radius:0;用直线分隔的紧凑交易工作台。IBM Plex Sans/本地中文无衬线作为界面文字,IBM Plex Mono 作为价格数量字体,数字右对齐且使用等宽数字。

ETH / USDT                         演示账户 A     已连接
──────────────────────────────────────────────────────
盘口                         下单                  余额
卖价 / 数量                  买入 / 卖出          ETH
最佳卖价                     限价 / 市价          USDT
最佳买价                     价格 / 数量
买价 / 数量                  买入
──────────────────────────────────────────────────────
当前订单:价格 / 数量 / 已成交 / 状态 / 撤单
──────────────────────────────────────────────────────
最近成交:时间 / 价格 / 数量

小屏按下单、盘口、订单、成交顺序堆叠;保留键盘焦点、label 和错误关联。界面文案简短:价格、数量、可用、冻结、买入、卖出、撤单、已连接;架构术语和日志水位放开发文档,正常页面不展示实现细节。

GSAP 只用于必要的行情变化提示和面板进入,150–250ms 候选时长;优先 transform/opacity,盘口量条使用 scaleX 而非 width。批量刷新 DOM,动画只作用于可见项;频繁同属性变化复用 quickTo/覆盖旧 tween。通过 useGSAP 作用域和 contextSafe 管理交互动画及清理,matchMedia 尊重 reduced-motion,不常驻无限动画或给全部节点设置 will-change。

开发用 Vite 代理 /api 和 WebSocket,生产由 Go 静态资源服务或反向代理同源分发。写操作先存 sessionStorage 保留原内容/稳定键直到明确结果,同标签页刷新可恢复;成功后查询携带 min_seq,遇到投影滞后显示“更新中”。交付时记录真实浏览器下单、成交、撤单、余额变化、断线重连证据。

11. 工程结构#

cmd/server/                 服务装配、诊断与生命周期
cmd/exchangectl/             离线初始化/检查/备份/恢复/投影重建
backend/engine.go、types.go  单写者核心与领域值
backend/runtime.go          提交屏障、队列、监督与排空
backend/store.go、query*.go  持久化投影和查询(另有 admin/market_query)
backend/auth.go、http.go     身份/权限与接入,observability.go 诊断
backend/maintenance.go      离线运维与对账
api/openapi.json            嵌入契约,生成前端类型
frontend/                   React 工作台、生成类型、真实浏览器测试
scripts/、deploy/           验证/性能/打包与云/容器配置
.github/workflows/          待推送运行的 CI 定义
docs/                       设计、规范、实验、部署和面试

采用紧凑 backend 包以保持学生项目可读;静态核心依赖测试限制核心文件引入 IO/锁,运行时所有权仍与目录名字无关。没有把初稿中的 internal 多目录拆分当成必须重构工作。

12. 性能、演进与验收#

先证明正确性,再测性能;重点报告纯核心吞吐/分配、日志提交延迟、端到端 p50/p95/p99、各队列深度、投影滞后、恢复时长及内存。初步场景目标为 100 命令/秒下可顺畅演示,端到端 p99 小于 100ms,10 万命令重放小于 30s;本版已取得短时 100/500/1000 请求/秒和 10万命令恢复证据,见报告;不对外承诺最大容量/百万 TPS。

可用 group commit 摊销同步写,但始终保留持久化屏障;应用队列解耦并不会消除磁盘瓶颈。若 profiling 证明 decimal 或 GC 为瓶颈,记录优化实验,不能未经讨论就替换用户指定的金额模型。按市场并行需要先解决跨市场共用资金的分区,不简单多开 goroutine。

单机容量估算、Redis 外围优化候选、多单写者分区及生产系统差距的深入说明见详细面试 Q&A。模拟模式未接Redis;链模式已接Redis缓存/限流,分区仍未实施;单机容量与恢复现有分层实测,边界见本版报告。

验收包含精确金额、价格时间顺序、可成交限价单、流动性不足正常返回、同键并发只生效一次、撤单和撮合竞态、恢复及投影重建、资金守恒、真实前端 API 调用、云服务器和容器两种路径。详细方案见测试设计、部署设计。

13. 当前已采用决策#

决策 建议 理由
单写者粒度 全局一个核心 goroutine 订单簿和共享账户同时消除业务锁
第一版资金 模拟 ETH/USDT,零手续费 可独立运行,交易和恢复闭环清晰
输入持久化 外围 SQLite WAL 日志库,FULL 批量提交 复用成熟事务与崩溃恢复,不自制日志文件格式
查询持久化 独立可重建 SQLite 投影 核心不做查询 IO,允许明确最终一致
快照 第二阶段实现,首版从头重放 先减少恢复协议复杂度
行情协议 小型全量快照,REST 查完整历史 前后端联调可靠,避免增量漏包协议扩大范围

用户已授权连续实现;当前选择已落地。后续业务或取舍变更仍须同步设计与验证,不把可选 P8 作为已实现能力。

文档一致性补充#

实现中的核心规则由 engine_version 与编译期常量共同约束,并未把可热改市场规则保存成配置表。成功响应前已 FULL 提交输入并 Apply,响应与去重/投影各自拥有独立对象;额度释放要等投影整批提交,详见阅读指南。

实际 HTTP 状态、游标、数据集与未知结果处理见接口使用指南,权威数据、离线重放成本与恢复限制见数据生命周期。最近正确性成绩见测试完善报告;历史 v0.3 负载数字不能替代修复后性能复测。

Windows 本地运行增量#

新增原生 Windows 一键构建/启动工具及回环本地管理员别名;变更仅在外围身份/配置/前端登录,不改变单写者核心、日志、资金与投影。常规密码规则保持,显式本地初始化允许 8–72 字节并约束回环;别名仍对应规范邮箱身份。设计与验证见Windows 说明与报告。

面向真实业务的后续架构评估#

从演示架构走向真实业务对照源码分析产品闭环、状态权威、链索引、对账、Tx Manager、可用性与交付门槛。阶段 A 已在 v0.5 完成,B–D 仍待实现,发售已在 v0.6 落地;本页模拟模式协议不因此改变,历史测试结论保留原日期。

v0.5 外围模块边界#

撮合继续走 FULL 日志→纯 Apply→投影/outbox;index.go 维护已确认链事件,reconcile.go 重放独立 Engine 检查全量快照。索引、结算、采样各自调度且可停止,均不取得运行核心指针。事务只能在一个库内原子,跨库依靠幂等和延迟分类。

独立读池:日志/投影的 WAL 读取与唯一写连接分开,每读池1连接;SQLite读池query_only,PG任务Reader独立1连接,owner与任务写池仍分别占用专用/业务连接。TestReadSnapshotDoesNotBlockWriter 保持旧水位快照时仍能完成新命令,避免对账占住唯一写池。查询仍有CPU/磁盘与WAL保留成本,需要超时和后续增量策略。

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