代码分支策略：Trunk-Based Development实践

# .github/workflows/ci.yml - Trunk-Based Development 的 CI 流水线配置
name: Trunk CI Pipeline
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
# 关键：并发控制，同一 PR 只保留最新的运行
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true
 
jobs:
  # 第一阶段：快速检查（< 3 分钟）
  quick-checks:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Lint
        run: npm run lint
      - name: Type check
        run: npm run typecheck
      - name: Unit tests
        run: npm run test:unit -- --coverage
      - name: Upload coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/
 
  # 第二阶段：集成测试（< 7 分钟）
  integration-tests:
    needs: quick-checks
    runs-on: ubuntu-latest
    timeout-minutes: 10
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_DB: testdb
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - name: Run integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/testdb
 
  # 第三阶段：构建验证（< 5 分钟）
  build-verification:
    needs: quick-checks
    runs-on: ubuntu-latest
    timeout-minutes: 8
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - name: Build production bundle
        run: npm run build
      - name: Smoke test
        run: |
          # 启动应用并验证健康检查
          npm run start &
          sleep 5
          curl -f http://localhost:3000/health || exit 1
          curl -f http://localhost:3000/api/version || exit 1
 
  # 合并检查门禁
  ci-passed:
    needs: [quick-checks, integration-tests, build-verification]
    runs-on: ubuntu-latest
    steps:
      - run: echo "All CI checks passed - safe to merge"

#!/bin/bash
# configure-branch-protection.sh
# 为 Trunk-Based Development 配置 GitHub 分支保护规则
 
REPO_OWNER="your-org"
REPO_NAME="your-repo"
GITHUB_TOKEN="${GITHUB_TOKEN:?请设置 GITHUB_TOKEN 环境变量}"
API_BASE="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}"
 
echo "=== 配置 Trunk-Based Development 分支保护规则 ==="
 
# 配置 main 分支保护规则
curl -s -X PUT \
  "${API_BASE}/branches/main/protection" \
  -H "Authorization: token ${GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github.v3+json" \
  -d '{
    "required_status_checks": {
      "strict": true,
      "contexts": [
        "quick-checks",
        "integration-tests",
        "build-verification"
      ]
    },
    "required_pull_request_reviews": {
      "dismiss_stale_reviews": true,
      "require_code_owner_reviews": true,
      "required_approving_review_count": 1,
      "require_last_push_approval": true
    },
    "restrictions": null,
    "enforce_admins": true,
    "required_linear_history": true,
    "allow_force_pushes": false,
    "allow_deletions": false,
    "block_creations": false,
    "required_conversation_resolution": true
  }' | jq '.'
 
echo ""
echo "=== 配置分支命名规则（GitHub Rulesets）==="
 
# 创建 Ruleset 限制功能分支命名和生命周期
curl -s -X POST \
  "${API_BASE}/rulesets" \
  -H "Authorization: token ${GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github.v3+json" \
  -d '{
    "name": "trunk-based-development-rules",
    "target": "branch",
    "enforcement": "active",
    "conditions": {
      "ref_name": {
        "include": ["refs/heads/feature/*", "refs/heads/bugfix/*"],
        "exclude": []
      }
    },
    "rules": [
      {
        "type": "creation"
      },
      {
        "type": "deletion"
      },
      {
        "type": "non_fast_forward"
      },
      {
        "type": "pull_request",
        "parameters": {
          "require_code_owner_review": true,
          "require_last_push_approval": true,
          "required_approving_review_count": 1,
          "dismiss_stale_reviews_on_push": true,
          "required_merge_method": "squash"
        }
      }
    ],
    "bypass_actors": [
      {
        "actor_id": 1,
        "actor_type": "OrganizationAdmin",
        "bypass_mode": "pull_request"
      }
    ]
  }' | jq '.'
 
echo ""
echo "分支保护规则配置完成！"
echo "- main 分支：要求 PR + CI 通过 + 1 人审批 + 线性历史"
echo "- 功能分支：强制 squash merge + 命名规范"

// feature-flags.ts - 基于 LaunchDarkly 风格的 Feature Flag 实现
// 适配 Trunk-Based Development 场景
 
interface FeatureFlagConfig {
  key: string;
  enabled: boolean;
  // 基于规则的评估
  rules?: FlagRule[];
  // 渐进式发布百分比
  rolloutPercentage?: number;
}
 
interface FlagRule {
  attribute: string;
  operator: 'eq' | 'in' | 'gt' | 'lt' | 'contains';
  values: string[];
}
 
interface UserContext {
  userId: string;
  attributes: Record<string, string | number | boolean>;
}
 
class FeatureFlagService {
  private flags: Map<string, FeatureFlagConfig> = new Map();
  private static instance: FeatureFlagService;
 
  private constructor() {
    this.initializeFlags();
  }
 
  static getInstance(): FeatureFlagService {
    if (!FeatureFlagService.instance) {
      FeatureFlagService.instance = new FeatureFlagService();
    }
    return FeatureFlagService.instance;
  }
 
  private initializeFlags(): void {
    // 从配置中心加载 Flag 定义
    // 生产环境应从远程配置服务（如 LaunchDarkly、Unleash）获取
    const defaultFlags: FeatureFlagConfig[] = [
      {
        key: 'new-checkout-flow',
        enabled: true,
        rolloutPercentage: 10, // 10% 用户可见
        rules: [
          { attribute: 'betaTester', operator: 'eq', values: ['true'] }
        ]
      },
      {
        key: 'payment-redesign',
        enabled: false, // 开发中，主干已合入但未开启
      },
      {
        key: 'search-algorithm-v2',
        enabled: true,
        rolloutPercentage: 50,
      }
    ];
 
    defaultFlags.forEach(flag => this.flags.set(flag.key, flag));
  }
 
  /**
   * 评估 Feature Flag
   * Trunk-Based Development 中的核心方法：
   * - 开发中功能：enabled=false，代码已合入主干但不影响用户
   * - 渐进式发布：rolloutPercentage 控制灰度比例
   * - 规则匹配：支持基于用户属性的精准投放
   */
  isEnabled(flagKey: string, context?: UserContext): boolean {
    const flag = this.flags.get(flagKey);
    if (!flag) {
      console.warn(`Feature flag "${flagKey}" not found, defaulting to false`);
      return false; // 未知 Flag 默认关闭，保证安全
    }
 
    if (!flag.enabled) {
      return false;
    }
 
    // 规则优先：如果用户匹配规则，直接放行
    if (context && flag.rules && flag.rules.length > 0) {
      const matchesRule = flag.rules.some(rule => {
        const attrValue = context.attributes[rule.attribute];
        if (attrValue === undefined) return false;
 
        switch (rule.operator) {
          case 'eq': return rule.values.includes(String(attrValue));
          case 'in': return rule.values.includes(String(attrValue));
          case 'gt': return Number(attrValue) > Number(rule.values[0]);
          case 'lt': return Number(attrValue) < Number(rule.values[0]);
          case 'contains': return rule.values.some(v => String(attrValue).includes(v));
          default: return false;
        }
      });
      if (matchesRule) return true;
    }
 
    // 渐进式发布：基于用户 ID 的确定性哈希
    if (flag.rolloutPercentage !== undefined && context) {
      const hash = this.deterministicHash(context.userId, flagKey);
      return (hash % 100) < flag.rolloutPercentage;
    }
 
    return flag.enabled;
  }
 
  /**
   * 确定性哈希：同一用户对同一 Flag 的评估结果始终一致
   * 这确保了渐进式发布中用户体验的连续性
   */
  private deterministicHash(userId: string, flagKey: string): number {
    const str = `${userId}:${flagKey}`;
    let hash = 0;
    for (let i = 0; i < str.length; i++) {
      const char = str.charCodeAt(i);
      hash = ((hash << 5) - hash) + char;
      hash = hash & hash; // Convert to 32bit integer
    }
    return Math.abs(hash);
  }
 
  /**
   * 动态更新 Flag（用于运维操作，无需重新部署）
   */
  updateFlag(flagKey: string, config: Partial<FeatureFlagConfig>): void {
    const existing = this.flags.get(flagKey);
    if (existing) {
      this.flags.set(flagKey, { ...existing, ...config });
      console.log(`Flag "${flagKey}" updated:`, config);
    }
  }
 
  /**
   * 清理已完成的 Feature Flag
   * 重要：Flag 完成使命后必须清理，避免技术债务积累
   */
  removeFlag(flagKey: string): void {
    this.flags.delete(flagKey);
    console.log(`Flag "${flagKey}" removed - feature is now permanent`);
  }
}
 
// 使用示例：Trunk-Based Development 中的功能开关
const flags = FeatureFlagService.getInstance();
 
// 场景一：新功能开发中，代码已合入 main 但 Flag 关闭
// 用户不会看到新功能，但代码已经在主干上被持续集成和测试
function getCheckoutPage(user: UserContext) {
  if (flags.isEnabled('new-checkout-flow', user)) {
    return renderNewCheckout(user);
  }
  return renderLegacyCheckout(user);
}
 
// 场景二：渐进式发布，逐步扩大用户范围
// 从 10% → 25% → 50% → 100%，每步观察指标后再推进
function getSearchResults(query: string, user: UserContext) {
  if (flags.isEnabled('search-algorithm-v2', user)) {
    return searchV2(query, user);
  }
  return searchV1(query, user);
}
 
// 导出供测试使用
export { FeatureFlagService, UserContext, FeatureFlagConfig };

// Branch by Abstraction 示例：替换通知系统
// 步骤 1：定义抽象层
public interface NotificationService {
    void send(String userId, String message);
    boolean isAvailable();
}
 
// 步骤 2：旧实现适配抽象层
public class LegacyEmailNotificationService implements NotificationService {
    private final SmtpClient smtpClient;
 
    @Override
    public void send(String userId, String message) {
        String email = userRepository.getEmail(userId);
        smtpClient.send(email, "Notification", message);
    }
 
    @Override
    public boolean isAvailable() {
        return smtpClient.isHealthy();
    }
}
 
// 步骤 3：新实现（可独立开发，通过 Feature Flag 控制）
public class PushNotificationService implements NotificationService {
    private final FcmClient fcmClient;
 
    @Override
    public void send(String userId, String message) {
        String deviceToken = userRepository.getDeviceToken(userId);
        fcmClient.push(deviceToken, message);
    }
 
    @Override
    public boolean isAvailable() {
        return fcmClient.isHealthy();
    }
}
 
// 步骤 3-4：路由层（渐进式迁移）
public class RoutingNotificationService implements NotificationService {
    private final NotificationService legacyService;
    private final NotificationService newService;
    private final FeatureFlagService flagService;
 
    @Override
    public void send(String userId, String message) {
        if (flagService.isEnabled("push-notifications", userId)) {
            try {
                newService.send(userId, message);
            } catch (NotificationException e) {
                // 降级到旧实现
                legacyService.send(userId, message);
            }
        } else {
            legacyService.send(userId, message);
        }
    }
 
    @Override
    public boolean isAvailable() {
        return legacyService.isAvailable() || newService.isAvailable();
    }
}

# Bazel BUILD 文件示例 - Monorepo 中的模块化构建
# 通过精确的依赖声明实现增量构建
 
load("@rules_nodejs//:index.bzl", "nodejs_binary", "npm_package")
 
# 支付服务模块 - 独立构建和测试
nodejs_binary(
    name = "payment-service",
    entry_point = "src/index.ts",
    deps = [
        "//shared:core-lib",
        "//shared:database-client",
        "@npm//express",
        "@npm//stripe",
    ],
)
 
# 只有 payment-service 的依赖变更时才会重新构建和测试
npm_package(
    name = "payment-service-package",
    srcs = glob(["src/**"]),
    deps = [":payment-service"],
)
 
# 测试目标 - 精确声明测试依赖
nodejs_test(
    name = "payment-service-test",
    srcs = glob(["test/**"]),
    deps = [
        ":payment-service",
        "@npm//jest",
        "@npm//supertest",
    ],
)

#!/bin/bash
# measure-tbd-metrics.sh
# 采集 Trunk-Based Development 关键度量指标
 
REPO_PATH="${1:-.}"
DAYS="${2:-30}"
 
echo "=== Trunk-Based Development 度量报告（最近 ${DAYS} 天）==="
echo ""
 
# 1. 分支存活时间统计
echo "--- 1. 分支存活时间 ---"
echo "已合并分支的平均存活时间："
git -C "$REPO_PATH" log --merges --since="${DAYS} days ago" \
  --format="%at %s" | \
  awk '{
    # 提取合并时间
    merge_time = $1
    # 提取分支名（假设格式为 "Merge pull request #N from org/branch-name"）
    for (i=3; i<=NF; i++) {
      if ($i ~ /^from/) {
        branch = $(i+1)
        break
      }
    }
  } END {
    print "  总合并数: NR"
  }'
 
# 2. 每人每日提交频率
echo ""
echo "--- 2. 每人每日提交频率 ---"
git -C "$REPO_PATH" log --since="${DAYS} days ago" \
  --format="%ae %ad" --date=short | \
  sort | uniq -c | \
  awk '{
    author = $2
    date = $3
    commits = $1
    total[author] += commits
    days[author]++
  } END {
    for (a in total) {
      avg = total[a] / days[a]
      printf "  %-30s 总提交: %3d  天数: %2d  日均: %.1f\n", a, total[a], days[a], avg
    }
  }' | sort -t: -k3 -rn
 
# 3. 主干健康度
echo ""
echo "--- 3. 主干健康度 ---"
# 假设 CI 状态通过 GitHub API 可获取
if [ -n "$GITHUB_TOKEN" ]; then
  REPO_OWNER=$(git -C "$REPO_PATH" remote get-url origin | sed -E 's|.*[:/]([^/]+)/([^/.]+).*|\1|')
  REPO_NAME=$(git -C "$REPO_PATH" remote get-url origin | sed -E 's|.*[:/]([^/]+)/([^/.]+).*|\2|')
 
  TOTAL_RUNS=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
    "https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/actions/runs?branch=main&per_page=100" | \
    jq '.total_count')
 
  SUCCESS_RUNS=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
    "https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/actions/runs?branch=main&status=success&per_page=1" | \
    jq '.total_count')
 
  if [ -n "$TOTAL_RUNS" ] && [ "$TOTAL_RUNS" -gt 0 ]; then
    HEALTH=$(echo "scale=2; $SUCCESS_RUNS * 100 / $TOTAL_RUNS" | bc)
    echo "  总构建数: $TOTAL_RUNS"
    echo "  成功构建数: $SUCCESS_RUNS"
    echo "  主干健康度: ${HEALTH}%"
  fi
else
  echo "  设置 GITHUB_TOKEN 环境变量以获取 CI 健康度数据"
fi
 
# 4. 变更规模统计
echo ""
echo "--- 4. 变更规模统计 ---"
git -C "$REPO_PATH" log --since="${DAYS} days ago" --format="" --numstat | \
  awk 'NF==3 {
    added += $1
    deleted += $2
    files++
  } END {
    if (files > 0) {
      printf "  总变更文件数: %d\n", files
      printf "  总新增行数: %d\n", added
      printf "  总删除行数: %d\n", deleted
      printf "  平均每次提交变更行数: %.0f\n", (added + deleted) / files
    }
  }'
 
echo ""
echo "=== 报告结束 ==="