当年我学 Servlet 的时候，最迷惑的不是那些 Doget、Dopost 方法，反而是配置这件事。明明写了一个 Java 类，为什么访问不到？为什么有人往 web.xml 里加几行 XML，有人在类上写个 @WebServlet 也能跑？后来才意识到，配置不是实验课上的附加题，而是 Servlet 的核心机制之一。今天这篇就专门讲清楚 Servlet 的两种配置方法，看完你就理解容器到底是怎么找到你写的那个类的，也知道自己该选哪种方式。
这篇适合刚入门 Java Web、被 web.xml 和注解两套写法搞晕的初学者，也适合那些会写代码但说不清“为什么这么配”的朋友。我把整个知识点拆成五块：配置的本质、web.xml 写法、注解写法、选型逻辑、以及新手容易踩的坑。尽量讲得实在，你能直接照着敲。
1. 先搞明白：Servlet 为什么要“配置”，两种方式到底在配什么
1.1 容器怎么知道你的 Servlet 类存在
很多人第一次写 Servlet 会用 IDE 自动生成一个类，比如：
public class HelloServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setCharacterEncoding("UTF-8"); response.getWriter().write("Hello, Servlet World!"); } }你在浏览器里输入http://localhost:8080/你的项目名/hello，Tomcat 会调用这个类的 doGet 方法。但这个过程中有一个关键问题：Tomcat 怎么知道HelloServlet这个类存在？怎么知道它对应的访问路径是/hello？
答案是：不配置，它就不知道。Tomcat 启动后只会扫描WEB-INF/classes目录下的编译产物和WEB-INF/lib下的依赖包，但把一个 Java 类和一段 URL 匹配关系对应起来，必须由开发者显式地告诉它。这个动作，就是“配置 Servlet”。
如果没配，你把项目部署到 Tomcat 后，控制台不会报错，浏览器会给你一个 404，页面提示找不到资源。新手在这步最容易怀疑是不是 Tomcat 装坏了，其实问题往往是“类写了，但容器不认识它”。
1.2 web.xml 与注解：集中登记和就地登记的区别
我打个比方。Servlet 像公司里的员工，容器像人事系统，URL 规则像员工的工牌。要让员工开工干活，你得在人事系统里给这个员工登记：他叫什么名字（servlet-name），真实身份是什么（servlet-class），工牌上写哪个门禁编号（url-pattern）。
那登记方式呢？有两种：
- web.xml 方式：所有员工的信息统一填在一张登记表上，交给 HR 统一录入。人事系统只要查表就能知道每个人的信息。
- 注解方式：员工自己把工牌挂在胸口，走到哪都能亮出来。系统只要扫描人脸（类上的注解）就能识别出谁是谁。
两种方式最终达到的效果一样：让容器明白“哪个类处理哪个 URL”。但实现路径不同，代码组织方式也不同。web.xml 把配置和代码分开，集中管理；注解把配置和代码放在一起，就地声明。理解了这一点，后面所有的细节都建立在它上面。
提示：一个 Servlet 不是配了就能访问，它只是被容器“认识”了。真正响应请求还涉及生命周期，但配置这一步是入口。先把入口搞对，再谈后面的东西。
2. 第一种配置法：web.xml 里写清楚“类”与“URL”的对应关系
2.1 一套能跑通的最小示例
用 web.xml 配置 Servlet，核心动作是“两步走”：第一步写 Servlet 类，第二步在 web.xml 里加两组 XML 标签。下面是一个完整的最小示例。
先写 Servlet 类（放在src/main/java/com/example/servlet/HelloServlet.java）：
package com.example.servlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.ServletException; import java.io.IOException; public class HelloServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/html"); response.setCharacterEncoding("UTF-8"); response.getWriter().write("<h1>Hello from web.xml Servlet</h1>"); } }然后编辑src/main/webapp/WEB-INF/web.xml：
<?xml version="1.0" encoding="UTF-8"?> <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_4_0.xsd" version="4.0"> <servlet> <servlet-name>HelloServlet</servlet-name> <servlet-class>com.example.servlet.HelloServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>HelloServlet</servlet-name> <url-pattern>/hello</url-pattern> </servlet-mapping> </web-app>部署到 Tomcat 后，启动项目，浏览器访问http://localhost:8080/你的项目名/hello，能看到那个一级标题，说明配置生效了。
从这套最小示例里可以提炼出最关键的一句话：servlet 标签只是“注册”这个类，servlet-mapping 标签才负责把 URL 绑上去。很多新手以为 servlet-class 写对了就完事，少了 mapping 那段照样 404。
2.2 web.xml 的结构拆解：四个元素，一个都不能少
web.xml 中 Servlet 相关的配置其实只有两类标签、四个重点字段。我用表格列出来，照着填不容易错：
| XML 标签 | 位置 | 作用 | 初学阶段最容易犯的错 |
|---|---|---|---|
<servlet-name> | 在<servlet>和<servlet-mapping>中各出现一次 | 定义一个逻辑名字，是两组标签之间的“连接暗号” | 两个标签里的名字没保持一致 |
<servlet-class> | 只在<servlet>中 | 填写 Servlet 类的完整限定名（含包名） | 只写了类名，没写包名；或路径写错 |
<url-pattern> | 只在<servlet-mapping>中 | 定义访问路径规则 | 忘记以/开头；用绝对 URL |
<servlet>与<servlet-mapping> | 平级，前后关系 | 前者完成类注册，后者完成 URL 绑定 | 只写注册忘记绑定，反之亦然 |
这里有三个细节必须敲黑板强调：
第一，servlet-name 本身没有任何技术含义。它不是 Java 类名，也不是 URL 路径，它只是一段内部标识。你叫它 hello、hs、第一个Servlet 都行，只要<servlet>里的名字和<servlet-mapping>里的名字严格一致。容器靠这个名字对得上号：哦，用户访问 /hello 时，我该去找那个名字叫 HelloServlet 的配置，然后实例化它下面写的那个类。
第二，servlet-class 一定是全限定名。你写了package com.example.servlet;，这里就要写com.example.servlet.HelloServlet。少写包名，容器在启动时会直接抛ClassNotFoundException，项目起不来，这算好的，能让你立刻发现问题；最怕的是类名写错但和别的类碰巧同名，那种情况排查起来更头疼。
第三，url-pattern 必须以中文语境下说的“斜杠”开头。/hello合法，hello不合法；/hello/*合法，hello/*不合法。这个规则比较死，但记不住就会踩很基础的坑。后面第四章我会专门展开讲 url-pattern 的匹配规则，这里先记住最基础的一条。
2.3 进阶配置：初始化参数与启动时机
web.xml 的配置能力不止“类 + URL”这么简单。两个非常常见的需求：给 Servlet 传递参数、让 Servlet 在容器启动时就初始化。
初始化参数：像给员工发入职手册
有些资源或参数，比如数据库连接串、文件路径、版本号，你想写成可配置的，不硬编码在 Java 类里。可以用<init-param>：
<servlet> <servlet-name>ConfigServlet</servlet-name> <servlet-class>com.example.servlet.ConfigServlet</servlet-class> <init-param> <param-name>appName</param-name> <param-value>MyFirstApp</param-value> </init-param> <init-param> <param-name>maxUploadSize</param-name> <param-value>10485760</param-value> </init-param> </servlet>在 Servlet 里通过getServletConfig().getInitParameter("appName")读取：
public class ConfigServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String appName = this.getServletConfig().getInitParameter("appName"); response.setCharacterEncoding("UTF-8"); response.setContentType("text/html"); response.getWriter().write("AppName: " + appName); } }好处是改参数不用改代码重新编译，改 XML 再重启容器就行。这在老式企业项目里非常常见。
load-on-startup：让Servlet提前“上岗”
默认情况下，Servlet 是在第一次被请求时才实例化的，这种叫懒加载。但如果 Servlet 初始化要加载大量缓存、建立长连接、预热数据，第一次访问就会特别慢，用户会明显感觉到卡顿。这时可以让它在容器启动阶段就初始化：
<servlet> <servlet-name>InitServlet</servlet-name> <servlet-class>com.example.servlet.InitServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet>load-on-startup的值是个整数，数字越小优先级越高。这里填 1，意思就是：项目一启动，容器就帮我创建这个 Servlet 的实例并调用 init() 方法。
我在实际项目里见过一种很典型的误用：把所有 Servlet 都配上load-on-startup，觉得“提前加载总归没坏处”。其实没必要，如果你这个 Servlet 只处理简单请求，没有重型初始化逻辑，懒加载完全够用，还省内存。这个配置属于“用到才加”，不用追求全员启动。
3. 第二种配置法：@WebServlet 注解，让配置跟着代码走
3.1 Servlet 3.0 之后的新玩法
web.xml 配置虽然清晰，但你一定也感受到了它的繁琐：每写一个 Servlet，就要回 web.xml 里加五六个标签，类一多，web.xml 膨胀得比代码还长，页面滚动都得半天。
Servlet 3.0 规范发布后，Java Web 开发多了一个选项：注解配置。在 Servlet 类上直接写@WebServlet，配置信息就内嵌在代码里，省去了在 web.xml 中注册和映射的过程。
用注解改写刚才的 HelloServlet：
package com.example.servlet; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.ServletException; import java.io.IOException; @WebServlet(urlPatterns = "/hello") public class HelloServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/html"); response.setCharacterEncoding("UTF-8"); response.getWriter().write("<h1>Hello from Annotation Servlet</h1>"); } }部署后访问http://localhost:8080/你的项目名/hello，效果和 web.xml 方式一模一样。web.xml 里什么都不用加，甚至可以是一个空配置。
我当时第一次用注解时心里嘀咕：这也太偷懒了吧，一行注解就完事？后来明白了，容器启动时会在指定目录下扫描类上的注解，发现有@WebServlet就自动完成注册和映射。本质上做的事情和 web.xml 相同，只不过信息源从“外部配置文件”变成了“类本身”。
这里有一个关键前提：你的容器必须支持 Servlet 3.0+ 规范。Tomcat 7 及以上版本才支持注解扫描，Tomcat 6 就只能老老实实用 web.xml。
3.2 @WebServlet 的各属性到底能配什么
注解的好处是配置就近，但坏处是很多人只会写一个urlPatterns，其他属性根本不知道。我把常用的属性整理成表格：
| 属性 | 作用 | 举例 |
|---|---|---|
urlPatterns | 映射路径，可写多个 | @WebServlet(urlPatterns = {"/hello", "/hi"}) |
value | 与urlPatterns等价，两者不能同时用 | @WebServlet("/hello") |
name | Servlet 的逻辑名称，类似 web.xml 的 servlet-name | @WebServlet(name = "HelloServlet", urlPatterns = "/hello") |
loadOnStartup | 容器启动时初始化，和 XML 里的 load-on-startup 一致 | @WebServlet(urlPatterns = "/init", loadOnStartup = 1) |
initParams | 指定初始化参数，是@WebInitParam数组 | 见下方综合示例 |
asyncSupported | 是否支持异步处理 | @WebServlet(urlPatterns = "/async", asyncSupported = true) |
description | 描述信息，相当于 XML 里的 description | @WebServlet(urlPatterns = "/hello", description = "登录接口") |
两个容易搞混的属性放在一起说：value和urlPatterns。@WebServlet("/hello")这种写法用的是value，@WebServlet(urlPatterns = "/hello")用的是urlPatterns，功能完全一样，但不要同时写，会直接报编译错误。官方建议多路径映射时用urlPatterns，单路径怎么顺手怎么来。
3.3 注解方式下的一个综合示例
为了让你直观看到注解能配多少东西，我写一个带初始化参数的例子：
package com.example.servlet; import javax.servlet.annotation.WebInitParam; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.ServletException; import java.io.IOException; @WebServlet( name = "UserServlet", urlPatterns = {"/user", "/u"}, loadOnStartup = 0, initParams = { @WebInitParam(name = "defaultPageSize", value = "20"), @WebInitParam(name = "appEnv", value = "dev") } ) public class UserServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String pageSize = this.getServletConfig().getInitParameter("defaultPageSize"); String env = this.getServletConfig().getInitParameter("appEnv"); response.setContentType("text/html"); response.setCharacterEncoding("UTF-8"); response.getWriter().write("pageSize=" + pageSize + ", env=" + env); } }访问/user和/u，两个路径都能命中同一个 Servlet。这是注解方式特别方便的一点：一个 Servlet 挂多个路径，只需要把数组写全，不用像 web.xml 那样重复写多组<servlet-mapping>。
注意：注解的 initParams 和 web.xml 的 init-param 在最终效果上没有区别。但如果一个 Servlet 在两个地方都配了初始化参数，以 web.xml 为准，这一点在很多容器上是有约定的，生产环境别依赖这种歧义，统一定在一处最省心。
4. 两种方式的选型逻辑：什么场景用什么，会不会互相冲突
4.1 现实项目里哪种更常见
这个问题几乎每个初学者都会问。我的观察是分阶段的：
- 传统 SSM / SSH 时代的老项目：web.xml 几乎雷打不动。因为那时候项目里 Servlet 较多，而且大量相关配置就是集中在 web.xml 里，比如过滤器 Filter、监听器 Listener、Spring 的上下文加载监听器、欢迎页、错误页，全都在这个文件里。散落各处的注解反而不好统一审查。
- 现代 Spring Boot 时代：Spring Boot 内置了 Spring MVC 的 DispatcherServlet，你写的控制器不再是 HttpServlet 子类，而是
@RestController标注的普通类。因此“Servlet 怎么配”这个问题在 Boot 型项目里被框架封装掉了。但如果你用的是原生 Servlet 项目、或者让 Boot 和外部 Servlet 容器配合，两种方式依旧都在用。 - 个人项目和快速原型：注解是首选。代码和配置在一起，改一个类就是改一处，不用在两个文件之间来回跳，心智负担小。
所以我的建议很直接：如果是学习理解机制，必须玩透 web.xml；如果是要快速交付功能，用注解。两条腿走路，缺一条都别扭。
4.2 同一 Servlet 同时在 web.xml 和注解里配置会怎样
这个问题很现实。比如你在 HelloServlet 类上写了@WebServlet("/hello")，又在 web.xml 里写了同样的/hello映射，会不会报错？
结论分情况：
- 如果类名不同、URL 相同，容器可能启动失败，出现
java.lang.IllegalArgumentException: The servlet name xxx is already defined之类的异常，因为容器认为产生了冲突。 - 如果完全相同的 Servlet 在注解和 web.xml 各配一遍，部分容器以 web.xml 的配置为准，注解会被忽略或覆盖。但不同容器之间表现有差异，不要拿生产环境去赌这个行为。
更常见的坑是“同名 Servlet、不同路径”。比如：
@WebServlet("/hello") public class HelloServlet extends HttpServlet { ... }web.xml 里却又这样写：
<servlet> <servlet-name>HelloServlet</servlet-name> <servlet-class>com.example.servlet.HelloServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>HelloServlet</servlet-name> <url-pattern>/sayHello</url-pattern> </servlet-mapping>容器里会出现两个逻辑名称都是 HelloServlet 的 Servlet？严格讲这属于定义了两次相同的名字，是不规范的做法，可能直接启动失败，也可能只有一个生效。我踩过这个坑之后养成一个习惯：一个 Servlet 的配置方式，全项目只选一种，绝不混着开。要么统一注解，要么统一 web.xml，这个规矩能让很多奇怪的问题在源头就消失。
4.3 url-pattern 的匹配细节：别让映射埋雷
配置方法学会了，路径规则同样重要。url-pattern 不是只能写一个具体的/hello，它支持几类写法，每种写法的匹配范围不同：
| 写法 | 匹配规则 | 示例 |
|---|---|---|
/hello | 精确匹配，只匹配这个路径 | /hello能访问；/hello/可能都不行 |
/hello/* | 目录匹配，匹配/hello/下的所有路径 | /hello/a、/hello/b/c都能访问 |
*.do | 扩展名匹配，匹配以.do结尾的路径 | /user/list.do可以访问 |
/ | 缺省路径，匹配所有没有其它规则匹配的请求 | 常用于把请求交给核心分发器 |
一个重要的匹配优先级规则：精确匹配 > 目录匹配 > 扩展名匹配 > 缺省匹配。容器收到/hello/a时，先找有没有精确的/hello/a，没有再看/hello/*，再看*.do，最后才落到/。
这个优先级机制对纯 Servlet 项目颇为关键，一个非常经典的坑是：把某个 Servlet 的 url-pattern 配成/*，结果所有路径都进了同一个 Servlet，连 JSP 页面请求也被它拦了，页面全部变成一串源码或空白。原因就是/和/*的区别没搞明白——/是缺省兜底，/*是目录匹配且优先级极高，会抢先拦住所有请求。
5. 新手最容易踩的配置坑和完整排查链路
5.1 404 最常见：映射看似写了，实则没生效
浏览器输入 URL 后长时间 404，这个问题在配置里占比最高。我建议按下面顺序排查，每步都能排除一类原因：
- 确认 URL 完整：是否少了项目上下文路径？访问 URL 的完整格式是
http://ip:端口/上下文路径/url-pattern。在 IDEA 的 Tomcat 配置里默认上下文路径可能是/项目名_war_exploded，和你以为的/项目名不一致，URL 就会 404。 - 确认类真的编译到了 classes 目录：项目构建产物里有没有
WEB-INF/classes/com/example/servlet/HelloServlet.class？有时代码保存了但没编译，Tomcat 运行的还是旧产物。 - 确认 web.xml 的映射真的存在：打开现在的 web.xml，看
<servlet-name>和<url-pattern>是否完整。新手很容易在复制模板时把 mapping 标签落到注释里，或者放到了别的<servlet>内部，结构嵌套错了。 - 确认 Tomcat 的 catalina.out / 控制台输出有没有报错：如果类名写错或
ClassNotFoundException，控制台一定有异常堆栈，找org.apache.catalina相关的关键词。 - 确认重启过容器：web.xml 的修改必须在重启后才生效。如果是热部署没触发，手动重启一次再试。
按这个链路走完，能解决大约九成的 404。剩下的一成是静态资源和动态映射重叠，或者权限拦截器等更深层的问题。
还有一个小细节：IDE 中创建的 web.xml 不一定会被自动打包到 WAR 里。看构建产物时重点确认WEB-INF/web.xml这个文件到底在不在部署目录中。之前遇到过 IDEA 把 web.xml 放进了src/main/resources，结果部署时根本没把它当 Web 配置读取，启动倒是正常，请求全部 404。
5.2 启动报错：servlet-name 不一致
web.xml 里<servlet>和<servlet-mapping>的 servlet-name 不一致时，Tomcat 启动通常直接报错：
The servlet named xxx is not defined in this web application这个报错说得很明白：在 mapping 里引用了一个不存在的 Servlet 名字。解决办法就是把两个名字改到完全一致。这里要特别留意空格和大小写：HelloServlet和HelloServlet之间有空格，看起来没问题，但对容器来说就是两个不同的字符串。
排查这类问题的小技巧：把 web.xml 里所有的<servlet-name>值列出来，和所有<servlet-mapping>里引用的名字做一次“配对”。多配一个不成对，立刻就能发现。
5.3 重复映射与静态资源冲突
我见过一个项目，一个 Servlet 对应/user，另一个 Servlet 也对应/user。Tomcat 启动时通常会提示类似 “Multiple mappings” 或直接覆盖，具体表现因版本而异。这种重复映射的根因，往往是一个人加了注解配置，另一个人加了 web.xml 配置，两个人互相不知道。
另外一类冲突是动态映射抢了静态资源。比如配了url-pattern = "/"之后，你会发现访问项目里的静态图片、CSS、JS 全部失效，因为它们都被 Servlet 接口拦走了，没有资源处理器来响应。这是新手理解文件的 Servlet 流程时最强烈的挫败感来源之一：明明配得“没错”，页面就是乱样。解决方案是不要轻易改写/或/*这种级别的路径，除非你很清楚自己在做请求入口分发。
5.4 改了配置没生效：关于重新部署
Servlet 映射变了、初始化参数变了，但浏览器访问还是旧行为。这有三个常见原因：
- 容器没有重新部署：要看到 web.xml 修改后的效果，必须重启 Tomcat 或触发一次 redeploy。
- 浏览器缓存了响应：尽管改了逻辑，但 HTTP 响应被浏览器缓存，按 F12 打开开发者工具，勾选 Disable cache 再试。
- IDE 缓存问题：IntelliJ IDEA 偶发没有同步最新 web.xml 到 target 目录，手动执行 Build > Build Artifacts > Rebuild，或者直接 Clean 后再启动。
我个人的习惯是：改 web.xml 这种关键配置后，先直接重启 Tomcat，不依赖热部署。热部署对类文件友好，但对 XML 配置的支持不是所有环境都可靠，与其来回试，不如一次重启干净利落。
6. 我的实操建议：两种方法，一个都不能少
写到这里，你应该能把握这两种方式的核心了。web.xml 是集中登记、外部管理，适合项目整体把控；注解是就地绑定、代码自带，适合快速迭代。两者背后服务的是同一个目标：让容器在正确的时间找到正确的类，处理正确的 URL 请求。
如果你刚入门，我建议你先拿 web.xml 手写几个 Servlet，理解类和 URL 的对应关系，再用注解来写，对比两者的差异。这个过程会让你真正理解容器的工作方式，而不是只知道在某一个类上抄一段注解就能跑。以后你再看 Spring MVC、Spring Boot 里的请求映射，也不会觉得它们神秘，本质上都是在做“谁能处理哪个 URL”这件事的登记。
最后分享一个实际经验：我在团队里带新人时，判断对方有没有真正理解 Servlet 配置，就看一个问题——“为什么注解方式不用写 web.xml 也能被访问？”能答出“容器扫描注解完成注册”这句话的人，后面学什么框架都不太会卡壳。你现在看到这句了，说明你也懂了。
