SuperAPI AI 工具集

library-api-design

编程与开发

查看项目

更新于 10-16 03:11

技能介绍

用途:这是 openzeppelin-contracts 仓库的 API 设计规则,供在 contracts/ 下新增、修改或审查合约时使用。该仓库是基础库,每个合约都会被下游继承,因此规则的核心是保持可继承性;多数规则不由 lint 强制,需要人为判断。

主要能力与约定:可覆盖的 public 和 internal 函数标为 virtual,但两类除外——仅转发无新增逻辑的别名函数,以及只填充默认参数的便利重载,规范形式才是 virtual,并需加 NatSpec NOTE 指向它。Solhint 的 no-external-virtual 会拦截 external virtual(fallback 除外),正确做法是改为 public virtual,因为 external 函数的覆盖无法调用 super。引用类型参数(string、bytes、数组、结构体)用 memory,包括 public 函数;calldata 只在三种窄场景有效:返回值是 msg.data 的切片、真正限定于单个函数的 internal calldata 解码辅助函数、工具库中带 Calldata 后缀的平行变体且基础版仍用 memory。默认用 public,仅在 ERC 规范本身定义为 external,或设计上明确禁止内部调用时才用 external,后者需 NatSpec NOTE 说明原因。public 函数只负责捕获 _msgSender() 并委托给接收显式 actor 参数的 internal 函数,逻辑都在 internal 变体。对有 mint、burn、transfer 等多入口的状态机,让 _mint/_burn/_transfer 作为非 virtual 别名委托到单一 virtual _update,扩展只覆盖 _update,且先调用 super._update 再加副作用。能安全地什么都不做时就 no-op 而非 revert:空输入静默跳过、幂等状态转换返回 bool、无默认行为的 internal virtual {} 钩子。应用逻辑用 _msgSender(),msg.sender 仅出现在 Context 层或有说明的协议级例外。super 需在 _update、supportsInterface 及建立在基础行为之上的扩展中调用,supportsInterface 遵循 interfaceId == type(X).interfaceId || super.supportsInterface(interfaceId),多基类时写 override(A, B)。constant 用于编译期已知值、命名 ALL_CAPS,immutable 用于构造函数设置值、命名 _camelCase;@custom:oz-upgrades-unsafe-allow state-variable-immutable 标签控制可升级变体是保持 immutable 还是转为普通存储槽。ERC-7201 命名空间存储是可选而非默认,仅在确实需要命名空间时使用,且必须用 SlotDerivation.erc7201Slot() 验证槽值,不可手算。

使用方式与限制:规则本身为人工判断型约定,具体 lint 配置、安装命令及完整代码示例资料未提供。