WildFly中JAX-RS端点访问返回404的问题排查

问题场景 #

按照教程开发WildFly下的JAX-RS HelloWorld应用，代码如下：

@Path("/hello")
public class HelloService {
    @GET
    @Path("/text")
    public String getHello () 
    {
        return "hello world!";
    } 
}

@ApplicationPath("/rest")
public class JaxRsActivator extends Application {
   
}

应用已成功部署到WildFly，访问上下文根显示"Forbidden"符合预期，但访问http://localhost:8080/contextRootLocationThatIsForbidden/rest/hello/text时返回"Not Found"。项目依赖配置如下：

<dependencies>

<!-- Import the CDI API, we use provided scope as the API is included in WildFly / JBoss EAP -->
<dependency>
    <groupId>jakarta.enterprise</groupId>
    <artifactId>jakarta.enterprise.cdi-api</artifactId>
    <scope>provided</scope>
</dependency>

<!-- Bean Validation Implementation 
   Provides portable constraints such as @Email 
   Hibernate Validator is shipped in WildFly / JBoss EAP -->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <scope>provided</scope>
</dependency>

<!-- Import the JPA API, we use provided scope as the API is included in WildFly / JBoss EAP -->
<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
    <scope>provided</scope>
</dependency>

<!-- Import the JSF API, we use provided scope as the API is included in WildFly / JBoss EAP -->
<dependency>
    <groupId>org.jboss.spec.javax.faces</groupId>
    <artifactId>jboss-jsf-api_2.3_spec</artifactId>
    <scope>provided</scope>
</dependency>

<!-- Import the JAX-RS API, we use provided scope as the API is included in WildFly / JBoss EAP -->
<dependency>
    <groupId>org.jboss.spec.javax.ws.rs</groupId>
    <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
    <scope>provided</scope>
</dependency>

<!-- Servlet API -->
<dependency>
    <groupId>org.jboss.spec.javax.servlet</groupId>
    <artifactId>jboss-servlet-api_4.0_spec</artifactId>
    <scope>provided</scope>
</dependency>

<!-- Import the EJB API, we use provided scope as the API is included in WildFly / JBoss EAP -->
<dependency>
    <groupId>org.jboss.spec.javax.ejb</groupId>
    <artifactId>jboss-ejb-api_3.2_spec</artifactId>
    <scope>provided</scope>
</dependency>

<!-- NEEDED because of XmlRootElement-->
<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>4.0.0</version>
</dependency>
<dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-impl</artifactId>
    <version>4.0.0</version>
    <scope>runtime</scope>
</dependency>

<dependency>
    <groupId>javax</groupId>
    <artifactId>javaee-api</artifactId>
    <version>8.0</version>
    <scope>provided</scope>
</dependency>

</dependencies>

可能的原因及解决方法 #

1. 上下文根路径错误 #

• 确认contextRootLocationThatIsForbidden是否正确：WildFly中应用的上下文根默认是war包的文件名（去掉.war后缀），或者在jboss-web.xml/web.xml中配置的<context-root>值。
• 解决：查看WildFly控制台的部署日志，找到类似Deployed "your-app-name.war" (runtime-name: "your-app-name.war")的记录，用your-app-name替换URL中的对应部分。

2. JAX-RS应用未被正确扫描 #

• 问题：JaxRsActivator继承Application但未显式注册资源类时，部分场景下WildFly的自动扫描可能失效。
• 解决：在JaxRsActivator中显式添加资源类：

@ApplicationPath("/rest")
public class JaxRsActivator extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<>();
        classes.add(HelloService.class);
        return classes;
    }
}

3. 依赖版本冲突 #

• 问题：依赖中同时引入了Java EE 8兼容的jboss-jaxrs-api_2.1_spec和Jakarta EE 9+的jakarta.xml.bind-api:4.0.0，版本不匹配导致JAX-RS容器无法正常加载。
• 解决：将JAXB依赖降级到Java EE 8兼容版本，或移除单独的JAXB依赖（javaee-api:8.0已包含JAXB API）：

<!-- 降级后的JAXB依赖 -->
<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>2.3.3</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-impl</artifactId>
    <version>2.3.3</version>
    <scope>runtime</scope>
</dependency>

4. 包结构不符合扫描规则 #

• 问题：如果HelloService和JaxRsActivator不在WEB-INF/classes的根包或其子包下，WildFly可能无法发现这些类。
• 解决：将所有JAX-RS相关类放在WEB-INF/classes下的有效包中（比如com.example.rest），确保包路径能被容器扫描到。

5. 缺少WEB-INF配置文件 #

• 问题：WAR包如果缺少WEB-INF/web.xml，部分情况下会导致JAX-RS容器初始化异常。
• 解决：添加一个空的web.xml到WEB-INF目录，或确认WildFly版本支持无web.xml的Jakarta EE模式。

6. WildFly JAX-RS模块异常 #

• 问题：WildFly内置的RESTEasy模块可能被禁用或损坏。
• 解决：查看WildFly的standalone.xml/domain.xml，确认存在以下子系统：

<subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>

如果不存在，手动添加该子系统，或重新安装WildFly。

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