Quarkus中如何为WebSocket路径参数注册自定义UUID解码器？

你遇到的核心问题是混淆了WebSocket消息解码器和JAX-RS路径参数转换器的作用范围：@ServerEndpoint的decoders属性是用来处理WebSocket传入的消息（比如文本/二进制消息）的解码，而不是处理URL路径参数的类型转换。所以你的UuidDecoder虽然实现了WebSocket的Decoder接口，但对@PathParam("id") UUID id这个路径参数的转换完全不起作用，这才导致了UT003028: Could not find decoder for type class java.util.UUID的错误。

正确的解决方案：使用JAX-RS ParamConverterProvider #

要让JAX-RS（Quarkus基于JAX-RS规范）能够自动将路径参数的字符串转换为UUID类型，你需要实现JAX-RS的ParamConverter和ParamConverterProvider接口，并注册为提供者。

步骤1：实现UUID参数转换器

首先创建一个ParamConverter的实现类，负责字符串到UUID的转换：

import javax.ws.rs.ext.ParamConverter;
import java.util.UUID;

public class UuidParamConverter implements ParamConverter<UUID> {
    @Override
    public UUID fromString(String value) {
        if (value == null || value.isBlank()) {
            return null;
        }
        try {
            return UUID.fromString(value);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Invalid UUID format: " + value);
        }
    }

    @Override
    public String toString(UUID value) {
        return value != null ? value.toString() : null;
    }
}

步骤2：实现参数转换器提供者

然后创建ParamConverterProvider，用来为UUID类型提供对应的转换器：

import javax.ws.rs.ext.ParamConverter;
import javax.ws.rs.ext.ParamConverterProvider;
import javax.ws.rs.ext.Provider;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import java.util.UUID;

@Provider
public class UuidParamConverterProvider implements ParamConverterProvider {
    @Override
    public <T> ParamConverter<T> getConverter(Class<T> rawType, Type genericType, Annotation[] annotations) {
        if (rawType.equals(UUID.class)) {
            return (ParamConverter<T>) new UuidParamConverter();
        }
        return null;
    }
}

注意这里的@Provider注解，它会让Quarkus自动发现并注册这个转换器提供者。

步骤3：调整WebSocket端点代码

你的SearchResource不需要修改@ServerEndpoint的decoders属性（除非你需要处理WebSocket消息中的UUID），保持原来的定义即可：

import java.util.UUID;
import java.util.logging.Logger;
import javax.websocket.OnOpen;
import javax.websocket.Session;
import javax.websocket.server.PathParam;
import javax.websocket.server.ServerEndpoint;

@ServerEndpoint(value = "/api/ws/search/{id}")
public class SearchResource {
    private static final Logger LOGGER = Logger.getLogger(SearchResource.class.getName());

    @OnOpen
    public void onOpen(Session session, @PathParam("id") UUID id) {
        LOGGER.info(String.format("We get an open event! ID: %s", id));
    }
}

为什么原来的方法不行？ #

再强调一下：WebSocket的Decoder接口是为了解码WebSocket的消息体（比如客户端发送的文本消息要转换成UUID对象），而@PathParam属于JAX-RS的路径参数处理范畴，两者的处理机制完全独立，所以你之前的UuidDecoder无法作用于路径参数。

额外说明 #

如果你使用的是较新版本的Quarkus（比如2.x及以上），其实框架已经内置了UUID的路径参数转换器，不需要自定义。但你使用的是1.2.0.Final这个比较老的版本，所以需要手动实现上面的转换器。

内容的提问来源于stack exchange，提问作者Alexey Vinogradov