MultiversX智能合约开发Skill mvx_project_architecture

---

name: mvx_project_architecture description: 用于MultiversX智能合约的生产级项目结构模式。

MultiversX项目架构

单合约结构

my-contract/
├── Cargo.toml
├── src/
│   ├── lib.rs              # #[contract] 特质 — 仅特质组合 + 初始化/升级
│   ├── storage.rs           # 所有 #[storage_mapper] 定义
│   ├── views.rs             # 所有 #[view] 端点
│   ├── config.rs            # 管理员配置端点
│   ├── events.rs            # #[event] 定义
│   ├── validation.rs        # 输入验证助手
│   ├── errors.rs            # 静态错误常量
│   └── helpers.rs           # 纯业务逻辑函数
├── meta/
├── wasm/
└── tests/

lib.rs模式：仅特质组合

#![no_std]
multiversx_sc::imports!();

#[multiversx_sc::contract]
pub trait MyContract:
    storage::StorageModule
    + config::ConfigModule
    + views::ViewsModule
    + events::EventsModule
    + validation::ValidationModule
    + helpers::HelpersModule
{
    #[init]
    fn init(&self) { }

    #[upgrade]
    fn upgrade(&self) { }

    #[endpoint]
    fn main_operation(&self) {
        self.validate_payment(&payment);
        let mut cache = cache::StorageCache::new(self);
        self.process_operation(&mut cache, &payment);
    }
}

errors.rs模式

pub static ERROR_NOT_ACTIVE: &[u8] = b"Contract is not active";
pub static ERROR_INVALID_AMOUNT: &[u8] = b"Invalid amount";
pub static ERROR_UNAUTHORIZED: &[u8] = b"Unauthorized";
pub static ERROR_ZERO_AMOUNT: &[u8] = b"Amount must be greater than zero";

命名约定

项目	约定	示例
合约包	kebab-case	liquidity-pool
模块文件	snake_case	storage.rs
存储键	camelCase	"totalSupply"
错误常量	SCREAMING_SNAKE	ERROR_INVALID_AMOUNT
模块特质	PascalCase	StorageModule
端点名称	snake_case	fn deposit_tokens(&self)
视图名称	camelCase (ABI)	#[view(getBalance)]

何时创建公共工作空间包

相同结构/数学/错误/事件在2+个合约中 → 移动到 common/ 包。