Kotlin 编码规范¶

// 好：尾随逗号让 diff 更干净，重排更安全
val event = CollectorEvent(
    timestampMs = now,
    source = "usage_stats",
    eventType = eventType,
    packageName = event.packageName,
    className = event.className,
    deviceContext = snapshot(context),
    rawPayload = JSONObject()
        .put("usageEventType", event.eventType)
        .put("configuration", event.configuration?.toString()),
)

// 差
val data = parse(s)
val result = execute(data)

// 好
val event = parseRawNotification(sbn)
val exitCode = execute(event)

companion object {
    const val ACTION_START = "com.dipecs.collector.action.START"
    const val ACTION_STOP = "com.dipecs.collector.action.STOP"
    const val ACTION_UPLOAD_NOW = "com.dipecs.collector.action.UPLOAD_NOW"

    private const val CHANNEL_ID = "dipecs_collector"
    private const val NOTIFICATION_ID = 1101
    private const val USAGE_POLL_INTERVAL_MS = 5_000L
}

// 好
private const val POLL_INTERVAL_MS = 5_000L
private const val UPLOAD_TIMEOUT_MS = 10_000L
private const val MAX_FILE_SIZE = 1_048_576L

// 差
private const val POLL_INTERVAL_MS = 5000L

// CloudUploader.kt
object CloudUploader {
    // ...
}

// 与 CloudUploader 紧密耦合的私有类型，可放同文件
private data class HttpResponse(val code: Int, val body: String)

class CollectorForegroundService : Service() {
    // 1. 属性（val / var / lateinit var）
    private val handler = Handler(Looper.getMainLooper())
    private lateinit var usageCollector: UsageCollector
    private var running = false

    // 2. init 块 / 回调对象
    private val pollRunnable = object : Runnable { ... }

    // 3. 生命周期方法（public）
    override fun onCreate() { ... }
    override fun onStartCommand(...) { ... }
    override fun onDestroy() { ... }
    override fun onBind(...) { ... }

    // 4. 私有方法
    private fun startCollector() { ... }
    private fun stopCollector() { ... }

    // 5. companion object（放最后）
    companion object {
        const val ACTION_START = "..."
        private const val CHANNEL_ID = "..."
    }
}

// 差：绕过了空安全检查
val pkg = event.packageName!!
val name = pkg.substring(1)

// 好：安全链式处理
val firstChar = event.packageName?.firstOrNull() ?: '?'

// 好：需要非空值时提前检查并及早返回
val pkg = event.packageName ?: return
val name = pkg.substring(1)

// 好：需要非空值时抛明确错误
val pkg = event.packageName
    ?: throw IllegalStateException("packageName must not be null for foreground event")

// 链式安全调用
val className = event.className?.takeIf { it.isNotBlank() }

// Elvis 提供默认值
val target = appContext.getExternalFilesDir(null) ?: appContext.filesDir

// 链式操作
deviceContext?.toJson() ?: JSONObject.NULL

// 好：立即用类型标注收窄
val manager: UsageStatsManager? = context.getSystemService(UsageStatsManager::class.java)
    ?: return

// 好：如果确定不会空，用 ?: return 及早退出
val nm = getSystemService(NotificationManager::class.java) ?: return

// 可接受：在 onCreate 中初始化
class CollectorForegroundService : Service() {
    private lateinit var usageCollector: UsageCollector

    override fun onCreate() {
        super.onCreate()
        usageCollector = UsageCollector(this)
    }
}

// 差：应该有默认值而非 lateinit
private lateinit var name: String  // 为什么不直接用 val + lazy 或默认值？

data class CollectorEvent(
    val eventId: String = UUID.randomUUID().toString(),
    val timestampMs: Long = System.currentTimeMillis(),
    val source: String,
    val eventType: String,
    val packageName: String? = null,
    val className: String? = null,
    val windowTitle: String? = null,
    val text: String? = null,
    val action: String? = null,
    val deviceContext: DeviceContext? = null,
    val rawEvent: JSONObject? = null,
    val rawPayload: JSONObject = JSONObject(),
)

data class MyType(
    // 1. 必填参数（无默认值）
    val source: String,
    val eventType: String,
    // 2. 可选参数（有默认值）
    val packageName: String? = null,
    val timestampMs: Long = System.currentTimeMillis(),
    // 3. 复杂对象（有默认值）
    val rawPayload: JSONObject = JSONObject(),
)

// 差：这不是数据类
data class EventStore(val context: Context) {  // Context 不应参与 equals
    fun append(event: CollectorEvent) { ... }
}

// 好：普通 class
class EventStore(context: Context) {
    private val appContext = context.applicationContext
    fun append(event: CollectorEvent) { ... }
}

// 差
fun eventName(eventType: Int): String {
    if (eventType == UsageEvents.Event.MOVE_TO_FOREGROUND) return "move_to_foreground"
    else if (eventType == UsageEvents.Event.MOVE_TO_BACKGROUND) return "move_to_background"
    else if (eventType == UsageEvents.Event.SCREEN_INTERACTIVE) return "screen_interactive"
    else return "usage_event_$eventType"
}

// 好：when 表达式让编译器检查穷举性
fun eventName(eventType: Int): String = when (eventType) {
    UsageEvents.Event.MOVE_TO_FOREGROUND -> "move_to_foreground"
    UsageEvents.Event.MOVE_TO_BACKGROUND -> "move_to_background"
    UsageEvents.Event.SCREEN_INTERACTIVE -> "screen_interactive"
    UsageEvents.Event.SCREEN_NON_INTERACTIVE -> "screen_non_interactive"
    UsageEvents.Event.KEYGUARD_SHOWN -> "keyguard_shown"
    UsageEvents.Event.KEYGUARD_HIDDEN -> "keyguard_hidden"
    UsageEvents.Event.ACTIVITY_RESUMED -> "activity_resumed"
    UsageEvents.Event.ACTIVITY_PAUSED -> "activity_paused"
    UsageEvents.Event.ACTIVITY_STOPPED -> "activity_stopped"
    else -> "usage_event_$eventType"
}

// 作为表达式（有返回值）——每个分支必须有返回
val result = when (action) {
    ACTION_START -> startCollector()
    ACTION_STOP -> stopCollector()
    ACTION_UPLOAD_NOW -> CloudUploader.uploadRecent(this, reason = "manual")
    else -> START_STICKY
}

// 作为语句（无返回值）——用于副作用
when {
    isForegroundEvent(event.eventType) -> handleForeground(event)
    isBackgroundEvent(event.eventType) -> handleBackground(event)
    event.eventType == SCREEN_INTERACTIVE -> handleScreenOn(event)
}

// Kotlin 的 if 可以返回值
val builder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    Notification.Builder(this, CHANNEL_ID)
} else {
    @Suppress("DEPRECATION")
    Notification.Builder(this)
}

// 差：箭头式嵌套
fun collect() {
    if (enabled) {
        val manager = getSystemService(...)
        if (manager != null) {
            val events = manager.query(...)
            if (events != null) {
                // 三层缩进后才到实际逻辑
            }
        }
    }
}

// 好：及早返回
fun collect() {
    if (!CollectorPreferences.isUsageEnabled(appContext)) return
    val manager = appContext.getSystemService(UsageStatsManager::class.java) ?: return
    val events = runCatching { manager.queryEvents(start, now) }.getOrNull() ?: return
    // 实际逻辑在这里，零缩进
}

// 差：try-catch 样板代码
val events: UsageEvents? = try {
    usageStatsManager.queryEvents(start, now)
} catch (e: Exception) {
    null
}
if (events == null) return

// 好：runCatching 链式处理
val events = runCatching { usageStatsManager.queryEvents(start, now) }
    .getOrNull() ?: return

// 更好：需要区分成功/失败时
runCatching {
    postJson(endpoint, payload, bearerToken)
}.onSuccess { response ->
    EventRepository.recordInternal(ctx, "upload_success", "...")
}.onFailure { error ->
    EventRepository.recordInternal(ctx, "upload_failed", error.message ?: "...")
}

// 可接受：不可恢复的编程错误
val pkg = event.packageName
    ?: throw IllegalStateException("packageName must not be null for foreground event")

// 差：用异常控制正常业务流程
fun upload(endpoint: String) {
    if (endpoint.isBlank()) throw IllegalArgumentException("endpoint is blank")
    // 调用者被迫用 try-catch 来处理这种"正常"情况
}

// 好：对于可恢复的错误用 Result 或 null 返回
fun upload(endpoint: String): Result<HttpResponse> {
    if (endpoint.isBlank()) return Result.failure(IllegalArgumentException("endpoint is blank"))
    // ...
}

// 在协程作用域中使用 supervisorScope 隔离错误
suspend fun collectAll() = supervisorScope {
    launch { collectUsage() }
    launch { collectDeviceContext() }
    launch { upload() }
    // 三个子协程互不影响——collectUsage 失败不影响 collectDeviceContext
}

// 不要用 coroutineScope，它会在任一子协程失败时取消所有兄弟

// 好：绑定到生命周期
class CollectorViewModel : ViewModel() {
    fun start() {
        viewModelScope.launch {
            while (isActive) {
                collect()
                delay(POLL_INTERVAL_MS)
            }
        }
    }
}

// 差：自由漂浮的协程
fun start() {
    GlobalScope.launch {  // 永远不会取消，泄漏
        while (true) {
            collect()
            delay(POLL_INTERVAL_MS)
        }
    }
}

// 所有 suspend 函数必须是可取消的
suspend fun processEvents(events: List<CollectorEvent>) {
    for (event in events) {
        // 每次迭代检查协程是否被取消
        ensureActive()
        processOne(event)
    }
}

// 或者使用 yield 让出执行权
suspend fun heavyComputation() {
    repeat(1000) { i ->
        doChunk(i)
        yield()  // 检查取消信号
    }
}

// 本项目中 Handler + Runnable 模式用于非协程场景
private val handler = Handler(Looper.getMainLooper())
handler.postDelayed(pollRunnable, POLL_INTERVAL_MS)

// 后台任务用 Executors（项目当前做法，见 CloudUploader）
private val executor = Executors.newSingleThreadExecutor()
executor.execute { /* 后台 I/O */ }

// let：可空链式处理
val pkg = event.packageName?.takeIf { it.isNotBlank() }?.let { sanitize(it) }

// apply：配置对象
val payload = JSONObject().apply {
    put("schema", "dipecs.collector.v1")
    put("reason", reason)
    put("events", JSONArray(events))
}

// also：副作用（日志/调试）
val result = compute().also { log("computed: $it") }

// takeIf：条件过滤
val validName = name?.takeIf { it.isNotBlank() } ?: return null

// 差：let 链式调用过长，难以阅读
val result = data?.let { parse(it) }?.let { validate(it) }?.let { transform(it) }
    ?: default

// 好：提前返回，逻辑清晰
val parsed = data?.let { parse(it) } ?: return default
if (!validate(parsed)) return default
return transform(parsed)

// 好：纯函数/委托性质的单例
object EventRepository {
    fun record(context: Context, event: CollectorEvent) {
        EventStore(context).append(event)
    }
}

object CloudUploader {
    fun uploadRecent(context: Context, reason: String = "manual") { ... }
}

class CollectorEvent(
    val source: String,
    ...
) {
    companion object {
        // 工厂方法
        fun fromNotification(sbn: StatusBarNotification): CollectorEvent = ...

        // 常量
        private const val SCHEMA_VERSION = "dipecs.collector.v1"
    }
}

// CollectorForegroundService：只管生命周期和调度
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
    when (intent?.action ?: ACTION_START) {
        ACTION_START -> startCollector()
        ACTION_STOP -> stopCollector()
        ACTION_UPLOAD_NOW -> CloudUploader.uploadRecent(this, reason = "manual")
    }
    return START_STICKY
}

// UsageCollector：只管采集逻辑（不知道自己在 Service 中运行）
class UsageCollector(private val context: Context) {
    fun collectSinceLastPoll() { ... }
}

class EventStore(context: Context) {
    private val appContext = context.applicationContext  // 安全
    // ...
}

// 在 Service 内部传给工具类时
EventRepository.record(this, event)  // Service this 等同于 applicationContext

// 好：线程模型清楚
class UsageCollector(private val context: Context) {
    /**
     * 采集自上次轮询以来的 UsageEvents 并写入 EventStore。
     *
     * 此方法可被 Handler post 到主线程调用（API < 28 时 queryEvents 有主线程限制）。
     */
    fun collectSinceLastPoll() { ... }
}

object CloudUploader {
    // 所有网络 I/O 在单线程 executor 中执行，调用者可在任意线程调用
    fun uploadRecent(context: Context, reason: String = "manual") { ... }
}

companion object {
    const val ACTION_START = "com.dipecs.collector.action.START"
    const val ACTION_STOP = "com.dipecs.collector.action.STOP"
    const val ACTION_UPLOAD_NOW = "com.dipecs.collector.action.UPLOAD_NOW"
}

val builder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    Notification.Builder(this, CHANNEL_ID)
} else {
    @Suppress("DEPRECATION")
    Notification.Builder(this)
}

// 格式：test<method>__<scenario>
@Test
fun testAppTransition__validPackage_returnsEvent() { ... }

@Test
fun testAppTransition__nullPackage_returnsNull() { ... }

@Test
fun testScreenState__allStates_haveValidJson() { ... }

@Test
fun testAppTransition() {
    val json = AndroidRawEventMapper.appTransition(
        timestampMs = 1000L,
        packageName = "com.test.app",
        activityClass = "MainActivity",
        transition = "Foreground",
    )
    assertEquals("com.test.app", json.getString("packageName"))
    assertEquals("Foreground", json.getString("transition"))
    assertEquals(1000L, json.getLong("timestampMs"))
}

/**
 * 采集自上次轮询以来的 [UsageEvents.Event] 并存储到 [EventStore]。
 *
 * 在 API < 28 时，[UsageStatsManager.queryEvents] 必须在主线程调用，
 * 因此此方法通过 [Handler] 在主线程事件循环中执行。
 *
 * 采集完成后更新 [CollectorPreferences.lastUsageQueryMs] 以避免重复采集。
 */
fun collectSinceLastPoll() { ... }

// 好
@Suppress("DEPRECATION")  // 此分支仅在 API < 26 时执行，旧设备无 NotificationChannel
Notification.Builder(this)

// 差：没有解释为什么 suppress
@Suppress("DEPRECATION")
Notification.Builder(this)

// build.gradle.kts
dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.1")
}