ENGINEERING CASE STUDY · RCA · POSTMORTEM
Gin + go-ethereum + Go embed + godotenv 的完整实现复盘，包含架构图、ERD、数据流、时序、故障根因和分阶段演进路线。
阶段结论： 当前项目已经跑通"浏览器 → Gin API → ethclient → Ethereum RPC"的只读闭环，并解决 Web 交付、框架选择、公共 RPC、GoLand 启动和 .env 加载问题。但它仍是查询型 Demo，不是完整链上数据平台；下一阶段的核心是 Indexer、数据库、Checkpoint 与链重组处理，而不是继续增加实时 RPC 页面。
一、背景与问题
项目从一个问题出发：如果用 Go 做链上数据服务，究竟需要哪些 API，后端应该选 Gin 还是 go-zero，以及如何提供一套可以直接操作的 Web 页面？
早期曾通过 Nginx 的 alias + autoindex 暴露本地目录，浏览器却只显示 undefined。这暴露了一个架构误区：目录可访问不等于应用可运行。链上数据产品需要应用入口、后端 API、RPC 访问和错误处理，而不是一个文件列表。
最终方案改为单进程交付：Gin 提供 HTTP API，go-ethereum/ethclient 访问标准 JSON-RPC，Web 控制台通过 Go embed 打包进二进制。
图 1：本地运行的 ChainScope 控制台，已连接 Ethereum 主网并返回真实最新区块数据
二、目标与约束
| 目标 | 本阶段结果 |
|---|---|
| 连接任意 EVM HTTP RPC | 已完成 |
| 查询网络、区块、交易、余额和日志 | 已完成 |
| 无需 Node.js 与 Nginx 的 Web 控制台 | 已完成 |
| GoLand 直接启动与 .env 配置 | 已完成 |
| 持续同步、数据库、重组处理 | 下一阶段 |
当前系统坚持只读边界，不接触私钥、不签名、不发送交易。公共 RPC 用于零成本验证，但不承诺 SLA；日志查询最大跨度限制为 5000 个区块，所有链上大整数使用字符串返回，避免 JavaScript 精度损失。
三、当前系统架构
图 2：当前架构采用单进程交付，Gin 同时承载 API 与嵌入式控制台
系统只有一个可执行进程。页面与 API 同源，因此无需额外配置 CORS；HTML、CSS 和 JavaScript 通过 embed.FS 编译进二进制，部署时只需启动 Go 服务。
| 组件 | 职责 |
|---|---|
| Server Bootstrap | 加载配置、连接 RPC、读取 Chain ID、启动和关闭 HTTP Server |
| Gin Handler | 路由、校验、超时、错误映射和 JSON 转换 |
| ethclient | 封装标准 EVM JSON-RPC 调用及链上类型 |
| Web UI | 概览、查询表单、JSON 高亮、复制与浏览器本地历史 |
四、为什么选择 Gin
Gin 不是因为"最强"而被选择，而是与当前复杂度匹配。项目只有一个进程、少量只读接口和明确的 RPC 边界，Gin 已能提供路由分组、中间件、错误恢复和 JSON 输出，同时不强制引入代码生成、服务发现和微服务治理。
| 方案 | 适用阶段 | 取舍 |
|---|---|---|
| Gin | 单体 API、Demo、中小型服务 | 开发直接、约束少；治理能力需自行补充 |
| go-zero | 明确拆分的微服务体系 | 代码生成和治理完整；当前阶段偏重 |
| 标准库 net/http | 极简服务或底层组件 | 依赖最少；路由与中间件需更多自建 |
五、API 与数据流
基础读取只需要 EVM JSON-RPC，不需要 Etherscan API，也不需要钱包私钥。当前服务使用 eth_chainId、eth_blockNumber、eth_getBlockByNumber、eth_getTransactionByHash、eth_getTransactionReceipt、eth_getBalance 和 eth_getLogs。
GET /healthz
GET /api/v1/network
GET /api/v1/blocks/latest
GET /api/v1/blocks/{number}
GET /api/v1/transactions/{hash}
GET /api/v1/accounts/{address}/balance?block=latest
GET /api/v1/logs?address={contract}&fromBlock={n}&toBlock={n}&topic0={hash}
图 3：从浏览器输入到链上节点，再回到 JSON 展示的完整数据流
前端校验用于缩短反馈路径，后端校验才是真正的安全边界。调用方可以绕过页面直接请求 API，因此地址格式、哈希长度、区块范围和日志跨度都必须由 Gin Handler 再次验证。
六、查询时序与关键实现
图 4：最新区块查询的同步调用链与返回路径
1. 超时与取消
每个 RPC 调用继承 HTTP 请求上下文，并增加默认 12 秒超时。浏览器取消请求或节点响应超时后，后端不会无限等待。启动阶段还会主动读取 Chain ID，使无效 RPC 在监听端口之前失败。
2. 精度策略
Wei、Gas Price、Fee Cap 等数值可能超过 JavaScript 安全整数范围，因此 API 使用十进制字符串。Ether 展示使用高精度转换，而不是先降级到 float64。
3. 错误语义
无效输入返回 400，链上对象不存在返回 404，上游 RPC 失败返回 502，健康检查无法访问节点时返回 503。错误体统一使用 error.code + error.message，避免前端解析不稳定的纯文本。
七、当前数据模型与规划 ERD
当前服务不落库，所以不存在数据库事务。运行时处理 Network、Block、Transaction、Receipt、Balance 和 Log，再转换成 JSON。需要注意：区块高度不是跨重组稳定标识，生产索引器必须同时保存 block_hash 和 parent_hash。
图 5：面向 Indexer 的核心数据库模型，当前尚未实现
表职责和业务关联键
- chains ：保存链级配置，
chain_id是业务唯一键。 - blocks ：建议以
(chain_id, hash)唯一，同时索引(chain_id, number, status)。 - transactions ：与 block 一对多，业务键为
(chain_id, tx_hash)。 - receipts ：与 transaction 一对零或一，复用
transaction_id作为主外键。 - logs ：关联 block 与 transaction，建议以
(chain_id, block_hash, log_index)唯一。 - token_transfers：由日志解码产生，必须能够从原始日志重新构建。
- sync_checkpoints：保存下一同步高度和最后确认哈希，用于恢复与连续性校验。
写入顺序与事务一致性
验证 parent_hash 连续性
→ 写入 block
→ 批量写入 transactions
→ 写入 receipts 和 logs
→ ABI 解码并写入派生表
→ 更新 sync_checkpoint
→ 提交数据库事务一个区块的明细和 checkpoint 必须在同一事务内提交，避免同步位置已经前进、数据却只写入一半。发现父哈希不连续时，应定位共同祖先，将受影响区块与派生数据标记为 orphaned 或事务回滚，再重放新的规范链。
八、Troubleshooting 与 RCA
故障一：Nginx 静态目录没有形成可用应用
Symptoms： 访问 /Downloads/ 后只显示 undefined，无法查询链上数据。
**Investigation：**Nginx 配置只有目录 alias 和 autoindex，没有应用入口、API 代理和交互逻辑。
**Root Cause：**用"文件目录交付"解决"Web 应用交付"，交付模型与产品目标不一致。
**Resolution：**用 Go embed 打包真正的 Web 控制台，由 Gin 同源提供页面和 API。
Verification： GET / 返回 ChainScope，静态资源返回 200，自动化测试验证 CSP 和 404。
**Lessons Learned：**静态文件可访问不等于应用可运行，应先定义入口、API 和部署单元。
故障二：已经配置 .env，仍然提示 RPC_URL is required
**Symptoms：**GoLand 编译成功，但程序启动后立即以 exit code 1 退出。
Investigation： GoLand 进程只有 GOROOT 和 GOPATH；代码直接调用 os.Getenv，没有 dotenv 加载器。
Root Cause： os.Getenv 只读取进程环境，不会自动解析工作目录中的 .env 文件。
图 6：从程序退出逐层追踪到配置加载机制和 IDE 进程边界
Resolution： 引入 godotenv v1.5.1，启动时调用 godotenv.Load()；没有 .env 时允许生产环境继续使用注入变量，解析失败则明确终止。
**Verification：**显式移除进程 RPC_URL，仅依赖 .env 启动，健康检查返回 ok，Chain ID 返回 1。
**Lessons Learned：**配置文件只是数据来源，必须明确由谁、在什么时候加载，以及环境变量之间的优先级。
故障三：.env 已加载，Gin 仍显示 debug 模式
**Symptoms：**RPC_URL 已生效，但终端仍输出 Gin debug 警告和路由注册信息。
Investigation： godotenv.Load() 在 main 中执行，Gin 包初始化发生在 main 之前。
**Root Cause：**GIN_MODE 进入环境的时间晚于 Gin 首次读取配置的时间。
Resolution： dotenv 加载后显式调用 gin.SetMode，再创建路由。
**Verification：**仅依赖 .env 启动后不再出现 debug 路由日志，API 继续正常响应。
**Lessons Learned：**配置加载时机与配置值同样重要，第三方库在 init 阶段读取环境时需要显式重配。
九、验证过程
go test ./...
go vet ./...
git diff --check
Health : ok
ChainID : 1
LatestBlock : 262023232026 年 10 月 16 日，单元测试全部通过，go vet 无问题，真实主网健康检查、网络、最新区块、指定区块、交易和余额查询均成功。区块高度是动态数据，文中的高度只代表当次验证证据。
当前仍缺少 mock RPC 故障测试、日志边界集成测试、浏览器端到端测试、并发与大区块压力测试，以及 Windows、Linux、容器三类环境的一致性验证。
十、方案取舍
| 决策 | 选择 | 代价 |
|---|---|---|
| HTTP 框架 | Gin | 治理能力后续补充 |
| 前端交付 | Go embed | 不适合复杂 SPA 工程 |
| 数据读取 | 实时 RPC | 查询受节点性能限制 |
| RPC 来源 | 免费公共节点 | 限流和 SLA 不可控 |
| 事件处理 | 原始 topics/data | 业务可读性不足 |
十一、从 Demo 到完整平台的阶段目标
图 7：先建立稳定查询，再建设 Indexer、领域数据和生产平台
阶段 1：只读查询 Demo（已完成）
真实主网 RPC、Gin API、Web 控制台、请求超时、统一错误、优雅关闭、dotenv 和基础测试已经形成最小闭环。
阶段 2：稳定查询服务
抽象 RPC Client，加入主备切换、有限重试、熔断、并发限流、短时缓存、请求 ID、Prometheus 指标和 OpenAPI。
阶段 3：Indexer 与数据库
引入 PostgreSQL、迁移脚本、批量写入、Checkpoint、幂等回补、确认数和链重组回滚。完成标准不是"能写库"，而是重启可恢复、重复执行不重复、短重组可纠正。
阶段 4：ABI 解码与领域数据
管理 ABI 与代理合约版本，解码 ERC-20、ERC-721、ERC-1155 和协议事件，从原始日志生成可重建的 Token 与业务派生表。
阶段 5：分析与生产化
增加聚合任务、排行榜、导出、鉴权、配额、审计、备份恢复、告警和运行手册，并依据查询规模评估 PostgreSQL 分区、ClickHouse、对象存储和搜索引擎。
十二、Lessons Learned
- 先建立真实 RPC、稳定 API 和可操作页面组成的最小闭环，再引入平台复杂度。
- RPC 是数据源，不是查询数据库；复杂历史检索和聚合必须依赖索引层。
- 链上金额必须跨前后端保持大整数精度，字符串是最稳妥的 JSON 约定。
latest是动态视图，不是最终事实；生产系统必须处理确认数和重组。- 配置要明确来源、优先级与加载时机，不能依赖 IDE 或框架的隐含惯例。
- 公共 RPC 适合验证，不适合作为平台 SLA 基础；应用侧必须保护请求范围和资源消耗。
总结本阶段已经证明 Gin、ethclient 与 Go embed 能以较低成本构建可运行的 EVM 只读数据产品。下一步不应继续堆叠更多实时 RPC 页面，而应优先建设可靠采集、数据库、Checkpoint 和链重组处理。只有数据能够恢复、校验和回滚，ABI 解码、统计分析和面向用户的平台能力才有稳定基础。
本文中的 RPC 地址、账号和业务数据均已脱敏；架构、表关系、故障机制与验证逻辑保持真实。