Coding Tips

Field Annotations

在 Kotlin 中对同一个属性使用多个注解，有两种常见写法：

逐个写（最直观）

data class SyncDTO(
    @field:NotBlank
    @field:Size(max = 64)
    var stable: String,

    @field:NotNull
    @field:PastOrPresent
    var startTime: Date,

    @field:NotNull
    @field:FutureOrPresent
    var endTime: Date
)

同一使用位置用"方括号聚合"

当多个注解都贴在同一个使用位置（如都贴到 field）时，可以用方括号一次性写

data class SyncDTO(
    @field:[NotBlank Size(max = 64)]
    var stable: String,

    @field:[NotNull PastOrPresent]
    var startTime: Date,

    @field:[NotNull FutureOrPresent]
    var endTime: Date
)

混合不同使用位置

如果不同注解需要贴到不同的位置（比如有的要贴 field ，有的要贴 get ），就分别指明：

data class User(
    @field:[NotBlank Size(max = 32)]
    @get:Schema(description = "用户名")
    val name: String
)

上面 NotBlank、Size 贴在字段；Schema 贴在 getter。

校验分组与嵌套校验

分组

interface Create
interface Update

data class Dto(
    @field:NotBlank(groups = [Create::class])
    @field:Size(max = 64, groups = [Create::class, Update::class])
    val code: String
)

嵌套对象列表校验

import jakarta.validation.Valid
import jakarta.validation.constraints.*

data class Order(
    @field:NotNull
    @field:Size(min = 1)
    @field:Valid // 确保嵌套对象也会被校验
    val items: List<OrderItem>
)

27 January 2026