阅读(4062) 赞(12)

solidity 源文件的布局

2022-05-10 17:56:37 更新

源文件可以包含任意数量的合约定义、import、 pragma和 using for指令以及 struct、enum、function、 error 和常量变量定义。

SPDX 许可证标识符

如果智能合约的源代码可用，则可以更好地建立对智能合约的信任。由于提供源代码总是涉及版权方面的法律问题，Solidity 编译器鼓励使用机器可读的SPDX 许可证标识符。每个源文件都应以说明其许可证的注释开头：

// SPDX-License-Identifier: MIT

编译器不会验证许可证是否是 SPDX 允许的列表的一部分，但它会在字节码元数据中包含提供的字符串。

如果您不想指定许可证或者源代码不是开源的，请使用特殊值UNLICENSED。请注意UNLICENSED（不允许使用，不在 SPDX 许可证列表中）与UNLICENSE（向所有人授予所有权利）不同。Solidity 遵循npm 建议。

编译器在文件级别的文件中的任何位置都可以识别注释，但建议将其放在文件的顶部。

有关如何使用 SPDX 许可证标识符的更多信息，请访问 SPDX 网站。

编译指示

该pragma关键字用于启用某些编译器功能或检查。pragma 指令始终位于源文件的本地，因此如果要在整个项目中启用它，则必须将 pragma 添加到所有文件中。如果您导入另一个文件，该文件中的编译指示不会自动应用于导入文件。

版本编译指示

源文件可以（并且应该）使用版本编译指示进行注释，以拒绝使用可能引入不兼容更改的未来编译器版本进行编译。我们试图将它们保持在绝对最低限度，并以语义变化也需要以语法变化的方式引入它们，但这并不总是可能的。因此，至少对于包含重大更改的版本，通读更改日志总是一个好主意。这些版本始终具有形式 0.x.0或x.0.0.

版本编译指示使用如下：pragma solidity ^0.5.2;

具有上述行的源文件不能使用 0.5.2 版本之前的编译器进行编译，并且它也不能在从 0.6.0 版本开始的编译器上工作（这第二个条件是通过 using 添加的^）。因为在 version 0.6.0之前不会有重大更改，您可以确保您的代码按照您的预期方式编译。编译器的确切版本不固定，因此仍然可以发布错误修复版本。

可以为编译器版本指定更复杂的规则，这些规则与npm使用的语法相同。

笔记
使用版本编译指示不会更改编译器的版本。它也不会启用或禁用编译器的功能。它只是指示编译器检查其版本是否与 pragma 所需的版本匹配。如果不匹配，编译器会发出错误。

ABI 编码器编译指示

通过使用pragma abicoder v1或pragma abicoder v2您可以在 ABI 编码器和解码器的两种实现之间进行选择。

新的 ABI 编码器 (v2) 能够编码和解码任意嵌套的数组和结构。它可能会产生不太理想的代码，并且没有像旧编码器那样接受过多的测试，但从 Solidity 0.6.0 开始被认为是非实验性的。您仍然必须使用pragma abicoder v2;。由于它将默认从 Solidity 0.8.0 开始激活，因此可以选择使用 pragma abicoder v1;。

新编码器支持的类型集是旧编码器支持的类型的严格超集。使用它的合约可以与没有限制的合约进行交互。仅当非abicoder v2合约不尝试进行需要仅由新编码器支持的解码类型的调用时，反向才是可能的。编译器可以检测到这一点并将发出错误。只需为您的合同启用abicoder v2就足以使错误消失。

笔记
此编译指示适用于激活它的文件中定义的所有代码，无论该代码最终在何处结束。这意味着选择了源文件以使用 ABI coder v1 编译的合约仍然可以包含通过从另一个合约继承来使用新编码器的代码。如果新类型仅在内部使用而不在外部函数签名中使用，则允许这样做。

笔记
在 Solidity 0.7.4 之前，可以使用pragma experimental ABIEncoderV2 选择 ABI coder v2 ，但无法显式选择 coder v1，因为它是默认设置。

实验性的Pragma

第二个 pragma 是实验性 pragma。它可用于启用默认情况下尚未启用的编译器或语言的功能。当前支持以下实验性编译指示：

ABIEncoderV2

因为 ABI 编码器 v2 不再被认为是实验性的，所以从 Solidity 0.7.4 开始可以通过pragma abicoder v2（请参见上文）选择它。

SMTChecker

在构建 Solidity 编译器时必须启用此组件，因此它并非在所有 Solidity 二进制文件中都可用。构建说明解释了如何激活此选项。在大多数版本中，它为 Ubuntu PPA 版本激活，但不适用于 Docker 映像、Windows 二进制文件或静态构建的 Linux 二进制文件。如果您在本地安装了 SMT 求解器并通过节点（而不是通过浏览器）运行 solc-js，则可以通过smtCallback为 solc-js 激活它。

如果您使用pragma experimental SMTChecker;，那么您会收到额外的安全警告，这些警告是通过查询 SMT 求解器获得的。该组件尚不支持 Solidity 语言的所有功能，并且可能会输出许多警告。如果它报告不支持的功能，则分析可能不完全正确。

导入其他源文件

语法和语义

Solidity 支持导入语句，以帮助模块化您的代码，这些代码类似于 JavaScript（从 ES6 开始）中可用的代码。但是，Solidity 不支持默认导出的概念。

在全局级别，您可以使用以下形式的导入语句：

import "filename";

该filename部分称为导入路径。此语句将所有全局符号从“文件名”（以及从那里导入的符号）导入当前全局范围（与 ES6 不同，但向后兼容 Solidity）。不推荐使用这种形式，因为它会意外地污染命名空间。如果您在“文件名”中添加新的顶级项目，它们会自动出现在所有从“文件名”导入的文件中。最好显式地导入特定符号。

以下示例创建一个新的全局符号symbolName，其成员是来自的所有全局符号"filename"：

import * as symbolName from "filename";

这导致所有全局符号都以symbolName.symbol.

这种语法的一个变体不是 ES6 的一部分，但可能有用的是：

import "filename" as symbolName;

这相当于。import * as symbolName from "filename";

如果存在命名冲突，您可以在导入时重命名符号。例如，下面的代码分别创建了新的全局符号alias和从内部symbol2引用 symbol1和。symbol2"filename"

import {symbol1 as alias, symbol2} from "filename";

导入路径

为了能够在所有平台上支持可重现的构建，Solidity 编译器必须抽象出存储源文件的文件系统的细节。由于这个原因，导入路径不直接引用主机文件系统中的文件。相反，编译器维护一个内部数据库（虚拟文件系统或简称VFS），其中为每个源单元分配一个唯一的源单元名称，该名称是一个不透明且非结构化的标识符。导入语句中指定的导入路径被翻译成源单元名称，用于在该数据库中查找对应的源单元。

使用标准 JSON API，可以直接提供所有源文件的名称和内容作为编译器输入的一部分。在这种情况下，源单元名称确实是任意的。但是，如果您希望编译器自动查找源代码并将其加载到 VFS 中，则您的源单元名称的结构需要使导入回调能够找到它们。使用命令行编译器时，默认导入回调仅支持从主机文件系统加载源代码，这意味着您的源单元名称必须是路径。一些环境提供更通用的自定义回调。例如， Remix IDE提供了一个让您从 HTTP、IPFS 和 Swarm URL 导入文件或直接引用 NPM 注册表中的包。

有关虚拟文件系统和编译器使用的路径解析逻辑的完整描述，请参见路径解析。

注释

可以使用单行注释 ( //) 和多行注释 ( /*...*/)。

// This is a single-line comment.

/*
This is a
multi-line comment.
*/

笔记
单行注释由 UTF-8 编码中的任何 unicode 行终止符（LF、VF、FF、CR、NEL、LS 或 PS）终止。结束符在注释之后仍然是源代码的一部分，所以如果它不是ASCII符号（这些是NEL、LS和PS），就会导致解析器错误。
此外，还有另一种类型的注释，称为 NatSpec 注释，在样式指南中有详细说明。它们用三斜杠 ( ///) 或双星号块 ( /** ... */) 编写，应直接在函数声明或语句上方使用。

← 模块化合约

合约结构 →