如果你第一次在网上搜 substrate 这个词大概率不是被它中文译名叫基底搞糊涂就是被一堆看起来互相矛盾的介绍弄懵。我当初从想发一条自己的链这个想法出发翻了不少资料才搞清楚Substrate 是一整套用 Rust 写成的区块链开发框架Polkadot 上的中继链、平行链以及大量独立网络底层跑的都是这套框架。这篇文章会先把 Substrate 最容易被误解的架构分层讲清楚再带你从零跑通一个自定义模块最后分享几个我在 pallet 开发和测试过程中真实踩过的坑。适合那种已经能跑通模板但还想真正理解并动手改链的开发者。1. substrate 到底是一个东西还是一堆东西很多人刚接触 Substrate 时最大的困惑是它到底是一个软件、一个 SDK还是一套协议我的理解其实很简单它是一个把区块链拆成标准零件然后允许你自由组装的框架。这也是它和以太坊这类整链交付方案最大的区别。要理解 Substrate先把它拆成三个不同层次的组件外部节点、运行时、以及 FRAME 这套 pallet 开发库。三者各自解决不同的问题但最终组合成一条完整的链。1.1 客户端你平时跑节点跑的是这一层客户端是编译后直接跑在你机器上的二进制程序也就是平时敲./target/release/node-template --dev启动的那个东西。它负责所有链底层但不涉及业务逻辑的工作包括网络层基于 libp2p 实现节点发现、区块同步、交易广播共识层比如生产区块用的 BABE 或 Aura最终性用的 GRANDPA存储层区块、状态、索引都落在 RocksDB 或 ParityDB 里RPC 层对外提供 JSON-RPC 接口前端应用通过它读写链。这部分代码对于绝大多数业务开发者来说是黑盒。你不必搞懂 GRANDPA 的投票协议到底怎么在节点间协调因为框架已经把它封装成稳定的共识引擎。这就像你开车不需要重新发明变速箱踩油门就能走。1.2 运行时真正被存到链上的业务逻辑真正有意思的是运行时。区块链的业务逻辑——比如余额怎么转、治理投票怎么算、自定义的业务模块怎么运行——全部在运行时里定义。Substrate 的做法很特别运行时不是直接编译成机器码而是编译成 Wasm然后以链上状态的形式存在链上。这带来的直接后果是链上的业务逻辑可以随区块一起被网络共识验证而且可以通过一次特殊的交易替换掉旧的 Wasm。这就是常说的无分叉升级后面我会专门讲。理解这个分层之后再去读 Substrate 文档你会有一种豁然开朗的感觉原来链上代码和链上数据是两个可以独立更新的东西。数据的存储结构在链上代码以 Wasm 形式也在链上两者绑定在一起但又各自独立演进。1.3 FRAME被反复复用的 pallet 工具箱第三层是 FRAME它是 Substrate 官方提供的一套 runtime 开发库。FRAME 的核心单元叫 pallet你可以把它理解成链上的一个功能模块。账户余额是一个 pallet交易费用是一个 pallet链上治理是一组 pallet你完全可以在上面添加自己业务逻辑的 pallet。层次主要职责你平时需要关注的程度外部节点客户端网络、共识、存储、RPC基本不用改Runtime业务逻辑的 Wasm 代码核心开发区域FRAME / pallet可复用的模块库复用 自定义我早期犯的一个错误是试图读懂每一行代码再动手。实际完全没必要。Substrate 的工程哲学就是分层屏蔽复杂度你在 pallet 里写业务逻辑时不需要关心区块是怎么广播出去的反过来你调整共识参数时也尽量不要碰业务代码。先接受这种分层再逐步深入比一开始死抠底层高效得多。2. 坦白说我也纠结过要不要自己从零搓一条链在做技术选型时我有个很轴的念头既然框架是别人的会不会有黑盒问题万一自定义需求很怪框架反而束缚手脚怎么办于是那段时间我真去调研了从零写一条链需要做的事结果很快就清醒了。2.1 自己写链要面对的问题清单如果完全从零开始你至少得解决以下问题P2P 网络节点之间怎么发现彼此、怎么同步区块、怎么广播交易状态存储账户余额、业务数据怎么持久化怎么保证可验证、可回溯共识算法区块由谁生产、怎么确认、怎么防止分叉和双花交易执行环境怎么把一段交易代码在节点里安全执行并且验证执行结果一致RPC 接口前端钱包、浏览器通过什么方式查询链上数据运行时升级业务规则变了之后现有的链怎么升级节点是否要硬分叉。这不是一年半载能做完的工程量。就算不考虑工程质量光是把这些模块正确组合并保证安全对专业团队都是很大的挑战。我意识到如果你最关心的是业务本身而不是重复发明区块链底层技术那么站在框架肩膀上走几乎是唯一务实的选择。开发方式需要自己写的部分工作量和风险从零写链P2P、共识、存储、RPC、业务逻辑、升级机制极高周期以年计Substrate FRAME只用 pallet 组合 自定义业务逻辑集中在 runtime 层可控2.2 为什么不直接拿智能合约框架做也有人说那我直接用智能合约平台不就行了确实如果你要做的逻辑复杂度不高合约是更快的路径。但 Substrate 和智能合约最大的区别在于合约是被链上固定规则包裹的沙盒程序而 Substrate 的 runtime 可以修改链本身的规则。举个例子。在智能合约里转账手续费的结构、共识参数、治理规则等等都在链层被固定合约不能越界修改。而在 Substrate 里你可以写一个 pallet 直接改掉交易费用的计算方式或者设计一套新的区块生产者激励机制。这种协议层可编程能力是普通合约平台给不了的。所以我的判断标准很简单如果你要做的是一条应用链或者你希望业务规则能深度定制到链层面选 Substrate如果业务逻辑可以完全落在现有合约平台的能力范围内那没有必要自建一条链的成本。2.3 我的选择什么项目适合 substrate具体来说我在下面几种场景里会优先考虑 Substrate对交易费用、出块节奏、共识参数有特殊要求业务数据模型很复杂合约存储难以优雅表达希望链上规则可以平滑升级不想硬分叉未来要接入跨链生态比如作为平行链接入中继链。反过来如果只是做一个标准的代币、一个 NFT 市场用成熟的合约平台可能更快。技术选型最忌为了框架而框架把需求摆出来答案往往很明显。3. 第一次跑通 node-template环境、编译以及别在错误版本上浪费时间Substrate 开发的第一步通常是拉一个 node-template 项目下来。这个模板已经配置好了一条链最基础的零件包括账户系统、余额模块、sudo 模块和一个示例 pallet。你的工作是在这个骨架上做加法而不是从中抽出部件。3.1 环境准备与模板下载Substrate 目前依赖 Rust 的 nightly 工具链并需要 Wasm 编译目标。如果你机器上没装过 Rust先去 rustup 官网装然后执行rustup update nightly rustup target add wasm32-unknown-unknown --toolchain nightly然后拉模板git clone https://github.com/substrate-developer-hub/substrate-node-template cd substrate-node-template这一步之后千万别急着删库里的旧分支。Substrate 的版本迭代非常快模板的当前版本如果和网上老教程对不上你会在编译阶段被一堆莫名其妙的宏错误轰炸。建议把模板 repository 一直保留在本地作为版本对照的参照物。3.2 编译和启动进入项目后直接编译 release 版本cargo build --release第一次编译需要下载并编译几百个依赖 crate耗时因机器而异二十分钟到一个小时都正常。这时候别盯着终端干着急可以去读读 runtime 目录下的代码结构或者提前把 polkadot-js/apps 前端工具准备好。编译完成后启动开发链./target/release/node-template --dev--dev参数会让节点以单人开发者模式启动自动清空之前的链上状态每次启动都是一条新链。如果你加了--tmp临时数据用完后自动删调试阶段我强烈建议两者连用./target/release/node-template --dev --tmp。3.3 连接前端节点默认监听ws://127.0.0.1:9944。把 polkadot-js/apps 打开切换网络到 Custom填上本地 WebSocket 地址就能看到你这条链的区块在滚动。前端完全通过链的元数据来识别链上有哪些模块、哪些可调用函数、哪些存储项所以即使你还没写任何前端代码只要改动 runtime前端界面会自动跟着变。3.4 新手最容易翻车的三个点第一cargo build和cargo b --release混用。Substrate 的 runtime 编译依赖WASM_BUILD环境变量release 和非 release 的构建产物不一致容易导致你改了代码却没有生效。固定用一个命令按项目文档来。第二编译报错先看版本。假如你从网上找了个自定义 pallet 代码粘贴之后疯狂报错八成不是逻辑问题而是它基于老版本 Substrate 写的。特别注意decl_module!这种老宏新版本里已经被 attribute 宏方案替代见到直接放弃别试着兼容。第三链刚启动完马上发交易测试偶尔会遇到交易不打包的情况。先等几个区块稳定再连上前端操作。4. 手写一个 pallet存储、调用与事件的三件套模板跑通之后真正的工程才刚刚开始。接下来我会带你在 runtime 里加一个自己的 pallet实现一个简单的链上凭证记录模块用户可以把一段数据的哈希登记到链上作为存在性证明之后还能把这个凭证转给其他人。4.1 用 pallet 组织业务逻辑pallet 是 Substrate runtime 的基本模块单元。以太坊合约里你写一个contract在 Substrate 里你写一个 pallet。pallet 可以访问系统级功能比如读取调用者身份、访问链上时间、操作存储并且天然支持事件和错误处理。模板自带一个pallet-template最简单的做法是复制它的目录改掉 crate 名字然后在 runtime 里挂载。但我建议你也看看它的结构因为一个标准 pallet 通常由四大部分组成Configtrait声明这个 pallet 依赖哪些外部类型Storage声明链上持久化数据Call可被交易调用的业务函数也叫 dispatchable callEvent和Error描述链上发生的事件和可预期的失败原因。4.2 一个链上凭证记录模块这个模块的存储结构不复杂就是一个账号 - 凭证记录的映射。凭证记录包含所有者、内容哈希、登记区块号。#[derive(Clone, Encode, Decode, PartialEq, RuntimeDebug, scale_info::TypeInfo)] pub struct RecordAccountId, BlockNumber { pub owner: AccountId, pub hash: Vecu8, pub created_at: BlockNumber, }存储部分用StorageMap#[pallet::storage] #[pallet::getter(fn records)] pub type RecordsT: Config StorageMap _, Blake2_128Concat, T::AccountId, RecordT::AccountId, T::BlockNumber, OptionQuery, ;先别急着跳进函数注意T::AccountId和T::BlockNumber这种写法。pallet 本身不关心账号具体是哪种类型它通过Config: frame_system::Config拿到 runtime 给它的类型。这套类型参数化机制让你的 pallet 可以在不同 runtime 里复用。登记的调用长这样#[pallet::call] implT: Config PalletT { #[pallet::weight(10_000)] pub fn create_record( origin: OriginForT, hash: Vecu8, ) - DispatchResult { let who ensure_signed(origin)?; ensure!( !Records::T::contains_key(who), Error::T::AlreadyExists ); let record Record { owner: who.clone(), hash, created_at: frame_system::Pallet::T::block_number(), }; Records::T::insert(who, record); Self::deposit_event(Event::T::RecordCreated(who)); Ok(()) } #[pallet::weight(10_000)] pub fn transfer_record( origin: OriginForT, to: T::AccountId, ) - DispatchResult { let who ensure_signed(origin)?; let mut record Records::T::get(who).ok_or(Error::T::NotFound)?; ensure!(record.owner who, Error::T::NotOwner); Records::T::remove(who); record.owner to.clone(); Records::T::insert(to, record); Self::deposit_event(Event::T::RecordTransferred(who, to)); Ok(()) } }这里出现了一个很关键的宏#[pallet::weight]。Substrate 要求每个可调用函数必须估算自己的计算成本它决定了这条交易在整个区块里占多大的资源额度。开发阶段图省事可以写固定值但上线前建议用官方的 benchmark 工具做真实测速不然区块生产者很容易被设计超重或过轻的交易影响。4.3 深入理解 weight 与 originweight和origin是 Substrate pallet 开发里绕不开的两个概念。origin是调用来源的认证信息。ensure_signed表示调用者必须是一个真实签名的账号如果调用来自 root链上治理或者未认证来源这里就会返回错误。这套访问控制是每条 call 的第一道门槛。weight除了关系到区块资源还牵扯到交易费计算权重越高费用通常越高。一个设计良好的 pallet每个 call 都应该给出合理权重。别以为权重只是数字它直接影响链的吞吐能力。5. 测试 pallet 不能靠 printlnmock runtime 与几个绕不开的坑pallet 写完之后你面临一个现实问题它跑在哪pallet 不能像普通 Rust 二进制一样有 main 函数直接运行它必须嵌入 runtime 才能工作。如果每次都启动节点来测试效率太低。Substrate 的标准做法是构建一个 mock runtime。5.1 为什么必须 mock 一个 runtimemock runtime 是一个最小可运行的 runtime 环境它只包含测试需要的 pallet比如frame_system加上你的自定义 pallet。它跑在普通 Rust 测试进程里不需要网络、不需要共识、不需要真实交易池所以测试可以飞快执行还能精确断言链上存储和事件。5.2 mock 代码骨架在 pallet 的src/mock.rs里你通常需要做两件事实现 runtime 配置、构建TestExternalities。construct_runtime!( pub enum Test { System: frame_system, TemplateModule: pallet_template, } ); impl frame_system::Config for Test { // 模板里有完整版本这里省略大部分 type 绑定 type AccountId u64; type BaseCallFilter frame_support::traits::Everything; // ... } pub fn new_test_ext() - sp_io::TestExternalities { let storage frame_system::GenesisConfig::default() .build_storage::Test() .unwrap(); storage.into() }这段代码里最不起眼但最容易出错的是依赖版本一致性。sp-io、sp-core、sp-runtime这些 crate 的版本必须和 runtime 使用的完全一致差一个 minor 版本都会编译出一堆类型不匹配的报错。5.3 典型测试用例写完 mock 之后测试就变得很直观了。以之前的凭证模块为例#[test] fn test_create_record() { new_test_ext().execute_with(|| { assert_ok!(TemplateModule::create_record( RuntimeOrigin::signed(1u64), vec![1u8, 2u8, 3u8], )); assert!(TemplateModule::records(1u64).is_some()); }); } #[test] fn test_create_record_duplicate_fails() { new_test_ext().execute_with(|| { assert_ok!(TemplateModule::create_record( RuntimeOrigin::signed(1u64), vec![1u8, 2u8, 3u8], )); assert_noop!( TemplateModule::create_record( RuntimeOrigin::signed(1u64), vec![4u8, 5u8, 6u8], ), Error::Test::AlreadyExists ); }); }execute_with里的闭包相当于替你搭好了链上状态沙盒每次测试进来都是干净状态修改存储不会污染其他用例。assert_ok!和assert_noop!是框架提供的测试宏前者断言调用成功后者断言失败并检查具体错误值。5.4 我踩过的几个坑第一个坑是事件没实现错误提示却指向宏。如果你在 pallet 里用了事件但没有正确声明RuntimeEvent类型编译错误经常出现在construct_runtime!附近一时很难联想到是 pallet 内的事件定义不完整。解决方法是先检查#[pallet::event]块是否存在再检查 runtime 的construct_runtime!里是否已经加入你的 pallet。第二个坑是存储键顺序不能乱调。编译器不会帮你检查construct_runtime!里 pallet 的顺序但存储编码会受顺序影响。你在开发中发现存储数据错乱、读不到旧数据大概率是调整了 pallet 顺序而没有执行存储迁移。开发阶段还好正式链上这属于高危操作。第三个坑是测试全绿但主链报错。mock runtime 和真实 runtime 的配置存在差异比如 mock 里AccountId u64真实 runtime 却是AccountId32。测试能通过的逻辑主链上因哈希前缀等细节不同仍然可能出错。所以 mock 测试只是第一道防线合入前一定要在--dev节点上手动走一遍关键流程。6. forkless 升级把链上代码和链上数据解耦Substrate 最有魅力、也最反直觉的特性是链上升级。传统区块链改成逻辑基本等于硬分叉节点必须全员换新二进制共识网络在某个高度分道扬镳。Substrate 提供了一条完全不同的路。6.1 硬分叉与无分叉升级普通链的规则被写进节点客户端的二进制里所以改规则必须改节点、动共识。而 Substrate 把 runtime 编译成 Wasm 并存在链上节点执行的其实是链上这份 Wasm。修改代码时你只需要编译一份新的 Wasm再通过一个特殊调用把它写到链上之后全链节点会自动执行新逻辑不需要替换二进制。我把这个过程理解为换发动机不换车架数据、账号、历史区块都在原地只有链上代码被原子地换掉了。6.2 实操一次升级升级流程不复杂。修改局部代码后先编译cargo build -p node-template-runtime --release构建产物会生成新的 Wasm 文件。然后在 polkadot-js 前端用 sudo 模块提交setCode调用把新的 Wasm 上传上去。几秒后链上代码就换成了新版本。如果只是新增了一个 call不会影响现有数据。但如果你的存储结构变了例如从StorageMap改成StorageDoubleMap那么旧键值不能被自动读取你需要写一个存储迁移逻辑在升级后把旧数据搬移到新键下。这个迁移逻辑往往比业务代码本身更考验人因为它要兼容链上可能跑了很久、积累了大量数据的现实情况。6.3 升级的风险与备份习惯开发期随便升级没关系但正式链上任何一次升级都必须先备份。我现在的习惯是先在--dev节点完整走一遍升级流程再对着测试网做一次带真实数据的演练最后才考虑生产链。升级过程中如果出现问题优先用快照回滚而不是慌张地继续发交易。另外升级后立刻检查前端元数据是否刷新。因为前端依赖元数据分析链上接口如果缓存没有清除你会看到一堆接口不存在的报错实际链上却一切正常。这个小问题在开发期往往比复杂的共识问题更浪费时间。最后再分享一个我很个人的体会Substrate 的学习曲线之所以陡不是因为它比别的框架复杂太多而是因为它给了你太多可以用自己的方式去做的事情。开发链和写普通后端的思维方式不太一样——你不仅关心功能对不对还要关心链上状态怎么演进、升级怎么平滑、数据怎么迁移。如果一开始被宏和类型绕晕了别着急那都是必经之路。多用 mock 测试兜底、多跑 dev 节点、把版本这个锚点牢牢锁住后面你会慢慢发现这套框架真正值钱的地方不是那些花哨的功能而是它把一条链要跨越长期运行这道坎这件事实实在在地拉近了。
从零理解 Substrate：架构分层、Pallet 开发与无分叉升级实战
如果你第一次在网上搜 substrate 这个词大概率不是被它中文译名叫基底搞糊涂就是被一堆看起来互相矛盾的介绍弄懵。我当初从想发一条自己的链这个想法出发翻了不少资料才搞清楚Substrate 是一整套用 Rust 写成的区块链开发框架Polkadot 上的中继链、平行链以及大量独立网络底层跑的都是这套框架。这篇文章会先把 Substrate 最容易被误解的架构分层讲清楚再带你从零跑通一个自定义模块最后分享几个我在 pallet 开发和测试过程中真实踩过的坑。适合那种已经能跑通模板但还想真正理解并动手改链的开发者。1. substrate 到底是一个东西还是一堆东西很多人刚接触 Substrate 时最大的困惑是它到底是一个软件、一个 SDK还是一套协议我的理解其实很简单它是一个把区块链拆成标准零件然后允许你自由组装的框架。这也是它和以太坊这类整链交付方案最大的区别。要理解 Substrate先把它拆成三个不同层次的组件外部节点、运行时、以及 FRAME 这套 pallet 开发库。三者各自解决不同的问题但最终组合成一条完整的链。1.1 客户端你平时跑节点跑的是这一层客户端是编译后直接跑在你机器上的二进制程序也就是平时敲./target/release/node-template --dev启动的那个东西。它负责所有链底层但不涉及业务逻辑的工作包括网络层基于 libp2p 实现节点发现、区块同步、交易广播共识层比如生产区块用的 BABE 或 Aura最终性用的 GRANDPA存储层区块、状态、索引都落在 RocksDB 或 ParityDB 里RPC 层对外提供 JSON-RPC 接口前端应用通过它读写链。这部分代码对于绝大多数业务开发者来说是黑盒。你不必搞懂 GRANDPA 的投票协议到底怎么在节点间协调因为框架已经把它封装成稳定的共识引擎。这就像你开车不需要重新发明变速箱踩油门就能走。1.2 运行时真正被存到链上的业务逻辑真正有意思的是运行时。区块链的业务逻辑——比如余额怎么转、治理投票怎么算、自定义的业务模块怎么运行——全部在运行时里定义。Substrate 的做法很特别运行时不是直接编译成机器码而是编译成 Wasm然后以链上状态的形式存在链上。这带来的直接后果是链上的业务逻辑可以随区块一起被网络共识验证而且可以通过一次特殊的交易替换掉旧的 Wasm。这就是常说的无分叉升级后面我会专门讲。理解这个分层之后再去读 Substrate 文档你会有一种豁然开朗的感觉原来链上代码和链上数据是两个可以独立更新的东西。数据的存储结构在链上代码以 Wasm 形式也在链上两者绑定在一起但又各自独立演进。1.3 FRAME被反复复用的 pallet 工具箱第三层是 FRAME它是 Substrate 官方提供的一套 runtime 开发库。FRAME 的核心单元叫 pallet你可以把它理解成链上的一个功能模块。账户余额是一个 pallet交易费用是一个 pallet链上治理是一组 pallet你完全可以在上面添加自己业务逻辑的 pallet。层次主要职责你平时需要关注的程度外部节点客户端网络、共识、存储、RPC基本不用改Runtime业务逻辑的 Wasm 代码核心开发区域FRAME / pallet可复用的模块库复用 自定义我早期犯的一个错误是试图读懂每一行代码再动手。实际完全没必要。Substrate 的工程哲学就是分层屏蔽复杂度你在 pallet 里写业务逻辑时不需要关心区块是怎么广播出去的反过来你调整共识参数时也尽量不要碰业务代码。先接受这种分层再逐步深入比一开始死抠底层高效得多。2. 坦白说我也纠结过要不要自己从零搓一条链在做技术选型时我有个很轴的念头既然框架是别人的会不会有黑盒问题万一自定义需求很怪框架反而束缚手脚怎么办于是那段时间我真去调研了从零写一条链需要做的事结果很快就清醒了。2.1 自己写链要面对的问题清单如果完全从零开始你至少得解决以下问题P2P 网络节点之间怎么发现彼此、怎么同步区块、怎么广播交易状态存储账户余额、业务数据怎么持久化怎么保证可验证、可回溯共识算法区块由谁生产、怎么确认、怎么防止分叉和双花交易执行环境怎么把一段交易代码在节点里安全执行并且验证执行结果一致RPC 接口前端钱包、浏览器通过什么方式查询链上数据运行时升级业务规则变了之后现有的链怎么升级节点是否要硬分叉。这不是一年半载能做完的工程量。就算不考虑工程质量光是把这些模块正确组合并保证安全对专业团队都是很大的挑战。我意识到如果你最关心的是业务本身而不是重复发明区块链底层技术那么站在框架肩膀上走几乎是唯一务实的选择。开发方式需要自己写的部分工作量和风险从零写链P2P、共识、存储、RPC、业务逻辑、升级机制极高周期以年计Substrate FRAME只用 pallet 组合 自定义业务逻辑集中在 runtime 层可控2.2 为什么不直接拿智能合约框架做也有人说那我直接用智能合约平台不就行了确实如果你要做的逻辑复杂度不高合约是更快的路径。但 Substrate 和智能合约最大的区别在于合约是被链上固定规则包裹的沙盒程序而 Substrate 的 runtime 可以修改链本身的规则。举个例子。在智能合约里转账手续费的结构、共识参数、治理规则等等都在链层被固定合约不能越界修改。而在 Substrate 里你可以写一个 pallet 直接改掉交易费用的计算方式或者设计一套新的区块生产者激励机制。这种协议层可编程能力是普通合约平台给不了的。所以我的判断标准很简单如果你要做的是一条应用链或者你希望业务规则能深度定制到链层面选 Substrate如果业务逻辑可以完全落在现有合约平台的能力范围内那没有必要自建一条链的成本。2.3 我的选择什么项目适合 substrate具体来说我在下面几种场景里会优先考虑 Substrate对交易费用、出块节奏、共识参数有特殊要求业务数据模型很复杂合约存储难以优雅表达希望链上规则可以平滑升级不想硬分叉未来要接入跨链生态比如作为平行链接入中继链。反过来如果只是做一个标准的代币、一个 NFT 市场用成熟的合约平台可能更快。技术选型最忌为了框架而框架把需求摆出来答案往往很明显。3. 第一次跑通 node-template环境、编译以及别在错误版本上浪费时间Substrate 开发的第一步通常是拉一个 node-template 项目下来。这个模板已经配置好了一条链最基础的零件包括账户系统、余额模块、sudo 模块和一个示例 pallet。你的工作是在这个骨架上做加法而不是从中抽出部件。3.1 环境准备与模板下载Substrate 目前依赖 Rust 的 nightly 工具链并需要 Wasm 编译目标。如果你机器上没装过 Rust先去 rustup 官网装然后执行rustup update nightly rustup target add wasm32-unknown-unknown --toolchain nightly然后拉模板git clone https://github.com/substrate-developer-hub/substrate-node-template cd substrate-node-template这一步之后千万别急着删库里的旧分支。Substrate 的版本迭代非常快模板的当前版本如果和网上老教程对不上你会在编译阶段被一堆莫名其妙的宏错误轰炸。建议把模板 repository 一直保留在本地作为版本对照的参照物。3.2 编译和启动进入项目后直接编译 release 版本cargo build --release第一次编译需要下载并编译几百个依赖 crate耗时因机器而异二十分钟到一个小时都正常。这时候别盯着终端干着急可以去读读 runtime 目录下的代码结构或者提前把 polkadot-js/apps 前端工具准备好。编译完成后启动开发链./target/release/node-template --dev--dev参数会让节点以单人开发者模式启动自动清空之前的链上状态每次启动都是一条新链。如果你加了--tmp临时数据用完后自动删调试阶段我强烈建议两者连用./target/release/node-template --dev --tmp。3.3 连接前端节点默认监听ws://127.0.0.1:9944。把 polkadot-js/apps 打开切换网络到 Custom填上本地 WebSocket 地址就能看到你这条链的区块在滚动。前端完全通过链的元数据来识别链上有哪些模块、哪些可调用函数、哪些存储项所以即使你还没写任何前端代码只要改动 runtime前端界面会自动跟着变。3.4 新手最容易翻车的三个点第一cargo build和cargo b --release混用。Substrate 的 runtime 编译依赖WASM_BUILD环境变量release 和非 release 的构建产物不一致容易导致你改了代码却没有生效。固定用一个命令按项目文档来。第二编译报错先看版本。假如你从网上找了个自定义 pallet 代码粘贴之后疯狂报错八成不是逻辑问题而是它基于老版本 Substrate 写的。特别注意decl_module!这种老宏新版本里已经被 attribute 宏方案替代见到直接放弃别试着兼容。第三链刚启动完马上发交易测试偶尔会遇到交易不打包的情况。先等几个区块稳定再连上前端操作。4. 手写一个 pallet存储、调用与事件的三件套模板跑通之后真正的工程才刚刚开始。接下来我会带你在 runtime 里加一个自己的 pallet实现一个简单的链上凭证记录模块用户可以把一段数据的哈希登记到链上作为存在性证明之后还能把这个凭证转给其他人。4.1 用 pallet 组织业务逻辑pallet 是 Substrate runtime 的基本模块单元。以太坊合约里你写一个contract在 Substrate 里你写一个 pallet。pallet 可以访问系统级功能比如读取调用者身份、访问链上时间、操作存储并且天然支持事件和错误处理。模板自带一个pallet-template最简单的做法是复制它的目录改掉 crate 名字然后在 runtime 里挂载。但我建议你也看看它的结构因为一个标准 pallet 通常由四大部分组成Configtrait声明这个 pallet 依赖哪些外部类型Storage声明链上持久化数据Call可被交易调用的业务函数也叫 dispatchable callEvent和Error描述链上发生的事件和可预期的失败原因。4.2 一个链上凭证记录模块这个模块的存储结构不复杂就是一个账号 - 凭证记录的映射。凭证记录包含所有者、内容哈希、登记区块号。#[derive(Clone, Encode, Decode, PartialEq, RuntimeDebug, scale_info::TypeInfo)] pub struct RecordAccountId, BlockNumber { pub owner: AccountId, pub hash: Vecu8, pub created_at: BlockNumber, }存储部分用StorageMap#[pallet::storage] #[pallet::getter(fn records)] pub type RecordsT: Config StorageMap _, Blake2_128Concat, T::AccountId, RecordT::AccountId, T::BlockNumber, OptionQuery, ;先别急着跳进函数注意T::AccountId和T::BlockNumber这种写法。pallet 本身不关心账号具体是哪种类型它通过Config: frame_system::Config拿到 runtime 给它的类型。这套类型参数化机制让你的 pallet 可以在不同 runtime 里复用。登记的调用长这样#[pallet::call] implT: Config PalletT { #[pallet::weight(10_000)] pub fn create_record( origin: OriginForT, hash: Vecu8, ) - DispatchResult { let who ensure_signed(origin)?; ensure!( !Records::T::contains_key(who), Error::T::AlreadyExists ); let record Record { owner: who.clone(), hash, created_at: frame_system::Pallet::T::block_number(), }; Records::T::insert(who, record); Self::deposit_event(Event::T::RecordCreated(who)); Ok(()) } #[pallet::weight(10_000)] pub fn transfer_record( origin: OriginForT, to: T::AccountId, ) - DispatchResult { let who ensure_signed(origin)?; let mut record Records::T::get(who).ok_or(Error::T::NotFound)?; ensure!(record.owner who, Error::T::NotOwner); Records::T::remove(who); record.owner to.clone(); Records::T::insert(to, record); Self::deposit_event(Event::T::RecordTransferred(who, to)); Ok(()) } }这里出现了一个很关键的宏#[pallet::weight]。Substrate 要求每个可调用函数必须估算自己的计算成本它决定了这条交易在整个区块里占多大的资源额度。开发阶段图省事可以写固定值但上线前建议用官方的 benchmark 工具做真实测速不然区块生产者很容易被设计超重或过轻的交易影响。4.3 深入理解 weight 与 originweight和origin是 Substrate pallet 开发里绕不开的两个概念。origin是调用来源的认证信息。ensure_signed表示调用者必须是一个真实签名的账号如果调用来自 root链上治理或者未认证来源这里就会返回错误。这套访问控制是每条 call 的第一道门槛。weight除了关系到区块资源还牵扯到交易费计算权重越高费用通常越高。一个设计良好的 pallet每个 call 都应该给出合理权重。别以为权重只是数字它直接影响链的吞吐能力。5. 测试 pallet 不能靠 printlnmock runtime 与几个绕不开的坑pallet 写完之后你面临一个现实问题它跑在哪pallet 不能像普通 Rust 二进制一样有 main 函数直接运行它必须嵌入 runtime 才能工作。如果每次都启动节点来测试效率太低。Substrate 的标准做法是构建一个 mock runtime。5.1 为什么必须 mock 一个 runtimemock runtime 是一个最小可运行的 runtime 环境它只包含测试需要的 pallet比如frame_system加上你的自定义 pallet。它跑在普通 Rust 测试进程里不需要网络、不需要共识、不需要真实交易池所以测试可以飞快执行还能精确断言链上存储和事件。5.2 mock 代码骨架在 pallet 的src/mock.rs里你通常需要做两件事实现 runtime 配置、构建TestExternalities。construct_runtime!( pub enum Test { System: frame_system, TemplateModule: pallet_template, } ); impl frame_system::Config for Test { // 模板里有完整版本这里省略大部分 type 绑定 type AccountId u64; type BaseCallFilter frame_support::traits::Everything; // ... } pub fn new_test_ext() - sp_io::TestExternalities { let storage frame_system::GenesisConfig::default() .build_storage::Test() .unwrap(); storage.into() }这段代码里最不起眼但最容易出错的是依赖版本一致性。sp-io、sp-core、sp-runtime这些 crate 的版本必须和 runtime 使用的完全一致差一个 minor 版本都会编译出一堆类型不匹配的报错。5.3 典型测试用例写完 mock 之后测试就变得很直观了。以之前的凭证模块为例#[test] fn test_create_record() { new_test_ext().execute_with(|| { assert_ok!(TemplateModule::create_record( RuntimeOrigin::signed(1u64), vec![1u8, 2u8, 3u8], )); assert!(TemplateModule::records(1u64).is_some()); }); } #[test] fn test_create_record_duplicate_fails() { new_test_ext().execute_with(|| { assert_ok!(TemplateModule::create_record( RuntimeOrigin::signed(1u64), vec![1u8, 2u8, 3u8], )); assert_noop!( TemplateModule::create_record( RuntimeOrigin::signed(1u64), vec![4u8, 5u8, 6u8], ), Error::Test::AlreadyExists ); }); }execute_with里的闭包相当于替你搭好了链上状态沙盒每次测试进来都是干净状态修改存储不会污染其他用例。assert_ok!和assert_noop!是框架提供的测试宏前者断言调用成功后者断言失败并检查具体错误值。5.4 我踩过的几个坑第一个坑是事件没实现错误提示却指向宏。如果你在 pallet 里用了事件但没有正确声明RuntimeEvent类型编译错误经常出现在construct_runtime!附近一时很难联想到是 pallet 内的事件定义不完整。解决方法是先检查#[pallet::event]块是否存在再检查 runtime 的construct_runtime!里是否已经加入你的 pallet。第二个坑是存储键顺序不能乱调。编译器不会帮你检查construct_runtime!里 pallet 的顺序但存储编码会受顺序影响。你在开发中发现存储数据错乱、读不到旧数据大概率是调整了 pallet 顺序而没有执行存储迁移。开发阶段还好正式链上这属于高危操作。第三个坑是测试全绿但主链报错。mock runtime 和真实 runtime 的配置存在差异比如 mock 里AccountId u64真实 runtime 却是AccountId32。测试能通过的逻辑主链上因哈希前缀等细节不同仍然可能出错。所以 mock 测试只是第一道防线合入前一定要在--dev节点上手动走一遍关键流程。6. forkless 升级把链上代码和链上数据解耦Substrate 最有魅力、也最反直觉的特性是链上升级。传统区块链改成逻辑基本等于硬分叉节点必须全员换新二进制共识网络在某个高度分道扬镳。Substrate 提供了一条完全不同的路。6.1 硬分叉与无分叉升级普通链的规则被写进节点客户端的二进制里所以改规则必须改节点、动共识。而 Substrate 把 runtime 编译成 Wasm 并存在链上节点执行的其实是链上这份 Wasm。修改代码时你只需要编译一份新的 Wasm再通过一个特殊调用把它写到链上之后全链节点会自动执行新逻辑不需要替换二进制。我把这个过程理解为换发动机不换车架数据、账号、历史区块都在原地只有链上代码被原子地换掉了。6.2 实操一次升级升级流程不复杂。修改局部代码后先编译cargo build -p node-template-runtime --release构建产物会生成新的 Wasm 文件。然后在 polkadot-js 前端用 sudo 模块提交setCode调用把新的 Wasm 上传上去。几秒后链上代码就换成了新版本。如果只是新增了一个 call不会影响现有数据。但如果你的存储结构变了例如从StorageMap改成StorageDoubleMap那么旧键值不能被自动读取你需要写一个存储迁移逻辑在升级后把旧数据搬移到新键下。这个迁移逻辑往往比业务代码本身更考验人因为它要兼容链上可能跑了很久、积累了大量数据的现实情况。6.3 升级的风险与备份习惯开发期随便升级没关系但正式链上任何一次升级都必须先备份。我现在的习惯是先在--dev节点完整走一遍升级流程再对着测试网做一次带真实数据的演练最后才考虑生产链。升级过程中如果出现问题优先用快照回滚而不是慌张地继续发交易。另外升级后立刻检查前端元数据是否刷新。因为前端依赖元数据分析链上接口如果缓存没有清除你会看到一堆接口不存在的报错实际链上却一切正常。这个小问题在开发期往往比复杂的共识问题更浪费时间。最后再分享一个我很个人的体会Substrate 的学习曲线之所以陡不是因为它比别的框架复杂太多而是因为它给了你太多可以用自己的方式去做的事情。开发链和写普通后端的思维方式不太一样——你不仅关心功能对不对还要关心链上状态怎么演进、升级怎么平滑、数据怎么迁移。如果一开始被宏和类型绕晕了别着急那都是必经之路。多用 mock 测试兜底、多跑 dev 节点、把版本这个锚点牢牢锁住后面你会慢慢发现这套框架真正值钱的地方不是那些花哨的功能而是它把一条链要跨越长期运行这道坎这件事实实在在地拉近了。
 上的完整安装部署指南｜从 Node.js 到 TaoToken 配置一步步跑通云端/本地开发环境)
