如何在Java REST API中通过不同查询参数重载Micronaut端点？

你遇到的DuplicateRouteException是因为Micronaut（以及大多数JVM Web框架）的路由匹配逻辑不会把查询参数的存在/数量作为区分路由的依据——它只认HTTP方法和请求路径，所以两个@Get("/query")的方法会被判定为重复路由。

不过要实现“根据不同查询参数映射到不同方法”的需求是可行的，下面给你两种常用方案：

方案1：合并方法，处理参数可选性 #

最直接的方式是把两个方法合并成一个，将可选的参数标记为可空，然后在方法内部根据参数是否存在来分支处理逻辑。这样既能保持端点统一，又能拆分业务逻辑：

@Get("/query")
public MyResponse query(
    @QueryValue @Valid @Format("yyyy-MM-dd") Date date,
    @QueryValue @Nullable Integer value // 标记为可空参数
) {
    if (value != null) {
        // 调用原date+value的业务逻辑
        return handleDateAndValueQuery(date, value);
    } else {
        // 调用原仅date的业务逻辑
        return handleDateOnlyQuery(date);
    }
}

// 把原业务逻辑抽成私有方法，保持代码整洁
private MyResponse handleDateOnlyQuery(Date date) {
    // 生成响应的代码
    return retval;
}

private MyResponse handleDateAndValueQuery(Date date, int value) {
    // 生成响应的代码
    return retval;
}

这种方案适合两个逻辑差异不大的场景，代码简洁易维护，还能避免路由冲突。

方案2：使用Micronaut的@Requires条件路由 #

如果你希望两个业务逻辑完全分开维护，可以用Micronaut提供的@Requires注解，给每个方法添加路由激活条件——只有当请求满足指定的参数条件时，对应的方法才会被匹配：

// 仅当请求包含date参数、且不包含value参数时激活
@Get("/query")
@Requires(requestParams = "date")
@Requires(notRequestParams = "value")
public MyResponse queryByDate(@QueryValue @Valid @Format("yyyy-MM-dd") Date date) {
    // 生成响应的代码
    return retval;
}

// 仅当请求同时包含date和value参数时激活
@Get("/query")
@Requires(requestParams = {"date", "value"})
public MyResponse queryByDateAndValue(
    @QueryValue @Valid @Format("yyyy-MM-dd") Date date,
    @QueryValue int value
) {
    // 生成响应的代码
    return retval;
}

注意：这种方式要考虑边界情况，比如如果请求只传value不传date，两个路由都不会匹配，会返回404，你可以根据需求添加额外的错误处理逻辑。

总结 #

直接像Java方法重载那样定义同路径、同HTTP方法的控制器方法是不行的，但通过上面两种方式，完全可以实现“根据不同查询参数映射到不同业务逻辑”的效果。如果逻辑差异小，优先选方案1；如果逻辑完全独立，方案2会更合适。

内容的提问来源于stack exchange，提问作者Jon Hill