基于Git Flow与Trunk-Based的分支策略、Code Review与CI/CD流水线配置实践

# scripts/check-branch-name.sh
#!/usr/bin/env bash
set -euo pipefail

BRANCH="${GITHUB_HEAD_REF:-$(git rev-parse --abbrev-ref HEAD)}"
# 允许 main 与 release tag 触发
if [[ "$BRANCH" == "main" ]]; then
  echo "branch ok: $BRANCH"; exit 0
fi

PATTERN='^(feat|fix|chore|refactor)/[A-Z]+-[0-9]+-[a-z0-9-]{3,40}$'
if [[ ! "$BRANCH" =~ $PATTERN ]]; then
  echo "::error::分支名不合规: $BRANCH"
  echo "期望格式: feat/PROJ-123-add-order-export"
  exit 1
fi
echo "branch ok: $BRANCH"

{
  "name": "protect-main",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["refs/heads/main"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 1,
        "dismiss_stale_reviews_on_push": true,
        "require_code_owner_review": true,
        "require_last_push_approval": true
      }
    },
    { "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": true,
        "required_status_checks": [
          { "context": "build-and-test" },
          { "context": "sonarqube-quality-gate" },
          { "context": "branch-name-check" }
        ]
      }
    }
  ]
}

## 变更说明


Closes PROJ-

## 变更类型
- [ ] feat 新功能
- [ ] fix 缺陷修复
- [ ] refactor 重构（无行为变更）
- [ ] chore 构建/依赖/配置

## 自测清单
- [ ] 本地 `mvn -q verify` 通过
- [ ] 新增/修改逻辑有对应单测，覆盖率不低于70%
- [ ] 涉及接口变更已更新 OpenAPI 文档
- [ ] 无敏感信息硬编码（密钥、内网地址）

## 风险与回滚

name: ci

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

env:
  MAVEN_OPTS: "-Xmx1g -XX:+UseG1GC"
  NODE_VERSION: "20.11.1"

jobs:
  branch-name-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - run: bash scripts/check-branch-name.sh

  build-and-test:
    runs-on: ubuntu-22.04
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # Sonar 需要完整历史做 blame
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"
          cache: maven
      - name: Backend verify
        run: mvn -B -q verify -Dspring.profiles.active=test
      - name: Upload surefire reports
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: surefire-reports
          path: target/surefire-reports/
          retention-days: 7

  frontend:
    runs-on: ubuntu-22.04
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9.1.0
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint && pnpm test -- --run
      - run: pnpm build

  sonarqube-quality-gate:
    needs: [build-and-test]
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"
          cache: maven
      - name: Sonar scan
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: |
          mvn -B sonar:sonar \
            -Dsonar.projectKey=saas-backend \
            -Dsonar.qualitygate.wait=true \
            -Dsonar.qualitygate.timeout=300 \
            -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

stages: [validate, test, quality, build]

variables:
  MAVEN_OPTS: "-Xmx1g"
  GIT_DEPTH: "50"

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

validate-branch:
  stage: validate
  image: alpine/git:2.43.0
  script:
    - apk add --no-cache bash
    - bash scripts/check-branch-name.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

unit-test:
  stage: test
  image: maven:3.9.6-eclipse-temurin-17
  cache:
    key: "m2-$CI_COMMIT_REF_SLUG"
    paths: [.m2/repository]
  script:
    - mvn -B -q verify -Dspring.profiles.active=test
  artifacts:
    when: on_failure
    paths: [target/surefire-reports/]
    expire_in: 1 week

quality-gate:
  stage: quality
  image: maven:3.9.6-eclipse-temurin-17
  needs: [unit-test]
  script:
    - mvn -B sonar:sonar -Dsonar.qualitygate.wait=true
  allow_failure: false