项目工程搭建与依赖配置：Gradle 协程依赖、模块划分、日志与测试框架初始化

1 为什么需要工程化模块划分？

Kotlin 协程轻量级后台队列在实际项目中，需要与业务代码、第三方库、测试环境解耦。合理的模块划分可以实现：

• 依赖控制：核心队列模块只依赖协程基础库，避免引入无关的 Android 或 Web 框架。
• 测试隔离：测试模块可单独配置模拟协程调度器，不影响生产模块。
• 日志解耦：通过 slf4j 门面统一日志输出，方便切换 Logback、Log4j 等实现。
• 编译加速：模块变更只重新编译影响的部分，大型项目优势明显。

2 工程结构总览

推荐使用 Gradle 多模块结构，根项目作为聚合工程，包含以下子模块：

模块名	职责	关键依赖
queue-core	协程后台队列核心实现（调度器、任务包装、生命周期）	kotlinx-coroutines-core, kotlin-logging
queue-test	单元测试、集成测试、模拟协程调度器	kotlin-test, kotlinx-coroutines-test, JUnit5
queue-app（可选）	示例应用程序，展示队列使用方式	依赖 queue-core

每个模块的 src/main/kotlin 和 src/test/kotlin 目录存放对应的源码与测试代码。

3 Gradle 依赖配置

3.1 根项目 build.gradle.kts

声明插件版本与子模块公共配置：

plugins {
    kotlin("jvm") version "1.9.22" apply false
}
subprojects {
    apply(plugin = "kotlin")
    group = "com.example.queue"
    version = "1.0.0"
    repositories {
        mavenCentral()
    }
}

3.2 queue-core 模块配置

plugins {
    kotlin("jvm")
}
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
    implementation("io.github.microutils:kotlin-logging:3.0.5")
    implementation("ch.qos.logback:logback-classic:1.4.14")
}

3.3 queue-test 模块配置

plugins {
    kotlin("jvm")
}
dependencies {
    implementation(project(":queue-core"))
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")
    testImplementation("org.jetbrains.kotlin:kotlin-test:1.9.22")
}
tasks.test {
    useJUnitPlatform()
}

3.4 版本统一管理（可选）

在根项目的 gradle.properties 中集中定义版本号，避免散落：

kotlinVersion=1.9.22
coroutinesVersion=1.8.0
junitVersion=5.10.0

然后在各模块中引用：version = rootProject.property("coroutinesVersion")。

4 日志框架初始化

在 queue-core 中添加日志输出工厂类，确保使用 Kotlin Logging 门面：

// src/main/kotlin/com/example/queue/core/Logging.kt
import mu.KotlinLogging

object QueueLogger {
    private val logger = KotlinLogging.logger {}
    fun info(msg: String) = logger.info { msg }
    fun error(msg: String, t: Throwable? = null) = logger.error(t) { msg }
}

同时在 src/main/resources/logback.xml 中配置输出格式（默认打印到控制台）：

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

5 测试框架初始化与验证

在 queue-test 中编写一个简单的协程测试，验证依赖是否正常扫描：

// src/test/kotlin/com/example/queue/test/SampleTest.kt
import kotlinx.coroutines.test.runTest
import org.junit.jupiter.api.Test
import kotlin.test.assertEquals

class SampleTest {
    @Test
    fun `coroutines test runtime works`() = runTest {
        val result = kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.Default) {
            "Hello from coroutine"
        }
        assertEquals("Hello from coroutine", result)
    }
}

执行 ./gradlew queue-test:test，输出应包含类似：

BUILD SUCCESSFUL in 3s
4 tests completed, 0 failed

6 常见错误与解决方案

7 本章小结

通过本章的项目搭建，我们获得了：

• 一个清晰的 Gradle 多模块工程骨架，核心与测试职责分离。
• 正确的协程、日志、测试依赖版本组合，避免运行时的 ClassNotFoundException。
• 可工作的日志输出与测试环境，为后续章节中队列的具体实现和调试奠定了基础。