01 搭建后端骨架

这篇只做一件事：创建一个能启动的后端骨架。

1. 环境准备

1. JDK 21
2. Gradle（可用 wrapper）
3. PostgreSQL（后续 Jimmer/JPA 访问）

2. 创建工程

可以先用 Spring Initializr 创建 Kotlin + Spring Boot 项目，然后补依赖。
也可以直接手建目录，这里给一份与你当前项目一致的 build.gradle.kts 示例。

如果你是直接用 IDEA 新建 Kotlin 工程，建议参数按你这套配置来：

1. Language: Kotlin
2. Build system: Gradle
3. Gradle DSL: Kotlin
4. JDK: 21
5. Gradle distribution: Wrapper（也可以自己选择本地安装好的gradle）
6. Gradle version: 9.0.0（或 IDEA 自动选择）
7. GroupId: io.github.qifan777
8. ArtifactId: data-agent-backend
9. 勾选 Add sample code

可以把这一步理解成：
先用 IDEA 帮我们生成一个干净的 Kotlin/Gradle 地基，然后再补 Spring Boot、Jimmer 和项目依赖。

如果你在国内网络环境下开发，建议先补一份 settings.gradle.kts，把插件仓库和依赖仓库都切到阿里云镜像，这样比只在 build.gradle.kts 里写 mavenCentral() 更稳。

pluginManagement {
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        google()
        gradlePluginPortal()
    }
}
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}
rootProject.name = "data-agent-backend"
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        maven { url = uri("https://maven.aliyun.com/repository/google") }
        google()
        mavenCentral()
    }
}

然后 build.gradle.kts 保持业务依赖本身即可：

plugins {
    kotlin("jvm") version "2.3.0"
    id("com.google.devtools.ksp") version "2.3.0"
    id("org.springframework.boot") version "3.5.12"
    id("tech.argonariod.gradle-plugin-jimmer") version "latest.release"
}
apply(plugin = "io.spring.dependency-management")

group = "io.github.qifan777"
version = "1.0"
jimmer {
    version = "0.10.6"
}


dependencies {
    implementation("io.github.oshai:kotlin-logging-jvm:8.0.01")
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("org.postgresql:postgresql")
}
kotlin {
    jvmToolchain(21)
}

tasks.test {
    useJUnitPlatform()
}

3. 最小启动类

@EnableImplicitApi
@SpringBootApplication
open class ServerApplication

fun main(args: Array<String>) {
    runApplication<ServerApplication>(*args)
}

4. 最小配置

application.yml 最小模板：

server:
  port: 9933
spring:
  application:
    name: data-agent
  profiles:
    active: private
  datasource:
    url: jdbc:postgresql://localhost:5432/data_agent_tutorial
    username:
    password:
    driver-class-name: org.postgresql.Driver
jimmer:
  dialect: org.babyfish.jimmer.sql.dialect.PostgresDialect
  show-sql: true
  pretty-sql: true
  language: kotlin
  client:
    ts:
      path: /ts.zip
    openapi:
      path: /openapi
      ui-path: /openapi-ui

5. 启动验证

./gradlew bootRun

看到 started on port(s): 9933 即通过。

6. 常见问题

1. Could not resolve dependency jimmer-spring-boot-starter
   优先检查 settings.gradle.kts 里的仓库配置是否生效。国内网络建议按上面的方式加上阿里云镜像，不要只依赖 mavenCentral()。

2. 数据库连接失败
   先用 psql 验证账号密码，再回看 application.yml。