URL路径中UUID使用最佳实践及Jackson解析异常咨询

1. 用引号包裹UUID是不是最佳实践？ #

绝对不是。REST API的URL路径里，UUID作为字符串类型的路径段，就该直接传原始格式（比如/endpoint/550e8400-e29b-41d4-a716-446655440000），加引号完全是画蛇添足——不仅增加客户端调用的麻烦，还可能导致路由匹配失败、参数解析逻辑混乱，完全不符合REST设计的简洁原则。

2. 正确的解决方式（含Jackson配置） #

你遇到的核心问题是Jackson把UUID字符串误当成数值解析了，根本不需要靠引号绕路，直接从根源解决：

先纠正最基础的问题：参数类型绑定 #

在Kotlin的API接口里，把路径参数的类型明确写成UUID（不管是java.util.UUID还是Kotlin标准库的kotlin.UUID），别写成数字类型（比如Long、Int）。举个Spring Boot的例子：

@GetMapping("/endpoint/{uuid}")
fun getResource(@PathVariable uuid: UUID): ResponseEntity<Resource> {
    // 业务逻辑实现
}

这么写的话，Jackson会自动识别UUID类型，按字符串格式解析，不会再把它当成数值瞎处理。

全局Jackson配置（适配所有UUID场景） #

如果项目里有很多UUID参数需要统一处理，可以全局配置Jackson，强制它把UUID按字符串解析：

@Configuration
class JacksonConfig {
    @Bean
    fun objectMapper(): ObjectMapper {
        return ObjectMapper()
            .registerModule(KotlinModule()) // 必须注册Kotlin模块
            .registerModule(JavaTimeModule())
            // 关闭之前错误开启的ALLOW_LEADING_ZEROS_FOR_NUMBERS，这个配置只针对数值，和UUID无关
            .disable(DeserializationFeature.ALLOW_LEADING_ZEROS_FOR_NUMBERS)
            // 注册UUID专用的序列化/反序列化器
            .also {
                it.registerModule(SimpleModule().apply {
                    addSerializer(UUID::class.java, UUIDSerializer())
                    addDeserializer(UUID::class.java, UUIDDeserializer())
                })
            }
    }
}

// 自定义UUID序列化器，确保输出格式正确
class UUIDSerializer : StdSerializer<UUID>(UUID::class.java) {
    override fun serialize(value: UUID?, gen: JsonGenerator?, provider: SerializerProvider?) {
        gen?.writeString(value?.toString())
    }
}

// 自定义UUID反序列化器，强制按字符串解析
class UUIDDeserializer : StdDeserializer<UUID>(UUID::class.java) {
    override fun deserialize(p: JsonParser?, ctxt: DeserializationContext?): UUID {
        return UUID.fromString(p?.text)
    }
}

局部字段配置（单字段适配） #

如果只是个别字段需要处理，直接在字段上加注解，强制Jackson按字符串解析：

data class Resource(
    @JsonFormat(shape = JsonFormat.Shape.STRING)
    val id: UUID,
    // 其他字段
)

关键提醒 #

之前你开启的ALLOW_LEADING_ZEROS_FOR_NUMBERS完全是走错方向了——这个配置是用来允许数值类型有前导零的，和UUID字符串半毛钱关系都没有，赶紧关掉它，避免引入其他解析问题。

内容的提问来源于stack exchange，提问作者Salvador Bascunan