为什么是持续集成/持续交付？
在我们深入了解设置之前，让我们简要介绍一下为什么 ci/cd 如此重要：
- 自动化测试：自动运行测试可确保代码在每次更改时保持稳定。
- 一致性：ci/cd 在整个代码库中强制执行标准（linting、格式化）。
- 可靠性：自动检查和测试最大限度地减少人为错误并提高代码可靠性。
- 快速反馈：开发人员会收到有关代码质量的即时反馈，以便及早发现问题。
在 readmegenie 中，我们利用 github actions 作为我们的 ci/cd 工具。它与 github 存储库顺利集成，并通过 yaml 配置文件提供灵活性和自动化。
readmegenie 的 ci/cd 管道
我们的 ci/cd 管道包括以下自动化步骤：
- linting 和格式检查：我们运行 ruff 和 black 以确保代码风格和一致性。
- 单元测试：我们使用单元测试来验证代码更改不会破坏现有功能。
- 覆盖率分析：我们使用coverage.py来确保代码在允许提交之前满足我们的覆盖率阈值。
- 预提交挂钩：我们添加了挂钩以在推送更改之前强制执行本地质量检查。
github actions 工作流程概述
ci 工作流程在 .github/workflows/python-app.yml 中定义。以下是工作流程每个部分的详细说明：
1. 触发工作流程
工作流程在主分支的每个推送和拉取请求上运行。这可确保所有代码更改在合并到生产环境之前都经过验证。
name: python application
on:
push:
branches: ["main"]
pull_request:
branches: ["main"]
2. 设置python环境
我们将 github actions 配置为使用 python 3.12.x，确保与本地开发环境的一致性。此步骤安装特定的python版本并准备依赖安装的环境。
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: set up python 3.12.x
uses: actions/setup-python@v3
with:
python-version: "3.12.x"
3. 安装依赖项
下一步是安装项目依赖项。在这里，我们升级pip并安装requirements.txt文件，它将安装其中指定的附加依赖项。
- name: install dependencies
run: |
python -m pip install --upgrade pip
pip install flake8 pytest
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
4. 运行 linting 和代码质量检查
linting 是我们工作流程的重要组成部分，确保代码符合指定的质量标准。我们运行 flake8，并带有标记语法错误、未定义名称和复杂性问题的选项。
- name: lint with flake8
run: |
# stop the build if there are python syntax errors or undefined names
flake8 . --count --select=e9,f63,f7,f82 --show-source --statistics
# exit-zero treats all errors as warnings. the github editor is 127 chars wide
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
5. 通过覆盖率分析运行测试
对于单元测试，我们使用 pytest 来运行所有测试用例。此外，我们使用覆盖率来跟踪测试了哪些代码行，确保我们的测试套件满足定义的 75% 覆盖率阈值。
以下命令运行测试并生成覆盖率报告，突出显示测试覆盖率中的任何差距。这对于质量保证至关重要，因为未经测试的代码是未来错误的潜在来源。
- name: test with pytest
run: |
pytest
- name: test functions and coverage
run: |
coverage run --source=. -m unittest discover -s tests
coverage report -m --fail-under=75
此覆盖率检查通过强制测试覆盖至少 75% 的代码库来确保高标准的代码质量。如果覆盖率低于此阈值，则不允许提交。
集成预提交挂钩
除了 ci/cd 之外，我们还设置了预提交挂钩，以在将任何更改推送到存储库之前在本地强制执行代码质量。这些钩子：
- 运行 ruff 进行 linting，运行 black 进行格式化。
- 通过在本地运行具有覆盖率的测试来强制执行最低覆盖率阈值。
以下是我们如何将覆盖率检查添加为 .pre-commit-config.yaml 中的预提交挂钩：
repos:
- repo: local
hooks:
- id: check-coverage
name: Check Coverage
entry: bash -c "coverage run --source=. -m unittest discover -s tests && coverage report -m --fail-under=75"
language: system
挑战和经验教训
设置 ci/cd 需要深入了解不同工具（flake8、pytest、coverage）如何在 github actions 中交互。以下是我们面临的一些挑战以及我们实施的解决方案：
处理不同的本地和远程配置
我们遇到了环境变量冲突的问题，特别是在测试 api 集成和配置处理时。在单元测试中使用@patch.dict和其他模拟技术使我们能够有效地模拟环境。
测试覆盖率和阈值
最大的挑战是确保足够的测试覆盖率。在 github actions 和预提交挂钩中使用带有 --fail-under=75 的coverage.py 有助于执行此标准。
未来的改进
为了使 ci/cd 管道更加强大，我们计划：
- 添加部署阶段：测试通过后自动部署到暂存或生产环境。
- 自动化代码质量徽章：添加动态徽章以在 readme 中显示覆盖率、linting 状态和测试结果。
- 扩大覆盖范围要求：随着我们改进测试并覆盖更多边缘情况，提高覆盖范围阈值。
外卖
通过这个项目，我意识到尽早建立强大的测试和 ci/cd 实践的重要性。如果我重新开始，我会专注于从一开始就编写全面的测试，并随着项目的进展逐步扩展和改进它们。这种方法可以防止丢失分支或未经测试的区域，并确保所有新代码顺利集成到覆盖良好的代码库中。
