# 08｜怎样沿着一次请求读完整个项目

前一站：[撮合与结算](07-trading-walkthrough.md) · 下一站：[故障和测试](09-failures-and-tests.md)

## 1. 不要从最大的文件逐行硬读

先确定一个问题，例如“点击领取，为什么只扣一次库存”，然后沿输入、状态、规则、持久化和测试寻找答案。每个文件先读包注释、类型、对外函数和测试名，遇到暂时不懂的库函数先记下职责，再回头追实现。

项目大量中文注释会解释单位、所有者、事务、错误和恢复。注释是阅读帮助，实际判断仍要看代码和测试；生成文件则不适合手动修改。

## 2. 第一轮：从页面追一次发售

| 顺序 | 文件 | 先找什么 |
| --- | --- | --- |
| 1 | [SaleApp.tsx](../../frontend/src/SaleApp.tsx) | 当前钱包、活动、恢复状态如何决定主按钮；提交时如何避免重复操作 |
| 2 | [sale-api.ts](../../frontend/src/sale-api.ts) | HTTP 地址、Cookie/CSRF/dataset、错误与金额处理 |
| 3 | [http.go](../../flashsale/http.go) | 路由、可信会话、Origin 校验、参数限制、调用 Store 的边界 |
| 4 | [types.go](../../flashsale/types.go) | Config、Activity、Voucher、Reservation 的字段和单位 |
| 5 | [store.go](../../flashsale/store.go) | 活动锁、同钱包唯一、请求键、库存与 outbox 同事务 |
| 6 | [processing.go](../../flashsale/processing.go) | inbox/job、固定签名、确认与安全回收状态事务 |
| 7 | [worker.go](../../flashsale/worker.go) | 后台循环如何调用发布、签名、索引和回收 |
| 8 | [FlashSale.sol](../../contracts/src/FlashSale.sol) | createActivity、hashVoucher、purchase、消费标记和两种转币 |
| 9 | [chain.go](../../flashsale/chain.go) | 确认块、Purchased、块 hash、规范锚点与 consumed 核验 |

练习：把“前端倒计时到零”和“SQL 安全过期”分别圈出来，确认它们不是同一个函数直接触发的同一件事。

## 3. 第二轮：补中间件与启动

[flashsale/middleware.go](../../flashsale/middleware.go) 说明业务怎样发布/接收消息；[messaging/rabbitmq.go](../../messaging/rabbitmq.go) 说明通用连接、队列、confirm、ack 与重连。前者知道业务 payload，后者处理运输协议，两层分开便于复用。

[cmd/saleserver/main.go](../../cmd/saleserver/main.go) 负责读取配置、打开数据库、验证链域、建立后台任务并启动 HTTP。Go 的 main 是程序装配入口，不能据文件名把这里误认为全部业务代码。

[run-sale-windows.ps1](../../scripts/run-sale-windows.ps1) 准备 Windows 依赖；[sale-dev.mjs](../../scripts/sale-dev.mjs) 组装本地链和双服务；[sale-local.mjs](../../contracts/scripts/sale-local.mjs) 部署并准备发售 fixture；[sale-middleware.mjs](../../scripts/sale-middleware.mjs) 管理完整模式的中间件连接。

练习：从启动脚本中找到本轮数据目录，解释重新启动为什么要换 dataset，而浏览器刷新不用换。

## 4. 第三轮：读链交易

先读 [types.go](../../chaintrade/types.go) 的 SignedOrder/Order/Intent，再读 [engine.go](../../chaintrade/engine.go) 的 Apply 和数量状态。拿 3 lot 中匹配 2 lot 的例子，手算 Remaining、Pending、Filled、Canceled。

接着读 [store.go](../../chaintrade/store.go) 的日志/投影流水线、[tasks.go](../../chaintrade/tasks.go) 的任务版本和 raw 保护、[chain.go](../../chaintrade/chain.go) 的发送与回执、[Settlement.sol](../../contracts/src/Settlement.sol) 的最终约束。

最后补 [history.go](../../chaintrade/history.go)、[index.go](../../chaintrade/index.go)、[reconcile.go](../../chaintrade/reconcile.go) 和 [observability.go](../../chaintrade/observability.go)。它们分别解决“历史怎样查”“链事实怎样持久记录”“多处状态怎样核对”“问题怎样被发现”。

页面端配合看 [Web3App.tsx](../../frontend/src/Web3App.tsx) 和 [Web3History.tsx](../../frontend/src/Web3History.tsx)。不要把最近 100 项行情窗口误认为全部交易历史。

## 5. 第四轮：回到模拟系统补 Go 基础

[backend/types.go](../../backend/types.go) → [engine.go](../../backend/engine.go) → [runtime.go](../../backend/runtime.go) → [store.go](../../backend/store.go) → [auth.go](../../backend/auth.go) → [http.go](../../backend/http.go) → [App.tsx](../../frontend/src/App.tsx)。

这里能看到 decimal、订单簿、FIFO、冻结资金、幂等、三阶段流水线、查询水位、邮箱认证和管理员操作。想从空目录亲手写，再进入[23 章模拟教程](../03-development/from-zero-tutorial.md)，不要直接把教学协议覆盖已有数据库。

## 6. 看到这些写法时该问什么

| 代码概念 | 先问自己 |
| --- | --- |
| `context.Context` | 超时取消的是等待、当前 IO，还是已经受理的业务？ |
| `defer tx.Rollback()` | 哪些语句必须同一事务完成，失败时释放什么？ |
| `go` / channel | 谁唯一修改状态，队列是否有界，关闭时如何排空？ |
| `big.Int` / 整数字符串 | 字段到底是币、最小单位、tick、lot 还是份数？ |
| `Commit()` | 成功点在哪里，回包前后崩溃各留下什么？ |
| `Ack` / `Nack` | SQL 是否已接手，是临时错误还是永久错误？ |
| 版本条件更新 | 迟到任务能否覆盖较新的终态？ |
| React effect / 请求序号 | 切钱包或切活动后，旧响应还能写到新页面吗？ |

## 7. 如何用测试帮助读代码

测试名描述一个要证明的性质。先看准备的数据、触发动作和断言，再回到实现。失败样例能说明为何某条看似多余的检查不能删。

入口：[发售组件测试](../../flashsale/store_test.go)、[RabbitMQ 测试](../../messaging/rabbitmq_test.go)、[发售合约测试](../../contracts/tests/flashsale.test.mjs)、[结算合约测试](../../contracts/tests/settlement.test.mjs)。如果源码文件名与阅读入口变化，以[代码指南](../03-development/code-reading-guide.md)和测试目录为准。

完成本章的标志：你能不靠背诵，从一个按钮找到 HTTP、事务、任务、合约和确认索引的路径，并为每一层说出一个失败边界。
