第1章 构建性能指标采集与基准线建立

构建性能优化始于精确的度量。没有可靠的数据，任何优化决策都缺乏依据。本章定义三个核心性能维度——构建时长、CPU/内存消耗、I/O等待；介绍 Gradle 内置报告工具和第三方采集方案；并指导你建立可复用的项目性能基线。所有操作均以可复现的命令、配置和脚本呈现，方便你直接嵌入现有项目。

1.1 核心指标定义

构建性能监控围绕三个核心维度展开：构建时长、资源消耗（CPU/内存）和I/O等待。每个维度下又细分为若干可量化指标。

• 构建时长（Total Build Time）
  从 Gradle 进程启动到构建完成的总耗时，细分为配置阶段、任务执行阶段和最终化阶段。是衡量构建效率最直观的顶层指标。
• CPU 消耗（CPU Usage）
  构建进程中 CPU 的利用率，反映并行任务执行效率。通常用百分比和平均负载表示。过高（接近 100%）可能意味着 I/O 阻塞不足；过低（<30%）可能表示并行度配置不合理。
• 内存消耗（Memory Usage）
  Gradle Daemon 进程的堆内存使用情况，包括峰值堆内存、GC 频率和暂停时间。频繁的 Full GC 会显著拖慢构建。
• I/O 等待（I/O Wait）
  磁盘读写和网络请求造成的 CPU 等待时间占比。缓存命中率低、依赖解析频繁、大文件处理都会推高 I/O 等待。

1.2 Gradle 内置报告工具

Gradle 提供了三种无须额外插件的内置报告能力，覆盖从宏观耗时到微观缓存细节的各个层次。

• Build Scan（--scan）
  生成交互式 Web 报告，包含任务级耗时、缓存命中/未命中详情、依赖解析树、GC 活动及插件耗时。适合开发者和 CI 管理员快速定位瓶颈。
• Profile Report（--profile）
  输出 HTML 格式的性能分析报告，按配置、任务执行、最终化三个阶段展示耗时分布。适合离线分析和归档。
• Build Cache Stats（--build-cache-stats）
  在构建结束时打印本地/远程缓存的命中次数、未命中次数及缓存键详情。适合缓存优化场景。

# 生成 Build Scan（需要接受条款后自动上传至 scans.gradle.com）
./gradlew build --scan

# 生成 Profile Report（输出至 build/reports/profile/）
./gradlew build --profile

# 打印构建缓存统计
./gradlew build --build-cache-stats

1.3 第三方工具采集

当内置报告无法满足持续集成或精细化监控需求时，可引入第三方工具补充系统级和自定义指标。

// build.gradle
gradle.addBuildListener(new BuildListener() {
    void buildFinished(BuildResult result) {
        println "构建耗时: ${result.action} ${System.currentTimeMillis()}"
    }
})
gradle.addListener(new TaskExecutionListener() {
    void beforeExecute(Task task) { /* 记录开始时间 */ }
    void afterExecute(Task task, TaskState state) {
        /* 计算耗时并输出 JSON */
    }
})

1.4 建立项目基线

基线是项目在特定环境下的标准性能参考数据。建立基线的目的是为后续优化提供可对比的锚点，避免因单次波动做出错误判断。

1.4.1 采集策略

• 在一致的硬件与软件环境下执行（相同 CPU/内存/OS/JDK/Gradle 版本）。
• 连续执行 5 次 全量构建（clean build），取中位数作为基线值。
• 记录环境快照（内核参数、可用内存、磁盘类型、Gradle Daemon 状态）。

1.4.2 基线数据格式

{
  "baseline": {
    "project": "my-app",
    "environment": {
      "os": "Linux 5.15.0-86-generic",
      "cpu": "Intel(R) Xeon(R) Platinum 8375C @ 2.90GHz (16 vCPUs)",
      "memory": "32 GB",
      "jdk": "17.0.8+7",
      "gradle": "8.5"
    },
    "metrics": {
      "totalBuildTimeMs": 142300,
      "configurationTimeMs": 8500,
      "taskExecutionTimeMs": 128000,
      "finalizationTimeMs": 5800,
      "cpuUsagePercent": 72.4,
      "peakMemoryMb": 2560,
      "ioWaitPercent": 8.7
    },
    "collectedAt": "2025-03-20T06:30:00Z",
    "sampleSize": 5
  }
}

1.4.3 基线对比分析流程

下图为从“构建执行”到“基线存储与对比”的完整数据流，后续章节的优化工作均以此流程为基础。

1.5 实战：一键采集与基线建立

以下脚本整合了 Gradle 内置工具和系统监控命令，可在 CI 或本地一键完成指标采集并生成基线 JSON 文件。

#!/bin/bash
# baseline-collect.sh —— 构建性能基线采集脚本
# 用法: ./baseline-collect.sh [project-dir]

set -euo pipefail
PROJECT_DIR="${1:-.}"
BASELINE_FILE="${PROJECT_DIR}/build/baseline.json"
SAMPLE_COUNT=5

echo "=== 构建性能基线采集 ==="
echo "项目目录: ${PROJECT_DIR}"
echo "采样次数: ${SAMPLE_COUNT}"

# 环境快照
OS_INFO=$(uname -a | cut -d' ' -f1-3)
CPU_MODEL=$(lscpu | grep "Model name" | cut -d':' -f2 | xargs)
MEM_TOTAL=$(free -h | grep Mem | awk '{print $2}')
JDK_VERS=$(java -version 2>&1 | head -1)
GRADLE_VERS=$("${PROJECT_DIR}/gradlew" --version 2>/dev/null | grep "Gradle" | head -1)

# 多次采集，取中位数
TIMES=()
CPU_PCT=()
MEM_PEAK=()
IO_PCT=()

for i in $(seq 1 ${SAMPLE_COUNT}); do
    echo "--- 第 ${i}/${SAMPLE_COUNT} 次构建 ---"

    # 后台启动资源监控
    pidstat -u -r -p $$ 1 > /tmp/pidstat_${i}.log &
    PIDSTAT_PID=$!

    START_MS=$(date +%s%3N)
    "${PROJECT_DIR}/gradlew" clean build --no-daemon --scan --profile 2>/dev/null
    END_MS=$(date +%s%3N)
    DURATION=$(( END_MS - START_MS ))
    TIMES+=("${DURATION}")

    kill ${PIDSTAT_PID} 2>/dev/null || true
    sleep 2  # 等待进程完全退出，避免资源采样重叠
done

# 从 pidstat 日志中提取 CPU 和内存峰值（简化处理：取平均值）
# 生产环境建议使用更 robust 的解析方式
CPU_SUM=0
MEM_SUM=0
for f in /tmp/pidstat_*.log; do
    [ -f "$f" ] || continue
    # 仅做示例，实际应解析 %CPU 和 RSS 列
    AVG_CPU=$(awk 'NR>3 && $NF!="" {sum+=$NF; cnt++} END {if(cnt>0) printf "%.1f", sum/cnt}' "$f")
    CPU_SUM=$(echo "${CPU_SUM} + ${AVG_CPU}" | bc -l 2>/dev/null || echo 0)
done
CPU_AVG=$(echo "scale=1; ${CPU_SUM} / ${SAMPLE_COUNT}" | bc -l 2>/dev/null || echo "0")

# 排序取中位数
IFS=$'\n' SORTED_TIMES=($(sort -n <<<"${TIMES[*]}"))
MEDIAN_IDX=$(( (SAMPLE_COUNT - 1) / 2 ))
MEDIAN_TIME=${SORTED_TIMES[${MEDIAN_IDX}]}

# 写入基线文件
cat > "${BASELINE_FILE}" << EOF
{
  "baseline": {
    "project": "$(basename ${PROJECT_DIR})",
    "environment": {
      "os": "${OS_INFO}",
      "cpu": "${CPU_MODEL}",
      "memory": "${MEM_TOTAL}",
      "jdk": "${JDK_VERS}",
      "gradle": "${GRADLE_VERS}"
    },
    "metrics": {
      "totalBuildTimeMs": ${MEDIAN_TIME},
      "cpuUsagePercent": ${CPU_AVG},
      "peakMemoryMb": 0,
      "ioWaitPercent": 0.0
    },
    "collectedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
    "sampleSize": ${SAMPLE_COUNT}
  }
}
EOF

echo "=== 基线已写入 ${BASELINE_FILE} ==="

1.6 常见错误与优化建议