mconf/mconf-aggr

Mconf-Aggregator

• 当前版本: 1.10.0

Python版本

注意：此步骤只需执行一次。

本项目需使用Python 3.9.10版本。开始前，需确保已设置正确版本。强烈建议使用版本管理器如pyenv。关于pyenv的安装说明，请查看https://github.com/pyenv/pyenv#installation%E3%80%82

注意：安装pyenv后，别忘了运行source ~/.bashrc。

安装pyenv后，在项目根目录执行以下命令：

bash
$ pyenv install 3.9.10
$ pyenv local 3.9.10
$ pyenv rehash

此时会生成.python-version文件，内容为3.9.10。建议验证Python版本是否切换成功：

bash
$ python --version

预期输出：

Python 3.9.10

此后，项目中所有Python相关命令（未使用虚拟环境时）均由pyenv提供。例如，which pip3的输出应类似：

/home/john_doe/.pyenv/shims/pip3

运行项目脚本时，需显式调用Python，如python main.py。不要将脚本设为可执行后直接运行，因为显式调用可确保使用pyenv指定的Python版本；直接运行可能使用系统Python（版本可能不符）。

故障排除：若pyenv使用异常，确保.bashrc或bash_profile文件末尾包含：eval "$(pyenv init -)"

虚拟环境

为控制Python版本及相关库，项目使用poetry管理虚拟环境，这是Python开发中的常见模式。

执行poetry install或poetry shell等命令时，若.venv文件夹不存在，poetry会自动创建虚拟环境。

安装poetry：

bash
$ make install-requisites-locally

激活虚拟环境：

bash
$ poetry shell

此时命令提示符开头会显示(.venv)，表明已进入虚拟环境，所有Python命令均由.venv提供。例如，which pip3的输出应类似：

/home/john_doe/myproject/.venv/bin/pip3

运行脚本时，需显式调用Python，如python main.py。不要将脚本设为可执行后直接运行，以确保使用虚拟环境中的Python版本。

退出虚拟环境：

bash
$ exit

注意：不要使用deactivate（venv常用命令），否则需重启poetry shell。

安装开发依赖：

bash
$ make install-deps-locally

依赖项

项目当前使用以下第三方包：

• psycopg2 2.7.3.1或更高版本 (官方网站)
• sphinx 1.6.3或更高版本 (官方网站)
• sqlalchemy 1.2.0b2或更高版本 (官方网站)

验证安装是否成功（在项目根目录）：

bash
$ python -c "import psycopg2"
$ python -c "import sqlalchemy"

成功时无输出。

注意：Sphinx用于生成文档，无需导入验证。

测试

项目使用标准unittest包进行测试。所有测试文件位于tests/目录，命名模式为*_test.py。测试主脚本为根目录的tests.py，配置文件为config/tests.json。

注意：修改代码后，请运行相关（最好是所有）测试。

关于unittest的更多信息，参见unittest官方文档。

运行单个测试

以测试aggregator_test.py为例，有两种方式：

• 通过tests.py脚本指定测试文件名（含扩展名）：

bash
$ python tests.py aggregator_test.py

• 直接调用unittest测试tests/目录下的文件：

bash
$ python -m unittest tests/aggregator_test.py

运行测试套件

可通过tests.py脚本运行多个测试模块（称为“测试套件”），用于按功能等维度分组测试。

在config/tests.json的test_suites字段中添加套件名称及tests/目录下的模块列表，即可创建新测试套件。

例如，运行aggregator套件：

bash
$ python tests.py aggregator

运行集成测试套件integration：

bash
$ python tests.py integration

运行所有测试

两种方式：

• 推荐方式：直接运行tests.py（不包含集成测试，需单独运行integration套件）：

bash
$ python tests.py

文档生成

项目使用Sphinx生成文档。

文档位于docs/目录，主要从Python代码的文档字符串生成。文档字符串格式为numpydoc，文档格式为reStructuredText。

请保持文档字符串始终最新。

生成HTML文档（在docs/目录）：

bash
$ make html

生成的文件位于docs/_build/html/目录。

可通过Python内置模块http.server启动临时服务器查看文档：

bash
$ cd docs/_build/html/
$ python -m http.server

服务器将运行在localhost:8000，可在浏览器中访问。

Docker

项目提供多个Dockerfile用于构建应用镜像，基于https://hub.docker.com/_/python/%E9%95%9C%E5%83%8F%E3%80%82

推荐通过下文的Makefile部分运行Docker相关命令。

Docker标签

Docker镜像标签遵循以下规则：

本地开发镜像标签：

• <app>-<完整版本>-<提交哈希>

稳定发布镜像标签：

• <app>-<数字版本>
• <app>-<主版本>
• <app>-<提交哈希>
• <app>-latest

不稳定发布镜像标签：

• <app>-<完整版本>
• <app>-<提交哈希>

示例：若webhook应用版本为0.0.2-pre-alpha，当前提交哈希为36fba5：

• 本地标签：webhook-0.0.2-pre-alpha-36fba5
• 稳定发布标签：webhook-0.0.2、webhook-0、webhook-36fba5、webhook-latest
• 不稳定发布标签：webhook-0.0.2-pre-alpha、webhook-36fba5

另有staging标签用于预发布镜像。

版本信息来自.version文件。

使用Docker开发

可使用单个Docker镜像进行开发，容器内代码会替换为当前目录的项目代码。

手动构建

手动构建开发镜像：

bash
$ docker build -f Dockerfile.development -t mconf/mconf-aggr:dev .

建议同时标记为latest：

bash
$ docker tag mconf/mconf-aggr:dev mconf/mconf-aggr:dev-latest

通过Makefile

推荐使用Makefile简化操作：

构建开发镜像：

bash
$ make docker-build-dev

运行开发镜像并传递额外参数（如端口映射）：

bash
$ make docker-run-dev EXTRA_OPTS="-p 8000:8000"

dockerize

为缩短构建时间，建议使用包含dockerize的基础镜像。

dockerize用于从模板文件和环境变量生成Docker容器配置文件，但其安装过程耗时。可预先构建包含dockerize的基础镜像：

dockerize/目录下有两个Dockerfile：

• Dockerfile.alpine.dockerize：构建alpine:latest-dockerize（基于alpine:latest，含dockerize）
• Dockerfile.python3.dockerize：构建python:3.6-alpine-dockerize（基于python:3.6-alpine，含dockerize）

通过Makefile构建这两个镜像（在dockerize/目录）：

bash
$ make docker-build

必须执行此步骤才能使用下文Makefile命令，因为最终镜像依赖这些包含dockerize的基础镜像。

使用VSCode调试

需配置launch.json（VSCode调试配置文件）。例如，调试aggregator：

json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Tests",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/tests.py",
            "console": "integratedTerminal"
        },
        {
            "name": "Python: 附加",
            "type": "python",
            "request": "attach",
            "port": 5678,
            "host": "localhost",
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "."
                }
            ]
        }
    ]
}

配置完成后，确保镜像已构建，通过Makefile运行容器。容器启动后，调试器将等待附加，点击“开始调试”即可在面板中看到调试控制台。

代码检查与自动格式化

使用flake8进行代码检查，black和isort进行格式化。执行以下命令：

bash
$ make lint  # 代码检查
$ make format  # 格式化

配置VSCode

示例.vscode/settings.json配置：

json
{
  "python.formatting.provider": "black",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.sortImports.args": ["--profile=black"],
  "python.sortImports.path": "${workspaceFolder}/.venv/bin/isort",

  "[python]": {
    "editor.codeActionsOnSave": { "source.organizeImports": true },
    "editor.formatOnSave": true,
    "editor.formatOnSaveMode": "file",
    "editor.rulers": [88]
  }
}

Makefile

可通过make工具执行以下主要任务：

• 运行mconf-aggr（无Docker）：$ make run
• 构建Docker镜像：$ make docker-build
• 构建开发Docker镜像：$ make docker-build-dev
• 运行Docker容器：$ make up
• 运行开发Docker容器：$ make up-dev
• 标记稳定Docker镜像：$ make docker-tag
• 标记不稳定Docker镜像：$ make docker-tag-unstable
• 标记latest Docker镜像：$ make docker-tag-latest
• 推送稳定Docker镜像到仓库：$ make docker-push
• 推送不稳定Docker镜像到仓库：$ make docker-push-unstable
• 推送latest Docker镜像到仓库：$ make docker-push-latest
• 运行测试：$ make test
• 构建HTML文档：$ make html
• 代码检查：$ make lint
• 代码格式化：$ make format
• 清理项目：$ make clean

Makefile默认参数：

AGGR_PATH=<当前目录>
DOCKER_USERNAME=mconf
REPOSITORY=mconf-aggr