如何在Spring中扩展RequestParam注解以简化控制器代码？

我正在构建一个API，目前遇到单个方法参数上注解过多的问题，示例代码如下：

@Tag(name = "Messages")
@GetMapping("/{queue}/messages")
override fun getMessages(
    @PathVariable("queue") queue: String,
    @RequestParam("reason") reason: String?,
    @RequestParam("status", defaultValue = "PENDING") status: String,
    @RequestParam("start_date", required = true) @DateTimeFormat(pattern = "dd/MM/yyyy HH:mm") startDate: LocalDateTime,
    @RequestParam("end_date", required = true) @DateTimeFormat(pattern = "dd/MM/yyyy HH:mm") endDate: LocalDateTime,
    @PageableDefault(sort = ["createdAt"], direction = Sort.Direction.ASC) pageable: PageRequest,
): Page<DLQMessage> {
    return reason?.let {
        return messages.fromQueueByReason(queue, reason, startDate, endDate, pageable)
    } ?: messages.fromQueue(queue, status, startDate, endDate, pageable)
}

这类注解数量过多影响代码整洁性，我希望创建一个自定义注解来整合Spring的多个注解（如@RequestParam和@DateTimeFormat），尝试编写的自定义注解代码如下：

@Target(AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
// @RequestParam("start_date", required = true)  
// @DateTimeFormat(pattern = "dd/MM/yyyy HH:mm")
// ^ --> This annotation is not applicable to target 'annotation class'
annotation class MessageDateFilter()

若能实现，我希望在控制器方法中像这样使用：

override fun getMessages(
    @MessageDateFilter startDate: LocalDateTime
)

请问如何在Spring中实现这类Spring注解的扩展？

在Spring中可以通过**元注解（Meta-Annotation）**和@AliasFor实现自定义复合注解，整合多个Spring原生注解，具体步骤如下：

1. 修正自定义注解的目标类型 #

因为要在控制器方法参数上使用，需将自定义注解的@Target调整为支持方法参数，Kotlin中对应AnnotationTarget.VALUE_PARAMETER：

@Target(AnnotationTarget.VALUE_PARAMETER)
@Retention(AnnotationRetention.RUNTIME)

2. 添加元注解并配置属性 #

直接将Spring原生注解作为元注解添加到自定义注解上，根据需求选择固定属性或灵活配置两种方式：

方式一：固定属性的复合注解（适配你的场景） #

针对start_date和end_date的固定参数名、日期格式，分别创建专用注解：

// 处理start_date参数的注解
@Target(AnnotationTarget.VALUE_PARAMETER)
@Retention(AnnotationRetention.RUNTIME)
@RequestParam(name = "start_date", required = true)
@DateTimeFormat(pattern = "dd/MM/yyyy HH:mm")
annotation class StartDateFilter

// 处理end_date参数的注解
@Target(AnnotationTarget.VALUE_PARAMETER)
@Retention(AnnotationRetention.RUNTIME)
@RequestParam(name = "end_date", required = true)
@DateTimeFormat(pattern = "dd/MM/yyyy HH:mm")
annotation class EndDateFilter

方式二：灵活配置的复合注解（可选） #

如果后续需要调整参数名、日期格式等属性，用@AliasFor映射元注解的属性，让自定义注解支持参数传递：

@Target(AnnotationTarget.VALUE_PARAMETER)
@Retention(AnnotationRetention.RUNTIME)
@RequestParam
@DateTimeFormat
annotation class MessageDateFilter(
    @get:AliasFor(annotation = RequestParam::class, attribute = "name")
    val paramName: String,
    @get:AliasFor(annotation = RequestParam::class, attribute = "required")
    val required: Boolean = true,
    @get:AliasFor(annotation = DateTimeFormat::class, attribute = "pattern")
    val pattern: String = "dd/MM/yyyy HH:mm"
)

3. 在控制器中使用自定义注解 #

使用固定属性的注解 #

直接替换原有的多个注解，代码大幅简化：

@Tag(name = "Messages")
@GetMapping("/{queue}/messages")
override fun getMessages(
    @PathVariable("queue") queue: String,
    @RequestParam("reason") reason: String?,
    @RequestParam("status", defaultValue = "PENDING") status: String,
    @StartDateFilter startDate: LocalDateTime,
    @EndDateFilter endDate: LocalDateTime,
    @PageableDefault(sort = ["createdAt"], direction = Sort.Direction.ASC) pageable: PageRequest,
): Page<DLQMessage> {
    // 业务逻辑保持不变
}

使用灵活配置的注解 #

若用了带参数的自定义注解，按需传递属性值即可：

override fun getMessages(
    @MessageDateFilter(paramName = "start_date") startDate: LocalDateTime,
    @MessageDateFilter(paramName = "end_date") endDate: LocalDateTime,
    // 其他参数...
): Page<DLQMessage> {
    // 业务逻辑保持不变
}

4. 注意事项 #

• 元注解的作用范围必须和自定义注解的@Target匹配，比如@RequestParam支持方法参数，所以自定义注解的@Target必须包含VALUE_PARAMETER（Kotlin）或PARAMETER（Java）。
• 所有需要自定义的属性，都可以通过@AliasFor映射到对应元注解的属性上，Spring会自动识别并处理这些元注解。
• 对于@PageableDefault这类其他Spring注解，也可以用同样的方式封装，进一步简化代码。

内容的提问来源于stack exchange，提问作者Rafa Acioly