Service：后台服务机制

// Service 的继承链（简化）
// Context → ContextWrapper → ContextThemeWrapper? 不！
// Service 直接继承 ContextWrapper，没有 Theme 相关能力
open class Service : ContextWrapper(), ComponentCallbacks2 {
    // 没有 Window、没有 DecorView、没有 setContentView()
    // 只有生命周期回调和 Binder 机制
}
 
// Activity 的继承链（简化）
// Context → ContextWrapper → ContextThemeWrapper → Activity
open class Activity : ContextThemeWrapper(), /* 多个接口 */ {
    // 拥有 PhoneWindow、DecorView、完整的 UI 体系
    private var mWindow: Window? = null  // PhoneWindow 实例
    // setContentView() 实际上是委托给 mWindow 来处理
}

// ActivityThread.main() —— 每个 Android App 进程的真正入口点
public static void main(String[] args) {
    // 1. 准备主线程的 Looper（消息循环器）
    //    这一步会创建 MessageQueue（消息队列）
    Looper.prepareMainLooper();
 
    // 2. 创建 ActivityThread 实例
    //    ActivityThread 并不是一个 Thread，而是主线程的"管家"
    ActivityThread thread = new ActivityThread();
 
    // 3. 将当前进程"附着"到 AMS
    //    通过 Binder 向 AMS 注册，告诉系统"我准备好了"
    thread.attach(false, startSeq);
 
    // 4. 获取主线程的 Handler（消息处理器）
    //    这个 Handler 就是著名的 "H"（ActivityThread 的内部类）
    if (sMainThreadHandler == null) {
        sMainThreadHandler = thread.getHandler();
    }
 
    // 5. 启动消息循环 —— 这是一个无限循环！
    //    主线程从此刻开始，就不断地从 MessageQueue 中取消息、处理消息
    //    这个循环永远不会主动退出（除非进程被杀死）
    Looper.loop();
 
    // 如果执行到这里，说明主线程的消息循环异常退出了
    throw new RuntimeException("Main thread loop unexpectedly exited");
}

// MyService.kt —— 验证 Service 运行线程的示例
class MyService : Service() {
 
    // onCreate() 在 Service 首次创建时调用
    override fun onCreate() {
        super.onCreate()
        // 打印当前线程信息
        // 你会发现输出的线程名是 "main"，线程 ID 与 UI 线程相同
        Log.d("ServiceThread", "onCreate - Thread: ${Thread.currentThread().name}")
        // 输出示例: onCreate - Thread: main
 
        // 获取主线程的 Looper 并与当前线程的 Looper 比较
        // 如果相等，说明当前确实在主线程上执行
        val isMainThread = Looper.myLooper() == Looper.getMainLooper()
        Log.d("ServiceThread", "Is Main Thread: $isMainThread")
        // 输出: Is Main Thread: true
    }
 
    // onStartCommand() 每次 startService() 调用时都会触发
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // 同样在主线程上执行
        Log.d("ServiceThread", "onStartCommand - Thread: ${Thread.currentThread().name}")
        // 输出: onStartCommand - Thread: main
 
        // ⚠️ 危险操作！如果在这里执行耗时任务，会阻塞主线程！
        // 例如：网络请求、大文件读写、复杂计算等
        // Thread.sleep(30000) // 千万不要这样做！会导致 ANR！
 
        // 正确做法：将耗时任务放到工作线程中
        Thread {
            // 这里才是后台线程
            Log.d("ServiceThread", "Worker - Thread: ${Thread.currentThread().name}")
            // 输出: Worker - Thread: Thread-2 (或其他非 main 的线程名)
            performHeavyWork()
        }.start()
 
        // 返回值决定了 Service 被系统杀死后的重启策略
        // START_STICKY: 系统会尝试重新创建 Service
        return START_STICKY
    }
 
    // onBind() 当有客户端通过 bindService() 绑定时调用
    override fun onBind(intent: Intent?): IBinder? {
        // 也在主线程上执行
        Log.d("ServiceThread", "onBind - Thread: ${Thread.currentThread().name}")
        // 输出: onBind - Thread: main
        return null
    }
 
    // 模拟耗时操作（应在工作线程中调用）
    private fun performHeavyWork() {
        // 模拟网络请求或数据库操作
        Thread.sleep(5000)
        Log.d("ServiceThread", "Heavy work done on: ${Thread.currentThread().name}")
    }
}

// ActiveServices.java —— AMS 中管理 Service 的核心类
// bumpServiceExecutingLocked() 方法：启动 ANR 定时器
private final void bumpServiceExecutingLocked(ServiceRecord r, 
        boolean fg, String why) {
    // ... 省略部分逻辑 ...
 
    // 如果该 Service 之前没有正在执行的操作，则需要设置超时
    if (r.executeNesting == 0) {
        // 标记该 Service 有正在执行的操作
        r.executeFg = fg;
 
        // 将该 ServiceRecord 加入"正在执行"列表
        // 这个列表就是 AMS 监控 ANR 的"黑名单"
        mDestroyingServices.add(r);
    }
 
    // 增加嵌套计数（一个 Service 可能同时有多个待执行操作）
    r.executeNesting++;
 
    // 更新执行开始时间（用于后续判断是否超时）
    r.executingStart = SystemClock.uptimeMillis();
 
    // ⚡ 关键！发送延迟消息 —— 这就是"定时炸弹"
    // fg 为 true 时使用 SERVICE_TIMEOUT（20秒）
    // fg 为 false 时使用 SERVICE_BACKGROUND_TIMEOUT（200秒）
    scheduleServiceTimeoutLocked(r.app);
}
 
// scheduleServiceTimeoutLocked() —— 实际埋炸弹的方法
void scheduleServiceTimeoutLocked(ProcessRecord proc) {
    if (proc.executingServices.size() == 0 || proc.thread == null) {
        return; // 没有正在执行的 Service，无需设置超时
    }
 
    // 获取 AMS 主线程的 Handler
    Message msg = mAm.mHandler.obtainMessage(
            ActivityManagerService.SERVICE_TIMEOUT_MSG);
    msg.obj = proc; // 消息携带目标进程信息
 
    // 根据前台/后台决定超时时长
    // 前台: 20秒, 后台: 200秒
    final long timeout = proc.execServicesFg
            ? SERVICE_TIMEOUT   // 20 * 1000
            : SERVICE_BACKGROUND_TIMEOUT; // 200 * 1000
 
    // 发送延迟消息 —— 炸弹已埋好，倒计时开始！
    mAm.mHandler.sendMessageDelayed(msg, timeout);
}

// ActiveServices.java
// serviceDoneExecutingLocked() —— Service 回调完成后的清理
private void serviceDoneExecutingLocked(ServiceRecord r, 
        boolean inDestroying, boolean finishing) {
    // 减少嵌套计数
    r.executeNesting--;
 
    if (r.executeNesting <= 0) {
        // 所有待执行操作都完成了
        if (r.app != null) {
            // 从"正在执行"列表中移除
            r.app.executingServices.remove(r);
 
            // 如果该进程没有其他正在执行的 Service
            if (r.app.executingServices.size() == 0) {
                // ✅ 关键！移除延迟消息 —— 拆除定时炸弹！
                mAm.mHandler.removeMessages(
                    ActivityManagerService.SERVICE_TIMEOUT_MSG, 
                    r.app);
            }
        }
    }
}

// ActivityManagerService.java
// MainHandler.handleMessage() —— AMS 主线程 Handler
case SERVICE_TIMEOUT_MSG: {
    // 定时炸弹爆炸了！
    // 调用 ActiveServices 的超时处理方法
    mServices.serviceTimeout((ProcessRecord) msg.obj);
    break;
}
 
// ActiveServices.java
// serviceTimeout() —— ANR 的最终触发点
void serviceTimeout(ProcessRecord proc) {
    // 获取当前时间
    final long now = SystemClock.uptimeMillis();
 
    // 计算超时阈值
    final long maxTime = now - 
        (proc.execServicesFg 
            ? SERVICE_TIMEOUT 
            : SERVICE_BACKGROUND_TIMEOUT);
 
    // 遍历该进程所有正在执行的 Service
    // 找出执行时间最长的那个
    ServiceRecord timeout = null;
    long nextTime = 0;
    for (int i = proc.executingServices.size() - 1; i >= 0; i--) {
        ServiceRecord sr = proc.executingServices.valueAt(i);
        // 如果该 Service 的执行开始时间早于阈值，说明超时了
        if (sr.executingStart < maxTime) {
            timeout = sr;
            break;
        }
    }
 
    if (timeout != null) {
        // 💥 确认超时，触发 ANR！
        // 这会弹出 ANR 对话框、dump 线程堆栈、记录日志
        mAm.mAnrHelper.appNotResponding(
            proc, "executing service " + timeout.shortInstanceName);
    }
}

// ❌ 错误示范：在 Service 回调中直接执行耗时操作
class BadService : Service() {
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // ❌ 直接在主线程执行网络请求
        // 这会阻塞主线程，如果超过 20秒（前台）或 200秒（后台），触发 ANR
        val url = URL("https://api.example.com/large-data")
        val connection = url.openConnection() as HttpURLConnection // 主线程阻塞！
        val data = connection.inputStream.bufferedReader().readText() // 持续阻塞！
        processData(data) // 还在主线程上处理数据！
 
        return START_STICKY
    }
 
    override fun onBind(intent: Intent?): IBinder? = null
 
    private fun processData(data: String) { /* ... */ }
}

// ✅ 正确示范：将耗时操作移到工作线程
class GoodService : Service() {
 
    // 使用 Kotlin 协程作用域管理后台任务的生命周期
    // SupervisorJob 确保一个子协程失败不会取消其他子协程
    // Dispatchers.IO 指定在 IO 线程池上执行
    private val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // ✅ 在 IO 线程上启动协程执行耗时操作
        // onStartCommand 本身立即返回，不阻塞主线程
        serviceScope.launch {
            try {
                // 网络请求在 IO 线程上执行，不会阻塞主线程
                val data = fetchDataFromNetwork()
                // 数据处理也在 IO 线程上
                processData(data)
            } catch (e: Exception) {
                // 异常处理
                Log.e("GoodService", "Task failed", e)
            } finally {
                // 任务完成后，停止 Service 释放资源
                // stopSelf(startId) 确保只有最后一个请求完成时才真正停止
                stopSelf(startId)
            }
        }
 
        // 立即返回，主线程畅通无阻
        // START_REDELIVER_INTENT: 如果 Service 被杀，系统会用最后一个 Intent 重启它
        return START_REDELIVER_INTENT
    }
 
    override fun onDestroy() {
        super.onDestroy()
        // ✅ Service 销毁时取消所有协程，防止内存泄漏
        serviceScope.cancel()
    }
 
    override fun onBind(intent: Intent?): IBinder? = null
 
    // 挂起函数：在协程中执行网络请求
    private suspend fun fetchDataFromNetwork(): String {
        // withContext(Dispatchers.IO) 确保在 IO 线程池执行
        return withContext(Dispatchers.IO) {
            val url = URL("https://api.example.com/large-data")
            val connection = url.openConnection() as HttpURLConnection
            connection.inputStream.bufferedReader().readText()
        }
    }
 
    private fun processData(data: String) { /* 数据处理逻辑 */ }
}

// traces.txt 示例片段（简化）
"main" prio=5 tid=1 Native
  | group="main" sCount=1 dsCount=0 flags=1 obj=0x72a01e18 self=0xb4000078
  | sysTid=12345 nice=-10 cgrp=default sched=0/0 handle=0x7890abcd
  | state=S schedstat=( 12345678 87654321 999 ) utm=100 stm=50 core=2 HZ=100
  | stack=0x7fc0000000-0x7fc0002000 stackSize=8192KB
  at java.net.SocketInputStream.socketRead0(Native Method)        // ← 阻塞在这里！
  at java.net.SocketInputStream.socketRead(SocketInputStream.java:116)
  at java.net.SocketInputStream.read(SocketInputStream.java:171)
  at java.io.BufferedInputStream.fill(BufferedInputStream.java:246)
  at java.io.BufferedInputStream.read(BufferedInputStream.java:265)
  at com.example.BadService.onStartCommand(BadService.kt:15)      // ← 你的代码
  at android.app.ActivityThread.handleServiceArgs(ActivityThread.java:4456)
  at android.app.ActivityThread.access$2000(ActivityThread.java:237)
  at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2050)
  at android.os.Handler.dispatchMessage(Handler.java:106)
  at android.os.Looper.loop(Looper.java:223)                      // ← 主线程消息循环
  at android.app.ActivityThread.main(ActivityThread.java:7656)     // ← 主线程入口

// 定义一个用于后台数据同步的 Started Service
class DataSyncService : Service() {
 
    // onCreate 只在 Service 首次创建时调用一次
    // 适合做一次性的初始化工作，比如创建线程池、初始化数据库连接
    override fun onCreate() {
        super.onCreate()
        // 在这里初始化资源，例如线程池
        Log.d("DataSyncService", "Service 实例被创建，执行一次性初始化")
    }
 
    // 每次通过 startService() 发起请求时都会回调此方法
    // intent: 携带调用者传递的数据（可能为 null，见后文 flags 讨论）
    // flags: 系统附加的标志位，指示本次启动的额外信息
    // startId: 本次启动请求的唯一标识符，用于精确停止对应的请求
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // 从 Intent 中提取需要同步的数据 URL
        val syncUrl = intent?.getStringExtra("sync_url") ?: return START_NOT_STICKY
 
        // 注意：Service 默认运行在主线程！
        // 必须手动开启子线程来执行耗时操作，否则会阻塞 UI 并触发 ANR
        Thread {
            // 在子线程中执行实际的数据同步逻辑
            performDataSync(syncUrl)
 
            // 关键：任务完成后，使用 stopSelf(startId) 而非 stopSelf()
            // stopSelf(startId) 只有在 startId 是最近一次请求时才会真正停止服务
            // 这样可以安全地处理多个并发请求：只有最后一个请求完成后服务才停止
            stopSelf(startId)
        }.start()
 
        // 返回值决定了系统在内存不足杀死服务后的重建策略
        // START_NOT_STICKY: 不自动重建（适合可重试的非关键任务）
        // START_STICKY: 重建但 intent 为 null（适合媒体播放等持续性服务）
        // START_REDELIVER_INTENT: 重建并重新传递最后一个 intent（适合必须完成的任务）
        return START_NOT_STICKY
    }
 
    // Started Service 不需要绑定功能，但 onBind 是抽象方法，必须实现
    // 返回 null 表示此服务不支持绑定
    override fun onBind(intent: Intent?): IBinder? = null
 
    // 服务被销毁时回调，释放所有资源
    override fun onDestroy() {
        super.onDestroy()
        Log.d("DataSyncService", "Service 被销毁，释放资源")
    }
 
    // 实际的数据同步逻辑（运行在子线程中）
    private fun performDataSync(url: String) {
        Log.d("DataSyncService", "正在同步数据: $url")
        // 模拟网络请求耗时
        Thread.sleep(3000)
        Log.d("DataSyncService", "数据同步完成: $url")
    }
}

// 在 Activity 中启动 Started Service
class MainActivity : AppCompatActivity() {
 
    // 用户点击"同步"按钮时触发
    fun onSyncButtonClicked() {
        // 构建 Intent，指定目标 Service 并携带数据
        val intent = Intent(this, DataSyncService::class.java).apply {
            // 通过 Extra 传递需要同步的 URL
            putExtra("sync_url", "https://api.example.com/sync")
        }
        // 启动服务——调用后 Activity 与 Service 之间不再有任何关联
        // 即使 Activity 被销毁，Service 仍会继续运行
        startService(intent)
    }
 
    // 如果需要主动停止服务（而非等服务自己 stopSelf）
    fun onCancelSyncClicked() {
        val intent = Intent(this, DataSyncService::class.java)
        // stopService 会触发 Service 的 onDestroy
        stopService(intent)
    }
}

时间线示意：
 
t1: startService() → onStartCommand(startId=1)  → 开始任务1
t2: startService() → onStartCommand(startId=2)  → 开始任务2
t3: startService() → onStartCommand(startId=3)  → 开始任务3
t4: 任务1完成 → stopSelf(1) → 最新startId是3，不等于1 → 服务继续运行 ✓
t5: 任务3完成 → stopSelf(3) → 最新startId是3，等于3 → 但任务2还在？
    实际上系统只看 startId 是否是最新的，所以服务会停止！
    因此，如果任务可能乱序完成，需要自己维护计数器

// 一个提供音乐播放能力的 Bound Service
class MusicService : Service() {
 
    // 内部类 LocalBinder 继承自 Binder
    // 它的唯一职责是提供一个方法让客户端获取 Service 实例的引用
    inner class LocalBinder : Binder() {
        // 返回外部类 MusicService 的实例
        // 因为是 inner class，可以直接访问外部类的 this 引用
        fun getService(): MusicService = this@MusicService
    }
 
    // 创建 Binder 实例——注意这是一个成员变量，整个 Service 生命周期内只有一个
    private val binder = LocalBinder()
 
    // 当前播放状态，客户端可以通过 getService() 拿到 Service 后直接读取
    private var isPlaying = false
 
    // 当前播放的曲目名称
    private var currentTrack: String = ""
 
    // 第一个客户端绑定时调用，返回 IBinder 对象
    // 后续客户端绑定时，系统直接复用这个 IBinder，不会再调用 onBind
    override fun onBind(intent: Intent?): IBinder {
        Log.d("MusicService", "onBind: 第一个客户端绑定")
        return binder
    }
 
    // 所有客户端解绑后调用
    // 返回 true 表示：如果后续有新客户端重新绑定，调用 onRebind() 而非 onBind()
    // 返回 false（默认）表示：后续重新绑定时仍调用 onBind()
    override fun onUnbind(intent: Intent?): Boolean {
        Log.d("MusicService", "onUnbind: 所有客户端已解绑")
        return false
    }
 
    // ========== 以下是 Service 对外暴露的业务方法 ==========
 
    // 播放指定曲目
    fun play(trackName: String) {
        currentTrack = trackName
        isPlaying = true
        Log.d("MusicService", "开始播放: $trackName")
        // 实际实现中这里会调用 MediaPlayer 等播放器 API
    }
 
    // 暂停播放
    fun pause() {
        isPlaying = false
        Log.d("MusicService", "暂停播放: $currentTrack")
    }
 
    // 查询当前是否正在播放
    fun isCurrentlyPlaying(): Boolean = isPlaying
 
    // 获取当前曲目名称
    fun getCurrentTrackName(): String = currentTrack
}

class MusicPlayerActivity : AppCompatActivity() {
 
    // 持有 Service 的引用，绑定成功后赋值
    private var musicService: MusicService? = null
 
    // 标记是否已成功绑定，用于在 onStop 中安全解绑
    private var isBound = false
 
    // ServiceConnection 是客户端与 Service 之间的"桥梁"
    // 它定义了连接建立和断开时的回调逻辑
    private val connection = object : ServiceConnection {
 
        // 绑定成功时回调（运行在主线程）
        // name: 服务的 ComponentName（包名 + 类名）
        // service: Service 的 onBind() 返回的 IBinder 对象
        override fun onServiceConnected(name: ComponentName?, service: IBinder?) {
            // 将 IBinder 向下转型为我们定义的 LocalBinder
            val binder = service as MusicService.LocalBinder
            // 通过 LocalBinder 获取 Service 实例
            musicService = binder.getService()
            // 标记绑定成功
            isBound = true
            Log.d("MusicPlayerActivity", "已绑定到 MusicService")
 
            // 绑定成功后可以立即使用 Service 的方法
            // 例如：更新 UI 显示当前播放状态
            updatePlaybackUI()
        }
 
        // 连接意外断开时回调（注意：主动调用 unbindService 不会触发此回调）
        // 只有在 Service 所在进程崩溃或被系统杀死时才会触发
        override fun onServiceDisconnected(name: ComponentName?) {
            musicService = null
            isBound = false
            Log.d("MusicPlayerActivity", "与 MusicService 的连接意外断开")
        }
    }
 
    override fun onStart() {
        super.onStart()
        // 在 onStart 中绑定服务，确保 Activity 可见时服务可用
        val intent = Intent(this, MusicService::class.java)
        // BIND_AUTO_CREATE: 如果 Service 不存在则自动创建
        // 这是最常用的 flag，几乎所有绑定场景都会使用
        bindService(intent, connection, Context.BIND_AUTO_CREATE)
    }
 
    override fun onStop() {
        super.onStop()
        // 在 onStop 中解绑，与 onStart 中的 bindService 对称
        // 必须检查 isBound 标志，避免重复解绑导致 IllegalArgumentException
        if (isBound) {
            unbindService(connection)
            isBound = false
        }
    }
 
    // 用户点击播放按钮
    fun onPlayClicked() {
        // 通过 Service 引用直接调用方法——这就是 Bound Service 的魅力
        // 无需 Intent、无需序列化、无需等待回调，直接方法调用
        musicService?.play("Shape of You - Ed Sheeran")
    }
 
    // 用户点击暂停按钮
    fun onPauseClicked() {
        musicService?.pause()
    }
 
    // 更新 UI 显示播放状态
    private fun updatePlaybackUI() {
        val isPlaying = musicService?.isCurrentlyPlaying() ?: false
        val trackName = musicService?.getCurrentTrackName() ?: "未知"
        // 更新 UI 控件...
    }
}

时间线：
t1: startService()    → onCreate() → onStartCommand()     [Started锁: 🔒, Bound锁: 🔓]
t2: bindService()     → onBind()                           [Started锁: 🔒, Bound锁: 🔒]
t3: unbindService()   → onUnbind()                         [Started锁: 🔒, Bound锁: 🔓]
    → Service 继续运行！因为 Started 锁还没打开
t4: stopService()     → onDestroy()                        [Started锁: 🔓, Bound锁: 🔓]
    → 两道锁都开了，Service 销毁 ✓

时间线：
t1: startService()    → onCreate() → onStartCommand()     [Started锁: 🔒, Bound锁: 🔓]
t2: bindService()     → onBind()                           [Started锁: 🔒, Bound锁: 🔒]
t3: stopService()     → 什么都不会发生！                     [Started锁: 🔓, Bound锁: 🔒]
    → Started 锁打开了，但 Bound 锁还锁着，Service 继续存活
    → 注意：此时 onDestroy 不会被调用！
t4: unbindService()   → onUnbind() → onDestroy()          [Started锁: 🔓, Bound锁: 🔓]
    → 两道锁都开了，Service 销毁 ✓

时间线：
t1: bindService()     → onCreate() → onBind()             [Started锁: 🔓, Bound锁: 🔒]
t2: unbindService()   → onUnbind() → onDestroy()          [Started锁: 🔓, Bound锁: 🔓]
    → Started 锁本来就是开的，Bound 锁一打开就销毁 ✓

时间线：
t1: startService()         → onCreate() → onStartCommand()  [Started: 🔒, Bound计数: 0]
t2: Activity_A.bind()      → onBind()                       [Started: 🔒, Bound计数: 1]
t3: Activity_B.bind()      → (不再调用onBind，复用IBinder)    [Started: 🔒, Bound计数: 2]
t4: Activity_A.unbind()    → (计数减一，Service继续)          [Started: 🔒, Bound计数: 1]
t5: stopService()          → (Started锁开了，但还有绑定)      [Started: 🔓, Bound计数: 1]
t6: Activity_B.unbind()    → onUnbind() → onDestroy()       [Started: 🔓, Bound计数: 0]
    → 全部条件满足，Service 销毁 ✓

// 混合型 Service：既可以被 start（后台持续播放），也可以被 bind（UI 交互控制）
class MusicPlaybackService : Service() {
 
    // ==================== Binder 相关 ====================
 
    // 内部 Binder 类，供同进程客户端获取 Service 引用
    inner class PlaybackBinder : Binder() {
        // 客户端通过此方法拿到 Service 实例后，可直接调用 public 方法
        fun getService(): MusicPlaybackService = this@MusicPlaybackService
    }
 
    // Binder 实例，在 onBind 中返回给客户端
    private val binder = PlaybackBinder()
 
    // ==================== 播放状态 ====================
 
    // 当前是否正在播放
    private var isPlaying = false
 
    // 当前曲目信息
    private var currentTrack: String = "无"
 
    // 播放进度（秒）
    private var currentPosition: Int = 0
 
    // 用于模拟播放进度更新的 Handler
    private val handler = Handler(Looper.getMainLooper())
 
    // 进度更新的 Runnable
    private val progressUpdater = object : Runnable {
        override fun run() {
            if (isPlaying) {
                // 每秒递增播放进度
                currentPosition++
                // 通知所有注册的监听器（观察者模式）
                listeners.forEach { it.onProgressChanged(currentPosition) }
                // 1秒后再次执行
                handler.postDelayed(this, 1000)
            }
        }
    }
 
    // ==================== 观察者模式：让 UI 实时感知状态变化 ====================
 
    // 定义播放状态监听接口
    // 客户端（Activity/Fragment）实现此接口来接收实时更新
    interface PlaybackListener {
        // 播放状态变化时回调
        fun onPlaybackStateChanged(isPlaying: Boolean, trackName: String)
        // 播放进度变化时回调（每秒一次）
        fun onProgressChanged(positionInSeconds: Int)
    }
 
    // 监听器列表——支持多个 UI 组件同时监听
    // 使用 CopyOnWriteArrayList 保证线程安全
    private val listeners = mutableListOf<PlaybackListener>()
 
    // 注册监听器（客户端在 onServiceConnected 后调用）
    fun registerListener(listener: PlaybackListener) {
        if (!listeners.contains(listener)) {
            listeners.add(listener)
        }
    }
 
    // 注销监听器（客户端在 unbind 前调用，防止内存泄漏）
    fun unregisterListener(listener: PlaybackListener) {
        listeners.remove(listener)
    }
 
    // ==================== 生命周期回调 ====================
 
    override fun onCreate() {
        super.onCreate()
        // Service 实例被创建——无论是通过 start 还是 bind 触发的
        // 这里做一次性初始化：创建 MediaPlayer、初始化音频焦点等
        Log.d("MusicPlayback", "onCreate: Service 实例创建")
    }
 
    // Started 模式的入口：处理 startService() 请求
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // 从 Intent 中解析要执行的动作
        val action = intent?.action
 
        when (action) {
            // 播放动作：从 Intent 中获取曲目信息并开始播放
            "ACTION_PLAY" -> {
                val track = intent.getStringExtra("track_name") ?: "未知曲目"
                play(track)
            }
            // 暂停动作
            "ACTION_PAUSE" -> pause()
            // 停止动作：停止播放并终止服务
            "ACTION_STOP" -> {
                stop()
                // 调用 stopSelf() 打开 "Started 锁"
                // 如果此时没有客户端绑定，Service 会被销毁
                // 如果还有客户端绑定，Service 继续存活直到所有客户端解绑
                stopSelf()
            }
        }
 
        // START_STICKY：系统杀死后会重建 Service，但 intent 为 null
        // 适合音乐播放器：即使被杀，重建后可以恢复到"就绪"状态
        // 用户可以从通知栏或 Activity 重新触发播放
        return START_STICKY
    }
 
    // Bound 模式的入口：返回 IBinder 给客户端
    override fun onBind(intent: Intent?): IBinder {
        Log.d("MusicPlayback", "onBind: 第一个客户端绑定")
        // 返回 Binder 对象，客户端通过它获取 Service 引用
        return binder
    }
 
    // 所有客户端解绑后调用
    override fun onUnbind(intent: Intent?): Boolean {
        Log.d("MusicPlayback", "onUnbind: 所有客户端已解绑")
        // 清空监听器列表，防止持有已销毁 Activity 的引用导致内存泄漏
        listeners.clear()
        // 返回 true：下次有客户端重新绑定时，系统会调用 onRebind() 而非 onBind()
        // 这在混合型服务中很有用——Service 可能因为 Started 模式仍在运行，
        // 用户重新打开 Activity 时需要重新绑定
        return true
    }
 
    // 当 onUnbind 返回 true 后，新客户端重新绑定时调用
    // 注意：此时不会再调用 onBind()，而是调用 onRebind()
    override fun onRebind(intent: Intent?) {
        Log.d("MusicPlayback", "onRebind: 客户端重新绑定")
        super.onRebind(intent)
    }
 
    override fun onDestroy() {
        super.onDestroy()
        // 清理所有资源
        handler.removeCallbacks(progressUpdater)
        listeners.clear()
        Log.d("MusicPlayback", "onDestroy: Service 被销毁，所有资源已释放")
    }
 
    // ==================== 业务方法（供客户端通过 Binder 调用） ====================
 
    // 开始播放指定曲目
    fun play(trackName: String) {
        currentTrack = trackName
        currentPosition = 0
        isPlaying = true
        // 启动进度更新循环
        handler.post(progressUpdater)
        // 通知所有监听器状态变化
        listeners.forEach { it.onPlaybackStateChanged(true, trackName) }
        Log.d("MusicPlayback", "开始播放: $trackName")
    }
 
    // 暂停播放
    fun pause() {
        isPlaying = false
        // 停止进度更新
        handler.removeCallbacks(progressUpdater)
        // 通知监听器
        listeners.forEach { it.onPlaybackStateChanged(false, currentTrack) }
        Log.d("MusicPlayback", "暂停播放: $currentTrack")
    }
 
    // 停止播放并重置状态
    fun stop() {
        isPlaying = false
        currentPosition = 0
        currentTrack = "无"
        handler.removeCallbacks(progressUpdater)
        listeners.forEach { it.onPlaybackStateChanged(false, "") }
        Log.d("MusicPlayback", "停止播放")
    }
 
    // 查询当前播放状态（供 UI 初始化时同步状态）
    fun getPlaybackState(): PlaybackState {
        return PlaybackState(isPlaying, currentTrack, currentPosition)
    }
 
    // 播放状态数据类
    data class PlaybackState(
        val isPlaying: Boolean,       // 是否正在播放
        val trackName: String,        // 当前曲目名
        val positionSeconds: Int      // 当前播放位置（秒）
    )
}

class NowPlayingActivity : AppCompatActivity(), MusicPlaybackService.PlaybackListener {
 
    // Service 引用
    private var playbackService: MusicPlaybackService? = null
 
    // 绑定状态标记
    private var isBound = false
 
    // ServiceConnection 实现
    private val serviceConnection = object : ServiceConnection {
 
        override fun onServiceConnected(name: ComponentName?, service: IBinder?) {
            // 获取 Service 引用
            val binder = service as MusicPlaybackService.PlaybackBinder
            playbackService = binder.getService()
            isBound = true
 
            // 注册自己为播放状态监听器
            // Activity 实现了 PlaybackListener 接口，所以直接传 this
            playbackService?.registerListener(this@NowPlayingActivity)
 
            // 同步当前播放状态到 UI
            // 这一步很重要：用户可能是从通知栏点进来的，
            // 此时音乐已经在播放，UI 需要立即反映当前状态
            val state = playbackService?.getPlaybackState()
            state?.let { updateUI(it) }
 
            Log.d("NowPlaying", "已绑定到 MusicPlaybackService")
        }
 
        override fun onServiceDisconnected(name: ComponentName?) {
            // 意外断开（进程被杀等）
            playbackService = null
            isBound = false
            Log.d("NowPlaying", "与 MusicPlaybackService 的连接意外断开")
        }
    }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_now_playing)
 
        // 点击播放按钮：通过 startService 确保后台持续播放
        // 同时通过 Binder 直接调用 play 方法
        findViewById<Button>(R.id.btn_play).setOnClickListener {
            // 先 startService 确保 Service 不会因为 unbind 而死亡
            val startIntent = Intent(this, MusicPlaybackService::class.java).apply {
                action = "ACTION_PLAY"
                putExtra("track_name", "Bohemian Rhapsody - Queen")
            }
            startService(startIntent)
 
            // 如果已经绑定，也可以直接通过 Binder 调用（效果相同，但更直接）
            // playbackService?.play("Bohemian Rhapsody - Queen")
        }
 
        // 点击暂停按钮：通过 Binder 直接调用
        findViewById<Button>(R.id.btn_pause).setOnClickListener {
            playbackService?.pause()
        }
 
        // 点击停止按钮：停止服务
        findViewById<Button>(R.id.btn_stop).setOnClickListener {
            val stopIntent = Intent(this, MusicPlaybackService::class.java).apply {
                action = "ACTION_STOP"
            }
            // stopService 会触发 onStartCommand 中的 ACTION_STOP 处理
            // 然后 Service 内部调用 stopSelf()
            startService(stopIntent)
            // 注意：这里不直接调用 stopService()，而是发送一个 ACTION_STOP 的 intent
            // 这样 Service 可以在停止前做清理工作（保存播放位置等）
        }
    }
 
    override fun onStart() {
        super.onStart()
        // 绑定到 Service，建立通信通道
        val bindIntent = Intent(this, MusicPlaybackService::class.java)
        bindService(bindIntent, serviceConnection, Context.BIND_AUTO_CREATE)
    }
 
    override fun onStop() {
        super.onStop()
        // 解绑前先注销监听器，防止 Service 持有已暂停 Activity 的引用
        if (isBound) {
            playbackService?.unregisterListener(this)
            unbindService(serviceConnection)
            isBound = false
        }
        // 注意：解绑后 Service 不一定会销毁！
        // 如果之前调用过 startService，Service 会继续在后台运行
        // 这正是混合型的核心价值所在
    }
 
    // ==================== PlaybackListener 回调实现 ====================
 
    // 播放状态变化时由 Service 回调（运行在主线程，可直接更新 UI）
    override fun onPlaybackStateChanged(isPlaying: Boolean, trackName: String) {
        // 更新播放/暂停按钮的图标
        val playButton = findViewById<Button>(R.id.btn_play)
        playButton.text = if (isPlaying) "暂停" else "播放"
 
        // 更新曲目名称显示
        val trackText = findViewById<TextView>(R.id.tv_track_name)
        trackText.text = trackName
    }
 
    // 播放进度变化时由 Service 每秒回调一次
    override fun onProgressChanged(positionInSeconds: Int) {
        // 更新进度条和时间显示
        val progressText = findViewById<TextView>(R.id.tv_progress)
        val minutes = positionInSeconds / 60
        val seconds = positionInSeconds % 60
        progressText.text = String.format("%02d:%02d", minutes, seconds)
    }
 
    // 辅助方法：根据播放状态更新整个 UI
    private fun updateUI(state: MusicPlaybackService.PlaybackState) {
        onPlaybackStateChanged(state.isPlaying, state.trackName)
        onProgressChanged(state.positionSeconds)
    }
}

t1: startService()       → onCreate() → onStartCommand()
t2: Activity_A.bind()    → onBind() → 返回 IBinder
t3: Activity_A.unbind()  → onUnbind() → 返回 true  ← 关键：必须返回 true
    → Service 继续运行（因为 Started 锁还在）
t4: Activity_B.bind()    → onRebind()  ← 不是 onBind()！
    → 系统将之前缓存的 IBinder 传给 Activity_B
t5: Activity_B.unbind()  → onUnbind()
t6: stopService()        → onDestroy()

// 推荐的绑定/解绑生命周期配对
class BestPracticeActivity : AppCompatActivity() {
 
    // ✅ 正确：onStart/onStop 配对
    override fun onStart() {
        super.onStart()
        // 绑定服务
        bindService(intent, connection, Context.BIND_AUTO_CREATE)
    }
 
    override fun onStop() {
        super.onStop()
        // 解绑服务——与 onStart 严格对称
        if (isBound) {
            unbindService(connection)
            isBound = false
        }
    }
 
    // ❌ 错误示范：onCreate/onDestroy 配对绑定
    // 问题：Activity 在 stopped 状态时仍持有绑定，浪费资源
    // 更大的问题：配置变更时 onCreate 会再次调用，导致重复绑定
 
    // ❌ 错误示范：onResume/onPause 配对绑定
    // 问题：绑定/解绑过于频繁（每次弹出对话框都会触发 onPause）
    // 频繁的 bind/unbind 会造成不必要的性能开销
}

// frameworks/base/services/core/java/com/android/server/am/ServiceRecord.java
// 以下为简化后的关键字段（非完整源码）
 
class ServiceRecord {
    // 记录所有通过 bindService 建立的连接
    // key 是 Intent.FilterComparison（用于区分不同 Intent 的绑定）
    // value 是 IntentBindRecord，内部又包含所有绑定到该 Intent 的客户端连接列表
    final ArrayMap<Intent.FilterComparison, IntentBindRecord> bindings;
 
    // 记录通过 startService 传入的所有 delivery 列表
    // 每次 onStartCommand 被调用时，对应的 StartItem 会被加入此列表
    final ArrayList<StartItem> deliveredStarts;
 
    // 关键标志位：Service 是否处于 "started" 状态
    // 调用 startService 后设为 true
    // 调用 stopSelf/stopService 后设为 false
    boolean startRequested;
 
    // 最后一次 onStartCommand 的 startId
    int lastStartId;
 
    // 绑定计数相关：当前有多少活跃的绑定连接
    int getConnectionCount();
}

// AMS 内部判断 Service 是否应该销毁的简化逻辑
fun shouldDestroyService(record: ServiceRecord): Boolean {
    // 条件一：是否还处于 started 状态
    // 如果 startRequested 为 true，说明还没有被 stop，不能销毁
    val isStopped = !record.startRequested
 
    // 条件二：是否还有活跃的绑定连接
    // 遍历所有 IntentBindRecord，检查是否还有未解绑的客户端
    val hasActiveBindings = record.bindings.values.any { intentBind ->
        intentBind.apps.isNotEmpty() // apps 记录了绑定到此 intent 的所有客户端进程
    }
 
    // 只有两个条件同时满足时才销毁
    // isStopped == true 且 hasActiveBindings == false
    return isStopped && !hasActiveBindings
}

// 一个典型的 Service.onCreate() 实现示例
class MusicPlaybackService : Service() {
 
    // 声明但不在此处初始化——因为构造函数执行时 Context 尚未注入
    private lateinit var mediaPlayer: MediaPlayer
    // 工作线程的 Handler，用于将耗时操作从主线程转移出去
    private lateinit var serviceHandler: Handler
    // HandlerThread 提供了一个自带 Looper 的后台线程
    private lateinit var handlerThread: HandlerThread
 
    override fun onCreate() {
        // 调用父类实现——虽然 Service.onCreate() 的默认实现是空的，
        // 但这是一个良好的编程习惯，防止未来 Android 版本在父类中添加逻辑
        super.onCreate()
 
        // 创建一个后台工作线程，线程名用于调试时在 Thread Dump 中识别
        // HandlerThread 内部会自动创建 Looper 并启动消息循环
        handlerThread = HandlerThread("MusicService-Worker")
        // start() 必须在获取 Looper 之前调用，否则 getLooper() 会阻塞或返回 null
        handlerThread.start()
 
        // 将 Handler 绑定到工作线程的 Looper 上
        // 通过这个 Handler post 的所有 Runnable 都会在工作线程上执行
        serviceHandler = Handler(handlerThread.looper)
 
        // 初始化 MediaPlayer——这是一个依赖 Context 的操作
        // 如果放在构造函数中会因 Context 未注入而崩溃
        mediaPlayer = MediaPlayer()
        // 设置音频属性，指定这是音乐类型的音频流
        mediaPlayer.setAudioAttributes(
            AudioAttributes.Builder()
                .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC) // 内容类型：音乐
                .setUsage(AudioAttributes.USAGE_MEDIA)              // 用途：媒体播放
                .build()
        )
 
        // 在 onCreate 中注册广播接收器，监听耳机拔出事件
        // 这样可以在耳机拔出时自动暂停播放，提升用户体验
        val filter = IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY)
        registerReceiver(noisyReceiver, filter)
    }
 
    // 耳机拔出时的广播接收器
    private val noisyReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context?, intent: Intent?) {
            // 当音频即将变为"嘈杂"（即从耳机切换到外放）时暂停播放
            mediaPlayer.pause()
        }
    }
 
    // ... 其他生命周期方法
}

// onStartCommand 的完整方法签名
override fun onStartCommand(
    intent: Intent?,    // 启动 Service 时传入的 Intent，可能为 null（见下文解释）
    flags: Int,         // 系统传入的附加标志位，描述本次启动的"上下文信息"
    startId: Int        // 本次启动请求的唯一标识符，用于精确停止 Service
): Int {               // 返回值告诉系统：如果 Service 被杀死，应该如何处理重启
    // ...
}

// 演示 startId 的精确停止机制
class MultiTaskDownloadService : Service() {
 
    // 用于在工作线程上执行下载任务的 Handler
    private lateinit var serviceHandler: Handler
    private lateinit var handlerThread: HandlerThread
 
    override fun onCreate() {
        super.onCreate()
        // 创建工作线程，避免在主线程执行网络 I/O
        handlerThread = HandlerThread("DownloadWorker")
        handlerThread.start()
        serviceHandler = Handler(handlerThread.looper)
    }
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // 防御性检查：intent 可能为 null（系统重启场景）
        // 如果为 null，说明没有有效的任务指令，直接尝试停止
        if (intent == null) {
            stopSelfResult(startId) // 安全停止：只有当这是最后一个 startId 时才真正停止
            return START_NOT_STICKY  // 告诉系统不需要重启
        }
 
        // 从 Intent 中提取下载 URL
        val downloadUrl = intent.getStringExtra("url") ?: return START_NOT_STICKY
 
        // 捕获当前的 startId 到局部变量中（闭包捕获）
        // 这一步至关重要——因为 onStartCommand 会被多次调用，
        // 如果直接在 lambda 中引用参数 startId，每个 lambda 捕获的都是各自调用时的值
        val currentStartId = startId
 
        // 将下载任务投递到工作线程执行
        serviceHandler.post {
            // 模拟下载操作（实际应使用 OkHttp/Retrofit 等）
            performDownload(downloadUrl)
 
            // 下载完成后，尝试用当前任务的 startId 停止 Service
            // 关键逻辑：stopSelfResult 会判断 currentStartId 是否是最新的
            // 如果在此任务执行期间又有新的 startService() 调用进来，
            // 那么最新的 startId 会大于 currentStartId，stopSelfResult 返回 false，
            // Service 继续运行，不会影响后续任务
            val stopped = stopSelfResult(currentStartId)
            // stopped = true  → 这是最后一个任务，Service 将被销毁
            // stopped = false → 还有更新的任务在处理中，Service 继续运行
        }
 
        // 返回 START_REDELIVER_INTENT：如果 Service 在任务完成前被杀死，
        // 系统会重新创建 Service 并重新投递这个 Intent，确保下载任务不会丢失
        return START_REDELIVER_INTENT
    }
 
    // 模拟下载操作
    private fun performDownload(url: String) {
        // 实际的网络下载逻辑...
        Thread.sleep(5000) // 模拟耗时操作
    }
 
    override fun onBind(intent: Intent?): IBinder? = null // 纯启动型 Service，不支持绑定
 
    override fun onDestroy() {
        super.onDestroy()
        // 释放工作线程资源
        // quitSafely() 会等待已投递的消息处理完毕后再退出，比 quit() 更安全
        handlerThread.quitSafely()
    }
}

// 综合演示：根据不同业务场景选择合适的返回值
class SmartService : Service() {
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // 通过 Intent 的 action 字段区分不同类型的任务
        return when (intent?.action) {
 
            // 场景 1：定期清理缓存——即使被杀也无所谓，下次定时任务会再次触发
            "ACTION_CLEANUP_CACHE" -> {
                // 在工作线程中执行缓存清理
                cleanupCacheAsync()
                // 不需要重启，错过一次清理不会有任何影响
                START_NOT_STICKY
            }
 
            // 场景 2：后台音乐播放——需要持续运行，但播放状态可以从持久化存储恢复
            "ACTION_PLAY_MUSIC" -> {
                val trackId = intent.getLongExtra("track_id", -1L)
                if (trackId != -1L) {
                    // 将当前播放的曲目 ID 持久化，以便 Service 重启后恢复
                    saveCurrentTrack(trackId)
                    startPlayback(trackId)
                }
                // 使用 START_STICKY：Service 被杀后会自动重启
                // 重启时 intent 为 null，需要从持久化存储中读取上次播放的曲目
                START_STICKY
            }
 
            // 场景 3：上传用户生成的内容——必须确保上传成功，不能丢失
            "ACTION_UPLOAD_CONTENT" -> {
                val contentUri = intent.getParcelableExtra<Uri>("content_uri")
                if (contentUri != null) {
                    // 在工作线程中执行上传，完成后调用 stopSelfResult(startId)
                    uploadContentAsync(contentUri, startId)
                }
                // 使用 START_REDELIVER_INTENT：如果上传过程中 Service 被杀，
                // 系统会重新投递这个 Intent，确保上传任务不会丢失
                START_REDELIVER_INTENT
            }
 
            // 场景 4：intent 为 null，说明这是 START_STICKY 触发的重启
            null -> {
                // 尝试从持久化存储恢复之前的状态
                val lastTrack = restoreLastTrack()
                if (lastTrack != null) {
                    startPlayback(lastTrack)
                    START_STICKY // 继续保持粘性重启策略
                } else {
                    // 没有可恢复的状态，安全停止
                    stopSelfResult(startId)
                    START_NOT_STICKY
                }
            }
 
            // 未知的 action，安全停止
            else -> {
                stopSelfResult(startId)
                START_NOT_STICKY
            }
        }
    }
 
    // 以下为辅助方法的占位声明
    private fun cleanupCacheAsync() { /* ... */ }
    private fun saveCurrentTrack(trackId: Long) { /* ... */ }
    private fun startPlayback(trackId: Long) { /* ... */ }
    private fun restoreLastTrack(): Long? { /* ... */ return null }
    private fun uploadContentAsync(uri: Uri, startId: Int) { /* ... */ }
 
    override fun onBind(intent: Intent?): IBinder? = null
 
    override fun onDestroy() {
        super.onDestroy()
    }
}

// 演示 onBind() 的多接口绑定模式
class MultiFacetedService : Service() {
 
    // 为"播放控制"接口定义的 Binder
    // 继承自 Binder 类，Binder 本身实现了 IBinder 接口
    inner class PlaybackBinder : Binder() {
        // 提供获取 Service 实例的方法，客户端通过它调用 Service 的公开方法
        // 使用 inner class 使得 Binder 可以访问外部 Service 的成员
        fun getService(): MultiFacetedService = this@MultiFacetedService
    }
 
    // 为"下载管理"接口定义的 Binder
    inner class DownloadBinder : Binder() {
        // 直接在 Binder 中暴露下载相关的方法
        fun enqueueDownload(url: String): Long {
            // 将下载任务加入队列，返回任务 ID
            return this@MultiFacetedService.enqueueDownloadInternal(url)
        }
 
        // 查询下载进度
        fun getProgress(taskId: Long): Int {
            return this@MultiFacetedService.getDownloadProgress(taskId)
        }
    }
 
    // 分别为两种接口创建单例 Binder 实例
    // 使用单例是因为 onBind() 对同一 Intent 只调用一次，
    // 但即使被多次调用，返回同一个实例也是安全且推荐的做法
    private val playbackBinder = PlaybackBinder()
    private val downloadBinder = DownloadBinder()
 
    override fun onBind(intent: Intent?): IBinder? {
        // 根据 Intent 的 action 返回不同的 Binder 接口
        // 这使得同一个 Service 可以向不同的客户端暴露不同的能力
        return when (intent?.action) {
            "action.PLAYBACK" -> {
                // 客户端请求播放控制接口
                playbackBinder
            }
            "action.DOWNLOAD" -> {
                // 客户端请求下载管理接口
                downloadBinder
            }
            else -> {
                // 未知的绑定请求，返回 null 表示拒绝绑定
                // 客户端的 ServiceConnection.onServiceConnected() 不会被调用
                null
            }
        }
    }
 
    // Service 的公开方法，客户端通过 PlaybackBinder.getService() 获取引用后调用
    fun play() { /* 播放逻辑 */ }
    fun pause() { /* 暂停逻辑 */ }
 
    // 内部方法，通过 DownloadBinder 间接暴露
    private fun enqueueDownloadInternal(url: String): Long { return System.currentTimeMillis() }
    private fun getDownloadProgress(taskId: Long): Int { return 0 }
 
    override fun onUnbind(intent: Intent?): Boolean = false
}

// 客户端（如 Activity）中绑定 Service 的完整流程
class PlayerActivity : AppCompatActivity() {
 
    // 持有 Service 的 Binder 引用，用于后续调用 Service 方法
    private var playbackBinder: MultiFacetedService.PlaybackBinder? = null
    // 标记是否已成功绑定，用于在 onStop 中安全解绑
    private var isBound = false
 
    // ServiceConnection 是客户端与 Service 之间的"连接状态监听器"
    private val connection = object : ServiceConnection {
 
        // 当绑定成功建立时回调
        // 参数 name: 被绑定的 Service 的 ComponentName
        // 参数 service: Service 的 onBind() 返回的 IBinder 对象
        override fun onServiceConnected(name: ComponentName?, service: IBinder?) {
            // 将 IBinder 向下转型为具体的 Binder 子类
            // 这种转型只在同进程绑定时安全——跨进程时 IBinder 是一个代理对象
            playbackBinder = service as? MultiFacetedService.PlaybackBinder
            isBound = true
 
            // 绑定成功后，可以立即通过 Binder 调用 Service 的方法
            playbackBinder?.getService()?.play()
        }
 
        // 当连接意外断开时回调（注意：主动调用 unbindService 不会触发此回调）
        // 触发场景：Service 所在进程崩溃、被系统杀死、或 Service 自行调用 stopSelf()
        override fun onServiceDisconnected(name: ComponentName?) {
            // 清除 Binder 引用，防止使用已失效的对象
            playbackBinder = null
            isBound = false
            // 注意：如果 Service 进程重启，系统会自动尝试重新绑定，
            // 届时 onServiceConnected 会再次被调用，你不需要手动重新调用 bindService()
        }
    }
 
    override fun onStart() {
        super.onStart()
        // 构建指向目标 Service 的显式 Intent，并设置 action 以选择绑定接口
        val intent = Intent(this, MultiFacetedService::class.java).apply {
            action = "action.PLAYBACK" // 指定请求播放控制接口
        }
        // bindService 的第三个参数是 flags，BIND_AUTO_CREATE 表示：
        // 如果 Service 尚未创建，则自动创建它（触发 onCreate + onBind）
        // 这是最常用的 flag，几乎所有绑定场景都会使用
        bindService(intent, connection, Context.BIND_AUTO_CREATE)
    }
 
    override fun onStop() {
        super.onStop()
        // 安全解绑：必须检查 isBound 标志，避免重复解绑导致 IllegalArgumentException
        // 这是一个非常常见的崩溃原因——如果 bindService 失败（返回 false），
        // 但你仍然在 onStop 中调用 unbindService，就会抛出异常
        if (isBound) {
            unbindService(connection)
            isBound = false
            playbackBinder = null
        }
    }
 
}
 

class ChatService : Service() {
 
    // 心跳间隔：全功率模式 vs 低功耗模式
    companion object {
        private const val HEARTBEAT_ACTIVE = 15_000L    // 15 秒，有客户端绑定时
        private const val HEARTBEAT_IDLE = 120_000L     // 120 秒，所有客户端解绑后
    }
 
    // 心跳定时器的 Handler
    private lateinit var heartbeatHandler: Handler
    // 当前心跳间隔
    private var currentHeartbeatInterval = HEARTBEAT_ACTIVE
 
    // 内部 Binder 类，向客户端暴露聊天功能
    inner class ChatBinder : Binder() {
        // 发送消息的方法
        fun sendMessage(chatId: String, message: String) {
            this@ChatService.sendMessageInternal(chatId, message)
        }
        // 获取未读消息数
        fun getUnreadCount(chatId: String): Int {
            return this@ChatService.getUnreadCountInternal(chatId)
        }
    }
 
    private val binder = ChatBinder()
 
    override fun onCreate() {
        super.onCreate()
        // 初始化心跳 Handler，绑定到主线程 Looper
        heartbeatHandler = Handler(mainLooper)
        // 启动心跳，初始为全功率模式
        scheduleHeartbeat(HEARTBEAT_ACTIVE)
    }
 
    override fun onBind(intent: Intent?): IBinder {
        // 首次绑定时调用
        // 确保心跳处于全功率模式
        scheduleHeartbeat(HEARTBEAT_ACTIVE)
        // 返回 Binder 对象，AMS 会缓存它并分发给所有后续绑定的客户端
        return binder
    }
 
    override fun onUnbind(intent: Intent?): Boolean {
        // 所有客户端都已解绑
        // 切换到低功耗心跳模式，减少资源消耗
        scheduleHeartbeat(HEARTBEAT_IDLE)
 
        // 返回 true：告诉 AMS 启用 rebind 机制
        // 下次有客户端绑定时，AMS 会调用 onRebind() 而不是 onBind()
        // 这让我们有机会在客户端回来时恢复全功率模式
        return true
    }
 
    override fun onRebind(intent: Intent?) {
        // 在 onUnbind 返回 true 的前提下，当新客户端重新绑定时被调用
        // 恢复全功率心跳模式
        scheduleHeartbeat(HEARTBEAT_ACTIVE)
 
        // 注意：onRebind 没有返回值，它不需要返回 IBinder
        // AMS 会继续使用之前 onBind() 返回并缓存的那个 IBinder
    }
 
    // 调度心跳的辅助方法
    private fun scheduleHeartbeat(intervalMs: Long) {
        // 先移除之前的心跳回调，避免重复调度
        heartbeatHandler.removeCallbacks(heartbeatRunnable)
        // 更新当前间隔
        currentHeartbeatInterval = intervalMs
        // 投递新的心跳任务
        heartbeatHandler.postDelayed(heartbeatRunnable, intervalMs)
    }
 
    // 心跳任务的 Runnable
    private val heartbeatRunnable = object : Runnable {
        override fun run() {
            // 执行心跳逻辑（如向服务器发送 ping）
            performHeartbeat()
            // 递归调度下一次心跳
            heartbeatHandler.postDelayed(this, currentHeartbeatInterval)
        }
    }
 
    private fun performHeartbeat() { /* 向服务器发送心跳包 */ }
    private fun sendMessageInternal(chatId: String, message: String) { /* ... */ }
    private fun getUnreadCountInternal(chatId: String): Int { return 0 }
 
    override fun onDestroy() {
        super.onDestroy()
        // 清理心跳定时器，防止内存泄漏
        heartbeatHandler.removeCallbacksAndMessages(null)
    }
}

class RobustService : Service() {
 
    // 在 onCreate 中初始化的各种资源
    private lateinit var handlerThread: HandlerThread
    private lateinit var serviceHandler: Handler
    private lateinit var wakeLock: PowerManager.WakeLock
    private lateinit var locationManager: LocationManager
    private var mediaPlayer: MediaPlayer? = null
 
    // 位置监听器
    private val locationListener = object : LocationListener {
        override fun onLocationChanged(location: Location) {
            // 处理位置更新
        }
    }
 
    // 广播接收器
    private val screenReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context?, intent: Intent?) {
            // 处理屏幕开关事件
        }
    }
 
    override fun onCreate() {
        super.onCreate()
 
        // 1. 创建工作线程
        handlerThread = HandlerThread("RobustService-Worker")
        handlerThread.start()
        serviceHandler = Handler(handlerThread.looper)
 
        // 2. 获取 WakeLock（保持 CPU 唤醒）
        val pm = getSystemService(Context.POWER_SERVICE) as PowerManager
        // 使用 PARTIAL_WAKE_LOCK：只保持 CPU 运行，不保持屏幕亮起
        // 标签用于调试和系统日志中识别是哪个组件持有 WakeLock
        wakeLock = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "MyApp::RobustService")
        wakeLock.acquire(10 * 60 * 1000L) // 设置超时，防止忘记释放
 
        // 3. 注册位置监听
        locationManager = getSystemService(Context.LOCATION_SERVICE) as LocationManager
        try {
            locationManager.requestLocationUpdates(
                LocationManager.GPS_PROVIDER,
                5000L,      // 最小时间间隔：5 秒
                10f,        // 最小距离变化：10 米
                locationListener
            )
        } catch (e: SecurityException) {
            // 缺少定位权限时的防御性处理
        }
 
        // 4. 注册广播接收器
        val filter = IntentFilter().apply {
            addAction(Intent.ACTION_SCREEN_ON)
            addAction(Intent.ACTION_SCREEN_OFF)
        }
        registerReceiver(screenReceiver, filter)
 
        // 5. 初始化 MediaPlayer
        mediaPlayer = MediaPlayer.create(this, R.raw.notification_sound)
    }
 
    override fun onDestroy() {
        // === 镜像原则：按照 onCreate 的逆序释放所有资源 ===
 
        // 5. 释放 MediaPlayer（与 onCreate 第 5 步对应）
        // 必须先调用 release() 释放底层的 native 资源
        // MediaPlayer 底层持有 C++ 层的 AudioTrack 和 codec 资源，
        // 如果不显式 release，这些 native 资源不会被 Java GC 回收
        mediaPlayer?.release()
        mediaPlayer = null // 置空引用，防止后续误用
 
        // 4. 注销广播接收器（与 onCreate 第 4 步对应）
        // 如果忘记注销，会导致 IntentReceiver 泄漏，
        // 系统会在 logcat 中打印 "Activity has leaked IntentReceiver" 警告
        try {
            unregisterReceiver(screenReceiver)
        } catch (e: IllegalArgumentException) {
            // 防御性处理：如果 receiver 未注册或已注销，避免崩溃
        }
 
        // 3. 移除位置监听（与 onCreate 第 3 步对应）
        // 不移除的话，LocationManager 会持有 Service 的引用，
        // 导致 Service 对象无法被 GC 回收（内存泄漏）
        locationManager.removeUpdates(locationListener)
 
        // 2. 释放 WakeLock（与 onCreate 第 2 步对应）
        // 检查 isHeld 是一个好习惯——如果 WakeLock 已经因超时自动释放，
        // 再次调用 release() 会抛出 RuntimeException
        if (wakeLock.isHeld) {
            wakeLock.release()
        }
 
        // 1. 停止工作线程（与 onCreate 第 1 步对应）
        // quitSafely() 会处理完消息队列中已有的消息后再退出
        // 而 quit() 会立即丢弃所有未处理的消息
        handlerThread.quitSafely()
 
        // 最后调用 super.onDestroy()
        // 虽然 Service 的默认实现是空的，但保持这个习惯是好的
        super.onDestroy()
    }
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        return START_STICKY
    }
 
    override fun onBind(intent: Intent?): IBinder? = null
}

// 假设以下调用序列发生在不同的时间点：
 
// T1: Activity A 启动 Service
// startService(intent)
// → Service.onCreate()        ← 首次创建
// → Service.onStartCommand()  ← 接收启动指令
 
// T2: Activity B 绑定 Service
// bindService(intent, conn, BIND_AUTO_CREATE)
// → Service.onBind()          ← 首次绑定，返回 IBinder
// → conn.onServiceConnected() ← Activity B 收到 IBinder
 
// T3: Activity A 停止 Service
// stopService(intent)
// → 什么都不会发生！          ← Service 不会被销毁
//   因为 Activity B 仍然绑定着，绑定型轨道尚未结束
//   AMS 内部标记：started = false, 但 bindings.isNotEmpty()
 
// T4: Activity B 解绑 Service
// unbindService(conn)
// → Service.onUnbind()        ← 所有客户端已解绑
// → Service.onDestroy()       ← 现在两个条件都满足了：
//                                started = false 且 bindings.isEmpty()
//                                Service 终于可以被销毁了

// 演示生命周期回调与工作线程之间的竞态条件及其解决方案
class ThreadSafeService : Service() {
 
    // 使用 volatile 确保多线程间的可见性
    // 当 onDestroy 将其设为 true 时，工作线程能立即感知到
    @Volatile
    private var isDestroyed = false
 
    // 使用 AtomicBoolean 也是一种选择，但对于简单的布尔标志，volatile 足够了
    private lateinit var handlerThread: HandlerThread
    private lateinit var serviceHandler: Handler
 
    override fun onCreate() {
        super.onCreate()
        handlerThread = HandlerThread("SafeWorker")
        handlerThread.start()
        serviceHandler = Handler(handlerThread.looper)
    }
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        val taskData = intent?.getStringExtra("task_data") ?: return START_NOT_STICKY
        val currentStartId = startId
 
        // 将任务投递到工作线程
        serviceHandler.post {
            // 在工作线程中执行耗时操作
            // 每一步操作前都检查 isDestroyed 标志
            // 这是一种"协作式取消"（cooperative cancellation）模式
            if (isDestroyed) return@post
 
            val step1Result = performStep1(taskData)
 
            // 再次检查——因为 step1 可能耗时很长，
            // 在此期间 onDestroy 可能已经在主线程上被调用了
            if (isDestroyed) return@post
 
            val step2Result = performStep2(step1Result)
 
            if (isDestroyed) return@post
 
            performStep3(step2Result)
 
            // 任务完成，尝试停止 Service
            // 注意：stopSelfResult 是线程安全的，可以在任何线程调用
            // 它内部通过 Binder IPC 与 AMS 通信，AMS 会在主线程上调度 onDestroy
            if (!isDestroyed) {
                stopSelfResult(currentStartId)
            }
        }
 
        return START_REDELIVER_INTENT
    }
 
    override fun onDestroy() {
        // 设置销毁标志——工作线程会在下一个检查点感知到这个变化
        // 由于 isDestroyed 是 volatile 的，这个写操作对工作线程立即可见
        isDestroyed = true
 
        // quitSafely 会让工作线程处理完当前正在执行的消息后退出
        // 但不会执行队列中尚未开始的消息
        // 这意味着如果工作线程正在执行 performStep2，它会执行完，
        // 但下一个 isDestroyed 检查会阻止 performStep3 的执行
        handlerThread.quitSafely()
 
        super.onDestroy()
    }
 
    // 模拟分步骤的耗时操作
    private fun performStep1(data: String): String {
        Thread.sleep(3000) // 模拟网络请求
        return "step1_result"
    }
 
    private fun performStep2(input: String): String {
        Thread.sleep(2000) // 模拟数据处理
        return "step2_result"
    }
 
    private fun performStep3(input: String) {
        Thread.sleep(1000) // 模拟结果持久化
    }
 
    override fun onBind(intent: Intent?): IBinder? = null
 
}
 

// 使用 Kotlin Coroutines 的现代化方案
class CoroutineService : Service() {
 
    // 创建一个与 Service 生命周期绑定的 CoroutineScope
    // SupervisorJob 确保一个子协程的失败不会取消其他子协程
    // Dispatchers.Main 确保 scope 的取消操作在主线程执行（与 onDestroy 一致）
    private val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
 
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        val taskData = intent?.getStringExtra("task_data") ?: return START_NOT_STICKY
        val currentStartId = startId
 
        // 在 serviceScope 中启动协程
        // 当 serviceScope 被取消时（在 onDestroy 中），
        // 所有通过它启动的协程都会自动收到取消信号
        serviceScope.launch {
            // withContext(Dispatchers.IO) 将执行切换到 IO 线程池
            // 同时保持对取消信号的响应——这是协程相比手动线程管理的巨大优势
            withContext(Dispatchers.IO) {
                // 每个 suspend 函数调用点都是一个"取消检查点"
                // 如果协程已被取消，会在这些点自动抛出 CancellationException
                val step1 = performStep1Suspend(taskData)
                val step2 = performStep2Suspend(step1)
                performStep3Suspend(step2)
            }
            // 回到主线程，安全地停止 Service
            stopSelfResult(currentStartId)
        }
 
        return START_REDELIVER_INTENT
    }
 
    // suspend 函数——可以被取消，不需要手动检查 isDestroyed 标志
    private suspend fun performStep1Suspend(data: String): String {
        // delay 是一个 suspend 函数，它会响应取消
        // 在实际代码中，这里会是 Retrofit 的 suspend 网络请求
        delay(3000)
        return "step1_result"
    }
 
    private suspend fun performStep2Suspend(input: String): String {
        delay(2000)
        return "step2_result"
    }
 
    private suspend fun performStep3Suspend(input: String) {
        delay(1000)
    }
 
    override fun onDestroy() {
        // 取消 serviceScope——所有通过它启动的协程都会被取消
        // 这一行代码等价于之前手动方案中的：
        // isDestroyed = true + handlerThread.quitSafely()
        // 但更安全、更优雅，且自动处理了所有的资源清理
        serviceScope.cancel()
 
        super.onDestroy()
    }
 
    override fun onBind(intent: Intent?): IBinder? = null
}

// === NotificationHelper.kt ===
// 封装 Notification 创建逻辑，便于复用
 
import android.app.Notification
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.PendingIntent
import android.content.Context
import android.content.Intent
import android.os.Build
import androidx.core.app.NotificationCompat
 
object NotificationHelper {
 
    // Channel ID 常量，整个应用中保持唯一
    const val CHANNEL_ID = "foreground_service_channel"
    // 通知 ID 常量，必须非零
    const val NOTIFICATION_ID = 1001
 
    /**
     * 创建 NotificationChannel（仅 API 26+ 需要）
     * 这个方法应该在 Application.onCreate() 或 Service.onCreate() 中调用
     * 重复调用是安全的——如果 Channel 已存在，系统会忽略
     */
    fun createChannel(context: Context) {
        // API 26 以下不需要 Channel，直接返回
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
 
        // 构建 Channel 对象
        // 参数1: channelId —— 唯一标识，与 Notification 中的 channelId 对应
        // 参数2: channelName —— 用户在系统设置中看到的名称
        // 参数3: importance —— IMPORTANCE_LOW 表示不发声、不弹横幅
        val channel = NotificationChannel(
            CHANNEL_ID,                              // channelId
            "Foreground Service Channel",            // 用户可见的 Channel 名称
            NotificationManager.IMPORTANCE_LOW       // 低优先级：静默展示
        ).apply {
            // 可选：设置 Channel 描述，帮助用户理解这个通知类别的用途
            description = "Used for foreground service notifications"
            // 可选：关闭振动（IMPORTANCE_LOW 默认就不振动，但显式设置更安全）
            enableVibration(false)
            // 可选：关闭呼吸灯
            enableLights(false)
        }
 
        // 通过 NotificationManager 注册 Channel
        val manager = context.getSystemService(NotificationManager::class.java)
        manager.createNotificationChannel(channel)   // 幂等操作，重复调用安全
    }
 
    /**
     * 构建前台服务所需的 Notification
     * @param context 上下文，用于创建 PendingIntent
     * @param title 通知标题
     * @param content 通知正文
     * @return 构建好的 Notification 对象
     */
    fun buildForegroundNotification(
        context: Context,
        title: String,
        content: String
    ): Notification {
        // 创建点击通知后跳转的 PendingIntent
        // FLAG_IMMUTABLE 是 Android 12+ 的强制要求
        val pendingIntent = PendingIntent.getActivity(
            context,                                  // 上下文
            0,                                        // requestCode，用于区分不同的 PendingIntent
            Intent(context, MainActivity::class.java),// 点击后打开的 Activity
            PendingIntent.FLAG_IMMUTABLE              // Android 12+ 必须指定 mutability
        )
 
        // 使用 NotificationCompat 构建通知，确保向下兼容
        return NotificationCompat.Builder(context, CHANNEL_ID)
            .setContentTitle(title)                   // 通知标题
            .setContentText(content)                  // 通知正文
            .setSmallIcon(R.drawable.ic_service)      // 状态栏小图标（必须设置）
            .setContentIntent(pendingIntent)          // 点击通知的跳转意图
            .setOngoing(true)                         // ongoing = true：用户无法滑动清除
            .setForegroundServiceBehavior(            // API 31+ 控制前台服务通知的展示行为
                NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE // 立即展示，不延迟
            )
            .build()                                  // 构建最终的 Notification 对象
    }
}