# Spring Boot (Kotlin) 框架指南 > 适用于：Spring Boot 3.x、Kotlin 1.9+、REST API、微服务与基本 Kotlin 模式的`.claude/skills/kotlin-guide/SKILL.md` 一起使用 ## 何时使用 * **企业应用程序**：经过验证的企业级框架，具有庞大的生态系统 * **微服务**：非常适合分布式系统的 Spring Cloud * **现有 Spring 生态系统**：利用 Spring 库、安全性、数据、云 * **复杂的业务逻辑**：复杂领域的丰富功能集 * **团队熟悉度**：具有 Java/Spring 背景并过渡到 Kotlin 的团队 ## 何时不使用 * **轻量级服务**：考虑使用 Ktor 来获得更简单、依赖性最小的服务 * **移动后端** ：Ktor 对于移动后端来说更加轻量级 * **Minimal Footprint** ：Spring Boot 具有更大的内存和启动占用空间 ## 项目结构我的项目/ ├── 构建.gradle.kts ├── 设置.gradle.kts ├── src/ │ ├── 主要/ │ │ ├── kotlin/com/example/myproject/ │ │ │ ├── MyProjectApplication.kt │ │ │ ├── 配置/ │ │ │ │ ├── SecurityConfig.kt │ │ │ │ ├── WebConfig.kt │ │ │ │ └── JwtProperties.kt │ │ │ ├── 控制器/ │ │ │ │ └── UserController.kt │ │ │ ├──服务/ │ │ │ │ └── UserService.kt │ │ │ ├── 仓库/ │ │ │ │ └── UserRepository.kt │ │ │ ├── 型号/ │ │ │ │ ├──实体/User.kt │ │ │ │ └── dto/UserDto.kt │ │ │ ├── 异常/ │ │ │ │ ├──GlobalExceptionHandler.kt │ │ │ │ └── 异常.kt │ │ │ └──安全/ │ │ │ ├── JwtService.kt │ │ │ ├── JwtAuthenticationFilter.kt │ │ │ └── CurrentUser.kt │ │ └── 资源/ │ │ ├── application.yml │ │ ├── application-dev.yml │ │ └── 数据库/迁移/ │ └── 测试/kotlin/com/example/myproject/ │ ├── 控制器/ │ ├── 服务/ │ └── 整合/ └── 自述文件.md ## 护栏 ### Spring-Kotlin 特定 * 使用构造函数注入（Kotlin默认，不需要`@Autowired`） * 永远不要使用 `lateinit var` 作为依赖项——构造函数注入是惯用的 * 对所有只读操作使用`@Transactional(readOnly = true)` * 对所有请求体参数使用`@Valid`进行自动验证 * 使用 Spring 配置文件 (`application-{profile}.yml`) 进行环境配置 * 切勿在配置文件中硬编码机密 - 使用 `${ENV_VAR:default}` 语法 * 使用`@ConfigurationProperties`数据类进行类型安全配置 * 优选使用具有“@field:”注释目标进行验证的 DTO 的 Kotlin 数据类 * 使用 `open` 修饰符或 `plugin.spring` （自动打开 `@Component` 类） ### 实体设计 * 通过“plugin.jpa”将“data class”用于JPA实体（自动生成无参数构造函数） * 优选使用“val”作为实体属性，使用“copy()”进行更新 * 使用UUID或自动生成的ID；可为空的`val id：UUID？ = null` 对于新实体 * 使用`@CreationTimestamp`和`@UpdateTimestamp`作为审计字段 * 将实体保存在`model/entity/`中，将DTO保存在`model/dto/`中 ### 服务层 * 用`@Service`标记所有服务类 * 使用`@Transactional`进行写操作，使用`@Transactional(readOnly = true)`进行读操作 * 抛出特定于域的异常（`NotFoundException`、`ConflictException`） * 从服务返回 DTO，切勿将实体暴露给控制器 * 使用 Kotlin null 安全性：对于可为 null 的查找，存储库方法返回 `T?` ### 控制器层 * 使用“@RestController”和“@RequestMapping”作为基本路径 * 返回带有显式状态码的 ResponseEntity` * 对所有传入的请求主体使用“@Valid @RequestBody” * 使用`@PreAuthorize`实现方法级安全性 * 使用`@PageableDefault`作为分页参数 ## 关键模式 ### 应用程序入口点 @SpringBootApplication 类 MyProjectApplication 有趣的主（参数：数组<字符串>）{ runApplication(*args) } ### 类型安全配置 @ConfigurationProperties（前缀=“jwt”）数据类 JwtProperties( val 秘密：字符串， val 过期时间：长，） # 应用程序.yml 智威汤逊：秘密：${JWT_SECRET:your-256-bit-secret-key-here} 过期时间：86400000 ### 具有数据类的实体 @实体 @Table(名称=“用户”) 数据类用户（ @Id @GenerateValue(策略 = GenerationType.UUID) 有效 ID：UUID？ = 空， @Column（唯一= true，可为空= false） val 电子邮件：字符串， @Column(可为空 = false) val 密码哈希：字符串， @Column(可为空 = false) 值名称：字符串， @Column(可为空 = false) val 角色: String = "USER", @CreationTimestamp @Column(可更新=假) val 创建时间：即时？ = 空， @更新时间戳 val updateAt：即时？ = 空，） ### 带验证的 DTO 数据类 CreateUserRequest( @field:NotBlank(message = "电子邮件为必填项") @field:Email(message = "电子邮件格式无效") val 电子邮件：字符串， @field:NotBlank(message = "需要密码") @field:Size(min = 8, message = "密码必须至少为 8 个字符") val 密码：字符串， @field:NotBlank(message = "姓名为必填项") @字段：大小（最小值= 1，最大值= 100）值名称：字符串，）数据类 UserResponse( 有效 ID：UUID， val 电子邮件：字符串，值名称：字符串， val 角色：字符串， val 创建时间：即时，）{ 伴生对象{ 来自（用户：用户）的乐趣：UserResponse = UserResponse（ id = 用户.id!!, 电子邮件=用户.电子邮件，名称=用户名，角色=用户.角色，创建时间=用户.创建时间!!, ） } } ### 存储库 @存储库接口 UserRepository : JpaRepository<用户，UUID> { 有趣的findByEmail（电子邮件：字符串）：用户？ fun containsByEmail(email: String): 布尔值 } ### 服务 @服务用户服务类（ private val userRepository: UserRepository, 私有 val 密码编码器：密码编码器，）{ @事务性有趣的createUser（请求：CreateUserRequest）：UserResponse { 如果（userRepository.existsByEmail（request.email））{ throw ConflictException("电子邮件已注册") } val 用户 = 用户（电子邮件=请求.电子邮件，密码Hash = 密码Encoder.encode(请求.密码), 名称 = 请求名称，）返回 UserResponse.from(userRepository.save(user)) } @Transactional(只读 = true) 有趣的 getUserById(id: UUID): UserResponse { val user = userRepository.findById(id) .orElseThrow { NotFoundException("未找到用户：$id") } 返回 UserResponse.from(用户) } @事务性有趣的 updateUser(id: UUID, 请求: UpdateUserRequest): UserResponse { val user = userRepository.findById(id) .orElseThrow { NotFoundException("未找到用户：$id") } val 更新 = user.copy( name = request.name ?: user.name, 电子邮件=请求.电子邮件？：用户.电子邮件，）返回 UserResponse.from(userRepository.save(updated)) } } ### 控制器 @RestController @RequestMapping("/api") 类用户控制器（私有val userService：UserService，）{ @PostMapping("/注册") 有趣的寄存器（ @Valid @RequestBody 请求：CreateUserRequest， ): ResponseEntity<用户响应> { val user = userService.createUser(请求) 返回 ResponseEntity.status(HttpStatus.CREATED).body(用户) } @GetMapping("/users/{id}") @PreAuthorize("hasRole('ADMIN') 或 @userSecurity.isOwner(#id, 身份验证)") fun getUser(@PathVariable id: UUID): ResponseEntity { 返回 ResponseEntity.ok(userService.getUserById(id)) } @GetMapping(“/用户”) @PreAuthorize("hasRole('ADMIN')") 有趣的 getAllUsers( @PageableDefault(size = 20) 可分页：可分页， ): ResponseEntity<页面<用户响应>> { 返回 ResponseEntity.ok(userService.getAllUsers(可分页)) } } ### 异常处理类 NotFoundException(消息：字符串) : RuntimeException(消息) 类 UnauthorizedException(消息: String) : RuntimeException(消息) 类冲突异常（消息：字符串）：运行时异常（消息）数据类错误响应（ val 时间戳：Instant = Instant.now(), val状态：Int，值错误：字符串， val 消息：字符串， val 详细信息：List? = 空，） @RestControllerAdvice 类 GlobalExceptionHandler { @ExceptionHandler(NotFoundException::类) 有趣的handleNotFound（例如：NotFoundException）= ResponseEntity .status(HttpStatus.NOT_FOUND) .body(ErrorResponse(状态= 404，错误=“NOT_FOUND”，消息= ex.message？：“未找到”)) @ExceptionHandler(MethodArgumentNotValidException::class) 有趣的handleValidation（例如：MethodArgumentNotValidException）：ResponseEntity { val 详细信息 = ex.bindingResult.fieldErrors.map { "${it.field}: ${it.defaultMessage}" } 返回 ResponseEntity.status(HttpStatus.BAD_REQUEST) .body(ErrorResponse(状态= 400，错误=“VALIDATION_ERROR”，消息=“验证失败”，详细信息=详细信息)) } } ### 安全配置 @配置 @EnableWebSecurity @EnableMethodSecurity 类安全配置（私有val jwtAuthenticationFilter：JwtAuthenticationFilter，）{ @豆子有趣的 securityFilterChain(http: HttpSecurity): SecurityFilterChain = http .csrf { it.disable() } .sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) } .authorizeHttpRequests { 授权 -> 授权 .requestMatchers("/api/register", "/api/login").permitAll() .requestMatchers("/health/**", "/actuator/**").permitAll() .anyRequest().authenticated() } .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter::class.java) .build() @豆子有趣的密码编码器（）：密码编码器= BCryptPasswordEncoder（12） } ### 当前用户的自定义注释 @Target(AnnotationTarget.VALUE_PARAMETER) @Retention(AnnotationRetention.RUNTIME) @AuthenticationPrincipal 注释类CurrentUser ## 协程集成 Spring Boot 在控制器和服务中支持 Kotlin 协程。添加这些依赖项：实现（“org.jetbrains.kotlinx：kotlinx-coroutines-core”）实现（“org.jetbrains.kotlinx：kotlinx-coroutines-reactor”）控制器中的挂起功能由 Spring WebFlux 自动处理： @GetMapping("/users/{id}") 暂停乐趣 getUser(@PathVariable id: UUID): ResponseEntity { val 用户 = userService.getUserById(id) 返回 ResponseEntity.ok(用户) } 有关详细的协程、WebFlux、测试和高级安全模式，请参阅 [references/patterns.md]()。 ## 命令 # 开发 ./gradlew boot运行 # 构建 ./gradlew 构建 # 测试 ./gradlew测试 # 覆盖率测试 ./gradlew 测试 jacocoTestReport # 格式（使用 ktlint） ./gradlew ktlintFormat # 棉绒 ./gradlew ktlintCheck # 构建 JAR ./gradlew bootJar # 运行 JAR java -jar build/libs/myproject-0.0.1-SNAPSHOT.jar # Docker 构建 docker build -t myproject 。 ## 最佳实践 ### 做 * 使用 DTO 和实体的数据类 * 使用 Kotlin null 安全功能（`?.`、`?:`、`requireNotNull`） * 使用`@Transactional(readOnly = true)`进行读操作 * 使用构造函数注入（Kotlin 中默认） * 使用`@Valid`进行请求验证 * 使用Spring profile进行环境配置 * 使用`@field:`注释目标对数据类属性进行验证注释 * 在有益的情况下使用协程进行异步操作 ### 不要 * 使用 `lateinit var` 作为依赖项（使用构造函数注入） * 忽略 Spring Data 存储库中的 null 安全性 * 使用 `!!` 运算符而不进行适当的空检查 * 在同一调用链中混合反应式代码和阻塞式代码 * 将秘密存储在配置文件中 * 直接在控制器响应中公开 JPA 实体 ## 参考文献有关详细模式和示例，请参阅： * [references/patterns.md]() \-- WebFlux 反应模式、JPA 高级模式、测试、安全高级模式 ## 外部参考 * [Spring Boot 文档]() * [Spring Kotlin 支持]() * [Spring 安全]() * [Spring Data JPA]() * [Kotlin + Spring Boot 指南]()

Spring Boot Kotlin

包含技能