# 开源与中间件选型

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

调研日期：2026-10-09。先检索官方说明、仓库源码和 GitHub 元数据，再选择；不以仓库 star 数或作者 benchmark 证明本项目性能。该段描述初次调研过程，不是当前安装状态；实现后的固定版本见本页末尾及 go.mod/package-lock.json。候选不等于已引入依赖。

## 1. 选型表

| 领域 | 检索候选 | 选择与理由 |
| --- | --- | --- |
| 十进制 | [shopspring/decimal](https://github.com/shopspring/decimal) | 遵循需求；精确加减乘，明确除法精度；直接阅读 LICENSE 为 MIT |
| 价档 | [GoDS](https://github.com/emirpasic/gods)、[google/btree](https://github.com/google/btree)、标准库 heap | GoDS 红黑树；已固定 `v1.18.1`，隐藏 interface 断言在小封装中；支持有序深度和任意价档删除 |
| 同价 FIFO | Go 标准库 `container/list` | 直接复用双向链表，订单索引保存节点，不自写链表 |
| 撮合现成库 | [i25959341/orderbook](https://github.com/i25959341/orderbook)、[exchange-core](https://github.com/exchange-core/exchange-core) | 两者均查阅，但暂不整体接入；下面给出具体不匹配点 |
| 事件流水线 | Go 有界 channel、Java LMAX Disruptor、第三方 Go port | 采用 LMAX 单写者思路，Go channel 起步；无性能证据前不开发 ring buffer 或 busy-spin |
| 输入日志 | SQLite WAL、[tidwall/wal](https://github.com/tidwall/wal)、[bbolt](https://github.com/etcd-io/bbolt)、PostgreSQL | 外围 SQLite 命令表 + WAL/FULL；复用事务、恢复与完整性检查，不自己写文件恢复协议 |
| Go SQLite 驱动 | [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite)、mattn/go-sqlite3 | 已采用 modernc v1.60.1，CGo-free；libc v1.77.1，实际内嵌 SQLite 3.53.4 |
| 读模型 | SQLite 独立文件 | 所有 SQL 在外围；结果按序投影，可以从输入重建 |
| HTTP | [chi](https://github.com/go-chi/chi)、Echo、net/http | 已采用标准 `net/http.ServeMux`，未引入 chi/Echo；路由与鉴权保持手写 |
| WebSocket | [coder/websocket](https://github.com/coder/websocket)、Gorilla | coder/websocket 有 context、连接关闭与 JSON 辅助；均在外围 |
| 接口生成 | [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen)、[openapi-typescript](https://github.com/openapi-ts/openapi-typescript) | 已用 openapi-typescript 生成 TS；Go DTO/路由/fetch 手写，以 kin-openapi 校验真实响应；未引入 oapi-codegen |
| 观测 | `log/slog`、[prometheus/client_golang](https://github.com/prometheus/client_golang) | 已采用 slog 与固定 Prometheus 文本输出，未引入 client_golang；计时/原子发布在外围 |
| 数据目录实例锁 | [gofrs/flock](https://github.com/gofrs/flock) 等成熟文件锁 | 已固定 gofrs/flock v0.12.1，Linux 本地目录验证；用于服务与离线工具互斥，不提供跨主机 fencing |
| 前端 | React / TypeScript / Vite；GSAP / @gsap/react；decimal.js（候选） | 已使用 React/TS/Vite/GSAP；金额仅传字符串，未安装 decimal.js；Number 只计算深度条展示比例 |
| UI 色彩 | [IBM Carbon](https://github.com/carbon-design-system/carbon) | 使用已有 White 主题色彩 token，满足成熟配色、无渐变、无圆角要求 |
| 部署 | 单机 systemd、Docker Compose + Caddy | 两套运行方式共享相同二进制与数据约定，单实例部署易验证 |

### 1.1 调研中发现的版本问题

GitHub 元数据显示 `google/btree` 在调研时已归档，最后推送时间 2024-08-21；归档不等于库不可用，但本项目优先 GoDS。GoDS `master` 已有 generic 代码，不能假设 master API 与 `v1.18.1` 一致；设计封装以固定稳定版源码为准，升级另做验证。

SQLite 官方 WAL 页面已披露 WAL-reset 问题：受影响版本包括 3.51.2，3.51.3 起修复，部分旧系列有回移修复。本项目实现时检查实际 `sqlite_version()`，不只看 Go driver tag。数据库写入和 checkpoint 由各自外围写者串行协调，不额外引入并发维护线程。

本轮部分 Go module proxy 请求失败，未检索出可靠的当前 latest module 版本，因此不编造“最新版本号”。实际开发锁定版本、许可证、Go 版本、漏洞检查结果写入开发记录。

## 2. 为什么不直接使用现成撮合引擎

`i25959341/orderbook` 提供 decimal、价格时间优先、市价、限价与撤单，`go.mod` 已使用 GoDS 和 decimal，证明这些基础组件可以复用。但当前 README 用 `github.com/muzykantov/orderbook` import，而仓库 go.mod 声明 `module orderbook`，README 函数返回签名也与当前源码不一致。接入前需固定可安装版本并验证。

其公开接口输出 done/partial 订单，尚未提供本项目需要的命令序号、完整 maker/taker 成交事件、模拟双资产冻结、全局幂等、价格保护及投影 envelope。直接接入再包装这些语义仍要做大量适配，且内部修改行为需审核以保证预扫描拒绝无副作用。保留为对照研究对象；核心只自写这些业务规则，树、链表、金额、持久化均复用。

`exchange-core` 是 Java 项目，明确使用 LMAX Disruptor，包含风控、账务、日志与快照，适合学习结构，但直接引入会增加跨语言运行与接口适配，也偏离 Go 面试项目的核心目标。其 README 高吞吐数值属于作者指定硬件和场景，不能搬为本项目指标。

## 3. WAL 存储方案取舍

| 方案 | 优点 | 本项目需额外承担 | 本版选择 |
| --- | --- | --- | --- |
| tidwall/wal | 单调 index、WriteBatch、默认 NoSync=false、分段与截断，简单直接 | 需明确末尾不完整记录处理、业务 envelope 校验、版本、幂等、备份一致性；源码内部有 mutex，放外围可接受 | 候选性能实验，暂不使用 |
| SQLite WAL | 原子事务、崩溃恢复、SQL 审计、完整性检查、成熟备份工具 | 更重的编码与 SQL 开销，批量提交、checkpoint、连接配置；仍需应用命令重放 | 采用；全部 IO 在外围 |
| bbolt | 成熟 KV 事务、单写者、纯 Go | 需要自定义命令索引及查询层，格式与备份依赖 KV 设计 | 保留替代，不和 SQLite 双持久化 |
| PostgreSQL | 成熟事务、运维生态和未来远程部署 | 单机演示多一个服务；持久化层网络路径和故障更多 | 后续按测量和需求迁移 |
| RabbitMQ / Redis Streams | 任务队列、消费确认与生态 | 不能代替账户/撮合状态机 | 模拟首版不加入；当前链交易/发售采用 RabbitMQ |

将 SQLite 移到外围后，核心并不调用 SQL；但流水线总体依然受耐久日志吞吐限制。若以后替换 tidwall/wal，只替换 Journal 接口是不够的，还必须重新验证提交不确定、尾记录恢复、备份和版本协议。

## 4. 官方与源码来源

| 来源 | 本轮使用的信息 |
| --- | --- |
| [LMAX Architecture](https://martinfowler.com/articles/lmax.html) | 单线程业务处理器、event sourcing、外部服务隔离、队列流水线；该文描述 JVM 实现 |
| [SQLite WAL](https://www.sqlite.org/wal.html) | WAL 提交/恢复、checkpoint、同机文件限制、WAL-reset 修复说明 |
| [SQLite synchronous](https://www.sqlite.org/pragma.html#pragma_synchronous) | FULL/NORMAL 耐久语义，连接级配置 |
| [SQLite transaction](https://www.sqlite.org/lang_transaction.html) | 事务读写与提交行为 |
| [SQLite backup](https://www.sqlite.org/backup.html) | 在线备份，不直接复制正在写入的 .db |
| [modernc SQLite 包文档](https://pkg.go.dev/modernc.org/sqlite) | CGo-free、连接池限制及 libc 版本配套要求 |
| [GoDS 固定版红黑树](https://github.com/emirpasic/gods/blob/v1.18.1/trees/redblacktree/redblacktree.go) | 自定义 comparator、非线程安全、Put/Get/Remove/Left/Right |
| [GoDS 固定版 iterator](https://github.com/emirpasic/gods/blob/v1.18.1/trees/redblacktree/iterator.go) | 顺/逆有序遍历，不以完整排序实现深度 |
| [decimal 源码与许可证](https://github.com/shopspring/decimal) | NewFromString、金额运算、MIT |
| [tidwall WAL 源码](https://github.com/tidwall/wal/blob/master/wal.go) | WriteBatch 中 sync，NoSync 和内部锁；未对其断电恢复做实验 |
| [Carbon colors 源码目录](https://github.com/carbon-design-system/carbon/tree/main/packages/colors/src/dtcg) | 官方色彩定义，避免自行编造色板 |
| [Carbon typography](https://github.com/carbon-design-system/carbon/tree/main/packages/type) | IBM Plex 与既有字号体系 |
| [GSAP React 文档](https://gsap.com/resources/React/) | useGSAP、作用域、清理 |
| [GSAP matchMedia](https://gsap.com/docs/v3/GSAP/gsap.matchMedia/) | reduced-motion 与响应式清理 |

所有库在引入时记录固定版本和 LICENSE。GoDS 为 BSD-2-Clause 主体，附加代码许可证见其 LICENSE；decimal GitHub 元数据的 SPDX 检测不完整，但直接 LICENSE 明确为 MIT。依赖升级通过兼容测试和更新记录，不能运行全量 `@latest` 覆盖已验证组合。

## v0.2 新增依赖与复用

2026-10-11：检索官方项目说明与固定版源码后锁定 `openapi-typescript 7.8.0`（MIT，devDependency），支持 OpenAPI 3.0/3.1，生成无运行时代码 TS 类型；Node 22 满足当前工具环境。`kin-openapi v0.133.0`（固定版 LICENSE 为 MIT）仅测试引用 openapi3 加载/结构验证/VisitJSON，避免自行编写契约校验器。Go 领域 DTO/路由先手写并用真实响应校验，不宣称生成了 Go 服务端或完整 fetch 客户端。

来源：[openapi-typescript](https://github.com/openapi-ts/openapi-typescript)、[kin-openapi 固定版](https://github.com/getkin/kin-openapi/tree/v0.133.0)、[OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3)。前端 lockfile 与 Go sum 固定传递依赖，npm audit 零漏洞见[本版报告](../reports/2026-10-11-v0.2.md)。

## v0.3 运维与工具链修复

2026-10-11：运维继续复用 modernc SQLite 的事务/checkpoint 与 gofrs/flock，独立重放对账复用既有 Engine/ProjectBatch；pprof 用 Go 标准库，Prometheus 固定文本格式输出阶段计数，避免安装新的基础服务。Go net/http 负载发生器使用固定工作者/有界队列，Python 只负责独立环境与资金对账；不自制 profiling/无锁环形队列。

govulncheck 扫描旧 Go 1.26.0 标准库发现可达漏洞，按实际漏洞修复版本升级最低 Go 1.26.9，并固定 x/crypto v0.58.0、x/sys v0.49.0。诊断工具固定 x/vuln v1.9.0（BSD-3-Clause），只作为扫描工具不进入业务依赖。前端审计实际零漏洞；Go 可达扫描与模块中未调用漏洞分开报告。版本/API 来源为固定模块元信息和扫描结果，见[v0.3 证据](../reports/2026-10-11-v0.3.md)，没有无差别升级全套 @latest。

## 当前依赖与选型核对

| 已使用组件 | 固定版本 | 使用位置 |
| --- | --- | --- |
| Go | go.mod 最低 1.26.9 | 标准 HTTP、slog、pprof 与编译工具链 |
| decimal / GoDS | 1.4.0 / 1.18.1 | 核心金额、价格红黑树 |
| modernc SQLite / libc | 1.60.1 / 1.77.1 | 三库事务；sqlite_version() 实测 3.53.4 |
| coder/websocket / flock | 1.8.13 / 0.12.1 | 外围推送、目录互斥 |
| x/crypto / x/sys | 0.58.0 / 0.49.0 | bcrypt、系统支持；升级原因见 v0.3 报告 |
| kin-openapi / openapi-typescript | 0.133.0 / 7.8.0 | 真实响应契约测试、TS 生成 |
| React / TypeScript / Vite | 19.1.0 / 5.8.3 / 6.4.4 | 页面、类型检查、构建 |
| GSAP / @gsap/react | 3.13.0 / 2.1.2 | 组件作用域动画与清理 |
| Playwright / Prettier | 1.64.0 / 3.5.3 | 浏览器验证、格式检查 |

版本表是当前锁定状态，不宣称 2026-10-11 网络检索到的最新版本。许可证与仓库状态的调研结论保留其调研日期；升级时重新核验。模拟模式Redis/消息总线仍未接入；链模式已使用Redis/PG/RabbitMQ，快照、decimal.js、Go路由生成仍为后续。

## v0.4 链模式选型

复用go-ethereum做ABI/RPC/EOA交易，pgx做PG、go-redis做Lua/cache、amqp091-go做RabbitMQ、OpenZeppelin5.4.0做ECDSA/EIP712/SafeERC20/ReentrancyGuard、ethers6.17.0做钱包、solc0.8.37编译、Anvil1.4.4做真实本地EVM。最终Go版本以go.mod和本轮漏洞报告为准。ganache初次审计有严重漏洞，已移除；固定锁文件与npm audit结果保留证据，未声称未来永无漏洞。

## v0.5 选型落实

继续复用 go-ethereum、SQLite、pgx、Redis、amqp091-go、OpenAPI 与 React，不替换成自研消息队列/分布式锁。索引用标准 eth_getLogs 固定 blockHash 补拉；事务保护事件/游标。任务 version BIGINT 同时支持 PG/SQLite，公开响应单独 TaskView。Prometheus 接标准文本 histogram 和规则配置，后续容量要求再引入专业索引服务与独立对账角色。
