Solidity 如何
把规则写进链上？Type · Function · Modifier · Event · Mapping · Struct

EVM 最终处理的是 256 位字、字节序列和存储槽；Solidity 在上面加了一套类型系统。 类型不仅决定“能存什么”，还决定 ABI 怎样编码、算术是否检查溢出、赋值是复制还是引用，以及哪些位置可以使用这个值。

本课示例为什么选这些类型？

function inspect(Progress calldata p)
    external pure
    returns (uint32)
{
    return p.completedLessons;
}

最容易写错的是“局部 storage 变量”

Progress storage p =
    progressOf[msg.sender];

p.completedLessons = 9;
// 直接改动合约状态

Progress memory p =
    progressOf[msg.sender];

p.completedLessons = 9;
// 只改临时副本，除非再写回

• storage → memory复制出独立副本；改 memory 不会自动写回。
• storage → local storage建立引用；通过局部变量改字段，就是改状态。
• calldata → memory / storage跨位置时复制；calldata 本身不可修改。
• memory → memory引用类型的局部赋值可能共享同一片数据，不能机械理解为深拷贝。
• calldata ≠ external 专属自 Solidity 0.6.9 起，public、internal、private 的引用类型参数也可声明为 calldata；它只描述位置与只读语义。

struct Progress {
    uint32 completedLessons;
    uint64 updatedAt;
    Stage stage;
    bool exists;
    string note;
}

mapping(
    address student
    => Progress progress
) private progressOf;

Mapping 的五条硬边界

第一组开关：谁能调用？

第二组开关：函数承诺做什么？

function inspect(address student)
    external
    returns (Progress memory)

外部调用的前四个字节

为什么有 indexed？

非 anonymous event 最多把三个参数标为 indexed。它们进入 topics，客户端可以按 topic 过滤； 未 indexed 的参数进入 data，适合完整展示。选择 indexed 字段，本质上是在设计未来的查询入口。

// SPDX-License-Identifier: MIT
pragma solidity 0.8.36;

contract StudyRegistry {
    // TYPE：有限状态，外部 ABI 中按整数编码
    enum Stage { Beginner, Core, Ecosystem, Builder }

    // STRUCT：一条学习记录的形状
    struct Progress {
        uint32 completedLessons;
        uint64 updatedAt;
        Stage stage;
        bool exists;
        string note;
    }

    address public immutable teacher;
    bool public paused;

    // MAPPING：学生地址 → Progress 记录
    mapping(address student => Progress progress)
        private progressOf;

    // EVENT：indexed 字段进入 topics，其余进入 data
    event ProgressUpdated(
        address indexed student,
        Stage indexed stage,
        uint32 completedLessons,
        string note
    );
    event PauseChanged(bool paused);

    error OnlyTeacher();
    error ContractPaused();
    error InvalidLessonCount();

    // MODIFIER：复用调用者检查
    modifier onlyTeacher() {
        if (msg.sender != teacher) revert OnlyTeacher();
        _;
    }

    // MODIFIER：复用暂停检查
    modifier whenActive() {
        if (paused) revert ContractPaused();
        _;
    }

    constructor() {
        teacher = msg.sender;
    }

    // FUNCTION：外部写入口，只有 teacher 可调用
    function setPaused(bool value)
        external
        onlyTeacher
    {
        paused = value;
        emit PauseChanged(value);
    }

    // calldata：动态字符串的只读调用输入
    function updateProgress(
        uint32 completedLessons,
        Stage stage,
        string calldata note
    )
        external
        whenActive
    {
        if (completedLessons > 1000) {
            revert InvalidLessonCount();
        }

        progressOf[msg.sender] = Progress({
            completedLessons: completedLessons,
            updatedAt: uint64(block.timestamp),
            stage: stage,
            exists: true,
            note: note
        });

        emit ProgressUpdated(
            msg.sender,
            stage,
            completedLessons,
            note
        );
    }

    // memory：把 storage 中的 struct 复制为返回值
    function getProgress(address student)
        external view
        returns (Progress memory)
    {
        return progressOf[student];
    }
}

按执行责任，而不是按行号阅读

成功与失败的原子性

当函数开始调用外部合约

本课示例没有外部调用，因此没有展示重入路径。真实合约一旦把控制权交给未知地址， 对方可能在原函数完成前回调。常见起点是 Checks → Effects → Interactions： 先检查、再更新自身状态、最后与外部交互；必要时再叠加成熟的重入保护与 pull-payment 设计。

核心术语

ABI

Application Binary Interface。描述函数、事件与错误怎样在链上字节和高层类型之间编码、解码。

Bytecode

EVM 可执行的字节序列。部署创建代码与部署后留在地址上的运行时代码不是同一段。

Calldata

外部调用的只读输入区域，包含 selector 和 ABI 编码参数，不跨调用持久化。

Memory

一次调用内的临时、可修改字节区域，随调用结束消失。

Storage

与合约地址关联的持久状态；写入通常是 EVM 操作中成本较高的一类。

Value type

赋值时按值复制的类型，例如 bool、整数、地址、定长 bytes 与 enum。

Reference type

语义受数据位置影响的类型，例如 array、struct；mapping 是只能位于 storage 的特殊引用类型。

Function selector

规范函数签名 Keccak-256 哈希的前 4 字节，用来选择外部函数入口。

Modifier

在 _; 周围包装函数体的可复用 Solidity 结构。

Topic

日志中最多四个 32 字节槽；非 anonymous event 通常用 topic0 保存事件签名哈希。

Custom error

用名字和可选参数描述 revert 原因的 ABI 项，通常比长字符串更节省部署与调用数据。

Atomicity

调用成功时相关变化一起提交；revert 时当前回滚范围内的状态与日志一起撤销。

官方与规范资料

• Solidity team · 2026Solidity 0.8.36 Release Announcement本课示例采用的稳定版本与安全修复说明。
• Solidity docs · v0.8.36Solidity Documentation固定版本的语言与编译器文档入口。
• Language referenceTypes值类型、引用类型、数据位置、Struct 与 Mapping。
• Language referenceContracts可见性、getter、Modifier、函数、Event 与 Custom Error。
• Compiler internalsContract ABI Specificationselector、参数编码、Event topics/data 与错误数据。
• Language referenceLayout of a Solidity Source FileSPDX、pragma、import 与顶层声明。
• Language referenceStructure of a Contract状态变量、函数、Modifier、Event、Error、Struct 与 Enum。
• Compiler internalsLayout of State Variables in Storage存储槽、打包、Mapping 与动态数组寻址。
• Compiler internalsLayout of Call Data外部调用参数与 calldata 布局。
• AdvisorySecurity Considerations重入、Gas 限制、授权、失败模式与安全建议。
• ethereum.orgIntroduction to smart contracts智能合约作为代码与状态的总体定位。
• ethereum.orgAnatomy of smart contracts状态、函数、环境变量、Event 与示例结构。