如何为FastAPI应用实现自动版本更新-原创手记-慕课网

FastAPI 入门系列 第3部分：版本管理

在这部分，我将解释为什么版本管理对于FastAPI应用来说至关重要。接下来，我将介绍如何通过语义版本管理、Git记录和python-semantic-release包来自动化实现。

最终，你就可以拥有一个自动版本管理系统（版本管理），用于你的FastAPI项目。

版本如何帮助我们呢？

避免混淆： 版本管理有助于跟踪更改，并避免对使用哪个版本产生混淆。
保持兼容性： 确保新更新与旧版本兼容，防止用户遇到问题。
更方便调试： 知道确切的版本可以让识别和修复错误更简单。
清晰沟通： 清晰地告诉其他开发人员和用户所做的更改。
顺畅更新： 使更新顺畅且可预测，不会破坏应用程序功能。

DALL-E 生成的图像概念如下：图像的两个抽象部分，左边是缠绕的线，表示混乱；右边是一条直线，表示清晰。

要了解语义化版本号

语义化版本号（SemVer）是最著名的版本号标准之一。它采用一个三部分的版本号：MAJOR.MINOR.PATCH。

当你做不兼容的API更改时，主要版本号增加。
当你以向后兼容的方式添加功能时，次要版本号增加。
当你做出向后兼容的错误修复时，补丁版本号增加。

想了解更多关于语义化版本的信息，请阅读以下文章或查看original docs。

软件版本控制：语义版本控制本文简要而全面地介绍语义版本控制。语义版本控制是一套简单的规则medium.com

自动版本更新:

有几个版本管理包。比如说，[semantic-release](https://github.com/semantic-release/semantic-release) 是在 Javascript 社区中最受欢迎的版本管理工具之一。

我们将使用python-semantic-release，它是semantic-release包的一个Python版本。

我们将它与我们自己的FastAPI项目通过如下三个简单步骤整合：

1. 安装 python-semantic-release

首先，你需要在你的环境里安装这个 python-semantic-release。

在激活的环境中，使用 poetry 将 python-semantic-release 添加到开发依赖，或者使用默认的 pip。

(proj_env) 用户@(主机名):~$ poerty add -G dev python-semantic-release

(proj-env) 用户名@主机名:~$ pip install python-semantic-release

2. 配置生成

生成项目的配置文件，并将生成的配置追加到 pyproject.toml 文件中，使用以下命令。

semantic-release generate-config --pyproject >> pyproject.toml

生成 semantic-release 配置文件并将结果追加到 pyproject.toml 文件中。(Generate semantic-release configuration and append the result to pyproject.toml file.)
在命令行中执行此命令。(Execute this command in the command line.)
(将输出追加到 pyproject.toml 文件中。)(append the output to pyproject.toml file.)

这是 semantic-release 生成的默认设置：

    [tool.semantic_release]  
    assets = []  
    build_command_env = []  
    commit_message = "{version}\n\n由 python-semantic-release 自动生成"  
    commit_parser = "angular"  
    logging_use_named_masks = false  
    major_on_zero = true  
    allow_zero_version = true  
    no_git_verify = false  
    tag_format = "v{version}"  
    version_variables = ["src/app/version.py:__version__"] # we added this  

    [tool.semantic_release.branches.main]  
    match = "(main|master)"  
    prerelease_token = "rc"  
    prerelease = false  

    [tool.semantic_release.changelog]  
    template_dir = "templates"  
    changelog_file = "CHANGELOG.md"  
    exclude_commit_patterns = []  

    [tool.semantic_release.changelog.environment]  
    block_start_string = "{%"  
    block_end_string = "%}"  
    variable_start_string = "{{"  
    variable_end_string = "}}"  
    comment_start_string = "{#"  
    comment_end_string = "#}"  
    trim_blocks = false  
    lstrip_blocks = false  
    newline_sequence = "\n"  
    keep_trailing_newline = false  
    extensions = []  
    autoescape = true  

    [tool.semantic_release.commit_author]  
    env = "GIT_COMMIT_AUTHOR"  
    default = "semantic-release <semantic-release>"  

    [tool.semantic_release.commit_parser_options]  
    allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "style", "refactor", "test"]  
    minor_tags = ["feat"]  
    patch_tags = ["fix", "perf"]  
    default_bump_level = 0  

    [tool.semantic_release.remote]  
    name = "origin"  
    type = "github"  
    ignore_token_for_push = false  
    insecure = false  

    [tool.semantic_release.publish]  
    dist_glob_patterns = ["dist/*"]  
    upload_to_vcs_release = true

3..\ 添加版本号

创建一个Python文件来存放你的版本信息，然后将其放在项目的根目录中。

    # /src/app/version.py

    """
    版本信息模块，由 python-semantic-release 包自动更新，请勿手动编辑此文件。

    此模块提供了代码版本信息，并由 python-semantic-release 包自动更新。

    请勿手动编辑此文件。
    """

    __version__ = 0.1.0

接下来，你需要在你的 pyproject.toml 文件中进行更新，让 semantic-release 知道如何使用该配置文件。

    [tool.semantic_release]  
    # ... 其他配置项  
    版本变量 = ['src/app/version.py:__version__']

搞定！ 🎉

现在你可以自动地通过你的Git提交信息的格式来提升版本。

使用 Git 提交消息实现自动版本管理

python-semantic-release 依赖于提交消息来检测如何升级到下一个版本。这确保了版本的一致性，并根据变更的类型进行调整。

默认情况下，它采用Angular样式。

提交的信息应遵循准确的格式，以保持可读性，并自动生成变更日志。

提交信息的规范是什么呢？

Header ：包括类型、影响范围（可选）和主题。
Body ：变更的具体内容。
Footer ：有关破坏性变更或问题引用的备注。

    <类型>(<范围>)：<主题>  
    （空行）  
    <内容>  
    （空行）  
    <底部>

种类

提交消息类型决定了你的应用的下一个版本号。例如，feat（功能）会将 MINOR 版本号增加，而 fix（修复）会将 PATCH 版本号增加。下面是标准类型：

feat：新增功能
fix：修复 bug
docs：文档更新
style：代码风格调整
refactor：代码重构（不修复 bug，不增加功能）
perf：性能优化
test：测试调整
chore：构建工具调整

你也可以在你的 pyproject.toml 文件中的 allowed_tags 列表里定义自定义标签。

让我们搞版本

现在我们来看看实际操作吧。添加您的更改，并按照标准格式提交吧：

(proj-env) 用@主机名:~$ git commit -m "feat: 添加自动版本管理"

使用 semantic-release，你可以根据提交信息自动提升版本号。这个干运行命令显示下一个版本号，不会做出任何更改。这意味着下一个版本是 v0.2.0。

    (proj-env) 用户@主机名:~$ semantic-release --noop version --print  
    🛡 因为提供了 '--noop' 参数，所以你正在以无操作模式运行。  
    0.2.0

生成下一个版本，请运行：

    (proj-env) 用户@服务器:~$ 发布语义化版本  
    0.2.0  
    下一个版本将是0.2.0! 🚀

semantic-release 会更新版本文件，提交变更，为提交打标签，并将所有更改推送到远程仓库。

你现在也可以把这个 version 添加到你的 FastAPI 应用中了

    from app.version import __version__  

    app = FastAPI(  
        version=__version__,  
    )

使用 GitHub Actions 进行自动化

你也可以设置你的 CI/CD 管道，使用 semantic-release 在每次成功合并到主分支后自动版本管理。

创建一个工作流文件

将下面的 YAML 配置保存到你的仓库中的 .github/workflows/version-bump.yml。

    name: 版本号提升

    on:  
      push:  
        branches:  
          - main  

    jobs:  
      bump-version:  
        运行于: ubuntu-latest  

        权限:  
            actions: 写  
            contents: 写  

        步骤:  
          - name: 检出代码仓库  
            uses: actions/checkout@v3  
            with:  
                fetch-depth: 0  

          - name: 使用 semantic-release 工具提升版本号  
            uses: python-semantic-release/python-semantic-release@master  
            with:  
                github_token: ${{ secrets.GITHUB_TOKEN }}

每次你把其他分支推送到主分支或者合并到主分支时，它会根据提交信息来增加代码版本，打标签，并在 GitHub 上为此版本发布。现在每次执行这些操作时，都会更新相应的版本信息。

结尾

在FastAPI项目中，版本管理对清晰度和控制至关重要。通过语义化版本控制、Git提交信息和python-semantic-release工具来自动化版本管理可以提高项目的清晰度和可维护性。

通过遵循此指南，你将为你的FastAPI应用程序拥有一套高效的版本管理，确保顺畅的更新、更简单的调试以及与团队的清晰地沟通。自动你的版本控制以保持你的FastAPI项目条理清晰并面向未来的发展。

一个了解更多信息的地方！了解更多吧！

使用Conda和Poetry设置FastAPI项目的第二篇：环境和依赖中

如何组织您的FastAPI项目（第1部分：规划）中

资源

语义版本 2.0.0semver.org

介绍: Poetry是一个用于Python的依赖管理和打包工具。它帮助管理依赖关系和打包，并允许你声明所需的库依赖…

GitHub - python-semantic-release/python-semantic-release: Python项目的自动语义发布…为Python项目自动处理语义发布。加入我们：github.com/python-semantic-release/python-semantic-release

[GitHub Actions 工作流语法 - GitHub 文档

工作流是由一个或多个作业组成的可配置的自动化流程。您需要创建一个 YAML 文件来定义您的工作流…docs.github.com](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions?source=post_page-----b008ed5f3edc--------------------------------)