使用@WebServlet注解的简单Servlet访问报错无法运行问题咨询

问题核心成因 #

• 注解扫描未覆盖目标类
  @WebServlet的生效依赖Web容器的类路径扫描逻辑。如果HelloServlet未放置在项目源码目录下、编译产物未输出到WEB-INF/classes路径，或是在框架集成场景下，组件扫描范围小于HelloServlet所在的包层级，容器启动时不会为该Servlet注册对应的URL映射，提交请求时自然无法匹配到有效资源。
• 规范版本不兼容
  @WebServlet是Servlet 3.0规范新增的注解配置能力。如果项目web.xml声明的规范版本低于3.0，或是部署用的Web容器（如Tomcat）版本不支持Servlet 3.0，注解配置会被完全忽略，等同于未定义该Servlet。
• 路径映射不匹配
  JSP表单的提交地址与Servlet注册地址未对齐：如果表单action写成带前置斜杠的/helloServlet，容器会将请求解析到容器根路径下，而非当前Web应用的上下文路径，最终因路径不一致返回404。
• 配置开关阻断注解扫描
  若web.xml根标签配置了核心阻断开关metadata-complete="true"属性，会强制容器关闭所有类路径下的注解扫描逻辑，哪怕代码中写了@WebServlet，也不会完成Servlet注册流程。

落地解决步骤 #

• 调整类路径扫描配置
  确认HelloServlet位于项目源码目录（Maven标准结构为src/main/java下的自定义包路径），编译后能正确输出到WEB-INF/classes目录；使用Spring Boot等集成Web环境时，需确认主启动类的组件扫描范围覆盖HelloServlet所在的包，避免将Servlet类放在启动类所在包的上层路径。
• 匹配规范版本要求
  将web.xml的声明版本调整为Servlet 3.0及以上，参考配置：

  <web-app 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/web-app_3_1.xsd"
           version="3.1">
  

  本地部署的Web容器版本需对应Servlet 3.0及以上（如Tomcat 7及以上版本）。
• 校准URL映射规则
  保持表单提交路径与Servlet注册路径的引用逻辑一致：JSP中form的action写为相对路径helloServlet，不要添加前置斜杠，容器会自动基于当前JSP的访问路径，拼接到Web应用上下文下的对应Servlet地址。可在容器启动日志中检索Servlet注册记录，确认/helloServlet映射已被成功加载。
• 开启注解扫描开关
  移除web.xml根标签下的metadata-complete="true"配置，或修改为metadata-complete="false"，允许容器自动扫描类路径下的Servlet注解完成注册。

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