@WebServlet 註解失效排查指南：Tomcat 版本與 Servlet 規範匹配關鍵

問題現象

使用 @WebServlet("/AskShopInfo") 註解標註 Servlet 類，配置 web.xml（版本 2.5），部署後訪問對應 URL 無法調用 Servlet 方法，無任何報錯。

根本原因

Servlet 版本不匹配：

• @WebServlet 是 Servlet 3.0（Java EE 6）引入的註解特性；
• web.xml 聲明 version="2.5" 且 metadata-complete="true"，強制容器按 2.5 規範處理，**忽略所有註解**；
• Tomcat 7.0+ 支持 Servlet 3.0，但若 web.xml 版本為 2.5 且 metadata-complete="true"，容器不會掃描註解。

解決方案（三選一）

方案一：升級 web.xml 至 3.0+ 並啟用註解掃描（推薦）

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://java.sun.com/xml/ns/javaee"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://java.sun.com/xml/ns/javaee 
                             https://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0"
         metadata-complete="false">  <!-- 關鍵：false 允許註解補全 -->
    <!-- 保留原有 listener, filter 等配置 -->
</web-app>

metadata-complete="false" 告訴容器：請掃描註解（@WebServlet, @WebFilter, @WebListener 等）作為部署描述符的補充。

方案二：保持 web.xml 2.5，在 web.xml 手動註冊 Servlet

<servlet>
    <servlet-name>AskShopInfo</servlet-name>
    <servlet-class>com.example.AskShopInfo</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>AskShopInfo</servlet-name>
    <url-pattern>/AskShopInfo</url-pattern>
</servlet-mapping>

適合不想升級 Servlet 版本的老項目維護。

方案三：確認 Tomcat 版本 ≥ 7.0

• Tomcat 6.x 僅支持 Servlet 2.5，**完全不支持**註解；
• Tomcat 7.0.x 支持 Servlet 3.0；
• Tomcat 8.5+/9.0+ 支持 Servlet 3.1/4.0。

驗證步驟

1. 修改 web.xml 版本與 metadata-complete；
2. 清理項目：Maven > Update Project / Project > Clean；
3. 重新部署到 Tomcat，查看啟動日志是否有 Initializing Spring DispatcherServlet 或 Servlet 註冊信息；
4. 瀏覽器訪問 https://localhost:8080/項目名/AskShopInfo 測試。

註解詳解參考

@WebServlet 註解詳解（CSDN）

總結

Servlet 註解生效的三要素：容器支持（Tomcat 7+）、web.xml 版本 ≥ 3.0、metadata-complete="false"。缺一不可。