Web3 交易系统
开发与源码

开发规范

当前 v0.6 增加独立发售与 RabbitMQ,见发售架构和本轮验证。下方 v0.3/v0.5 为既有核心的规范背景。

发售库存、资格、请求去重与 outbox 必须同一 SQL 事务提交;Redis 只做准入。消息发布经 RabbitMQ confirm 后才标记 outbox,消费经 SQL inbox/签名任务提交后才 ack,重投保持原业务 ID。持久凭证不能因重试改变正文或 deadline。过期回收必须基于同一已确认块的 hash、timestamp 和链上 consumed 状态,禁止按本机倒计时释放库存。前端在未知结果时恢复原请求/交易,不生成第二次购买。

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

历史 v0.4 变更记录(当前增量见页首 v0.5):链模式新代码仍需充分中文注释:整数tick/lot/原子单位、pending与filled、raw交易持久化顺序、对象所有权、取消竞态及恢复边界。Engine禁止SQL/JSON/RPC/时钟/随机/业务锁,由架构测试守护;手写OpenAPI经生成TS检查,生成文件不手改。未知广播保留原nonce/raw,禁止用Redis锁冒充资金或exactly-once。 当前链实现见v0.5架构,操作见开发、测试、部署,证据见本轮报告。

状态:开发规范,更新 2026-10-11。适用于当前及后续业务代码、测试、前端、配置和文档;架构变更以架构设计为准。

第 8 节充分注释已落实到现有源码,阅读入口见代码阅读指南。v0.2 已落实 OpenAPI/生成 TS、订单游标分页/数据集标识;v0.3 完成用户/审计/成交分页、loopback 指标/pprof、schema 校验、离线运维/对账、验证脚本与 CI 文件。Go 生成路由按 ADR 不采用;业务语义升级仍需单独历史 fixture。当前能力以实现和报告为准。

1. 领域与并发边界#

  1. engine、orderbook、领域金额代码只做内存业务运算。禁止 import SQL 驱动、HTTP/WebSocket、文件操作、观测输出包;禁止 time.Now、rand、sync.Mutex/RWMutex。
  2. 一个核心 goroutine 执行全部 Apply;新市场不能自行引入另一写者。核心拥有树、链表、订单、账户、去重状态,外围不读取这些对象。
  3. DTO、日志命令、核心结果必须有明确定义的所有权。跨队列后不复用 slice/map/指针;禁止把 OrderRef 暴露给 transport。
  4. 核心业务错误返回错误码。内部不变量破坏可以触发外围监督停机,禁止 recover 后继续撮合;不得把整个命令中途回滚交给 panic。
  5. 所有外围任务有生命周期、有限资源、超时与错误回传。禁止每条请求无限创建后台工作、无限队列、忽略 goroutine 错误。
  6. 接入后 HTTP context 取消不取消业务命令;关闭、背压和恢复分别由 runtime 协调。

2. 金额与 ID#

  • 价格、数量、余额、成交额为 decimal;解析仅从受限十进制字符串,禁止 NewFromFloat 和金额 float 中转。
  • 使用 decimal 方法比较与四则运算,不用 Go == 比较内部表示。展示除法明确精度,不能以展示均价结算。
  • 精度、tick、step、上限由已版本化市场配置定义;超精度拒绝,不能悄悄截断。
  • 只有索引用受控 int64 price_ticks,转换经过整除及溢出校验;金额数据库列为 TEXT。
  • API 的 seq/ID 为字符串;日志 INTEGER 限制有符号 64 位,拒绝溢出。
  • ID、事件索引、受理时间在输入确定后固定。恢复过程中不重新取时间、生成 UUID 或更改市场配置。

3. 数据与恢复协议#

输入日志先提交再撮合,JournalWriter 只能发送已提交前缀;投影不能超前。投影的业务更新和 applied_seq 同一事务,不能先更新水位再补余额。

各数据库连接初始化连接级 pragma,验证实际值。Journal/Projector/迁移/备份/checkpoint 都在外围,有明确的写者或维护锁协调,不在运行期间多进程操作同一个数据目录。

命令包含 schema_version,恢复遇到未知版本拒绝启动并说明需要的程序版本。变更引擎业务行为须验证历史 fixture;字段迁移和业务语义变更分开记录。生产数据的恢复、升级命令默认不删除原目录。

当前元数据保存 engine_version/dataset_id;市场规则是与引擎版本绑定的编译期常量,初始化资金以 CREDIT 输入日志并按系统保留键去重。未实现可热改的交易规则配置表。相同数据目录重启不重新注资、不自动挂演示单、不重置序号。

4. 接口规范#

OpenAPI 是字段名、枚举、金额字符串和错误码的契约源;生成代码头注明不可手改,检查重新生成无差异。当前源为 api/openapi.json,TS 由 openapi-typescript 生成,Go 仍手写且以 kin-openapi 真实响应测试对照;已提供 workflow 和本地 verify 脚本,未远程执行,不把文件存在称为远程 CI 通过。

接口使用 side:BUY/SELL,不继承 bid 布尔的歧义。未知字段、未知枚举、非法字段组合、超长载荷在接入层拒绝;资金和订单归属由核心验证。

写接口幂等键须限制长度和字符集,相同业务内容规范化后摘要一致;不把 request_id、received_at、seq 纳入摘要。响应保留 processed_seq/result_seq 的区别。

错误统一 JSON envelope,业务冲突与系统故障分开。日志与网络客户端必须检查返回值,客户端关闭 response body、配置 deadline、不把 4xx/5xx 解码为成功 DTO。列表限制 limit/depth,采用稳定复合游标,SQL 参数绑定避免拼接。

5. 日志与观测#

核心输出业务结果和统计增量,外围生成 slog 日志与 Prometheus 指标。区分 request_id、command_seq、order_id、trade_id;指标 label 使用有限枚举,不使用订单 ID、幂等键或完整账户作高基数字段。

当前指标包含 journal/Apply/投影阶段累计次数、累计与最大耗时,队列/在途占用、受理/容量拒绝/失败计数、三水位及投影 lag、恢复时长、订单/去重规模、堆/GC/goroutine。计时边界见 observability.go/runtime.go;批阶段 count 是批次数,core count 是命令数。尚无 HTTP 端到端/排队直方图、按业务原因拆分计数、告警平台;这些是后续观测目标,max 不得解释成 p99。

不记录原项目示例私钥,不在日志输出全部业务 payload。调试 pprof 和 metrics 仅在独立 loopback 监听;远程采样经受控 SSH 转发或容器网络命名空间访问,标准接口和错误响应不泄露堆栈。

6. 前端规范#

所有资金输入保留字符串;目前不做前端结算计算,未引入 decimal.js;将来需要预估时先引入经过核验的十进制库,不能用 JS Number 下结算结论。最终状态来自真实响应和查询,不写假成功或 mock 盘口替代联调。

引用 Carbon 色彩 token,禁止渐变、圆角方框,保持简短一致的文案与明确买卖标签。所有表单含 label、键盘操作、可见 focus 和不依赖颜色的状态;小屏正常操作。

GSAP 使用 @gsap/react/useGSAP、组件 ref scope、回调 contextSafe、卸载清理。优先 transform/opacity,盘口动画只处理可见数据并可中断,避免每条消息新建大量 tween;支持 reduced-motion。

网络断开后保留未明确结果的原内容和幂等键。v0.2 在发请求前保存 sessionStorage,按 dataset/账户/操作隔离;存储不可用则阻止发送。同标签页刷新可恢复,不承诺关标签/清存储后恢复。查询投影未赶上时保持“更新中”;不能拿旧余额覆盖最新下单反馈。接口重试区分幂等写和无副作用查询。

7. 代码、依赖与交付#

  • Go 执行 gofmt,使用可读的领域命名;依赖以接口围绕外部边界定义,不为每个结构体创建空泛接口。
  • Go modules、前端 lockfile、代码生成工具固定版本;Go/Node 构建镜像固定补丁标签,Debian 运行层为系列标签,尚未锁定 digest;README 主分支描述不等于发布版 API。
  • 引入依赖前核对许可证、release、兼容性及维护状态;保留归属,执行适用漏洞检查。
  • 测试优先验证业务性质与故障保证;低影响文案修改不增加镜像实现的机械测试。核心算法、恢复与资金变更必须有针对性测试。
  • 纯函数/单核心测试不启动业务服务;持久化和权限测试使用临时真实 SQLite/HTTP,前端纯函数用 Node test,hook/交互用真实浏览器。通过 scripts/test.sh 分层执行,新增业务测试同步用例目录。
  • 以每条命令后的数量/冻结/供给、价树/FIFO/索引和对象所有权为断言;测试不得只验证“无错误”。Go 覆盖率报告标注语句口径、未覆盖入口和子进程限制,不用提高百分比替代故障/权限验证。
  • 提交按可审阅单元组织:契约/领域、撮合、日志、投影、接口、前端、部署。变更说明写明问题、结果、验证与剩余限制。
  • 实现或决策变更同步更新架构、测试和部署;实验报告包含环境与原始命令,禁止只写“测试通过”。

每阶段完成定义:必要代码完成、相关测试通过、生成文件一致、文档更新、没有未解释的数据或恢复风险;不以“页面能打开”作为整个项目完成。

8. 代码注释要求(2026-10-10 新增)#

用户要求“完善代码的注释,越全越好”。将充分注释作为交付要求,适用于 Go/TypeScript、测试、脚本和部署配置。

  • 每个模块说明职责、依赖边界和关联文档;导出类型/函数及非平凡内部函数解释用途、输入输出和调用限制。
  • 并发代码标明可变状态的唯一所有者、队列生产者/消费者、阻塞点、关闭顺序、失败停机与重放行为;区分外围锁与核心无业务锁。
  • 撮合/资金解释价格时间优先、预扫描、自成交策略、冻结/释放与精确结算公式,给出人工可核对示例,注明数量/资金不变量。
  • 认证解释密码哈希、会话摘要、Cookie/CSRF/Origin、RBAC、管理员初始化和停用语义;不能把前端按钮隐藏描述为权限保证。
  • 持久化说明提交屏障、原子投影、水位、幂等、恢复、数据集/版本边界,明确哪些文件可重建。
  • 前端解释异步状态、请求取消、未知结果保留原幂等键、WS 重连、动画范围与卸载清理;仅展示用 Number 转换注明不参与结算。
  • 测试说明触发条件、为何断言能证明业务保证;部署脚本解释权限、卷、环境变量和不可逆动作。
  • 注释与实际行为一致,修改代码时同步修改。保留易读格式,以说明原因和边界为主,不机械逐行复述赋值,也不虚构尚未实现的保证。

审阅检查:从注册到下单、日志提交、核心撮合、资金变化、查询投影和重启恢复,读者可沿注释理解完整链路;剩余限制与文档一致。

当前落实位置:模块说明 ↗、撮合及资金 ↗、流水线 ↗、存储恢复 ↗、认证 ↗、接口 ↗、前端 ↗、测试证明点 ↗、部署配置 ↗。配套代码阅读指南提供调用链和人工可算例子。维护时优先更新源码旁说明,再同步指南/架构及验证报告,避免只有文档宣称充分注释。

9. v0.3 运行与维护规范#

诊断只用独立回环监听,固定阶段标签,禁止账号/key 高基数标签;核心不读时钟,外围计时。metrics max 不可写成 p99。常规 bash scripts/verify.sh 不修改源码/依赖,失败立即停止;CI 文件需远程实际执行才能称为 CI 通过。

离线维护取得服务相同 flock;backup/restore 拒绝覆盖目标,manifest/正规文件/摘要校验,金额逐表对账不走 SQL REAL。rebuild-views 保留原坏文件,不改 journal/auth。历史日志与去重不按 TTL 静默淘汰。新代码继续提供充分中文模块/函数/所有权/失败与资源注释。

新命令 schema_version=1,旧省略字段兼容 0;业务摘要排除格式版本/序号/时间,升级不破坏原键确认。未知格式/摘要错误/序号不一致直接拒绝恢复。Go 最低补丁 1.26.9;依赖升级同步 sum/构建/恢复与认证回归、govulncheck,模块未调用漏洞与可达漏洞分开记录。

10. 文档与注释的验收#

以源码、公开契约、真实测试为事实源。架构/认证解释保证,接口指南说明客户端流程,数据生命周期与排障手册说明维护动作,历史报告保留当时证据。当前结论变化时增加更正或新报告,不覆盖旧原始日志/摘要/性能成绩。

注释只修改轮次应检查去注释后的 Go/TS 语法结构和脚本有效内容未变,再做格式、构建、契约与适用回归。生成 TS、lockfile、构建产物、依赖目录和历史发布包不手工加注释。Markdown 链接、代码块、命令参数与环境变量均需核对;文档中的命令注明执行环境与资源影响。

Windows 本地工具补充#

本地演示凭证由用户明确指定,脚本只启用回环本地管理员例外,不放宽公开注册或常规部署。PowerShell 5.1 保留 UTF-8 BOM/CRLF、路径引用、原生命令退出码检查、进程环境恢复与生命周期;Windows npm 安装与 WSL node_modules 隔离。行为变更须测试别名/密码/RBAC/配置边界并同步契约,见Windows 指南。

v0.4 交付规则与注释审查#

每个新增顶层函数/类型提供用途和边界注释;状态字段解释单位或含义。特别核对:Price/Quantity的tick/lot、raw交易与链nonce、pending守恒、签名v必须27/28与EVM一致、旧域/未知版本拒绝、专用锁连接不可自动重连、confirmed取消竞态、日志与投影不同回包时机、React当前钱包每次复核、脚本固定端口不得连接别人的链。注释解释原因,避免只重复代码。

标准门槛包含chaintrade的单元/SQL/HTTP/架构测试、链OpenAPI生成一致性和真实schema校验。独立合约/浏览器/中间件/容器的环境条件与实际执行记录分开,参考链测试手册。接口修订不手改生成文件,证据和源码摘要不得由历史发布包推定。

v0.5 持续规范#

新增模块必须注释数值单位、事务边界、游标条件、旧数据未知时间、错误分类与回滚边界。数据库结构改动用事务显式版本;任务读后更新必须 CAS,禁止终态回退和签名交易换 nonce。公开返回使用 TaskView,禁止 raw/密钥。对账只读,不实现“发现差异就自动补发”。

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

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