When should I use 15-parameter-validation?

15-parameter-validation is useful in the following scenarios: • Standardizing API input validation: Using JSR-303 and custom annotations to automatically validate incoming request parameters at the Resource layer. • Custom Business Rule Enforcement: Implementing specific validation patterns such as 'CODE_STYLE' or 'ID_STYLE' using regex-based custom annotations. • Unified Error Handling: Utilizing custom exceptions (ErrorCodeException) and standardized error codes to provide consistent and user-friendly API error responses. • Multi-layer Data Integrity: Applying validation strategies across both API and Service layers to ensure data consistency throughout the application lifecycle. • Internationalization (i18n): Configuring error messages for global applications to provide localized feedback when validation fails.

15-parameter-validation

from TencentBlueKing

参数校验指南，涵盖 JSR-303 注解校验、自定义校验器、分组校验、嵌套校验、错误消息国际化。当用户实现参数校验、编写自定义校验注解、处理校验错误或配置校验分组时使用。

⭐2.5kstars🔀514forks📁View on GitHub🕐Updated Jan 9, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive guide for implementing robust parameter validation in software development, specifically tailored for Kotlin and Java environments. It covers JSR-303 standards, custom annotation design (like @BkField), nested validation, and internationalized error handling to ensure data integrity, enhance API security, and streamline developer workflows.

Use Cases

Standardizing API input validation: Using JSR-303 and custom annotations to automatically validate incoming request parameters at the Resource layer.
Custom Business Rule Enforcement: Implementing specific validation patterns such as 'CODE_STYLE' or 'ID_STYLE' using regex-based custom annotations.
Unified Error Handling: Utilizing custom exceptions (ErrorCodeException) and standardized error codes to provide consistent and user-friendly API error responses.
Multi-layer Data Integrity: Applying validation strategies across both API and Service layers to ensure data consistency throughout the application lifecycle.
Internationalization (i18n): Configuring error messages for global applications to provide localized feedback when validation fails.

name	15-parameter-validation
description	参数校验指南，涵盖 JSR-303 注解校验、自定义校验器、分组校验、嵌套校验、错误消息国际化。当用户实现参数校验、编写自定义校验注解、处理校验错误或配置校验分组时使用。

name

15-parameter-validation

description

参数校验

参数校验指南.

触发条件

当用户需要实现 API 参数校验、数据验证时，使用此 Skill。

@BkField 注解

@Target(AnnotationTarget.FIELD, AnnotationTarget.VALUE_PARAMETER)
@Retention(AnnotationRetention.RUNTIME)
annotation class BkField(
    val patternStyle: BkStyleEnum = BkStyleEnum.DEFAULT,
    val required: Boolean = false,
    val minLength: Int = -1,
    val maxLength: Int = -1,
    val message: String = ""
)

使用示例

interface UserPipelineResource {
    @POST
    @Path("/")
    fun create(
        @Parameter(description = "用户ID", required = true)
        @HeaderParam(AUTH_HEADER_USER_ID)
        @BkField(required = true, minLength = 1, maxLength = 64)
        userId: String,
        
        @Parameter(description = "项目ID", required = true)
        @PathParam("projectId")
        @BkField(patternStyle = BkStyleEnum.CODE_STYLE)
        projectId: String,
        
        @Parameter(description = "流水线名称", required = true)
        @BkField(required = true, minLength = 1, maxLength = 128)
        pipelineName: String
    ): Result<PipelineId>
}

校验模式

模式	说明	正则
`DEFAULT`	默认	无
`CODE_STYLE`	代码风格	`^[a-zA-Z][a-zA-Z0-9_-]*$`
`ID_STYLE`	ID 风格	`^[a-zA-Z0-9_-]+$`

ErrorCodeException

throw ErrorCodeException(
    statusCode = 400,
    errorCode = "2100013",
    defaultMessage = "无效参数",
    params = arrayOf(paramName)
)

常用错误码

错误码	说明
2100001	系统内部错误
2100013	参数校验失败
2119042	资源不存在

手动校验

fun validateParams(projectId: String, pipelineId: String) {
    if (projectId.isBlank()) {
        throw ErrorCodeException(
            errorCode = "2100013",
            defaultMessage = "projectId 不能为空"
        )
    }
    if (pipelineId.length > 64) {
        throw ErrorCodeException(
            errorCode = "2100013",
            defaultMessage = "pipelineId 长度不能超过64"
        )
    }
}

最佳实践

API 层校验：在 Resource 接口层使用注解校验
业务层校验：复杂业务逻辑在 Service 层校验
统一错误码：使用项目定义的错误码
友好提示：提供清晰的错误信息