Substrate开发中如何自定义模块存储？

Question

在Substrate框架中开发自定义模块时，如何正确声明和使用存储项（Storage Items）是开发者常遇到的问题。例如，定义一个`Value`存储项时，若未正确指定`get(fn)`访问器或遗漏`#[pallet::storage]`属性，会导致编译失败或运行时无法读取数据。此外，初学者常混淆`StorageValue`与`StorageMap`的适用场景，导致性能下降或逻辑错误。如何根据业务需求选择合适的存储类型，并确保其可被RPC接口安全访问？同时，存储项的默认值、权限控制及升级兼容性也常被忽视。请结合`decl_storage!`宏（旧版本）或`#[pallet::storage]`（新版本）说明最佳实践。

Answer 1

Substrate框架中存储项声明与使用的最佳实践

1. 存储项基础概念与核心作用

在Substrate框架中，存储项（Storage Items）是模块状态的核心组成部分，用于持久化链上数据。它们被定义在Pallet中，并通过特定宏或属性进行声明。存储项不仅影响运行时性能，还直接决定链的状态可访问性与安全性。

常见的存储类型包括：

• StorageValue：存储单个值，如账户余额、配置参数等。
• StorageMap：键值对映射，适用于按键查询的场景，如用户信息表。
• StorageDoubleMap：双键映射，支持更复杂的索引结构。
• StorageNMap：N维映射，灵活支持多层级键结构。

2. 声明方式演进：从decl_storage!到#[pallet::storage]

Substrate经历了宏语法的重大重构。旧版本使用decl_storage!宏集中声明所有存储项，而新版本采用属性宏分散式定义，提升可读性和模块化程度。

特性	旧版：decl_storage!	新版：#[pallet::storage]
语法风格	宏内集中定义	结构体属性式分散定义
编译错误定位	较难精确定位	行级错误提示清晰
可维护性	低，易产生“宏地狱”	高，符合Rust惯例
默认值处理	需显式指定config()	支持QueryKindTrait控制

3. 正确声明一个StorageValue示例

以下为新版语法中定义一个带getter的存储项：

#[pallet::storage]
#[pallet::getter(fn my_value)]
pub type MyValue<T: Config> = StorageValue<_, u32, ValueQuery>;

其中：

• #[pallet::storage]：标识该类型为存储项。
• #[pallet::getter(fn my_value)]：生成公开读取函数my_value()。
• ValueQuery：表示即使未设置也返回默认值（如0）。
• 若使用OptionQuery，则未设置时返回None。

4. 选择合适的存储类型：业务场景驱动设计

不同存储类型适用于不同访问模式：

业务需求	推荐存储类型	性能特点
全局开关或配置项	StorageValue	O(1)读写
用户余额映射	StorageMap	按键哈希查找，O(1)
权限分级管理（角色+资源）	StorageDoubleMap	支持两级索引遍历
复杂多维索引（如时间+地址+事件类型）	StorageNMap	灵活但需注意键编码开销

5. RPC接口安全暴露存储数据

要使存储项可通过RPC访问，需在rpc/runtime-api/src/lib.rs中定义对应API，并确保：

• 仅暴露必要的只读接口。
• 避免泄露敏感信息（如私钥、权限凭证）。
• 使用#[codec(skip)]隐藏不应序列化的字段。

// 在runtime api中暴露
#[api_version(2)]
pub trait MyPalletApi {
    fn get_my_value() -> u32;
}

6. 权限控制与写入安全机制

所有写操作必须在Pallet的可调用函数（#[pallet::call]）中进行，并结合T::EnsureOrigin校验调用者权限。

#[pallet::call]
impl<T: Config> Pallet<T> {
    #[pallet::weight(10_000)]
    pub fn set_value(origin, value: u32) -> DispatchResult {
        T::ControlOrigin::ensure_origin(origin)?;
        <MyValue<T>>::put(value);
        Ok(())
    }
}

7. 默认值策略与升级兼容性保障

使用ValueQuery可自动提供默认值，避免运行时解包错误。对于已有链升级，应：

• 避免删除已存在的存储项。
• 新增字段时使用OptionQuery以兼容旧状态。
• 利用StorageVersion机制标记版本迁移。

8. 存储项迁移流程图

graph TD
            A[启动节点] --> B{是否为首次启动?}
            B -- 是 --> C[无需迁移]
            B -- 否 --> D[检查StorageVersion]
            D --> E{当前版本 < 目标版本?}
            E -- 否 --> F[正常启动]
            E -- 是 --> G[执行Migration逻辑]
            G --> H[更新StorageVersion]
            H --> I[继续初始化]

9. 常见错误与调试建议

开发者常犯的错误包括：

• 遗漏#[pallet::getter]导致无法通过RPC读取。
• 误用StorageMap替代StorageValue造成冗余开销。
• 未设置config()导致genesis配置缺失。
• 在非可调用函数中直接修改存储，违反安全模型。

10. 性能优化与键空间规划

Substrate底层使用Trie结构存储数据，因此键的设计至关重要：

• 尽量缩短键长度。
• 避免频繁全表扫描操作。
• 使用StorageNMap时合理安排键序以优化前缀查询。
• 监控数据库增长趋势，防止状态膨胀。