1. 从一次线上故障说起为什么要搞懂 Catalina刚入行那会儿我对 Tomcat 的认知就停留在“把 war 包丢进 webapps启动 startup.sh浏览器能访问就行”。直到有一次生产环境出现了一个诡异问题某个接口在高并发下响应时间飙升但 CPU 和内存监控看起来都很正常日志里也没有任何报错。当时团队里几个人排查了一整天最后发现是 Servlet 的load-on-startup配置和某个 Filter 的初始化顺序出了问题导致部分请求在首次访问时被阻塞在类加载阶段。那次之后我才意识到如果只把 Tomcat 当成一个“黑盒”遇到深层次问题时就只能靠猜。而 Tomcat 最核心的部分就是它的Servlet 容器 Catalina。你可以把 Catalina 理解为 Tomcat 的“心脏”——它负责解析 XML 配置、管理 Servlet 生命周期、处理请求映射、维护 Session、执行 Filter 链几乎所有跟“动态请求处理”相关的逻辑都在这里完成。这篇内容适合谁看如果你已经用过 Tomcat 部署项目但对其内部结构一知半解或者你正在准备面试想搞清楚“Tomcat 为什么能处理 Servlet”这类问题又或者你遇到了请求映射、类加载、Session 共享等疑难杂症想从容器层面找到根因——那这篇关于 Catalina 的拆解应该能帮到你。我会从整体架构讲到核心组件再落到实操配置和排查技巧尽量把“为什么这么设计”和“实际怎么用”都讲透。2. Catalina 的整体架构与核心设计思路2.1 Catalina 到底是什么从“容器”这个词说起很多人第一次听到“Servlet 容器”这个词会觉得抽象。其实你可以把它类比成一个“餐厅的后厨管理系统”。Servlet 就是你写的菜谱处理逻辑而 Catalina 就是那个负责接收订单HTTP 请求、决定由哪个厨师Servlet来做、管理厨具Session、Filter、最后把菜端出去响应的整套体系。从代码层面看Catalina 是 Tomcat 的一个核心模块位于org.apache.catalina包下。它实现了 Java Servlet 规范中定义的容器行为同时在此基础上做了大量工程化扩展。Tomcat 的整体架构可以粗略分为两层连接器层Connector和容器层Container。Connector 负责底层的网络通信把字节流解析成HttpServletRequest对象而 Catalina 就是容器层负责处理这些请求对象并生成HttpServletResponse。这种分层设计的好处非常明显Connector 可以替换比如换成 NIO、APR 等不同实现而 Catalina 不需要关心底层用的是哪种 IO 模型。反过来Catalina 的容器逻辑也可以独立演进只要接口约定不变两者就能灵活组合。这其实是一种典型的“关注点分离”思路也是 Tomcat 能长期保持稳定和可扩展的关键原因。2.2 为什么采用分层容器结构Server、Service、Engine、Host、ContextCatalina 的容器结构是嵌套的从外到内依次是Server → Service → Engine → Host → Context。很多初学者会觉得这层套娃太复杂但每一层都有明确的职责划分。Server 是整个 Tomcat 实例的顶层代表一个 JVM 里通常只有一个 Server。Service 是 Server 内部的一个逻辑单元它把 Connector 和 Engine 绑定在一起——也就是说一个 Service 负责“从哪个端口接收请求”以及“交给哪个引擎处理”。Engine 是真正处理请求的核心容器它内部可以包含多个 Host。Host 代表一个虚拟主机对应一个域名。Context 则是我们最熟悉的“一个 Web 应用”也就是一个 war 包解压后的目录或者一个应用上下文。为什么要设计这么多层核心原因是隔离与复用。比如一台服务器上可以部署多个域名Host每个域名下可以跑多个应用Context它们共享同一个 Engine 的处理能力但彼此之间又相互隔离。如果没有这层结构所有应用混在一起配置和资源管理会变得极其混乱。注意很多人在配置server.xml时只关注 Connector 的端口忽略了 Host 和 Context 的层级关系导致虚拟主机配置不生效。理解这个嵌套结构是排查此类问题的前提。2.3 生命周期管理Lifecycle 接口的统一设计Catalina 里几乎所有核心组件都实现了Lifecycle接口。这个接口定义了一套标准的状态流转init → start → stop → destroy。每个组件在启动时会触发LifecycleEvent父组件负责调用子组件的start方法形成一条启动链。这种设计的精妙之处在于统一管理。比如你调用Server.start()它会依次启动 Service、Engine、Host、Context最后启动各个 WrapperServlet 包装器。停止时则反向执行。整个过程不需要人工干预也不会出现“某个组件忘了启动”的情况。从实操角度看如果你在自定义 Valve 或 Listener 时发现初始化顺序不对大概率是因为没有正确实现 Lifecycle 接口或者把组件挂载到了错误的层级。我个人的经验是自定义组件尽量挂载在 Context 或 Host 级别这样生命周期由容器统一管理不容易出问题。3. 核心组件深度拆解与实操要点3.1 Engine 与 Host请求进入容器的第一站当 Connector 把请求交给 Catalina 后首先到达的是 Engine。Engine 的主要职责是选择正确的 Host。它内部维护了一个 Host 列表根据请求中的域名或者 IP来匹配对应的虚拟主机。如果找不到匹配的 Host就会使用默认 Host通常是localhost。Host 的配置在server.xml中非常直观Host namewww.example.com appBasewebapps unpackWARstrue autoDeploytrue Context path/myapp docBase/opt/apps/myapp reloadablefalse/ /Host这里有几个关键参数值得展开说。appBase指定了应用的基础目录Tomcat 会自动扫描这个目录下的 war 包或文件夹。unpackWARs决定是否自动解压 war 包生产环境一般设为true方便查看和修改配置。autoDeploy控制是否自动部署新应用开发环境可以开启生产环境建议关闭以避免意外部署。Context的docBase可以指向任意目录不一定非要在appBase下。这个特性在部署外部应用时非常有用。reloadable参数需要特别小心设为true时Tomcat 会监控WEB-INF/classes和WEB-INF/lib下的变化并自动重启应用。开发时很方便但生产环境开启会带来严重的性能开销因为每次类变化都会触发整个应用的重新加载。实操心得我曾经遇到过一个应用启动特别慢的问题排查后发现是reloadabletrue加上WEB-INF/lib下有大量 jar 包Tomcat 每次启动都要扫描所有 jar 的时间戳。改成false后启动时间从 90 秒降到了 15 秒。3.2 Context 与 WrapperServlet 的真正归宿Context 代表一个 Web 应用它是 Catalina 中最重要的容器之一。一个 Context 内部可以包含多个 Wrapper每个 Wrapper 对应一个 Servlet 实例。Wrapper 是容器层级的最底层也是 Servlet 生命周期的实际管理者。Servlet 的加载和初始化流程大致是这样的Context 启动时会读取web.xml或注解配置解析出所有 Servlet 定义。如果某个 Servlet 配置了load-on-startup且值大于等于 0Context 会立即调用它的init()方法。否则Servlet 会在第一次请求到达时才被初始化。这里有一个容易被忽略的细节Servlet 实例在容器中通常是单例的。也就是说多个请求会共享同一个 Servlet 对象。这就解释了为什么在 Servlet 中定义实例变量是不安全的——多个线程同时访问会导致数据混乱。正确的做法是把状态保存在局部变量、ThreadLocal或者外部存储中。// 错误示范实例变量存在线程安全问题 public class MyServlet extends HttpServlet { private int count 0; // 多个线程共享会出问题 protected void doGet(HttpServletRequest req, HttpServletResponse resp) { count; // 非原子操作并发下结果不可预期 } } // 正确做法使用局部变量或原子类 public class MyServlet extends HttpServlet { private AtomicInteger count new AtomicInteger(0); protected void doGet(HttpServletRequest req, HttpServletResponse resp) { int current count.incrementAndGet(); // 原子操作线程安全 } }Wrapper 还负责管理 Servlet 的过滤器链。Filter 的执行顺序由web.xml中的filter-mapping顺序决定而不是filter的定义顺序。这个细节在排查“Filter 为什么没生效”时非常关键。3.3 Pipeline 与 Valve请求处理的流水线机制Catalina 的请求处理采用了一种叫Pipeline-Valve的机制。你可以把它想象成一条流水线请求从 Engine 的 Pipeline 进入依次经过各个 Valve最后到达 Host、Context、Wrapper 的 Pipeline。每个 Valve 都可以对请求做预处理、后处理或者决定是否继续传递。Tomcat 内置了很多标准 Valve比如AccessLogValve负责记录访问日志RemoteAddrValve负责 IP 过滤ErrorReportValve负责生成错误页面。你也可以自定义 Valve实现鉴权、限流、请求日志等逻辑。public class CustomValve extends ValveBase { Override public void invoke(Request request, Response response) throws IOException, ServletException { long start System.currentTimeMillis(); try { getNext().invoke(request, response); // 传递给下一个 Valve } finally { long cost System.currentTimeMillis() - start; if (cost 1000) { // 记录慢请求 System.out.println(Slow request: request.getRequestURI() cost cost ms); } } } }自定义 Valve 需要在server.xml或context.xml中配置。这里有个经验Valve 的配置位置决定了它的作用范围。配置在 Engine 下对所有 Host 生效配置在 Host 下对该主机所有应用生效配置在 Context 下只对该应用生效。我一般把通用逻辑如访问日志放在 Engine 级别把业务相关逻辑放在 Context 级别。注意Valve 的invoke方法中如果不调用getNext().invoke()请求就会被中断后续的 Servlet 不会执行。这个特性可以用来做拦截但也要小心别误伤正常请求。4. 实操过程从零搭建一个 Catalina 级别的自定义容器4.1 环境准备与依赖引入要深入理解 Catalina最好的方式是自己动手写一个简化版的容器。这里我用 Maven 来管理依赖核心只需要 Servlet API 和 Tomcat 的嵌入版依赖。dependencies dependency groupIdorg.apache.tomcat.embed/groupId artifactIdtomcat-embed-core/artifactId version9.0.80/version /dependency dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency /dependencies选择 Tomcat 9 而不是 10 的原因是Tomcat 10 开始把javax.servlet换成了jakarta.servlet很多现有项目还没迁移。如果你是新项目可以直接上 Tomcat 10 或 11但要注意包名变化。4.2 手动创建 Server、Service 和 Connector下面这段代码展示了如何用编程方式启动一个内嵌 Tomcat并手动配置 Catalina 的核心组件。public class EmbeddedTomcatDemo { public static void main(String[] args) throws Exception { // 创建 Server Tomcat tomcat new Tomcat(); tomcat.setBaseDir(/tmp/tomcat-demo); tomcat.setPort(8080); // 获取 Server 和 Service Server server tomcat.getServer(); Service service server.findService(Tomcat); // 配置 Connector Connector connector new Connector(org.apache.coyote.http11.Http11NioProtocol); connector.setPort(8080); connector.setURIEncoding(UTF-8); service.addConnector(connector); // 创建 Engine 并绑定到 Service Engine engine new StandardEngine(); engine.setName(MyEngine); engine.setDefaultHost(localhost); service.setContainer(engine); // 创建 Host Host host new StandardHost(); host.setName(localhost); host.setAppBase(webapps); engine.addChild(host); // 创建 Context Context context new StandardContext(); context.setPath(/demo); context.setDocBase(/tmp/tomcat-demo/webapps/demo); context.addLifecycleListener(new Tomcat.FixContextListener()); host.addChild(context); // 添加自定义 Servlet Wrapper wrapper context.createWrapper(); wrapper.setName(hello); wrapper.setServletClass(HelloServlet.class.getName()); wrapper.setLoadOnStartup(1); context.addChild(wrapper); context.addServletMappingDecoded(/hello, hello); // 启动 tomcat.start(); tomcat.getServer().await(); } }这段代码虽然不长但涵盖了 Catalina 的核心组件创建过程。你可以看到Engine、Host、Context、Wrapper 是逐层添加的这正好对应了前面讲的嵌套结构。FixContextListener是 Tomcat 提供的一个监听器负责在 Context 启动时做一些必要的初始化工作比如设置类加载器、解析web.xml等。4.3 配置 Servlet 映射与初始化参数Servlet 映射是 Catalina 请求路由的核心。除了上面代码中的addServletMappingDecoded你也可以通过web.xml来配置。两种方式本质上是等价的但编程方式更适合动态场景。servlet servlet-namehello/servlet-name servlet-classcom.example.HelloServlet/servlet-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param load-on-startup1/load-on-startup /servlet servlet-mapping servlet-namehello/servlet-name url-pattern/hello/url-pattern /servlet-mappingload-on-startup的值决定了 Servlet 的初始化顺序。值越小优先级越高如果多个 Servlet 都配置了相同的值Tomcat 会按照它们在web.xml中出现的顺序依次初始化。这个细节在排查“某个 Servlet 初始化依赖另一个 Servlet”的问题时很有用。init-param可以通过ServletConfig.getInitParameter()获取。我一般用它来传递一些简单的配置比如编码格式、超时时间等。但要注意init-param只在 Servlet 初始化时读取一次运行期间修改web.xml不会生效除非重启应用。4.4 请求处理全流程跟踪当一个请求到达时Catalina 的处理流程大致如下Connector 接收请求解析成Request和Response对象。Engine 的 Pipeline 开始执行第一个 Valve 通常是StandardEngineValve。StandardEngineValve根据请求的 Host 找到对应的 Host 容器。Host 的 Pipeline 执行StandardHostValve根据请求路径找到对应的 Context。Context 的 Pipeline 执行StandardContextValve找到匹配的 Wrapper。Wrapper 的 Pipeline 执行StandardWrapperValve调用 Servlet 的service()方法。Servlet 处理完成后响应沿原路返回经过各个 Valve 的后处理逻辑。这个流程看起来简单但每一步都有大量细节。比如StandardContextValve会检查请求的路径是否匹配 Context 的路径如果不匹配就返回 404。StandardWrapperValve会处理 Servlet 的加载、初始化和线程安全。实操心得如果你在自定义 Valve 中打印请求日志发现日志顺序和预期不一致很可能是因为 Valve 的配置位置不对。Engine 级别的 Valve 先执行然后是 Host、Context、Wrapper。理解这个顺序对排查问题非常重要。5. 常见问题与排查技巧实录5.1 请求 404映射配置的常见坑404 是 Catalina 层面最常见的问题之一。原因通常有以下几种问题现象可能原因排查方法访问/hello返回 404Servlet 映射路径写错检查url-pattern是否以/开头访问/demo/hello返回 404Context 路径不匹配检查context.setPath()和实际访问路径静态资源 404默认 Servlet 未启用检查conf/web.xml中 DefaultServlet 配置所有请求都 404Host 的 appBase 配置错误检查appBase目录是否存在且可读我遇到过一个比较隐蔽的案例url-pattern配置成了hello而不是/hello结果 Tomcat 把它当成了精确匹配只有访问/hello时才会命中但实际请求路径是/demo/hello导致 404。后来改成/*或者/hello/*才解决。5.2 类加载冲突ClassNotFoundException 与 NoClassDefFoundErrorCatalina 的类加载机制遵循双亲委派模型但做了一些调整。每个 Web 应用有自己的WebappClassLoader它优先加载WEB-INF/classes和WEB-INF/lib下的类然后再委托给父加载器。这种设计是为了让应用之间的类相互隔离。但这也带来了一个常见问题如果两个应用依赖了同一个 jar 的不同版本可能会出现ClassNotFoundException或NoClassDefFoundError。排查这类问题时我一般会检查WEB-INF/lib下是否有重复的 jar。使用-verbose:class参数启动 JVM观察类的加载来源。检查catalina.properties中的tomcat.util.scan.StandardJarScanFilter.jarsToSkip配置避免不必要的 jar 扫描。注意如果应用依赖了 Tomcat 本身提供的类如javax.servlet不要把这些 jar 打包到WEB-INF/lib中否则会导致类加载冲突。5.3 Session 丢失Cookie 与路径的微妙关系Session 丢失是另一个高频问题。常见原因包括Cookie 路径不匹配如果应用部署在/demo下但 Cookie 的 Path 设置成了/浏览器可能不会发送 Cookie。Session 超时默认 30 分钟可以在web.xml中通过session-config调整。多应用共享 Session默认情况下每个应用有独立的 Session。如果需要共享可以配置crossContexttrue或者使用外部 Session 存储。session-config session-timeout60/session-timeout cookie-config nameMYSESSIONID/name path//path http-onlytrue/http-only /cookie-config /session-confighttp-only设为true可以防止 JavaScript 读取 Cookie提升安全性。secure属性设为true则只在 HTTPS 下发送 Cookie。这些细节在生产环境配置中非常重要。5.4 性能调优线程池与连接器参数Catalina 本身的性能开销并不大大部分性能问题出在 Connector 和线程池配置上。以下是一些关键参数参数默认值建议值说明maxThreads200500-1000最大工作线程数minSpareThreads1050最小空闲线程数acceptCount100500等待队列长度connectionTimeout2000010000连接超时时间毫秒maxConnections8192根据硬件调整最大连接数调整这些参数时不要盲目照搬网上的“最优配置”。我一般会先用默认配置跑一轮压测观察 CPU、内存、线程数的变化再逐步调整。比如maxThreads设得太大反而会因为线程切换开销导致性能下降。实操心得有一次我把maxThreads从 200 调到了 2000结果 QPS 不升反降。后来用jstack分析发现大量线程在竞争锁实际有效并发并没有提高。最后调回 500 并优化了业务逻辑性能才稳定下来。6. 从 Catalina 设计中学到的工程思维Catalina 的代码量很大但它的设计思路其实很清晰分层、解耦、生命周期统一管理。这三条原则不仅适用于 Web 容器也适用于大多数中间件和框架设计。分层让每一层只关注自己的职责Engine 不需要知道 Connector 用的是 NIO 还是 APRContext 不需要知道 Host 的域名解析逻辑。解耦让组件可以独立替换和测试比如你可以自定义一个 Valve 来替换默认的访问日志实现。生命周期统一管理则保证了启动和停止的顺序可控避免了资源泄漏和状态不一致。我在实际工作中遇到复杂系统设计时经常会回想 Catalina 的结构。比如设计一个任务调度系统可以类比成 Server → Scheduler → JobGroup → Job 的层级设计一个 API 网关可以类比成 Engine → Host → Context → Wrapper 的请求处理链。这种“套娃式”的容器结构虽然看起来繁琐但在需要隔离和复用的场景下往往是最稳妥的方案。最后分享一个小技巧如果你在排查 Tomcat 问题时不知道从哪下手可以先打开conf/logging.properties把org.apache.catalina的日志级别调到FINE。这样 Catalina 会输出详细的容器启动、请求路由和 Servlet 调用日志很多问题看一眼日志就能定位。当然生产环境记得调回去不然日志量会爆炸。
1. 从一次线上故障说起为什么要搞懂 Catalina刚入行那会儿我对 Tomcat 的认知就停留在“把 war 包丢进 webapps启动 startup.sh浏览器能访问就行”。直到有一次生产环境出现了一个诡异问题某个接口在高并发下响应时间飙升但 CPU 和内存监控看起来都很正常日志里也没有任何报错。当时团队里几个人排查了一整天最后发现是 Servlet 的load-on-startup配置和某个 Filter 的初始化顺序出了问题导致部分请求在首次访问时被阻塞在类加载阶段。那次之后我才意识到如果只把 Tomcat 当成一个“黑盒”遇到深层次问题时就只能靠猜。而 Tomcat 最核心的部分就是它的Servlet 容器 Catalina。你可以把 Catalina 理解为 Tomcat 的“心脏”——它负责解析 XML 配置、管理 Servlet 生命周期、处理请求映射、维护 Session、执行 Filter 链几乎所有跟“动态请求处理”相关的逻辑都在这里完成。这篇内容适合谁看如果你已经用过 Tomcat 部署项目但对其内部结构一知半解或者你正在准备面试想搞清楚“Tomcat 为什么能处理 Servlet”这类问题又或者你遇到了请求映射、类加载、Session 共享等疑难杂症想从容器层面找到根因——那这篇关于 Catalina 的拆解应该能帮到你。我会从整体架构讲到核心组件再落到实操配置和排查技巧尽量把“为什么这么设计”和“实际怎么用”都讲透。2. Catalina 的整体架构与核心设计思路2.1 Catalina 到底是什么从“容器”这个词说起很多人第一次听到“Servlet 容器”这个词会觉得抽象。其实你可以把它类比成一个“餐厅的后厨管理系统”。Servlet 就是你写的菜谱处理逻辑而 Catalina 就是那个负责接收订单HTTP 请求、决定由哪个厨师Servlet来做、管理厨具Session、Filter、最后把菜端出去响应的整套体系。从代码层面看Catalina 是 Tomcat 的一个核心模块位于org.apache.catalina包下。它实现了 Java Servlet 规范中定义的容器行为同时在此基础上做了大量工程化扩展。Tomcat 的整体架构可以粗略分为两层连接器层Connector和容器层Container。Connector 负责底层的网络通信把字节流解析成HttpServletRequest对象而 Catalina 就是容器层负责处理这些请求对象并生成HttpServletResponse。这种分层设计的好处非常明显Connector 可以替换比如换成 NIO、APR 等不同实现而 Catalina 不需要关心底层用的是哪种 IO 模型。反过来Catalina 的容器逻辑也可以独立演进只要接口约定不变两者就能灵活组合。这其实是一种典型的“关注点分离”思路也是 Tomcat 能长期保持稳定和可扩展的关键原因。2.2 为什么采用分层容器结构Server、Service、Engine、Host、ContextCatalina 的容器结构是嵌套的从外到内依次是Server → Service → Engine → Host → Context。很多初学者会觉得这层套娃太复杂但每一层都有明确的职责划分。Server 是整个 Tomcat 实例的顶层代表一个 JVM 里通常只有一个 Server。Service 是 Server 内部的一个逻辑单元它把 Connector 和 Engine 绑定在一起——也就是说一个 Service 负责“从哪个端口接收请求”以及“交给哪个引擎处理”。Engine 是真正处理请求的核心容器它内部可以包含多个 Host。Host 代表一个虚拟主机对应一个域名。Context 则是我们最熟悉的“一个 Web 应用”也就是一个 war 包解压后的目录或者一个应用上下文。为什么要设计这么多层核心原因是隔离与复用。比如一台服务器上可以部署多个域名Host每个域名下可以跑多个应用Context它们共享同一个 Engine 的处理能力但彼此之间又相互隔离。如果没有这层结构所有应用混在一起配置和资源管理会变得极其混乱。注意很多人在配置server.xml时只关注 Connector 的端口忽略了 Host 和 Context 的层级关系导致虚拟主机配置不生效。理解这个嵌套结构是排查此类问题的前提。2.3 生命周期管理Lifecycle 接口的统一设计Catalina 里几乎所有核心组件都实现了Lifecycle接口。这个接口定义了一套标准的状态流转init → start → stop → destroy。每个组件在启动时会触发LifecycleEvent父组件负责调用子组件的start方法形成一条启动链。这种设计的精妙之处在于统一管理。比如你调用Server.start()它会依次启动 Service、Engine、Host、Context最后启动各个 WrapperServlet 包装器。停止时则反向执行。整个过程不需要人工干预也不会出现“某个组件忘了启动”的情况。从实操角度看如果你在自定义 Valve 或 Listener 时发现初始化顺序不对大概率是因为没有正确实现 Lifecycle 接口或者把组件挂载到了错误的层级。我个人的经验是自定义组件尽量挂载在 Context 或 Host 级别这样生命周期由容器统一管理不容易出问题。3. 核心组件深度拆解与实操要点3.1 Engine 与 Host请求进入容器的第一站当 Connector 把请求交给 Catalina 后首先到达的是 Engine。Engine 的主要职责是选择正确的 Host。它内部维护了一个 Host 列表根据请求中的域名或者 IP来匹配对应的虚拟主机。如果找不到匹配的 Host就会使用默认 Host通常是localhost。Host 的配置在server.xml中非常直观Host namewww.example.com appBasewebapps unpackWARstrue autoDeploytrue Context path/myapp docBase/opt/apps/myapp reloadablefalse/ /Host这里有几个关键参数值得展开说。appBase指定了应用的基础目录Tomcat 会自动扫描这个目录下的 war 包或文件夹。unpackWARs决定是否自动解压 war 包生产环境一般设为true方便查看和修改配置。autoDeploy控制是否自动部署新应用开发环境可以开启生产环境建议关闭以避免意外部署。Context的docBase可以指向任意目录不一定非要在appBase下。这个特性在部署外部应用时非常有用。reloadable参数需要特别小心设为true时Tomcat 会监控WEB-INF/classes和WEB-INF/lib下的变化并自动重启应用。开发时很方便但生产环境开启会带来严重的性能开销因为每次类变化都会触发整个应用的重新加载。实操心得我曾经遇到过一个应用启动特别慢的问题排查后发现是reloadabletrue加上WEB-INF/lib下有大量 jar 包Tomcat 每次启动都要扫描所有 jar 的时间戳。改成false后启动时间从 90 秒降到了 15 秒。3.2 Context 与 WrapperServlet 的真正归宿Context 代表一个 Web 应用它是 Catalina 中最重要的容器之一。一个 Context 内部可以包含多个 Wrapper每个 Wrapper 对应一个 Servlet 实例。Wrapper 是容器层级的最底层也是 Servlet 生命周期的实际管理者。Servlet 的加载和初始化流程大致是这样的Context 启动时会读取web.xml或注解配置解析出所有 Servlet 定义。如果某个 Servlet 配置了load-on-startup且值大于等于 0Context 会立即调用它的init()方法。否则Servlet 会在第一次请求到达时才被初始化。这里有一个容易被忽略的细节Servlet 实例在容器中通常是单例的。也就是说多个请求会共享同一个 Servlet 对象。这就解释了为什么在 Servlet 中定义实例变量是不安全的——多个线程同时访问会导致数据混乱。正确的做法是把状态保存在局部变量、ThreadLocal或者外部存储中。// 错误示范实例变量存在线程安全问题 public class MyServlet extends HttpServlet { private int count 0; // 多个线程共享会出问题 protected void doGet(HttpServletRequest req, HttpServletResponse resp) { count; // 非原子操作并发下结果不可预期 } } // 正确做法使用局部变量或原子类 public class MyServlet extends HttpServlet { private AtomicInteger count new AtomicInteger(0); protected void doGet(HttpServletRequest req, HttpServletResponse resp) { int current count.incrementAndGet(); // 原子操作线程安全 } }Wrapper 还负责管理 Servlet 的过滤器链。Filter 的执行顺序由web.xml中的filter-mapping顺序决定而不是filter的定义顺序。这个细节在排查“Filter 为什么没生效”时非常关键。3.3 Pipeline 与 Valve请求处理的流水线机制Catalina 的请求处理采用了一种叫Pipeline-Valve的机制。你可以把它想象成一条流水线请求从 Engine 的 Pipeline 进入依次经过各个 Valve最后到达 Host、Context、Wrapper 的 Pipeline。每个 Valve 都可以对请求做预处理、后处理或者决定是否继续传递。Tomcat 内置了很多标准 Valve比如AccessLogValve负责记录访问日志RemoteAddrValve负责 IP 过滤ErrorReportValve负责生成错误页面。你也可以自定义 Valve实现鉴权、限流、请求日志等逻辑。public class CustomValve extends ValveBase { Override public void invoke(Request request, Response response) throws IOException, ServletException { long start System.currentTimeMillis(); try { getNext().invoke(request, response); // 传递给下一个 Valve } finally { long cost System.currentTimeMillis() - start; if (cost 1000) { // 记录慢请求 System.out.println(Slow request: request.getRequestURI() cost cost ms); } } } }自定义 Valve 需要在server.xml或context.xml中配置。这里有个经验Valve 的配置位置决定了它的作用范围。配置在 Engine 下对所有 Host 生效配置在 Host 下对该主机所有应用生效配置在 Context 下只对该应用生效。我一般把通用逻辑如访问日志放在 Engine 级别把业务相关逻辑放在 Context 级别。注意Valve 的invoke方法中如果不调用getNext().invoke()请求就会被中断后续的 Servlet 不会执行。这个特性可以用来做拦截但也要小心别误伤正常请求。4. 实操过程从零搭建一个 Catalina 级别的自定义容器4.1 环境准备与依赖引入要深入理解 Catalina最好的方式是自己动手写一个简化版的容器。这里我用 Maven 来管理依赖核心只需要 Servlet API 和 Tomcat 的嵌入版依赖。dependencies dependency groupIdorg.apache.tomcat.embed/groupId artifactIdtomcat-embed-core/artifactId version9.0.80/version /dependency dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency /dependencies选择 Tomcat 9 而不是 10 的原因是Tomcat 10 开始把javax.servlet换成了jakarta.servlet很多现有项目还没迁移。如果你是新项目可以直接上 Tomcat 10 或 11但要注意包名变化。4.2 手动创建 Server、Service 和 Connector下面这段代码展示了如何用编程方式启动一个内嵌 Tomcat并手动配置 Catalina 的核心组件。public class EmbeddedTomcatDemo { public static void main(String[] args) throws Exception { // 创建 Server Tomcat tomcat new Tomcat(); tomcat.setBaseDir(/tmp/tomcat-demo); tomcat.setPort(8080); // 获取 Server 和 Service Server server tomcat.getServer(); Service service server.findService(Tomcat); // 配置 Connector Connector connector new Connector(org.apache.coyote.http11.Http11NioProtocol); connector.setPort(8080); connector.setURIEncoding(UTF-8); service.addConnector(connector); // 创建 Engine 并绑定到 Service Engine engine new StandardEngine(); engine.setName(MyEngine); engine.setDefaultHost(localhost); service.setContainer(engine); // 创建 Host Host host new StandardHost(); host.setName(localhost); host.setAppBase(webapps); engine.addChild(host); // 创建 Context Context context new StandardContext(); context.setPath(/demo); context.setDocBase(/tmp/tomcat-demo/webapps/demo); context.addLifecycleListener(new Tomcat.FixContextListener()); host.addChild(context); // 添加自定义 Servlet Wrapper wrapper context.createWrapper(); wrapper.setName(hello); wrapper.setServletClass(HelloServlet.class.getName()); wrapper.setLoadOnStartup(1); context.addChild(wrapper); context.addServletMappingDecoded(/hello, hello); // 启动 tomcat.start(); tomcat.getServer().await(); } }这段代码虽然不长但涵盖了 Catalina 的核心组件创建过程。你可以看到Engine、Host、Context、Wrapper 是逐层添加的这正好对应了前面讲的嵌套结构。FixContextListener是 Tomcat 提供的一个监听器负责在 Context 启动时做一些必要的初始化工作比如设置类加载器、解析web.xml等。4.3 配置 Servlet 映射与初始化参数Servlet 映射是 Catalina 请求路由的核心。除了上面代码中的addServletMappingDecoded你也可以通过web.xml来配置。两种方式本质上是等价的但编程方式更适合动态场景。servlet servlet-namehello/servlet-name servlet-classcom.example.HelloServlet/servlet-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param load-on-startup1/load-on-startup /servlet servlet-mapping servlet-namehello/servlet-name url-pattern/hello/url-pattern /servlet-mappingload-on-startup的值决定了 Servlet 的初始化顺序。值越小优先级越高如果多个 Servlet 都配置了相同的值Tomcat 会按照它们在web.xml中出现的顺序依次初始化。这个细节在排查“某个 Servlet 初始化依赖另一个 Servlet”的问题时很有用。init-param可以通过ServletConfig.getInitParameter()获取。我一般用它来传递一些简单的配置比如编码格式、超时时间等。但要注意init-param只在 Servlet 初始化时读取一次运行期间修改web.xml不会生效除非重启应用。4.4 请求处理全流程跟踪当一个请求到达时Catalina 的处理流程大致如下Connector 接收请求解析成Request和Response对象。Engine 的 Pipeline 开始执行第一个 Valve 通常是StandardEngineValve。StandardEngineValve根据请求的 Host 找到对应的 Host 容器。Host 的 Pipeline 执行StandardHostValve根据请求路径找到对应的 Context。Context 的 Pipeline 执行StandardContextValve找到匹配的 Wrapper。Wrapper 的 Pipeline 执行StandardWrapperValve调用 Servlet 的service()方法。Servlet 处理完成后响应沿原路返回经过各个 Valve 的后处理逻辑。这个流程看起来简单但每一步都有大量细节。比如StandardContextValve会检查请求的路径是否匹配 Context 的路径如果不匹配就返回 404。StandardWrapperValve会处理 Servlet 的加载、初始化和线程安全。实操心得如果你在自定义 Valve 中打印请求日志发现日志顺序和预期不一致很可能是因为 Valve 的配置位置不对。Engine 级别的 Valve 先执行然后是 Host、Context、Wrapper。理解这个顺序对排查问题非常重要。5. 常见问题与排查技巧实录5.1 请求 404映射配置的常见坑404 是 Catalina 层面最常见的问题之一。原因通常有以下几种问题现象可能原因排查方法访问/hello返回 404Servlet 映射路径写错检查url-pattern是否以/开头访问/demo/hello返回 404Context 路径不匹配检查context.setPath()和实际访问路径静态资源 404默认 Servlet 未启用检查conf/web.xml中 DefaultServlet 配置所有请求都 404Host 的 appBase 配置错误检查appBase目录是否存在且可读我遇到过一个比较隐蔽的案例url-pattern配置成了hello而不是/hello结果 Tomcat 把它当成了精确匹配只有访问/hello时才会命中但实际请求路径是/demo/hello导致 404。后来改成/*或者/hello/*才解决。5.2 类加载冲突ClassNotFoundException 与 NoClassDefFoundErrorCatalina 的类加载机制遵循双亲委派模型但做了一些调整。每个 Web 应用有自己的WebappClassLoader它优先加载WEB-INF/classes和WEB-INF/lib下的类然后再委托给父加载器。这种设计是为了让应用之间的类相互隔离。但这也带来了一个常见问题如果两个应用依赖了同一个 jar 的不同版本可能会出现ClassNotFoundException或NoClassDefFoundError。排查这类问题时我一般会检查WEB-INF/lib下是否有重复的 jar。使用-verbose:class参数启动 JVM观察类的加载来源。检查catalina.properties中的tomcat.util.scan.StandardJarScanFilter.jarsToSkip配置避免不必要的 jar 扫描。注意如果应用依赖了 Tomcat 本身提供的类如javax.servlet不要把这些 jar 打包到WEB-INF/lib中否则会导致类加载冲突。5.3 Session 丢失Cookie 与路径的微妙关系Session 丢失是另一个高频问题。常见原因包括Cookie 路径不匹配如果应用部署在/demo下但 Cookie 的 Path 设置成了/浏览器可能不会发送 Cookie。Session 超时默认 30 分钟可以在web.xml中通过session-config调整。多应用共享 Session默认情况下每个应用有独立的 Session。如果需要共享可以配置crossContexttrue或者使用外部 Session 存储。session-config session-timeout60/session-timeout cookie-config nameMYSESSIONID/name path//path http-onlytrue/http-only /cookie-config /session-confighttp-only设为true可以防止 JavaScript 读取 Cookie提升安全性。secure属性设为true则只在 HTTPS 下发送 Cookie。这些细节在生产环境配置中非常重要。5.4 性能调优线程池与连接器参数Catalina 本身的性能开销并不大大部分性能问题出在 Connector 和线程池配置上。以下是一些关键参数参数默认值建议值说明maxThreads200500-1000最大工作线程数minSpareThreads1050最小空闲线程数acceptCount100500等待队列长度connectionTimeout2000010000连接超时时间毫秒maxConnections8192根据硬件调整最大连接数调整这些参数时不要盲目照搬网上的“最优配置”。我一般会先用默认配置跑一轮压测观察 CPU、内存、线程数的变化再逐步调整。比如maxThreads设得太大反而会因为线程切换开销导致性能下降。实操心得有一次我把maxThreads从 200 调到了 2000结果 QPS 不升反降。后来用jstack分析发现大量线程在竞争锁实际有效并发并没有提高。最后调回 500 并优化了业务逻辑性能才稳定下来。6. 从 Catalina 设计中学到的工程思维Catalina 的代码量很大但它的设计思路其实很清晰分层、解耦、生命周期统一管理。这三条原则不仅适用于 Web 容器也适用于大多数中间件和框架设计。分层让每一层只关注自己的职责Engine 不需要知道 Connector 用的是 NIO 还是 APRContext 不需要知道 Host 的域名解析逻辑。解耦让组件可以独立替换和测试比如你可以自定义一个 Valve 来替换默认的访问日志实现。生命周期统一管理则保证了启动和停止的顺序可控避免了资源泄漏和状态不一致。我在实际工作中遇到复杂系统设计时经常会回想 Catalina 的结构。比如设计一个任务调度系统可以类比成 Server → Scheduler → JobGroup → Job 的层级设计一个 API 网关可以类比成 Engine → Host → Context → Wrapper 的请求处理链。这种“套娃式”的容器结构虽然看起来繁琐但在需要隔离和复用的场景下往往是最稳妥的方案。最后分享一个小技巧如果你在排查 Tomcat 问题时不知道从哪下手可以先打开conf/logging.properties把org.apache.catalina的日志级别调到FINE。这样 Catalina 会输出详细的容器启动、请求路由和 Servlet 调用日志很多问题看一眼日志就能定位。当然生产环境记得调回去不然日志量会爆炸。
