MBE 文档中心

🚀 CI/CD 完整指南

📋 概述

MBE Monorepo 严格遵循 CI/CD 最佳实践，确保代码质量和项目稳定性。

🔄 CI/CD 流程

1. Pre-commit Hooks（提交前检查）

安装:

pip install pre-commit
pre-commit install

自动检查项:

  • ✅ 代码格式（ruff）
  • ✅ 代码格式化（ruff format）
  • ✅ Monorepo 结构验证
  • ✅ 模块边界检查
  • ✅ YAML/JSON/TOML 语法
  • ✅ 文件末尾换行
  • ✅ 调试语句检查

手动运行:

pre-commit run --all-files

2. GitHub Actions CI Pipeline

触发条件

  • Push 到 main, master, develop 分支
  • Pull Request 到 main, master 分支
  • 手动触发（workflow_dispatch）

Pipeline Jobs

Job 1: Validate（验证）

  • Monorepo 结构验证
  • 模块边界检查
  • 运行时间: ~30秒

Job 2: Lint（代码检查）

  • Ruff 代码检查
  • 代码格式验证
  • 运行时间: ~1分钟

Job 3: Test Monorepo（Monorepo 测试）

  • 单元测试
  • 集成测试
  • 用户注册功能测试（新增）
  • 运行时间: ~3-5分钟

Job 4-6: Module Tests（模块测试）

  • Core 模块测试
  • Platform 模块测试
  • SDK 测试
  • 运行时间: ~2-3分钟/模块

Job 7: Docker Build（Docker 构建）

  • 仅在 main/master 分支运行
  • 构建 API 和 Worker 镜像
  • 运行时间: ~5-10分钟

3. 专项测试工作流

用户注册功能测试 (test-registration.yml)

触发条件:

  • 修改 private/platform/src/users/**
  • 修改 tests/integration/test_user_registration.py

测试内容:

  • ✅ 新用户注册成功
  • ✅ refresh_token 返回验证
  • ✅ 重复邮箱错误处理
  • ✅ 必填字段验证
  • ✅ nickname 字段支持

📝 代码提交规范

Commit Message 格式

<type>(<scope>): <subject>

<body>

<footer>

示例:

fix(users): 注册接口返回 refresh_token

- 修复注册接口缺少 refresh_token 的问题
- 添加 nickname 字段支持（数据库兼容性）
- 改进错误信息显示

Closes #123

Type 类型

  • feat: 新功能
  • fix: 修复 bug
  • docs: 文档更新
  • test: 测试相关
  • refactor: 重构
  • chore: 构建/工具相关
  • perf: 性能优化
  • style: 代码格式（不影响功能）

🧪 测试要求

测试覆盖率

  • 最低要求: 70%
  • 目标: 80%+
  • 关键功能: 90%+

测试类型

  1. 单元测试 (@pytest.mark.unit)

    • 测试单个函数/方法
    • 快速执行（<1秒）
    • 不依赖外部服务

  2. 集成测试 (@pytest.mark.integration)

    • 测试 API 端点
    • 需要数据库/Redis
    • 验证完整流程

  3. 端到端测试 (@pytest.mark.e2e)

    • 测试完整用户流程
    • 需要完整环境
    • 运行时间较长

测试文件结构

tests/
├── unit/              # 单元测试
│   └── test_utils.py
├── integration/       # 集成测试
│   ├── test_api.py
│   ├── test_database.py
│   └── test_user_registration.py  # 新增
└── conftest.py        # 测试配置

🔍 代码质量检查

Ruff 配置

检查规则:

  • E: 错误（Error）
  • W: 警告（Warning）
  • F: 格式（Format）

忽略规则:

  • E501: 行长度（由格式化工具处理）
  • W291-W293: 空白行相关

运行检查:

ruff check private/platform/src/users/
ruff format private/platform/src/users/

📦 发布流程

版本号规范

遵循 Semantic Versioning:

  • MAJOR.MINOR.PATCH
  • 示例: 1.2.3

发布步骤

  1. 更新版本号

    # 在 pyproject.toml 或 __init__.py 中更新版本

  2. 更新 CHANGELOG.md

    • 添加新功能/修复说明
    • 更新日期

  3. 创建 Git Tag

    git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

  4. CI 自动构建和发布

    • GitHub Actions 自动触发
    • 构建 Docker 镜像
    • 发布到 Registry

🚨 CI/CD 失败处理

常见失败原因

  1. 测试失败

    • 检查测试输出
    • 修复失败的测试
    • 确保测试环境正确

  2. 代码检查失败

    • 运行 ruff check 查看问题
    • 运行 ruff format 自动修复
    • 重新提交

  3. 构建失败

    • 检查 Dockerfile
    • 检查依赖版本
    • 查看构建日志

重新运行 CI

  • GitHub Actions: 点击 "Re-run jobs"
  • 本地: 运行 pre-commit run --all-files

📚 相关文档

✅ CI/CD 检查清单

提交代码前确保：

  • Pre-commit hooks 通过
  • 所有测试通过
  • 代码覆盖率达标
  • 代码格式正确
  • 文档已更新
  • CHANGELOG 已更新
  • Commit message 符合规范

重要: 所有代码更改必须通过 CI/CD 检查才能合并到主分支！