From 9e587bc4fab5769deae03c47a54d961f81d74690 Mon Sep 17 00:00:00 2001 From: "engine-labs-app[bot]" <140088366+engine-labs-app[bot]@users.noreply.github.com> Date: Tue, 11 Nov 2025 06:27:49 +0000 Subject: [PATCH] docs(ci): add automated test and release design for logic-ide SDK Introduce comprehensive documentation detailing CI/CD strategy for logic-ide with dual compatibility for Spring Boot 2.x and 3.x. This addresses the need for automated testing and standardized release whenever the version number is changed. - Defines process for PR checks, version bump detection, and full compatibility test matrix across Spring Boot versions - Specifies Maven profile use, trigger conditions, artifact publishing, and rollback - Provides GitHub Actions YAML skeleton for implementation reference - Clarifies responsibilities and lifecycle of automated releases This change enables clear, traceable, and consistent delivery practices for SDK releases. --- ...21\345\270\203\350\256\276\350\256\241.md" | 178 ++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 "\350\207\252\345\212\250\345\214\226\346\265\213\350\257\225\344\270\216\345\217\221\345\270\203\350\256\276\350\256\241.md" diff --git "a/\350\207\252\345\212\250\345\214\226\346\265\213\350\257\225\344\270\216\345\217\221\345\270\203\350\256\276\350\256\241.md" "b/\350\207\252\345\212\250\345\214\226\346\265\213\350\257\225\344\270\216\345\217\221\345\270\203\350\256\276\350\256\241.md" new file mode 100644 index 0000000..39658ea --- /dev/null +++ "b/\350\207\252\345\212\250\345\214\226\346\265\213\350\257\225\344\270\216\345\217\221\345\270\203\350\256\276\350\256\241.md" @@ -0,0 +1,178 @@ +# logic-ide 自动化测试与发布设计 + +## 背景与目标 +- **产品形态**：`logic-ide` 对外作为 SDK，为业务系统提供逻辑编排与运行时能力，需要同时兼容 Spring Boot 2.7.x 与 Spring Boot 3.x。 +- **主要诉求**：在研发提交流程中，当版本号发生变更（例如 `pom.xml` 或 `logic-ide` 模块版本升级）时，自动触发完整的兼容性测试，并在通过所有质量门禁后自动化发布。 +- **期望结果**：缩短发布周期、降低回归漏测风险，确保每次版本迭代都经过双版本 Spring Boot 兼容性验证并生成可追溯的构建产物。 + +## 流程总览 +``` +开发提交/合并 -> 版本变更检测 -> CI 预检 (PR 检查) -> 主干合并 -> +版本校验 Job (diff) -> Maven 构建矩阵 (Boot2 / Boot3) -> 集成 & 回归测试 -> +质量门禁 (覆盖率/安全/制品签名) -> Maven Central / 私服 发布 -> Release Note & Tag -> +通知 & 反馈闭环 +``` + +## 触发策略设计 +### 1. Pull Request 阶段 +- **触发条件**：任意针对 `main`/`release-*` 分支的 PR。 +- **目标**：快速反馈编译、单元测试、风格校验问题，避免缺陷进入主干。 +- **测试范围**： + - `mvn -pl logic-ide -am -DskipITs test` + - 静态检查 (`spotless`, `checkstyle`, `spotbugs`) 按需开关。 + - 仅校验默认（Spring Boot 2.7）依赖，以缩短反馈周期。 + +### 2. 版本号变更自动发布 +- **触发条件**：`main` 分支上存在版本号提升的提交。 +- **检测逻辑**： + 1. 在工作流的初始化 Job 中对比 `HEAD^..HEAD` 修改文件，若涉及 `pom.xml`、`logic-ide/pom.xml` 或 `logic-sdk/pom.xml` 等版本定义文件则继续。 + 2. 使用 `mvn help:evaluate -Dexpression=project.version` 在前后两个 commit 中提取版本，并通过脚本比对是否发生语义化提升。 + 3. 也可追加校验提交信息（如 `release:` 前缀）或标签触发，确保发布动作受控。 +- **手动触发**：保留 `workflow_dispatch` 输入参数（版本号、是否跳过发布）以支持运维介入或热补。 + +## 测试矩阵与构建策略 +| 维度 | Spring Boot 2.7.x | Spring Boot 3.1.x/3.2.x | +| --- | --- | --- | +| JDK | Temurin 17 | Temurin 17/21（按兼容策略） | +| Maven Profile | `-Pboot2`（或默认 profile） | `-Pboot3`（引入 Spring Boot 3 依赖 BOM） | +| 构建命令 | `mvn -pl logic-ide -am clean verify -DskipITs=false -Pspring-boot-2` | `mvn -pl logic-ide -am clean verify -DskipITs=false -Pspring-boot-3` | +| 测试重点 | 历史存量业务场景回归、Bean 兼容性、序列化差异 | Jakarta 命名空间适配、`jakarta.*` 依赖校验、Spring Boot 3 API 变更 | + +> **Profile 约定**：在 Maven `logic-ide` 模块中新增 `spring-boot-2` 与 `spring-boot-3` profile，分别引入对应版本 BOM 与差异化依赖（如 `spring-boot-starter-validation` vs `jakarta.validation-api`）。测试命令通过 `-Pspring-boot-{x}` 切换依赖集。 + +## CI Pipeline 分阶段设计 +1. **Stage 0 – 初始化与版本检测** + - Checkout 代码、缓存 `.m2`、安装必要的 JDK。 + - 运行版本变更检测脚本，决定后续 Job 是否执行发布阶段。 + +2. **Stage 1 – 静态检查与快速回归** + - `mvn -pl logic-ide -am -DskipITs test` + - 自定义脚本检查公共 API 是否存在破坏性变更（可选）。 + +3. **Stage 2 – 兼容性测试矩阵** + - 使用 GitHub Actions Matrix 或 Jenkins 并行 Job： + ```yaml + strategy: + matrix: + boot-profile: [spring-boot-2, spring-boot-3] + java-version: [17] + steps: + - name: Run compatibility verify + run: mvn -pl logic-ide -am clean verify -P${{ matrix.boot-profile }} + ``` + - 可在 `spring-boot-3` 任务中追加迁移用例（如 Jakarta API 覆盖、Context 启动 Smoke Test）。 + +4. **Stage 3 – 集成 & 回归测试** + - 启动 `test-suite` 模块依赖示例，模拟业务系统嵌入逻辑。 + - 针对关键逻辑编排流程运行端到端测试，确保 `logic-runtime` + `logic-ide` 协同正常。 + - 如需与外部依赖（Redis、MySQL）联动，可通过 Docker 服务在流水线中启动。 + +5. **Stage 4 – 质量门禁** + - 覆盖率采集并上传至 SonarQube/Codecov。 + - 依赖漏洞扫描（`mvn org.owasp:dependency-check:check` 或 SCA 工具）。 + - 产物签名、SBOM 生成（CycloneDX Maven 插件）。 + - 若任一检测失败，阻断发布流程。 + +6. **Stage 5 – 发布与验证** + - 使用 `mvn -pl logic-ide -am -P deploy` 发布至 Maven 私服/Nexus。 + - 根据版本策略发布两套制品： + - `logic-ide-${version}-boot2.jar` + - `logic-ide-${version}-boot3.jar`（如采用分类器或 profile 区分）。 + - 自动创建 Git Tag 与 GitHub Release（附带 Release Note、兼容性说明、制品下载链接）。 + - 通知渠道（钉钉/企业微信/邮件）推送发布成功或失败信息。 + +## GitHub Actions 样例骨架 +```yaml +name: logic-ide-release + +on: + push: + branches: [main] + paths: + - 'pom.xml' + - 'logic-ide/**/pom.xml' + workflow_dispatch: + inputs: + targetVersion: + description: '手动发布版本号' + required: false + +jobs: + version-check: + runs-on: ubuntu-latest + outputs: + publish: ${{ steps.diff.outputs.version_changed }} + steps: + - uses: actions/checkout@v4 + - name: Detect version bump + id: diff + run: | + PREV_VERSION=$(git show HEAD^:pom.xml | mvn -q -N help:evaluate -Dexpression=project.version -DforceStdout) + CURR_VERSION=$(mvn -q -N help:evaluate -Dexpression=project.version -DforceStdout) + if [ "$PREV_VERSION" != "$CURR_VERSION" ]; then + echo "version_changed=true" >> "$GITHUB_OUTPUT" + else + echo "version_changed=false" >> "$GITHUB_OUTPUT" + fi + build-test: + needs: version-check + if: needs.version-check.outputs.publish == 'true' || github.event_name == 'workflow_dispatch' + runs-on: ubuntu-latest + strategy: + matrix: + boot-profile: [spring-boot-2, spring-boot-3] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-java@v3 + with: + distribution: temurin + java-version: '17' + - name: Cache Maven + uses: actions/cache@v3 + with: + path: ~/.m2/repository + key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} + - name: Verify ${{ matrix.boot-profile }} + run: mvn -pl logic-ide -am clean verify -P${{ matrix.boot-profile }} + release: + needs: build-test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Publish to Maven Repo + run: mvn -pl logic-ide -am deploy -Ppublish -s .github/maven-settings.xml + - name: Create Release + uses: softprops/action-gh-release@v1 + with: + tag_name: v${{ github.sha }} + name: logic-ide v${{ github.sha }} 发布 + body: '自动发布：兼容 Spring Boot 2 & 3' +``` +> 上述示例仅展示关键逻辑，实际落地时需拆分 settings、凭证管理与制品分类策略。 + +## 发布流程与角色职责 +1. **开发**：提交版本变更 PR，确保通过预检流水线。 +2. **Reviewer**：审核代码与版本变更合理性，合并至主干。 +3. **CI/CD 系统**：自动检测版本提升，执行兼容性验证、制品发布、发布记录生成。 +4. **运维/Release Owner**：监控流水线执行结果，如失败及时回滚或重新触发；如成功则更新外部公告。 + +## 版本管理与回滚策略 +- 采用语义化版本（Major.Minor.Patch）。 +- 流水线在发布前打 `pre-release` Tag，发布成功后升级为正式 Tag；失败则删除 `pre-release` Tag。 +- 引入 `mvn versions:revert` 快速回滚版本号；若制品已发布则通过 Maven Repo 废弃或 Block 该版本，并回滚代码 Tag。 + +## 安全与合规要求 +- 发布凭证使用 GitHub Encrypted Secrets 或 Jenkins Credentials，最小权限原则管理。 +- 所有制品附带 SBOM 与哈希校验值，保证可追溯性。 +- 引入开源依赖漏洞扫描，发现高危漏洞需阻断发布。 +- 流水线执行日志保存 180 天，支持审计追溯。 + +## 实施里程碑建议 +1. **阶段一**：引入双 profile 与本地脚本，确保在开发机器可以一键验证两个版本。 +2. **阶段二**：上线 PR 与版本检测流水线，完成自动化兼容性测试。 +3. **阶段三**：接入发布仓库、生成 Release Note、打通通知。 +4. **阶段四（优化）**：引入性能基准测试、Canary 发布、滚动回滚策略等高级能力。 + +--- + +通过上述 CI/CD 设计，`logic-ide` 能够在版本迭代时自动覆盖 Spring Boot 2 与 Spring Boot 3 的兼容性验证，并形成标准化的发布流水线，确保对外交付质量与发布效率。