2. 搭建 Choreographer 监控环境：Android Studio 配置、minSdkVersion 要求、依赖引入

Choreographer 是 Android 系统原生 android.view 包下的帧调度器，从 API 16（Android 4.1 Jelly Bean）开始提供。环境搭建的核心目标是在项目中正确引用 Choreographer API，并保证最低设备覆盖范围。本章按照实际项目接入流程，依次完成 Android Studio 项目参数配置、Gradle 依赖声明、以及最小 SDK 版本决策。

2.1 项目创建与基础配置

使用 Android Studio（建议版本 ≥ 4.2）新建一个空 Activity 项目或集成到现有项目中。关键配置集中于 app/build.gradle，以下为推荐起始参数：

android {
    compileSdk 34          // 至少 34，兼容最新 FrameMetrics API
    defaultConfig {
        applicationId "com.example.choreomonitor"
        minSdk 21           // 见 2.2 节 minSdkVersion 决策
        targetSdk 34
        versionCode 1
        versionName "1.0"
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
}

2.2 minSdkVersion 决策

Choreographer 核心回调 postFrameCallback 从 API 16 即支持，但为了获得更精准的掉帧定位能力，需要灵活选择支持 API 级别。决策流程图如下：

2.3 依赖引入

Choreographer 本身是 Android Framework 内置 API，无需添加任何外部依赖。但为了方便调试和扩展，可选择性引入以下官方库：

在 app/build.gradle 的 dependencies 块中按需添加：

dependencies {
    // Choreographer 不需要额外声明

    // 可选：AndroidX 核心库（提供 FrameMetricsAggregator）
    implementation "androidx.core:core:1.12.0"

    // 可选：协程支持
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0"
}

2.4 初始化入场代码示例

完成上述配置后，可在 MainActivity.onCreate() 中插入最简单的帧回调验证环境是否就绪：

// MainActivity.java
import android.view.Choreographer;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        Choreographer choreographer = Choreographer.getInstance();
        choreographer.postFrameCallback(new Choreographer.FrameCallback() {
            @Override
            public void doFrame(long frameTimeNanos) {
                // 第一帧回调到达，环境搭建成功
                Log.d("ChoreoEnv", "Frame received at " + frameTimeNanos);
                // 注意：只有不停重复注册才能持续监控，后续章节将封装
            }
        });
    }
}

2.5 常见错误与排查

• 编译错误：Cannot resolve symbol 'Choreographer' → 检查 compileSdk 是否 ≥ 16，且项目已同步 Gradle。
• 运行时异常：NoSuchMethodError（如 postFrameCallback 在低版本不存在） → 确认 minSdk ≥ 16。
• 未收到回调：Choreographer 只在 UI 线程工作，请确保在 UI 线程调用 postFrameCallback。

2.6 调试验证方法

运行应用并在 Logcat 中过滤 ChoreoEnv，如果每 16~17ms 输出一条日志，说明环境搭建成功。也可在 doFrame 中添加 android.os.Debug.startMethodTracing() 进行验证。