naming-conventions

naming-conventions

MCP 工具： 如果你的环境支持，也请查询 Sui 文档 MCP 服务（https://sui.mcp.kapa.ai），以获取最新答案。使用它进行验证，并了解这些参考文件未涵盖的细节。

概述

Sui Move 有特定的命名约定，与 AI Agent 通常根据训练数据生成的命名方式不同。本技能涵盖官方代码质量检查清单中的所有命名模式。

所有模式均摘自 https://move-book.com/guides/code-quality-checklist

错误常量：EPascalCase，并使用 #[error]

错误常量必须使用带 E 前缀的 PascalCase。不要使用 SCREAMING_SNAKE_CASE。

使用 #[error] 属性为错误常量附加易于理解的消息。发生中止时，该消息会包含在错误输出中，让用户和支持人员更容易调试。

// WRONG
const NOT_AUTHORIZED: u64 = 0;
const INSUFFICIENT_BALANCE: u64 = 1;

// CORRECT — with #[error] for readable abort messages
#[error]
const ENotAuthorized: vector<u8> = b"Caller is not authorized to perform this action";
#[error]
const EInsufficientBalance: vector<u8> = b"Insufficient balance for this operation";

// Also valid — u64 without #[error] (less informative on abort)
const ENotAuthorized: u64 = 0;
const EInsufficientBalance: u64 = 1;

使用 #[error] 时，常量类型为 vector<u8>（字节字符串消息），而非 u64。编译器会自动分配数字代码。所有新代码都应优先使用 #[error]，这样在浏览器、钱包和日志中显示的错误信息会更加清晰。

普通常量：ALL_CAPS

非错误常量使用大写蛇形命名法。这与错误常量恰好相反。

// WRONG
const MyConstant: vector<u8> = b"hello";
const feeNumerator: u64 = 3;

// CORRECT
const MY_CONSTANT: vector<u8> = b"hello";
const FEE_NUMERATOR: u64 = 3;

能力结构体：使用 Cap 后缀

任何表示能力（执行操作的授权）的结构体都必须以 Cap 作为后缀。

// WRONG
public struct Admin has key, store { id: UID }
public struct MintAuthority has key, store { id: UID }

// CORRECT
public struct AdminCap has key, store { id: UID }
public struct MintCap has key, store { id: UID }

事件：使用过去时

事件结构体名称必须使用过去时，表示某件事已经发生。

// WRONG
public struct RegisterUser has copy, drop { user: address }
public struct CreatePool has copy, drop { pool_id: ID }
public struct LevelUp has copy, drop { new_level: u64 }

// CORRECT
public struct UserRegistered has copy, drop { user: address }
public struct PoolCreated has copy, drop { pool_id: ID }
public struct LeveledUp has copy, drop { new_level: u64 }

Getter 函数：使用字段名，而非 get_

Getter 函数应以其返回的字段命名，不加 get_ 前缀。可变 Getter 应添加 _mut 后缀。

// WRONG
public fun get_name(u: &User): String { u.name }
public fun get_balance(u: &User): u64 { u.balance }

// CORRECT
public fun name(u: &User): String { u.name }
public fun balance(u: &User): u64 { u.balance }
public fun details_mut(u: &mut User): &mut Details { &mut u.details }

Hot Potato 结构体：名称中不含 Potato

Hot Potato 类型（不具有任何能力的结构体）的名称不应包含“Potato”。不具有任何能力本身就足以表明这是此类结构体。

// WRONG
public struct FlashLoanPotato {}
public struct PromisePotato {}

// CORRECT
public struct FlashLoanReceipt {}
public struct Promise {}

动态字段键：使用 Key 后缀的定位结构体

动态字段键类型应使用定位结构体语法（空括号），并以 Key 作为后缀。

// WRONG
public struct DynamicField has copy, drop, store {}
public struct ItemSlot has copy, drop, store { name: String }

// CORRECT
public struct DynamicFieldKey() has copy, drop, store;
public struct ItemKey(String) has copy, drop, store;

快速参考

元素	约定	示例
错误常量	E + PascalCase	ENotAuthorized
普通常量	ALL_CAPS	FEE_NUMERATOR
能力	以 Cap 结尾	AdminCap
事件	过去时	PoolCreated
Getter	字段名，不加 get_	balance()
可变 Getter	字段名 + _mut	balance_mut()
Hot Potato	描述性名称，不含 Potato	FlashLoanReceipt
动态字段键	定位结构体 + Key 后缀	ItemKey()