系列导航
| 顺序 | 文章 | 定位 |
|---|---|---|
| 1 | 📍当前：Web3 链上转账完整流程（小白版） | 零代码，建立整体认识 |
| 2 |  智能合约：从零看懂一个代币合约 | 合约源码、测试、部署，转账时链上发生了什么 |
| 3 | 前端：用 MetaMask + ethers 完成链上转账 | 网页如何连接钱包、发起转账 |
| 4 | 后端：监听链上事件并同步到数据库 | 后端如何把链上记录可靠地抄进数据库 |
本系列围绕一个学习项目展开，它只做一件事：发行一种叫 MTK 的代币，并让用户之间可以互相转账。 本篇不含任何代码，只帮你搭好"整体地图"，后面三篇再分别钻进合约、前端、后端。
读完本篇你将学会
- 看懂 Web3 里最常见的 5 个词：钱包、地址、区块链、智能合约、燃料费
- 分清"原生币"和"代币"，知道本项目的 MTK 属于哪一类
- 知道一个 Web3 App 由哪三部分组成、各自负责什么
- 说清一笔链上转账从准备账户到出现在列表里的完整 4 步
前置知识：无需任何区块链基础。懂一点前端或后端开发会更好理解，但不是必须。
一、先认识 5 个词
这一章解决的问题：看 Web3 文章时满屏陌生词，先把最核心的 5 个弄明白。
| 词 | 一句话解释 | 生活类比 |
|---|---|---|
| 钱包（MetaMask） | 浏览器插件，保管你的私钥，替你"签字" | 你的印章 |
| 地址（Address） | 0x 开头的一串字符，就是你的账号 | 银行卡号 |
| 区块链（Blockchain） | 一本所有人都能查、没人能偷改的公共账本 | 公开的总账本 |
| 智能合约（Solidity） | 部署在链上的一段程序，规定"谁有多少币、怎样才能转"，用 Solidity 语言编写 | 银行的规章制度 + 金库 |
| 燃料费（Gas） | 在链上做任何"写操作"都要付的手续费 | 办业务的手续费 |
再补 4 个小词：**私钥（Private Key）**是只有你知道的一串密码，谁拿到它谁就能动你的资产；**签名（Signature）**是用私钥给操作"盖章"，证明是本人发起；**交易（Transaction）**是向区块链提交的一次写操作，比如转账、部署合约；**区块（Block）**是链把一段时间内的交易打包成的"一页账"，一页页串起来就是"链"。
记住一句话：钱在链上，数据库里只是"抄本"。
二、原生币 vs 代币：MTK 属于哪一种？
这一章解决的问题：BTC、ETH、USDT、MTK 都叫"币"，它们到底有什么区别？
Web3 代币泛指在区块链上发行的数字资产。它不只能当"钱"用，还可以代表投票治理权、某项服务的使用权，或某件独一无二的资产（如 NFT，非同质化代币，每一个都独一无二）。日常交流中，大家把它们统称为"代币"或"加密货币"；但从技术上看，可以细分为三类：
| 类别 | 是什么 | 余额记在哪里 | 例子 |
|---|---|---|---|
| 原生币（Coin） | 区块链"自带"的币，每条链只有一个，用来支付手续费、维护网络安全 | 直接记在账户上 | BTC、ETH、BNB、SOL、TRX、XRP、ZEC、DOGE、HYPE |
| 代币（Token） | 通过智能合约在别人的链上发行，自己没有独立的链，"寄生"在已有的链上 | 记在发行它的合约里 | USDT、USDC、LINK、OKB、本项目的 MTK |
| 测试币 | 测试网的原生币，没有任何真实价值，供开发者免费领取、测试用 | 直接记在账户上 | Sepolia ETH |
测试网（Testnet）：和真实网络（主网，Mainnet）规则一样、但币不值钱的"练习场"，专门给开发者试错用。
主流币种对比：
| 名称 | 类别 | 所在的链 | 主要用途 | 真实价值 |
|---|---|---|---|---|
| BTC（比特币） | 原生币 | Bitcoin | 区块链的鼻祖，价值存储（"数字黄金"）、点对点支付 | 有 |
| ETH（以太币） | 原生币 | Ethereum | 支付 Gas、运行智能合约，以太坊生态的"硬通货" | 有 |
| BNB（币安币） | 原生币 | BNB Chain | 支付 Gas；同时是币安交易所的平台币（可抵扣交易手续费） | 有 |
| SOL（索拉纳币） | 原生币 | Solana | 支付手续费、运行智能合约，以速度快、费用低著称 | 有 |
| TRX（波场币） | 原生币 | TRON | 支付手续费；质押 TRX 可获得"带宽 / 能量"来抵扣手续费 | 有 |
| XRP（瑞波币） | 原生币 | XRP Ledger | 跨境结算与支付 | 有 |
| ZEC（大零币） | 原生币（隐私币） | Zcash | 支持"隐私交易"：用零知识证明隐藏转账双方和金额 | 有 |
| DOGE（狗狗币） | 原生币（Meme 币） | Dogecoin | 源于网络玩笑的币，主要用于小额支付、打赏 | 有 |
| HYPE（Hyperliquid 币） | 原生币 | Hyperliquid | Hyperliquid 链的原生币：支付 Gas、质押，与链上合约交易所生态绑定 | 有 |
| USDT（泰达币） | 代币（稳定币） | 同时发行在 Ethereum（ERC-20）、TRON（TRC-20）等多条链上 | 由 Tether 公司发行，锚定 1 美元，常用于避险和交易计价 | 有（约 1 美元） |
| USDC（美元币） | 代币（稳定币） | 同时发行在 Ethereum、Solana、Base 等多条链上 | 由 Circle 公司发行，锚定 1 美元，定期公布储备审计 | 有（约 1 美元） |
| LINK（Chainlink 币） | 代币 | 以 ERC-20 形式发行在 Ethereum 上，也可跨链到其他链 | Chainlink 预言机网络的代币：支付节点把链外数据（如价格）送上链的费用、质押 | 有 |
| OKB（欧易平台币） | 代币（平台币） | 以 ERC-20 形式发行在 Ethereum 上；同时是 OKX 旗下 X Layer 链的 Gas 币 | OKX 交易所的平台币：抵扣手续费、参与平台活动 | 有 |
| Sepolia ETH（Sepolia 测试币） | 测试币 | Ethereum Sepolia 测试网 | 开发者测试；本项目部署合约、转账的手续费都用它 | 无（0 元） |
| MTK（MyToken，本项目） | 代币 | anvil / Sepolia | 学习演示：本项目用智能合约自己发行的代币 | 无 |
表中几个词：**质押（Staking）**指把币锁定一段时间来换取收益或权益；零知识证明是一种"不泄露内容也能证明它成立"的密码学技术；**预言机（Oracle）**负责把链外数据送上链。看不懂也不影响读本系列。
看懂这张表，就能理解本项目里的几个现象：
- MTK 和 USDT 是同一类东西：都是用智能合约发行的代币。USDT 在以太坊上的合约，和本项目的 MyToken 一样遵循 ERC-20 标准（以太坊上代币的"统一接口规范"，规定了查余额、转账等功能该叫什么名字、怎么用，钱包因此能认出所有 ERC-20 代币）。
- 手续费只能用原生币付：所以转 MTK 要付 SepoliaETH；同理，在以太坊上转 USDT 要付 ETH，在波场上转 USDT 要付 TRX。
- 按用途还能再细分：稳定币（USDT、USDC）、隐私币（ZEC）、Meme 币（DOGE）、预言机代币（LINK）、平台币（BNB、OKB）。"原生币 / 代币"说的是技术上怎么发行，"稳定币 / 平台币"说的是拿来做什么，两种分法可以同时成立，比如 USDC 既是代币，也是稳定币。
- 同一个币可能有多重身份：BNB 既是 BNB Chain 的原生币，又是币安的平台币；OKB 在以太坊上是 ERC-20 代币，在 X Layer 上又被用作 Gas。判断"原生币还是代币"，要看在哪条链上。
- 代币要"导入"才看得到：原生币余额在账户上，钱包直接就能显示；代币余额在合约里，钱包得知道合约地址才能去查。
- Sepolia ETH 虽然叫 ETH，但本身没有价值：它在测试网上的作用和 ETH 在主网上完全一样（付 Gas），但不能兑换成真钱。平时优先去水龙头免费领取；水龙头领不到时（不少水龙头要求账户在主网上有余额，或限制每天的领取量），也可以在闲鱼等平台花少量钱买一点应急。只按"够用"的量买，千万不要当成投资，也不要相信任何"测试币会升值"的说法。
小结：原生币是链自带的、记在账户上；代币是合约发行的、记在合约里。MTK 是代币，转它要用原生币付手续费。
三、这个 App 由三部分组成
这一章解决的问题：一个能转账的 Web3 App，背后到底有哪些"零件"？
| 部分 | 在哪里运行 | 负责什么 | 详细文档 |
|---|---|---|---|
| 智能合约 | 区块链上 | 记账：谁有多少 MTK；执行转账 | 第 2 篇：智能合约 |
| 前端页面 | 浏览器 | 让用户点按钮查余额、转账，并交给钱包签名 | 第 3 篇：前端 |
| 后端 + 数据库 | 服务器 | 把链上的转账记录"抄"到数据库，配上昵称给页面展示 | 第 4 篇：后端 |
它们之间的关系可以画成三条线：
- 转账：页面 → 钱包签名 → 区块链上的合约改账本
- 看记录：区块链 → 后端监听并抄写 → 数据库 → 页面列表
- 查余额：页面直接问区块链（免费，不用签名）
和传统 Web 开发最大的不同：账本不在自己的数据库里，而在链上的合约里。后端停了照样能转账，数据库只是方便查询的副本。
四、两条链：先在本地练，再上测试网
这一章解决的问题：开发时在哪条链上跑？为什么要两条？
anvil 是在自己电脑上运行的"迷你区块链"，用来开发调试；Sepolia 是以太坊的公共测试网，全世界共享，用来做最终验证。
| 对比 | 本地链 anvil | 测试链 Sepolia |
|---|---|---|
| 在哪里 | 自己的电脑 | 全世界共享的公共测试网 |
| 测试币怎么来 | 启动就送，每个账户 10000 ETH | 去"水龙头"网站免费领或闲鱼购买 |
| 谁能看到 | 只有自己 | 任何人，可在 sepolia.etherscan.io 查询 |
| 转账后多久出现在列表 | 几秒 | 约半分钟（要等 2 个区块确认） |
| 用途 | 开发调试，随时可以重来 | 模拟真实网络，做最终验证 |
**水龙头（Faucet）**是免费发放测试币的网站，像"免费试用装"；区块浏览器（如 sepolia.etherscan.io）是查链上数据的网站，输入地址或交易就能看到详情。
两条链的账本完全独立：同一个地址在两条链上的余额互不相干。
五、完整流程：4 步走
这一章解决的问题：一笔 MTK 转账从零开始，到底要经历哪几步？
第 1 步：准备账户
- 在 MetaMask 里创建账户。创建账户不上链、不花钱，只是用助记词（Mnemonic，一组 12 个左右的英文单词，是所有账户私钥的"总钥匙"）算出一把新钥匙。
- 本项目的账户分工：
| 用途 | 本地链 anvil | 测试链 Sepolia |
|---|---|---|
| 部署者（拿到全部 MTK） | Anvil-A | 部署者和持币人 |
| 收款 / 转账 | Anvil-B、C、D | 收款人1、收款人2 |
- Sepolia 上还要准备一点 SepoliaETH 当手续费（去水龙头领或闲鱼购买）。
第 2 步：发行 MTK（部署合约）
- 合约代码里写好了：名字 MyToken、符号 MTK、总量 100 万、部署时全部给部署者。
- 部署（Deploy）就是发一笔特殊交易，把合约代码放到链上。部署完会得到一个合约地址：
- 本地链：
0xdc64…f6c9 - Sepolia：
0xcbee…2447
- 本地链：
- 合约一旦部署就永远不能修改。想改名字只能重新部署一个新合约。
- 本项目实测，部署在 Sepolia 上大约花 0.001 SepoliaETH。
第 3 步：转账
以 Sepolia 上"收款人2 转 500 MTK 给收款人1"为例：
- 打开页面，选择 Sepolia，连接 MetaMask，选中收款人2。
- 填入收款人1 的地址，点"查询余额"。查询是免费的，不弹钱包。
- 填金额 500，点"转账"。
- MetaMask 弹窗，显示手续费约 0.0006 SepoliaETH，点确认。
- 交易被打包进区块（网络把交易正式写进账本的一页），合约把收款人2 的余额减 500、收款人1 的余额加 500，并发出一条 Transfer 事件（Event，合约在链上留下的一条"公告"：谁转给谁、多少）。到这里转账已经完成。
- 页面上的进度条依次亮起：签名并广播 → 打包上链 → 后端已入库。
第 4 步：在列表里看到记录
- 后端一直在"监听"MTK 合约的 Transfer 事件。一有转账，就把"谁转给谁、多少钱"写进数据库。
- 页面从后端读取记录，显示成"迷糊的水獭#7322 → 勇敢的鹦鹉#3717，500 MTK"。
- 昵称是后端随机起的，链上只有地址，没有昵称。
小结：准备账户 → 部署合约 → 签名转账（合约改账本）→ 后端抄进数据库。第 3 步完成时钱就已经到账，第 4 步只是为了方便展示。
六、数据库里有什么
这一章解决的问题：既然钱在链上，后端数据库到底存了什么？
| 表 | 存什么 | 例子 |
|---|---|---|
| users | 地址和昵称的对应关系 | 0x455b… = 迷糊的水獭#7322 |
| transactions | 每一笔转账（从链上抄来的） | 收款人2 → 收款人1，500 MTK |
| sync_states | 后端抄到了第几个区块 | Sepolia 已抄到第 11786xxx 块 |
删光数据库也不会丢钱：余额在链上。重启后端，它会从链上把记录重新抄回来。
七、常见疑问
转 MTK 为什么要付 SepoliaETH？ 手续费只能用这条链的原生币付，而且由发起转账的人付。收款的人不用付，也不用提前做任何准备。
"导入代币"是干什么的？ 告诉 MetaMask "去这个合约查一下我有多少 MTK"。它只影响钱包里能不能看到余额，不影响收款。
为什么 Sepolia 转账要等半分钟才出现在列表？ 后端要等这笔交易之后再出 2 个区块（约 24 秒）才入库，这叫等待"确认数"。原因是公共链上偶尔会发生区块重组（Reorg）：刚出的几个区块可能被撤销、换成另一个版本，多等几块能避免记录作废。本地链 anvil 不会重组，所以几秒就能看到。
MetaMask 里的账户为什么删不掉？ 账户是用助记词按顺序算出来的，删了还能再算出来，所以只能隐藏。
转账总量会变吗？ 不会。转账只是在账户之间挪数字。所有人的余额加起来永远是 100 万 MTK。
八、最该记住的 5 句话
- 余额存在合约里，不在钱包里，也不在数据库里。
- 查余额免费；转账要签名、付手续费，手续费由发起方付。
- 合约部署后不能修改，合约地址由"部署者 + 第几笔交易"算出来。
- 转账真正完成的标志：合约改了账本，并发出一条 Transfer 事件。
- 后端只是抄写员：监听 Transfer 事件，抄进数据库，给页面展示。
九、技术栈与工具清单（参与项目前必读）
这一章要解决的问题：想亲手把项目跑起来，需要装哪些工具？每个工具在哪一环起作用？
只想了解概念的读者可以先跳过，准备动手运行项目时再回来看。表格里的名词会在第 2～4 篇中逐一讲解。
以下版本号是本项目安装时拉取到的最新版本。
智能合约层
| 名称 | 版本 | 作用 / 本项目用途 | Web2 类比 | 链接 |
|---|---|---|---|---|
| Solidity | 0.8.37 | 编写 MyToken 合约的语言；编译目标 EVM 版本为 osaka（见 foundry.toml） | Go / Java 语言本身 |  https://github.com/ethereum/solidity |
| Foundry（forge / cast / anvil） | 1.8.3 | forge：编译、测试、部署脚本、Gas 报告；cast：命令行调用链；anvil：本地链 | go build + go test + curl + 本地数据库 | https://github.com/foundry-rs/foundry |
| forge-std | 1.16.2 | Foundry 测试标准库（Test、vm.prank、vm.expectEmit） | testify | https://github.com/foundry-rs/forge-std |
| OpenZeppelin Contracts | 5.7.0 | 经过审计的 ERC20 实现，MyToken 继承自它 | 官方标准库 / Spring Security | https://github.com/OpenZeppelin/openzeppelin-contracts |
forge-std 和 OpenZeppelin 以 git 子模块的形式放在
contracts/lib/下，版本锁定在contracts/foundry.lock。make install会依次执行git submodule update --init --recursive和forge install。
后端（Go）
| 名称 | 版本 | 作用 / 本项目用途 | 链接 |
|---|---|---|---|
| Go | 1.27 | 后端编程语言（1.24 及以上才支持 go tool air 这种 tool 依赖写法） | https://github.com/golang/go |
| Gin | 1.12.0 | HTTP 路由，提供 /api/* 接口 | https://github.com/gin-gonic/gin |
| gin-contrib/cors | 1.7.9 | 跨域中间件。开发环境中前端（5173 端口）访问后端（8080 端口）时需要 | https://github.com/gin-contrib/cors |
| GORM | 1.31.2 | ORM：模型定义、AutoMigrate、一对多关联、Preload、OnConflict | https://github.com/go-gorm/gorm |
| GORM MySQL Driver | 1.6.0 | GORM 连接 MySQL 的驱动 | https://github.com/go-gorm/mysql |
| go-ethereum（geth） | 1.17.6 | ethclient 通过 HTTP 查询链上数据（FilterLogs 查询事件、BlockNumber、HeaderByNumber），通过 WebSocket 订阅事件（SubscribeFilterLogs）；crypto.Keccak256Hash 计算事件签名 | https://github.com/ethereum/go-ethereum |
| shopspring/decimal | 1.4.0 | 精确的十进制运算：把最小单位换算成可读金额（amountDisplay），避免 float64 丢精度 | https://github.com/shopspring/decimal |
| godotenv | 1.5.1 | 加载 backend/.env | https://github.com/joho/godotenv |
| Air | 1.67.4 | 热重载，保存 .go 文件后自动编译并重启。已通过 go get -tool 写入 go.mod，用 go tool air 运行 | https://github.com/air-verse/air |
前端
| 名称 | 版本 | 作用 / 本项目用途 | 链接 |
|---|---|---|---|
| Node.js | 24 | 运行 pnpm、Vite、vue-tsc 的 JavaScript 运行时（本机实测 v24.14.0；Docker 构建使用 node:24-alpine） | https://github.com/nodejs/node |
| TypeScript | 6.0.3 | 前端编程语言，所有代码都是 .ts 或 <script setup lang="ts">，没有 .js 文件 | https://github.com/microsoft/TypeScript |
| pnpm | 11.x | 包管理器，锁文件是 pnpm-lock.yaml（本机实测 11.12.0；Docker 构建中通过 corepack enable 启用） | https://github.com/pnpm/pnpm |
| Vite | 8.3 | 开发服务器与构建工具；配置了路径别名 /@/ → src/ | https://github.com/vitejs/vite |
| @vitejs/plugin-vue | 6.0.9 | Vite 的 Vue 插件，让 Vite 能编译 .vue 单文件组件 | https://github.com/vitejs/vite-plugin-vue |
| Vue 3 | 3.5 | UI 框架 | https://github.com/vuejs/core |
| vue-tsc | 3.3 | 对 .vue 文件做类型检查，执行 pnpm build 时会先运行它 | https://github.com/vuejs/language-tools |
| @vue/tsconfig | 0.9.1 | Vue 官方的 TypeScript 基础配置，tsconfig.app.json 继承自它 | https://github.com/vuejs/tsconfig |
| @types/node | 26.6.2 | Node.js 的类型声明，供 vite.config.ts（用到 node:url）做类型检查 | https://github.com/DefinitelyTyped/DefinitelyTyped |
| TDesign Vue Next | 1.20.8 | 腾讯出品的 Vue 3 组件库：Form、Input、Button、Table、Tag、RadioGroup、Steps、Message | https://github.com/Tencent/tdesign-vue-next |
| Ethers.js | 6.17 | 与链交互：BrowserProvider 连接钱包、Contract 调用合约、parseUnits / formatUnits 换算金额 | https://github.com/ethers-io/ethers.js |
| MetaMask | — | 浏览器钱包：保管私钥并签名，通过 EIP-1193（window.ethereum）暴露给页面 | https://github.com/MetaMask/metamask-extension |
TypeScript 固定在 6.x 的原因：TypeScript 7 是用原生代码重写的版本，不再提供 vue-tsc 依赖的 JS 编译器 API，实测
vue-tsc会直接报错ERR_PACKAGE_PATH_NOT_EXPORTED。等 vue-tsc 适配 TS 7 后再升级。
链服务
| 名称 | 作用 / 本项目用途 | 链接 |
|---|---|---|
| Sepolia + Etherscan | 公共测试链；在区块浏览器里可以查看交易和 Event Log |  https://sepolia.etherscan.io |
| Infura（本项目使用）/ Alchemy | 托管的 RPC 节点服务。后端用 HTTPS 地址查询（SEPOLIA_RPC_URL），用 WSS 地址订阅事件（SEPOLIA_WS_URL）；forge / cast 部署时也用它 |  https://www.infura.io 、 https://www.alchemy.com |
| publicnode 公共 RPC | 免费公共节点，只在"向 MetaMask 添加 Sepolia 网络"时作为参数传入（前端 VITE_SEPOLIA_PUBLIC_RPC） |  https://ethereum-sepolia-rpc.publicnode.com |
| Sepolia 水龙头（Faucet） | 免费领取 SepoliaETH，用于支付部署和转账的 Gas。Infura、Alchemy、Google Cloud 等都有提供，不少要求账户在主网上有少量余额 |  https://cloud.google.com/application/web3/faucet/ethereum/sepolia |
数据库、开发工具与部署
| 名称 | 作用 / 本项目用途 | 链接 |
|---|---|---|
| MySQL 8+ | 存储 users、transactions、sync_states 三张表（Docker Compose / K8s 中使用 mysql:8.4 镜像） |  https://dev.mysql.com/doc/ |
| Git | 管理代码；合约依赖以 git 子模块形式安装 |  https://git-scm.com |
| jq | export-abi.sh 用它从 JSON 中提取 ABI 和合约地址；Makefile 的 seed-* 用它读取部署者地址 | https://github.com/jqlang/jq |
| Make | 把常用命令统一成 make xxx，make help 可查看全部命令 |  https://www.gnu.org/software/make/ |
| Docker / Docker Compose | 构建镜像，一键启动 mysql、backend、frontend。用到的基础镜像：golang:1.27（编译后端）、gcr.io/distroless/static-debian12（运行后端，不含 shell，攻击面小）、node:24-alpine（构建前端）、nginx:alpine、mysql:8.4 |  https://docs.docker.com |
| nginx | 托管前端静态文件，并把 /api 反向代理到后端 |  https://nginx.org |
| Kubernetes（kubectl） | 容器编排，部署清单在 deploy/k8s/ | https://github.com/kubernetes/kubernetes |
一次转账中各工具的出场顺序： MetaMask 签名 → ethers 编码并发送 → anvil / Infura 节点 → Solidity 合约执行 → go-ethereum 通过 WebSocket 收到事件推送、再用 eth_getLogs 查询日志 → GORM 写入 MySQL → Gin 提供接口 → decimal 换算金额 → TDesign 表格展示
下一篇预告
现在你已经有了整张地图。下一篇
后续 3 篇分别适合谁读（建议按顺序，只关心某一端也可以直接跳读）：
- 第 2 篇 智能合约：想知道"链上的规则是怎么写出来的"、对 Solidity 感兴趣的读者
- 第 3 篇 前端：前端开发者，想知道网页如何连接 MetaMask、发起一笔真实的链上转账
- 第 4 篇 后端：后端开发者，想知道如何把链上数据可靠地同步到自己的数据库