Tomcat部署JAX-RS Web应用遇404错误，求排查方案

问题概述 #

• 基于JAX-RS的Java Web应用，本地IntelliJ以解压WAR形式运行正常，但部署到Tomcat服务器后，API端点访问始终返回404错误
• 应用部署为Atools，访问API URL为http://mydomain:8080/ATools/api/atools/check，仅localhost访问日志有404记录；放置index.jsp到应用根目录后，http://mydomain:8080/ATools可正常显示首页
• 同一Tomcat上的同类布局克隆应用可正常运行，对比发现正常应用部署时输出WELD相关日志，故障应用无该日志，虽怀疑beans.xml配置问题，但两个项目的beans.xml位置及内容一致

相关代码 #

RestApplication类 #

package com.mydom.ai;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/api")
public class RestApplication extends Application {

}

AiResource类 #

package com.mydom.ai;

import javax.ws.rs.*;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.Response;

@Path("/atools")
public class AiResource {

   @GET
   @Path("/")
   public Response index() {
       return Response.ok("Status: OK").build();
   }

   @GET
   @Path("/check")
   public Response parseGet() {
      try{
          ACheck check = new ACheck();
          check.check();
      }catch (Exception ex){
          ex.printStackTrace();
      }
      return Response.ok().entity("Check OK").build();
  }
}

部署日志 #

故障应用catalina.out日志 #

11-Dec-2024 11:31:20.615 INFO [localhost-startStop-4] org.apache.catalina.startup.HostConfig.deployWAR Deploying web application archive [/opt/java/apache-tomcat-8.5.65/webapps/Atools.war]
11-Dec-2024 11:31:22.509 INFO [localhost-startStop-4] org.apache.jasper.servlet.TldScanner.scanJars At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that were scanned but no TLDs were found in them. Skipping unneeded JARs during scanning can improve startup time and JSP compilation time.
11-Dec-2024 11:31:22.525 INFO [localhost-startStop-4] org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive [/opt/java/apache-tomcat-8.5.65/webapps/Atools.war] has finished in [1,910] ms

正常应用WELD初始化日志 #

24/12/11 18:49:16 Version:148 - WELD-000900: 3.1.8 (Final)
24/12/11 18:49:17 Bootstrap:236 - WELD-000101: Transactional services not available. Injection of @Inject UserTransaction not available. Transactional observers will be invoked synchronously.
24/12/11 18:49:17 Bootstrap:235 - WELD-ENV-002003: Weld SE container 58776860-2afa-406e-a40e-00c03fc446bb initialized

beans.xml配置 #

<?xml version="1.0" encoding="UTF-8"?>
   <beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                  
     http://xmlns.jcp.org/xml/ns/javaee/beans_2_0.xsd"
        bean-discovery-mode="all">
   </beans>

排查方法与检查项 #

• 核对JAX-RS及CDI依赖完整性：解压故障应用WAR包，对比正常应用的WEB-INF/lib目录，确认是否缺失JAX-RS实现（如Jersey/RESTEasy）及其CDI集成依赖（如weld-servlet-core、cdi-api），这类依赖是WELD容器初始化的必要条件
• 验证beans.xml物理路径：确认故障应用的beans.xml是否准确位于WEB-INF/beans.xml，注意路径大小写（Tomcat对文件系统路径大小写敏感）
• 统一应用路径大小写：Tomcat部署的WAR包名为Atools.war，访问URL使用ATools，尝试用http://mydomain:8080/Atools/api/atools/check访问，避免因系统大小写敏感导致路径不匹配
• 手动注册资源类：修改RestApplication类，显式添加资源类以避免自动扫描失效：

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

• 启用Tomcat调试日志：修改conf/logging.properties，将org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level设为FINE，重启Tomcat后查看详细部署日志，确认JAX-RS应用是否被正确注册
• 检查类打包路径：确认RestApplication和AiResource类是否被正确打包到WEB-INF/classes/com/mydom/ai/路径下，无包路径错误或类缺失
• 验证CDI容器触发条件：确认故障应用的pom.xml（或构建脚本）中是否包含CDI相关依赖，确保构建时这些依赖被打包进WAR包

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