Restlet从1.0.10升级到2.4后带查询参数的路由映射异常

问题描述 #

Restlet从1.0.10升级到2.4版本后，原有路由逻辑失效：

• 不带dn查询参数的请求（如/operations/arrivals/comp?COMP-ID=525&GRANULARITY=DAY）本应映射到compReport.class
• 带dn查询参数的请求（如/operations/arrivals/comp?COMP-ID=525&dn=1234&GRANULARITY=DAY）本应映射到DNcompReport.class

原路由配置在1.0.10中正常，但升级后：

• 默认情况下，带dn的请求仍会匹配compReport.class
• 全局设置route.setDefaultMatchingQuery(true)后，带dn的请求能正确映射，但不带dn的请求会返回404 Not Found

原因分析 #

Restlet 2.x对路由匹配逻辑做了重大调整：

1. 默认不再将查询参数纳入路由匹配范围，原1.x中通过?{a}dn={b}的写法无法被2.x正确解析
2. 全局开启defaultMatchingQuery(true)会强制所有路由必须匹配查询参数，导致不带dn的请求因不符合任何路由的查询条件而返回404

解决方案 #

不要使用全局查询匹配，而是为单个路由配置查询参数匹配规则，确保不同请求精准命中对应处理类：

// 1. 注册不带dn参数的路由，仅匹配路径，不校验查询参数
router.attach("/operations/arrivals/comp", compReport.class);

// 2. 注册带dn参数的路由，开启查询匹配并指定匹配规则
TemplateRoute dnRoute = router.attach("/operations/arrivals/comp", DNcompReport.class);
// 开启该路由的查询参数匹配
dnRoute.setMatchingQuery(true);
// 设置模板，确保仅匹配包含dn参数的请求（参数值可任意）
dnRoute.setTemplate(new Template("/operations/arrivals/comp?dn={dn}", Template.MODE_EQUALS));

关键说明 #

• 路由注册顺序很重要：先注册不带查询参数的路由，再注册带查询参数的路由，Restlet会按顺序匹配第一个符合条件的路由
• 仅给需要匹配查询参数的路由开启setMatchingQuery(true)，不会影响其他路由的正常匹配
• Template.MODE_EQUALS表示严格匹配路径和指定的查询参数（只要存在dn参数即可，不管值是什么）

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