如何验证JBoss 7.4是否读取生效undertow-handlers.conf

第一步：确认配置基础正确性 #

• 检查部署后实际展开的应用目录，确认WEB-INF路径下存在名为undertow-handlers.conf的文件，文件名完全匹配（注意是复数handlers，不要漏写s，大小写完全一致），文件编码为UTF-8无BOM头。
• 如果是EAR包嵌套WAR部署，配置文件必须放在对应子WAR的WEB-INF目录下，放在EAR层级目录不会生效。
• 排查构建流程，确认Maven/Gradle等构建工具没有把该配置文件过滤掉，最终打包进WAR的文件内容和本地编写的一致。

第二步：开启DEBUG日志确认加载流程 #

默认INFO级别日志不会输出undertow-handlers.conf的加载过程，需要手动调整日志级别，执行以下JBoss CLI命令即可：

connect
/subsystem=logging/logger=io.undertow.servlet.handlers:add(level=DEBUG)
/subsystem=logging/logger=io.undertow.server.handlers.builder:add(level=DEBUG)

配置完成后重启对应应用或整个JBoss实例：

• 如果日志中出现Parsing handler chain from WEB-INF/undertow-handlers.conf相关输出，说明文件被成功识别
• 如果完全没有相关输出，说明配置文件未被部署扫描器识别，回到第一步检查文件位置和打包结果
• 如果出现参数解析错误日志，根据提示修正配置语法即可

第三步：修正现有配置的语法问题 #

当前使用的配置存在两处问题，会直接导致规则不生效：

1. path(/)是精确匹配根路径规则，仅当访问http://域名/这一个路径时才会触发handler，所有子路径请求都不会命中，匹配全站路径需要使用path-prefix(/)
2. case-sensitive是路径匹配谓词的参数，不属于samesite-cookiehandler的参数，之前把参数写在handler位置会被直接忽略，导致匹配规则不符合预期

修正后的有效配置如下：

path-prefix('/', case-sensitive=false) -> samesite-cookie(mode=LAX, enable-client-checker=false, add-secure-for-none=false)

注：add-secure-for-none=false仅在mode=None时生效，配置LAX模式时可以不写该参数。

第四步：验证配置生效 #

1. 快速验证方法：临时把配置替换为测试规则path-prefix('/') -> response-header('X-Undertow-Test', 'active')，重启应用后访问任意应用路径，查看响应头是否存在X-Undertow-Test: active字段，如果存在说明handler链加载正常。
2. 切回SameSite配置后，访问任意业务接口，查看Set-Cookie响应头，正常情况下所有Cookie属性末尾会携带SameSite=Lax标记。

内容的提问来源于stack exchange，提问作者V-O