Sanic 贡献指南：从源码安装到测试、代码规范与 PR 流程的完整实践手册-育师

Sanic 贡献指南：从源码安装到测试、代码规范与 PR 流程的完整实践手册

【免费下载链接】sanicAccelerate your web app development | Build fast. Run fast.项目地址: https://gitcode.com/gh_mirrors/sa/sanic

导读

本文基于 Sanic 官方贡献指南（仓库内 CONTRIBUTING.md 及其完整版 guide/content/en/organization/contributing.md）编写，系统讲解如何以源码方式搭建 Sanic 开发环境、理解其依赖管理策略、使用 tox 运行单元测试与各类质量检查，以及通过 Pull Request 向 Sanic 提交代码时必须遵守的规范。读完本文，你将掌握一套可直接落地执行的 Sanic 本地开发、测试与提交工作流，并理解这些流程背后的源码与配置依据。

说明：仓库根目录的 CONTRIBUTING.md 仅有两行内容并指向官方站点，完整贡献指南的实际全文位于 guide/content/en/organization/contributing.md，本文以该完整文档为主体展开。

参与方式：不只是写代码

Sanic 社区欢迎各种形式的贡献。官方指南明确指出：如果你不习惯提交代码，为源码文件补充 docstring、或为 Sanic 用户指南提供文档与实现示例，同样是备受珍视的贡献方式。这意味着贡献门槛被刻意降低——文档编写、示例补充与代码提交在社区中享有同等价值。

此外，Sanic 承诺为所有参与者提供友好、安全、包容的环境，无论其性别、性取向、残障、种族、宗教或个人特征如何。相应的行为标准由 CODE_OF_CONDUCT.md 规定，其完整内容同样位于 guide/content/en/organization/code-of-conduct.md，涵盖承诺（Our Pledge）、行为标准（Our Standards）、维护者职责、适用范围（Scope）、执行机制（Enforcement）等条款，要求参与者使用包容性语言、尊重不同观点、优雅接受建设性批评，并禁止骚扰、贬损性评论、未经许可公开他人隐私等行为。

环境准备：从源码安装开发版

要进行 Sanic 的本地开发（尤其是运行测试），官方强烈推荐从源码安装。假设你已经克隆了仓库并进入工作目录，且已创建好虚拟环境，只需执行：

pip install -e ".[dev]"

-e表示以可编辑（editable）模式安装，源码改动会即时生效，无需重复安装；.[dev]则安装包含完整开发依赖的 extras。安装完成后，sanic命令即来自 setup.py 中注册的入口点sanic = sanic.__main__:main。

从 setup.py 的源码看，Sanic 的最低运行依赖（install_requires）包括sanic-routing>=23.12.0、httptools>=0.0.10、aiofiles、websockets、multidict、html5tagger、tracerite、typing-extensions等，其中uvloop与ujson通过环境标记仅安装在 CPython 且非 Windows 平台（见 setup.py）。

环境变量的可选影响

安装脚本支持两个可选环境变量来剥离加速依赖（见 setup.py）：

SANIC_NO_UJSON=1：不安装 uJSON，同时移除对应的types_ujson类型存根；
SANIC_NO_UVLOOP=1：不安装 uvLoop。

这两个开关在 tox 的-no-ext测试环境中会被显式设置（见 tox.ini），用于验证 Sanic 在无这些加速库时的兼容性。

依赖管理策略：setup.py 而非 requirements*.txt

Sanic不使用requirements*.txt文件管理任何依赖，这是刻意的设计，目的是简化依赖维护的复杂度。所有依赖关系都集中在 setup.py 中通过extras_require声明。官方文档给出了清晰的分类表：

依赖类型	用途	安装方式
requirements（基础依赖）	Sanic 运行所需的最小依赖集	`pip3 install -e .`
tests_require / extras_require['test']	运行 Sanic 单元测试所需的依赖	`pip3 install -e '.[test]'`
extras_require['dev']	参与贡献所需的额外开发依赖	`pip3 install -e '.[dev]'`
extras_require['docs']	构建与增强 Sanic 文档所需依赖	`pip3 install -e '.[docs]'`

对照 setup.py 的源码，这一结构完全吻合：

tests_require包含sanic-testing>=23.6.0、pytest>=8.2.2、pytest-xdist>=3.5.0、pytest-cov、coverage、beautifulsoup4、pytest-sanic、pytest-benchmark、chardet==3.*、ruff、bandit、mypy、slotscheck>=0.8.0,<1等；
dev_require = tests_require + ["cryptography", "tox", "towncrier"]——即在测试依赖之上追加 tox（测试编排）与 towncrier（changelog 生成）；
docs_require则包含sphinx>=2.1.2、sphinx_rtd_theme、m2r2、enum-tools[sphinx]、mistune、autodocsumm、msgspec、python-frontmatter、docstring-parser、libsass等文档构建工具；
此外还有ext（sanic-ext）、http3（aioquic）等额外 extras。

由于dev依赖基于tests_require拼接，pip install -e ".[dev]"一次性覆盖了测试与开发所需的全部工具链。

用 tox 运行测试与质量检查

Sanic 的测试与质量检查全部由 tox.ini 编排，官方推荐直接运行：

tox

不传参数时，tox 会按envlist依次执行所有环境（见 tox.ini）：py310, py311, py312, py313, py314, pyNightly, pypy310各 Python 版本的测试环境，以及对应的-no-ext变体、lint、check、security、docs、type-checking。也就是说，一次tox会跑完全部单元测试、代码风格检查及其他校验。

tox 的基础测试环境（[testenv]）配置了extras = test, http3，并以pytest -n 3 --dist loadgroup {posargs:tests}并行执行测试（见 tox.ini）。下面按官方文档逐一说明各专用环境。

运行单元测试

对应 tox 环境：[testenv]及各 Python 版本专属环境（如py310等）。

tox -e py37 -v -- tests/test_config.py # 或 tox -e py310 -v -- tests/test_config.py

其中-v输出详细信息，--之后的参数会透传给 pytest，因此可以指定单个测试文件甚至单个用例来快速迭代。注意：当前仓库 setup.py 声明python_requires = ">=3.10"，tox 的envlist也是py310起的版本矩阵，因此实际可用的环境以本机已安装的 Python 版本为准（如py310、py311等）。

运行 lint 检查

对应 tox 环境：[testenv:lint]。

官方文档说明 lint 执行flake8、black与isort检查，命令为：

tox -e lint

对照 tox.ini 的当前实现，lint 环境实际执行的命令是ruff check sanic、ruff format sanic --check与slotscheck --verbose -m sanic——即风格检查已统一迁移到 ruff、sanic/base/meta.py、sanic/blueprints.py、sanic/middleware.py、sanic/response/types.py、sanic/server/async_server.py 等文件均包含__slots__声明。

运行类型注解检查

对应 tox 环境：[testenv:type-checking]，执行mypy检查（见 tox.ini）：

tox -e type-checking

Sanic 对类型注解要求严格——PR 规范中明确要求代码"正确地"进行类型注解，这正是mypy sanic检查的意义所在。

运行其他检查

对应 tox 环境：[testenv:check]，执行打包元数据校验（见 tox.ini）：

tox -e check

其实际命令为python setup.py check -r -s，即检查setup.py中声明的依赖（-r）与元数据（-s）是否完整合法。

运行静态安全分析

对应 tox 环境：[testenv:security]，执行 bandit 安全扫描（见 tox.ini）：

tox -e security

命令为bandit --recursive sanic -b ./bandit.baseline，其中-b ./bandit.baseline指定基线文件，允许已确认的已知告警不再重复报告，从而让新引入的安全问题更容易被暴露。基线文件位于仓库根目录 bandit.baseline。

运行文档健全性检查

对应 tox 环境：[testenv:docs]，对文档做健全性检查（见 tox.ini）：

tox -e docs

该环境仅限 Linux/macOS 平台，安装docs, http3extras 后执行make docs-test。仓库 Makefile 中docs-test目标会先执行docs-clean，再在docs目录下执行make dummy，以验证文档可被正确构建且无引用错误。

代码风格：四件套与 make pretty

为保持代码一致性，Sanic 使用以下工具：

isort：对 Python import 排序，将导入分为内置（built-in）、第三方（third-party）、项目内（project-specific）三类，各类内部按字母序排列；
black：Python 代码格式化器，统一代码排版；
flake8：Python 风格检查器，聚合了 PyFlakes、pycodestyle 与 Ned Batchelder 的 McCabe 脚本（复杂度检查）；
slotscheck：确保__slots__定义没有问题（例如槽位重叠、基类缺失槽位等）。

需要强调的是：isort、black、flake8、slotscheck 这四项检查都会在tox -e lint中执行。虽然当前仓库的 lint 命令已用ruff统一取代 isort/black/flake8 的调用（见 tox.ini），但检查目标完全一致——导入排序、代码格式化与风格合规。

提交前的捷径：make pretty

官方文档给出的"最简单"方式是在提交前运行：

make pretty

查看仓库 Makefile 可知，pretty目标实际由两部分组成：

fix: ruff check ${RUFF_FORMATTED_FOLDERS} --fix format: ruff format ${RUFF_FORMATTED_FOLDERS} pretty: format fix

其中RUFF_FORMATTED_FOLDERS = sanic examples scripts tests guide docs（见 Makefile），即make pretty会对源码、示例、脚本、测试、文档等全部目录先执行ruff format再执行ruff check --fix，自动修复大部分格式与风格问题。与之配套的还有make fix（仅修复 lint）、make format（仅格式化）等目标。

Pull Request 提交规则

官方文档给出了清晰的 PR 批准规则，共 9 条：

所有 PR 必须通过单元测试；
所有 PR 必须经过至少一位当前 Core Developer 团队成员审阅并批准；
所有 PR 必须通过 flake8 检查（当前对应 tox.ini 中lint环境的ruff check sanic）；
所有 PR 必须满足 isort 与 black 要求（当前对应ruff format sanic --check）；
所有 PR 必须正确地进行类型注解，除非获得豁免；
所有 PR 必须与现有代码保持一致；
若要从任何公共接口删除/更改内容，必须依据弃用政策附上弃用消息（deprecation message）；
若实现新功能，必须至少附带一个单元测试；
示例必须属于以下类别之一：
- 展示如何使用 Sanic；
- 展示如何使用 Sanic 扩展；
- 展示如何将 Sanic 与异步库结合使用。

仓库中 examples 目录正是第 9 条的直观体现——例如 examples/hello_world.py（Sanic 基础用法）、examples/authorized_sanic.py 与 examples/logdna_example.py（扩展集成）、examples/limit_concurrency.py（异步并发场景）等。

弃用消息的源码实现

第 7 条提到的弃用机制在源码层有对应实现。Sanic 在 sanic/logging/deprecation.py 提供deprecation(message, version)工具函数，其 docstring 明确要求：当功能即将被移除时，version参数至少应为下一个版本号 + 2；函数会以[DEPRECATION vX.Y]前缀的格式输出告警信息，并触发DeprecationWarning（颜色化输出见源码中Colors.RED/Colors.YELLOW的应用）。

而弃用政策进一步规定：在功能被弃用或引入破坏性 API 变更之前，必须对外公开，并通过两个发布周期持续显示弃用警告；LTS 版本中不得进行任何弃用。仅当绝对必要（例如为遏制重大安全问题时别无替代方案）才可绕过该流程。

文档与示例贡献

官方指南中"Documentation"一节目前标注为"Check back. We are reworking our documentation so this will change."（文档正在重构中，此部分将有所变化），表明 Sanic 团队正在重新整理文档体系。当前仓库的文档主要由两部分构成：

docs 目录：基于 Sphinx 的 API 文档（docs/conf.py），涵盖 app、blueprints、router、server 等 API 参考；
guide 目录：用户指南内容，覆盖入门、基础、进阶、部署、插件等主题，例如 guide/content/en/guide/getting-started.md、guide/content/en/guide/basics/app.md 等。

通过 Makefile 的make docs、make docs-test、make docs-serve目标，可以分别构建文档、做健全性测试、或启动本地文档预览服务（sphinx-autobuild docs docs/_build/html --port 9999 --watch ./，见 Makefile）。若你选择以文档或示例的方式参与贡献，这些命令就是你的主要工具。

一站式贡献工作流总结

综合全文，一次完整的 Sanic 贡献流程可以归纳为：

准备环境：克隆仓库、创建虚拟环境，执行pip install -e ".[dev]"安装全部开发依赖；
编写/修改代码：遵循 Sanic 的代码风格，为新功能补充单元测试，必要时添加符合弃用政策的弃用消息；
本地自检：运行make pretty自动格式化与修复风格问题；运行tox -e py310 -v -- tests/xxx.py聚焦验证改动相关的测试；运行tox -e lint、tox -e type-checking确认风格与类型检查通过；
全量验证：提交 PR 前运行tox跑完全部环境的单元测试与质量检查（必要时单独执行tox -e security与tox -e docs）；
提交 PR：确保改动通过全部单元测试、获得至少一位 Core Developer 审阅批准、通过风格与类型检查、与新功能配套的单元测试齐备，且代码与现有实现保持一致。