开发指南

编码指南

我们大部分情况下会遵循 PEP 8 指南，可以在这里查看：https://pythonlang.cn/dev/peps/pep-0008/

测试指南

Swift 拥有全面的测试套件和 pep8 检查，这些套件和检查会在所有提交的代码上运行。建议开发者自行执行测试，以便尽早发现回归。开发者还应在提交代码更改时保持测试套件的最新状态。

可以使用 tox 在隔离的环境中执行 Swift 的测试和 pep8 检查：http://tox.testrun.org/

要执行测试

  • 确保 pip 和 virtualenv 已升级，以满足 OpenStack 全局需求 中列出的版本要求

    pip install pip -U
pip install virtualenv -U

  • 安装 tox

    pip install tox

  • 生成要安装的发行包列表以进行测试

    tox -e bindep

    现在使用您的发行包管理器（如 apt-get、dnf、yum 或 zypper）安装这些包。

  • 从 swift 仓库的根目录运行 tox

    tox

要使用 pytest 运行选定的单元测试子集

  • 使用 tox 创建虚拟环境

    tox devenv -e py3 .env

注意

或者，以下是手动准备虚拟环境的步骤

virtualenv .env
source .env/bin/activate
pip3 install -r requirements.txt -r test-requirements.txt -c py36-constraints.txt
pip3 install -e .
deactivate

  • 激活虚拟环境

    source .env/bin/activate

  • 运行一些单元测试，例如

    pytest test/unit/common/middleware/crypto

  • 运行所有单元测试

    pytest test/unit

注意

如果您使用 cd ~/swift; sudo python setup.py develop 安装，则可能需要在运行 tox 之前执行 cd ~/swift; sudo chown -R ${USER}:${USER} swift.egg-info。

  • 默认情况下，tox 将运行 tox.ini 文件 envlist 选项中列出的所有单元测试和 pep8 检查。可以在 tox 命令行上或通过设置 TOXENV 环境变量指定测试环境的子集。例如，要仅运行 pep8 检查和 python3 单元测试，请使用

    tox -e pep8,py3

    或者

    TOXENV=py3,pep8 tox

    要使用 python3.12 专门运行单元测试

    tox -e py312

注意

从 tox 版本 2.0.0 开始，大多数环境变量不会自动传递到测试环境。Swift 的 tox.ini 覆盖此默认行为，以便传递匹配 SWIFT_* 和 *_proxy 的变量名，但升级 tox 后可能需要运行 tox --recreate 才能使之生效 <2.0.0。

相反，如果您不希望将这些环境变量传递到测试环境，则需要在调用 tox 之前取消设置它们。

此外，如果您遇到 DistributionNotFound，请尝试使用 tox --recreate 或删除 .tox 目录以强制 tox 重新创建依赖项列表。

Swift 的测试需要在 /tmp 或 TMPDIR 环境变量中提供一个可用的 XFS 目录。

Swift 的功能测试可以针对 SAIO（Swift All In One） 或其他正在运行的 Swift 集群使用以下命令执行

tox -e func

功能测试要使用的端点和授权凭据应在 test.conf 文件中配置，如 设置运行 Swift 的脚本 部分所述。

环境变量 SWIFT_TEST_POLICY 可设置为指定将用于测试的特定存储策略名称。设置后，否则不会指定策略或从可用策略中随机选择策略的测试将使用指定的策略。使用多个策略的测试将包含指定的策略。指定的策略必须在被测集群上可用。

例如，此命令将使用策略“silver”运行功能测试

SWIFT_TEST_POLICY=silver tox -e func

要运行单个功能测试，请使用 --no-discover 选项以及指向特定测试方法的路径，例如

tox -e func -- --no-discover test.functional.tests.TestFile.testCopy

进程内功能测试

如果未找到 test.conf 文件，则功能测试框架将在执行功能测试的同一进程中实例化一组 Swift 服务器。这种“进程内测试”模式也可以通过将环境变量 SWIFT_TEST_IN_PROCESS 设置为 true（或 false）值来启用（或禁用）执行 tox -e func 之前。

在使用“进程内测试”模式时，可以使用环境变量设置一些服务器配置选项

  • 可以通过将环境变量 SWIFT_TEST_IN_MEMORY_OBJ 设置为 true 值来选择可选的内存对象服务器。

  • 可以通过将环境变量 SWIFT_TEST_IN_PROCESS_CONF_LOADER 设置为 encryption 来将加密添加到代理管道。

  • 可以通过将环境变量 SWIFT_TEST_IN_PROCESS_CONF_LOADER 设置为 ec 来安装 2+1 EC 策略作为默认策略。

  • 可以通过设置 SWIFT_TEST_DEBUG_LOGS 来启用输出到 stdout 的日志记录。

例如，此命令将使用代理服务器中启用的加密运行进程内模式功能测试

SWIFT_TEST_IN_PROCESS=1 SWIFT_TEST_IN_PROCESS_CONF_LOADER=encryption \
    tox -e func

此示例也可以使用 func-encryption tox 环境运行

tox -e func-encryption

tox.ini 文件还指定了用于运行其他进程内功能测试配置的测试环境，例如

tox -e func-ec

要调试功能测试，请使用“进程内测试”模式，并将 --pdb 标志传递给 tox

SWIFT_TEST_IN_PROCESS=1 tox -e func -- --pdb \
    test.functional.tests.TestFile.testCopy

“进程内测试”模式搜索 proxy-server.conf 和 swift.conf 配置文件，从中复制配置选项并覆盖一些选项以适应进程内测试。搜索将首先查找 <custom_conf_source_dir> 中的配置文件，该目录可以可选地使用环境变量指定

SWIFT_TEST_IN_PROCESS_CONF_DIR=<custom_conf_source_dir>

如果未设置 SWIFT_TEST_IN_PROCESS_CONF_DIR，或者在 <custom_conf_source_dir> 中未找到配置文件，搜索将查找源树中的 etc/ 目录。如果仍然找不到配置文件，则将使用来自 etc/ 的相应示例配置文件（例如 proxy-server.conf-sample 或 swift.conf-sample）。

在使用“进程内测试”模式时，SWIFT_TEST_POLICY 可以设置为指定将用于测试的特定存储策略名称，如上所述。设置后，此策略必须存在于 swift.conf 文件中，并且其相应的环文件必须存在于 <custom_conf_source_dir>（如果指定）或 etc/ 中。测试设置会将指定的策略设置为默认策略并使用其环文件属性来构建测试对象环。这允许针对各种策略类型和环文件进行进程内测试。

例如，此命令将使用在 $HOME/my_tests 中找到的配置文件和策略“silver”运行进程内模式功能测试

SWIFT_TEST_IN_PROCESS=1 SWIFT_TEST_IN_PROCESS_CONF_DIR=$HOME/my_tests \
   SWIFT_TEST_POLICY=silver tox -e func

S3 API 跨兼容性测试

目录 test/s3api 中的跨兼容性测试旨在验证 Swift S3 API 的行为方式与 AWS S3 API 相同。当针对 Swift 端点（启用 S3 API）或 AWS S3 端点运行时，它们应通过。

要针对 AWS S3 端点运行，必须编辑 /etc/swift/test.conf 文件以提供 AWS 密钥 ID 和密钥。或者，可以通过设置 SWIFT_TEST_AWS_CONFIG_FILE 环境变量加载 AWS CLI 样式的凭据文件，例如

SWIFT_TEST_AWS_CONFIG_FILE=~/.aws/credentials pytest ./test/s3api

注意

当使用 SWIFT_TEST_AWS_CONFIG_FILE 时，区域默认为 us-east-1 并且仅加载默认凭据。

编码风格

Swift 使用带有 OpenStack hacking 模块的 flake8 来强制编码风格。

使用 pip 或您的操作系统包安装 flake8 和 hacking。

建议将 flake8+hacking 与您的编辑器集成，以便自动化它，而不会被 Jenkins 捕获。

例如，对于 Vim，syntastic 插件可以为您做到这一点。

文档指南

文档字符串中的文档应遵循 PEP 257 约定（如 PEP 8 指南中所述）。

更具体地说

  1. 应使用三引号表示所有文档字符串。

  2. 如果文档字符串很简单且适合一行，则只需使用一行。

  3. 对于占用多行的文档字符串，应在开引号之后和闭引号之前换行。

  4. Sphinx 用于构建文档，因此使用重构文本标记来指定参数、返回值等。可以在这里找到有关 sphinx 特定标记的文档：https://sphinx-doc.cn/en/2025.2/

要构建文档，请运行

pip install -r requirements.txt -r doc/requirements.txt
sphinx-build -W -b html doc/source doc/build/html

然后浏览到 doc/build/html/index.html。这些文档在每次提交后自动生成，并且可在 https://docs.openstack.org/swift/2025.2/ 上找到。

Manpages

为了检查您在 manpage 中的更改是否正确，请在 Swift 仓库的根目录中使用此命令

./.manpages