Tomcat 這玩意兒做 Java Web 的基本繞不開(kāi)。可現(xiàn)實(shí)里最常見(jiàn)的場(chǎng)景是本地跑得好好的一上服務(wù)器就報(bào)Address already in useIDEA 里點(diǎn)啟動(dòng)控制臺(tái)刷出一屏紅字最后一行寫(xiě)著could not obtain connection to query metadata項(xiàng)目部署上去訪問(wèn)是 404日志里連個(gè)像樣的提示都沒(méi)有。多數(shù)人這時(shí)候的做法是百度關(guān)鍵詞找到一條差不多的答案復(fù)制粘貼重啟好了——但下次換個(gè)環(huán)境又炸因?yàn)閴焊恢肋@個(gè)報(bào)錯(cuò)是從哪一層冒出來(lái)的。我這篇文章想干兩件事。第一件把 Tomcat 常見(jiàn)的報(bào)錯(cuò)按出問(wèn)題的層次重新梳理一遍從啟動(dòng)腳本、端口、類加載、連接池一路到 SSL 配置講清楚每種報(bào)錯(cuò)背后到底發(fā)生了什么為什么這么解。第二件也是我覺(jué)得更有意思的——手動(dòng)寫(xiě)一個(gè)能跑起來(lái)的迷你 Tomcat用ServerSocket加線程池自己解析 HTTP 報(bào)文、自己映射 Servlet、自己加載WEB-INF下的類。寫(xiě)完之后你再回頭看那些報(bào)錯(cuò)會(huì)發(fā)現(xiàn)它們的位置感一下子就清晰了ClassNotFoundException 是類加載層的事404 是映射層的事端口沖突是網(wǎng)絡(luò)層的事各歸各位。這篇內(nèi)容適合誰(shuí)看正在被 Tomcat 報(bào)錯(cuò)折磨的運(yùn)維和后端同學(xué)、想搞明白 Web 容器內(nèi)部到底怎么回事的初中級(jí)開(kāi)發(fā)者、以及準(zhǔn)備給現(xiàn)有項(xiàng)目做容器替換或者調(diào)優(yōu)的人。代碼部分我會(huì)給完整可運(yùn)行的版本但更重要的是每一步為什么這么設(shè)計(jì)——這才是我自己踩坑之后真正記住的東西。1. 先想清楚Tomcat 到底替我們接管了哪些活1.1 一個(gè)請(qǐng)求進(jìn)來(lái)經(jīng)過(guò)了幾道手很多人對(duì) Tomcat 的認(rèn)知停留在放 war 包的地方。但你只要自己寫(xiě)過(guò)一次最原始的 Socket 服務(wù)就會(huì)立刻明白它省掉了多少事。一個(gè) HTTP 請(qǐng)求從瀏覽器發(fā)出到你的doGet方法被執(zhí)行中間至少經(jīng)歷了這些環(huán)節(jié)內(nèi)核把 TCP 連接交給監(jiān)聽(tīng)端口的進(jìn)程Tomcat 的 Acceptor 線程接住這個(gè)連接交給 Worker 線程Worker 從 socket 上讀字節(jié)流按 HTTP 協(xié)議切分出請(qǐng)求行、請(qǐng)求頭、請(qǐng)求體根據(jù)請(qǐng)求行里的 URI找到對(duì)應(yīng)的 Host、Context也就是你的應(yīng)用、Wrapper也就是那個(gè)具體的 Servlet構(gòu)造HttpServletRequest和HttpServletResponse兩個(gè)包裝對(duì)象調(diào)用Servlet.service()最后把響應(yīng)對(duì)象里的狀態(tài)行、響應(yīng)頭、響應(yīng)體按協(xié)議格式寫(xiě)回 socket 并關(guān)閉連接。這里面每一環(huán)都可能出錯(cuò)而且報(bào)錯(cuò)信息分布在完全不同的地方。端口被占用是內(nèi)核層直接就拒絕了URI 找不到對(duì)應(yīng) Context 是映射層的問(wèn)題Servlet 類加載不出來(lái)是類加載器的問(wèn)題。你把這條鏈路在腦子里畫(huà)出來(lái)排查速度至少快一倍。1.2 為什么手寫(xiě)一遍是最快的理解方式我在帶新人的時(shí)候有個(gè)固定動(dòng)作讓對(duì)方用ServerSocket寫(xiě)一個(gè)只返回 hello 的服務(wù)。寫(xiě)完之后再問(wèn)一句如果我要支持兩個(gè)不同的路徑返回不同內(nèi)容呢他就自然開(kāi)始想路由表再問(wèn)如果我要讓用戶自己寫(xiě)類來(lái)處理請(qǐng)求呢他就自然想到接口和反射再問(wèn)如果用戶把類打包成 jar 放在某個(gè)目錄下呢他就自然碰到類加載器。這就是手寫(xiě)迷你 Tomcat 的價(jià)值——它把你平時(shí)當(dāng)成黑盒的那一層拆成了幾個(gè)你能一手寫(xiě)完的小模塊。而且這個(gè)過(guò)程不白費(fèi)功夫Tomcat 本身的架構(gòu)也是這么分層的Server→Service→ConnectorEngine→Host→Context→Wrapper。你手寫(xiě)的版本就是它的一根簡(jiǎn)化骨架。1.3 報(bào)錯(cuò)分類的底層邏輯我把常見(jiàn)報(bào)錯(cuò)歸成五大類后面第 5 章會(huì)逐條展開(kāi)報(bào)錯(cuò)層次典型現(xiàn)象排查入口啟動(dòng)腳本 / 環(huán)境雙擊閃退、JAVA_HOME not foundcatalina.bat、setclasspath.bat輸出網(wǎng)絡(luò) / 端口Address already in usenetstat、lsof、ps -ef部署 / 映射404、歡迎頁(yè)不對(duì)、應(yīng)用未加載logs/catalina.out、conf/server.xml類加載 / 依賴ClassNotFoundException、NoClassDefFoundErrorWEB-INF/lib、WEB-INF/classes資源 / 配置連接池拿不到連接、SSL 握手失敗、亂碼數(shù)據(jù)源配置、keystore、Connector編碼這張表你貼在工位上遇到紅字先定位它在哪一行比漫無(wú)目的地搜關(guān)鍵詞高效得多。2. 手動(dòng)實(shí)現(xiàn)迷你 Tomcat 的整體設(shè)計(jì)2.1 拆成三層網(wǎng)絡(luò)層、協(xié)議層、容器層我在設(shè)計(jì)這個(gè)迷你容器的時(shí)候刻意做了嚴(yán)格分層因?yàn)榉謱颖旧砭褪菫榱俗寛?bào)錯(cuò)有歸屬。網(wǎng)絡(luò)層只干一件事綁定端口accept()阻塞等待連接把Socket丟給線程池。它完全不懂 HTTP也不懂你的業(yè)務(wù)。協(xié)議層負(fù)責(zé)把InputStream里的字節(jié)翻譯成結(jié)構(gòu)化的請(qǐng)求對(duì)象再把結(jié)構(gòu)化的響應(yīng)對(duì)象序列化回字節(jié)。容器層則負(fù)責(zé)路由、Servlet 生命周期、類加載。為什么非要這么分因?yàn)榉滞曛竽阋獡Q實(shí)現(xiàn)的時(shí)候成本極低。比如網(wǎng)絡(luò)層從 BIO 換成 NIO容器層一行都不用改協(xié)議層要支持 HTTP/1.1 的chunked傳輸也只需要改動(dòng)解析和寫(xiě)出這兩個(gè)方法。Tomcat 的Connector和Container分離就是這個(gè)道理只不過(guò)它做得更極致。2.2 網(wǎng)絡(luò)模型為什么從 BIO 起步有人會(huì)說(shuō)都什么年代了還寫(xiě) BIO。但對(duì)一個(gè)用來(lái)理解原理的迷你實(shí)現(xiàn)BIO 加線程池是最優(yōu)解原因有三點(diǎn)。第一代碼路徑清晰。一個(gè)請(qǐng)求一個(gè)線程你打斷點(diǎn)的時(shí)候能完整看到從accept到service的調(diào)用棧不會(huì)在 Selector 的事件循環(huán)里迷失。第二它足夠支撐中等規(guī)模場(chǎng)景。Tomcat 直到 8.5 才默認(rèn)啟用 NIO此前長(zhǎng)期使用的 APR 和 BIO 組合在生產(chǎn)環(huán)境跑了十幾年說(shuō)明 BIO 加合理線程池并不是不能用。第三也是關(guān)鍵的一點(diǎn)——它讓你直觀感受到maxThreads這個(gè)參數(shù)到底限制的是什么。當(dāng)你看到線程池滿了之后新連接全部堵在accept隊(duì)列里你就永遠(yuǎn)不會(huì)再隨便把maxThreads調(diào)到 5000。提示迷你實(shí)現(xiàn)用 BIO 是為了理解生產(chǎn)上 Tomcat 8.5 以后默認(rèn)就是 NIO 模式IO 多路復(fù)用在連接數(shù)上萬(wàn)時(shí)優(yōu)勢(shì)明顯這一點(diǎn)不要混淆。2.3 目錄結(jié)構(gòu)與職責(zé)劃分我最終落地的結(jié)構(gòu)是這樣的mini-tomcat/ ├── src/main/java/com/example/mt/ │ ├── MiniTomcat.java // 啟動(dòng)入口網(wǎng)絡(luò)層 │ ├── http/ │ │ ├── MiniRequest.java // 請(qǐng)求對(duì)象協(xié)議層 │ │ ├── MiniResponse.java // 響應(yīng)對(duì)象協(xié)議層 │ │ └── HttpParser.java // 報(bào)文解析 │ ├── container/ │ │ ├── MiniServlet.java // Servlet 接口 │ │ ├── ServletMapping.java // 路由表 │ │ └── WebXmlParser.java // 配置解析 │ └── loader/ │ └── WebappClassLoader.java └── webapps/ └── demo/ ├── WEB-INF/web.xml ├── WEB-INF/classes/ └── index.html每個(gè)包的邊界和前面說(shuō)的三層嚴(yán)格對(duì)應(yīng)。MiniTomcat里的代碼不會(huì)出現(xiàn)Servlet字樣container包里的代碼不會(huì)出現(xiàn)Socket字樣。這個(gè)約束看起來(lái)很教條但你寫(xiě)下去就會(huì)發(fā)現(xiàn)它逼著你在正確的層次上解決問(wèn)題。比如 URL 解碼把%E4%B8%AD還原成中文它天然屬于協(xié)議層就該放在HttpParser里而不是散落在路由查找的代碼中。3. 核心細(xì)節(jié)拆解報(bào)文解析、路由映射與類加載3.1 HTTP 請(qǐng)求解析里最容易踩的三個(gè)坑第一個(gè)坑BufferedReader和請(qǐng)求體的沖突。新手最常見(jiàn)的寫(xiě)法是new BufferedReader(new InputStreamReader(socket.getInputStream()))然后readLine()讀第一行得到請(qǐng)求行。這在純 GET 請(qǐng)求下沒(méi)問(wèn)題因?yàn)?GET 沒(méi)有請(qǐng)求體。但一旦是 POST你再用同一個(gè) reader 去讀 body就會(huì)讀到空——因?yàn)锽ufferedReader內(nèi)部做了緩沖已經(jīng)把一部分 body 吃進(jìn)它自己的緩沖區(qū)了而你從InputStream直接再讀讀到的是緩沖區(qū)之后的內(nèi)容。正確做法是解析完請(qǐng)求頭和請(qǐng)求行之后根據(jù)Content-Length頭從原始的InputStream上精確讀取對(duì)應(yīng)字節(jié)數(shù)。這也是為什么 Tomcat 內(nèi)部對(duì)ServletInputStream有嚴(yán)格的狀態(tài)機(jī)管理——一旦你調(diào)用了getReader()再調(diào)getInputStream()就會(huì)拋IllegalStateException。它就是在防這種讀串了的情況。第二個(gè)坑請(qǐng)求頭的行結(jié)束符。HTTP 協(xié)議規(guī)定是\r\n但有些客戶端或者手寫(xiě)的測(cè)試工具會(huì)只發(fā)\n。readLine()恰好能容忍這兩種所以手工解析時(shí)用它反而安全。但如果你自己用read()逐字節(jié)找\r\n就得考慮兼容。第三個(gè)坑URI 的編碼。請(qǐng)求行里的 URI 是經(jīng)過(guò)百分號(hào)編碼的中文參數(shù)、空格、特殊符號(hào)都會(huì)變成%XX形式。加上號(hào)在表單提交里代表空格這兩套規(guī)則混在一起很容易解析錯(cuò)。我的處理順序是先按?切出 path 和 query再對(duì) query 按切分、按切分最后對(duì) key 和 value 分別做URLDecoder.decode(value, UTF-8)。注意URLDecoder會(huì)把也解成空格這在 query 場(chǎng)景下是符合規(guī)范的。3.2 響應(yīng)格式與狀態(tài)碼的封裝響應(yīng)寫(xiě)出去的時(shí)候最容易忽略的是頭部順序和Content-Length。HTTP 響應(yīng)格式是HTTP/1.1 200 OK\r\n Content-Type: text/html;charsetUTF-8\r\n Content-Length: 128\r\n \r\n body我見(jiàn)過(guò)有人把Content-Length算錯(cuò)結(jié)果是瀏覽器一直轉(zhuǎn)圈等數(shù)據(jù)直到超時(shí)。原因通常是用了Writer寫(xiě)字符但在計(jì)算長(zhǎng)度的時(shí)候算的是字符數(shù)而實(shí)際發(fā)出的是字節(jié)數(shù)。中文一個(gè)字符 UTF-8 下占三個(gè)字節(jié)這個(gè)差值會(huì)讓Content-Length偏小瀏覽器收到少于聲明長(zhǎng)度的數(shù)據(jù)就會(huì)一直等。所以在迷你實(shí)現(xiàn)里我統(tǒng)一用ByteArrayOutputStream先在內(nèi)存里把響應(yīng)體字節(jié)攢好拿到真實(shí)的字節(jié)長(zhǎng)度之后再寫(xiě)Content-Length最后一次性刷出去。這個(gè)先攢后發(fā)的思路和 Tomcat 里OutputBuffer的設(shè)計(jì)是一致的。3.3 路由映射從 URI 到 Servlet 實(shí)例路由的本質(zhì)是一個(gè)查找表。我在實(shí)現(xiàn)時(shí)用了最簡(jiǎn)單的方式MapString, MiniServletkey 是url-patternvalue 是單例的 Servlet 實(shí)例。這是為了簡(jiǎn)化真實(shí) Tomcat 里每個(gè)請(qǐng)求都會(huì)拿一個(gè)StandardWrapper它管理著 Servlet 實(shí)例的單例和生命周期。匹配規(guī)則上我先實(shí)現(xiàn)了精確匹配然后補(bǔ)了兩條匹配類型寫(xiě)法例子精確匹配/user/list請(qǐng)求路徑完全相同才命中前綴匹配/user/*以/user/開(kāi)頭都命中擴(kuò)展名匹配*.do以.do結(jié)尾都命中默認(rèn)匹配/兜底通常指向靜態(tài)資源處理優(yōu)先級(jí)是精確 前綴 擴(kuò)展名 默認(rèn)這一點(diǎn)必須和 Servlet 規(guī)范保持一致否則同一個(gè)項(xiàng)目從真正 Tomcat 遷移到你的迷你容器上行為就不一樣了。順便說(shuō)一句這個(gè)優(yōu)先級(jí)順序是很多人配置DispatcherServlet時(shí)踩坑的來(lái)源——/*會(huì)覆蓋掉*.jsp的映射導(dǎo)致 JSP 直接變成下載文件。3.4 類加載器隔離Tomcat 最容易被誤解的一層WEB-INF/classes和WEB-INF/lib/*.jar是應(yīng)用私有的父加載器看不到它們這就是所謂的類加載隔離。為什么要隔離因?yàn)橥粋€(gè) Tomcat 上可能跑十個(gè)應(yīng)用它們依賴的spring-core版本可能完全不同。如果不隔離第一個(gè)加載的版本就會(huì)覆蓋后面所有的應(yīng)用。Tomcat 的類加載順序和標(biāo)準(zhǔn)雙親委派是反的它先嘗試用WebappClassLoader自己加載加載不到才交給父加載器。這個(gè)打破雙親委派的行為正是很多ClassNotFoundException和LinkageError的根源。我在迷你實(shí)現(xiàn)里用URLClassLoader簡(jiǎn)化了這件事public class WebappClassLoader extends URLClassLoader { public WebappClassLoader(File webappDir, ClassLoader parent) throws Exception { super(buildUrls(webappDir), parent); } private static URL[] buildUrls(File webappDir) throws Exception { ListURL urls new ArrayList(); File classes new File(webappDir, WEB-INF/classes); if (classes.exists()) { urls.add(classes.toURI().toURL()); } File lib new File(webappDir, WEB-INF/lib); File[] jars lib.listFiles((d, n) - n.endsWith(.jar)); if (jars ! null) { for (File jar : jars) { urls.add(jar.toURI().toURL()); } } return urls.toArray(new URL[0]); } }有了它你在 Servlet 里寫(xiě)Class.forName(com.example.MyService)就能找到應(yīng)用私有的類而不會(huì)跑到系統(tǒng)的 classpath 里去找。理解了這幾十行代碼你再看 Tomcat 那些NoClassDefFoundError思路會(huì)清楚很多要么是 jar 沒(méi)進(jìn)WEB-INF/lib要么是同一個(gè)類被兩個(gè)加載器加載了導(dǎo)致類型轉(zhuǎn)換失敗。4. 完整實(shí)操寫(xiě)一個(gè)能跑靜態(tài)資源和 Servlet 的迷你容器4.1 環(huán)境準(zhǔn)備與工程搭建我用的是 JDK 17 加 Maven 的極簡(jiǎn)配置。為什么選 17 而不是 8因?yàn)閁RLClassLoader在 9 以后的模塊化環(huán)境下有一些限制但用于加載普通 jar 依然沒(méi)問(wèn)題而且 17 的Socket和字符串處理 API 更順手。如果你所在的項(xiàng)目必須用 JDK 8代碼也能原樣跑只是readAllBytes這類方法要換成循環(huán)讀取。pom.xml里只有一個(gè) JUnit其余全靠 JDK 自帶。這一點(diǎn)很重要——我刻意不引第三方 HTTP 庫(kù)就是為了讓你看清協(xié)議本身的處理過(guò)程。用 Netty 或者 Undertow 能更快跑起來(lái)但那就失去意義了。4.2 啟動(dòng)類網(wǎng)絡(luò)層的核心二十行public class MiniTomcat { private final int port; private final ExecutorService pool Executors.newFixedThreadPool(50); private final ServletMapping mapping new ServletMapping(); public MiniTomcat(int port) { this.port port; } public void start() throws Exception { mapping.load(new File(webapps/demo)); try (ServerSocket server new ServerSocket(port)) { System.out.println(MiniTomcat started on port port); while (true) { Socket socket server.accept(); pool.execute(() - handle(socket)); } } } private void handle(Socket socket) { try (socket; InputStream in socket.getInputStream(); OutputStream out socket.getOutputStream()) { MiniRequest req HttpParser.parse(in); MiniResponse resp new MiniResponse(out); if (req null) { return; } if (!mapping.dispatch(req, resp)) { StaticResourceHandler.handle(req, resp); } resp.flush(); } catch (Exception e) { e.printStackTrace(); } } }這里有個(gè)細(xì)節(jié)值得說(shuō)try (socket; in; out)這種寫(xiě)法會(huì)在代碼塊結(jié)束時(shí)自動(dòng)關(guān)閉所有資源。很多人手寫(xiě) HTTP 服務(wù)時(shí)忘了關(guān) Socket跑壓測(cè)的時(shí)候幾百個(gè)連接瞬間把文件句柄耗盡報(bào)Too many open files。生產(chǎn)上的 Tomcat 有連接池和空閑回收手寫(xiě)版本就必須靠try-with-resources兜底。線程池固定 50 個(gè)線程也是一種取舍。真實(shí)場(chǎng)景應(yīng)該做成可配置并且要意識(shí)到accept到線程池之后如果池子滿了任務(wù)會(huì)進(jìn)無(wú)界隊(duì)列連接會(huì)一直堆著不處理。生產(chǎn)上更穩(wěn)妥的做法是給隊(duì)列設(shè)個(gè)上限滿了就快速返回 503這也是 Tomcat 的acceptCount在干的事。4.3 請(qǐng)求與響應(yīng)對(duì)象的實(shí)現(xiàn)要點(diǎn)public class MiniRequest { private String method; private String uri; private String path; private String protocol; private final MapString, String headers new HashMap(); private final MapString, String params new HashMap(); private byte[] body; public String getParameter(String name) { return params.get(name); } public String getHeader(String name) { return headers.get(name.toLowerCase()); } public String getMethod() { return method; } public String getPath() { return path; } // 省略 setter }MiniResponse我給了它三個(gè)核心方法setStatus、setHeader、write。write把字節(jié)寫(xiě)進(jìn)內(nèi)存緩沖flush負(fù)責(zé)拼裝成完整報(bào)文寫(xiě)出去。這里再?gòu)?qiáng)調(diào)一遍前面提過(guò)的順序問(wèn)題一定要在flush里現(xiàn)算Content-Length不要提前寫(xiě)死。public void flush() throws IOException { byte[] data buffer.toByteArray(); StringBuilder head new StringBuilder(); head.append(HTTP/1.1 ).append(status).append(\r\n); if (!headers.containsKey(content-type)) { headers.put(Content-Type, text/html;charsetUTF-8); } headers.put(Content-Length, String.valueOf(data.length)); headers.forEach((k, v) - head.append(k).append(: ).append(v).append(\r\n)); head.append(\r\n); out.write(head.toString().getBytes(StandardCharsets.ISO_8859_1)); out.write(data); out.flush(); }注意響應(yīng)頭我用ISO_8859_1編碼寫(xiě)出去。這不是筆誤HTTP 頭部按規(guī)范只允許 ASCII 字符用ISO_8859_1保證每個(gè)字節(jié)原樣傳輸。如果用 UTF-8 編碼頭部遇到非 ASCII 字符會(huì)變成多字節(jié)客戶端解析頭部就會(huì)錯(cuò)位。4.4 靜態(tài)資源處理與 404 兜底靜態(tài)資源處理的價(jià)值在于它讓整個(gè)容器看起來(lái)像個(gè)真東西你可以在webapps/demo下丟一個(gè)index.html瀏覽器訪問(wèn)就能看到頁(yè)面。public class StaticResourceHandler { public static void handle(MiniRequest req, MiniResponse resp) throws IOException { String path req.getPath(); if (/.equals(path)) { path /index.html; } File file new File(webapps/demo, path); if (!file.exists() || file.isDirectory()) { resp.setStatus(404); resp.write(h1404 Not Found/h1.getBytes(StandardCharsets.UTF_8)); return; } String name file.getName().toLowerCase(); resp.setHeader(Content-Type, MimeTypes.of(name)); resp.write(Files.readAllBytes(file.toPath())); } }有一個(gè)安全問(wèn)題必須在手寫(xiě)版本里就養(yǎng)成習(xí)慣路徑穿越。如果用戶請(qǐng)求/../../etc/passwd直接拼接路徑就會(huì)讀到系統(tǒng)文件。真實(shí) Tomcat 通過(guò)canonicalPath校驗(yàn)來(lái)解決。我在迷你版里加了一句規(guī)范化檢查這對(duì)理解 Tomcat 的安全加固很有幫助。順便說(shuō) JSP。我最初也想在迷你版里跑 JSP但真正的 JSP 需要先編譯成 Servlet 再加載執(zhí)行工作量翻倍。我選擇的做法是把 JSP 的編譯產(chǎn)物手動(dòng)放到WEB-INF/classes下當(dāng)成普通 Servlet 來(lái)跑。這也順帶解釋了熱詞里那個(gè)操作——web 項(xiàng)目配置 tomcat 后查看 jsp 編譯后的 java 類你在 Tomcat 的work/Catalina/localhost/應(yīng)用名/org/apache/jsp/目錄下就能看到這些中間產(chǎn)物。項(xiàng)目莫名其妙報(bào) JSP 相關(guān)錯(cuò)誤的時(shí)候去那個(gè)目錄看生成的 Java 文件比盯著 JSP 源碼猜快得多。4.5 啟動(dòng)驗(yàn)證與目錄約定把MiniTomcat跑起來(lái)控制臺(tái)輸出MiniTomcat started on port 8080然后瀏覽器訪問(wèn)localhost:8080/index.html看到頁(yè)面訪問(wèn)localhost:8080/hello看到 Servlet 返回的內(nèi)容整個(gè)鏈路就通了。驗(yàn)證順序我建議這樣走先靜態(tài)資源再精確匹配的 Servlet再帶參數(shù)的 POST最后中文參數(shù)。每一步都通過(guò)再往下走出問(wèn)題的時(shí)候定位范圍就很小。我當(dāng)初第一次寫(xiě)的時(shí)候POST 中文參數(shù)一路亂碼最后發(fā)現(xiàn)是Content-Length用的是字符數(shù)而不是解碼后的字節(jié)數(shù)導(dǎo)致 body 讀少了一半U(xiǎn)TF-8 多字節(jié)字符被截?cái)?。這類問(wèn)題在真正的 Tomcat 里之所以不常見(jiàn)就是因?yàn)樗腛utputBuffer和編碼器已經(jīng)處理好了這些邊界。5. Tomcat 常見(jiàn)報(bào)錯(cuò)逐條排查實(shí)錄5.1 啟動(dòng)類報(bào)錯(cuò)端口、環(huán)境變量與腳本問(wèn)題java.net.BindException: Address already in use是出現(xiàn)頻率最高的一條。它的意思非常字面端口已經(jīng)被別的進(jìn)程占了。Linux 下排查用lsof -i:8080或者netstat -tunlp | grep 8080Windows 下用netstat -ano | findstr 8080拿到 PID再去任務(wù)管理器或者taskkill /PID xxx /F處理。有時(shí)候你確認(rèn)沒(méi)有 Java 進(jìn)程占著那就要考慮是不是之前的 Tomcat 沒(méi)殺干凈用ps -ef | grep tomcat過(guò)一遍再用kill -9清理。還有一種隱蔽情況TIME_WAIT狀態(tài)的連接還在占用端口這時(shí)候要么等一會(huì)兒要么在Connector上配SO_REUSEADDR。Neither the JAVA_HOME nor the JRE_HOME environment variable is defined這條出現(xiàn)在 Windows 下雙擊startup.bat閃退的場(chǎng)景。原因是setclasspath.bat在啟動(dòng)時(shí)找不到 JDK 路徑。解決方式是設(shè)好JAVA_HOME環(huán)境變量指向 JDK 根目錄而不是bin目錄。如果你機(jī)器上有多個(gè) JDK想讓 Tomcat 用指定的那個(gè)比如 JDK 17 而系統(tǒng)默認(rèn)是 8可以在setclasspath.bat開(kāi)頭顯式加一行set JAVA_HOMED:\jdk-17這樣只影響這個(gè) Tomcat 實(shí)例不動(dòng)全局環(huán)境變量多個(gè) Tomcat 并存時(shí)特別有用。注意JAVA_HOME指的是 JDK 安裝目錄含bin/java的那一層不是 JRE 目錄也不是bin目錄本身。這一條看著簡(jiǎn)單但我見(jiàn)過(guò)太多人在這里多寫(xiě)一層或者少寫(xiě)一層。5.2 部署與映射類報(bào)錯(cuò)404 與歡迎頁(yè)404 的成因太多我一般按這個(gè)順序排查先看logs/catalina.out里有沒(méi)有應(yīng)用的啟動(dòng)日志如果連 Deployment of web application archive 這種字樣的日志都沒(méi)有說(shuō)明 war 包根本沒(méi)被掃描到檢查webapps目錄權(quán)限和conf/server.xml里的appBase配置如果有啟動(dòng)日志但訪問(wèn)還是 404那大概率是 context path 對(duì)不上你在server.xml里配了Context path/myapp瀏覽器就得訪問(wèn)/myapp/xxx少一段多一段都不行。歡迎頁(yè)配置也是個(gè)高頻坑。web.xml里的welcome-file-list決定了訪問(wèn)目錄路徑時(shí)默認(rèn)返回哪個(gè)文件。如果列表里配了index.html但目錄下只有index.jspTomcat 不會(huì)自動(dòng)幫你找直接 404。而且歡迎頁(yè)的查找是順序匹配的列表越靠前的優(yōu)先級(jí)越高把index.html放在index.jsp前面會(huì)導(dǎo)致 JSP 永遠(yuǎn)不生效——明明文件在就是不顯示。打包方式也影響結(jié)果。war 包放進(jìn)去 Tomcat 會(huì)自動(dòng)解壓但如果你同時(shí)保留了舊的解壓目錄Tomcat 可能用的是舊目錄里的內(nèi)容。我踩過(guò)的坑是更新 war 包忘了刪對(duì)應(yīng)的解壓目錄改了半天代碼發(fā)現(xiàn)沒(méi)生效最后發(fā)現(xiàn)跑的是老目錄。穩(wěn)妥做法是停掉服務(wù)、刪掉 war 包和解壓目錄、再放新包。5.3 類加載與依賴類報(bào)錯(cuò)java.lang.ClassNotFoundException和NoClassDefFoundError看著像含義不同。前者是主動(dòng)加載時(shí)沒(méi)找到通常是Class.forName或者容器掃描時(shí)拋的后者是編譯期存在、運(yùn)行期找不到常常意味著類在加載過(guò)程中失敗了比如靜態(tài)代碼塊拋了異?；蛘哳惐粌蓚€(gè)不同的加載器加載了。排查的第一個(gè)動(dòng)作是確認(rèn) jar 的位置。項(xiàng)目依賴必須是WEB-INF/lib下的 jar或者WEB-INF/classes下的 class 文件放在 Tomcat 的lib目錄里雖然也能用但那是容器級(jí)別的類加載器多個(gè)應(yīng)用會(huì)互相干擾強(qiáng)烈不建議。第二個(gè)動(dòng)作是看有沒(méi)有版本沖突。兩個(gè)不同版本的同一個(gè)包同時(shí)出現(xiàn)在WEB-INF/lib里Tomcat 按文件名排序加載先加載的生效行為就變得不可預(yù)期。我整理過(guò)一個(gè)快速判斷表現(xiàn)象大概率原因處理方式啟動(dòng)時(shí)立刻報(bào) CNFEjar 缺失或路徑不對(duì)檢查WEB-INF/lib運(yùn)行到某個(gè)功能才報(bào)反射加載的類名拼寫(xiě)錯(cuò)誤核對(duì)全限定類名報(bào) NoClassDefFoundError 且?guī)?Cause靜態(tài)初始化失敗看異常鏈最底層類型轉(zhuǎn)換失敗 ClassCastException同類被雙加載器加載統(tǒng)一依賴來(lái)源5.4 資源與連接類報(bào)錯(cuò)連接池拿不到連接熱詞里那條could not obtain connection to query metadata : cannot create我特別想展開(kāi)講因?yàn)樗湫土?。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在應(yīng)用啟動(dòng)階段連接池Druid、HikariCP、DBCP 都可能嘗試建立第一條物理連接時(shí)失敗了。報(bào)錯(cuò)信息本身只說(shuō)了拿不到連接真正的原因藏在異常鏈里往往是下面幾種之一。其一是 JDBC 驅(qū)動(dòng)和數(shù)據(jù)庫(kù)版本不匹配。比如數(shù)據(jù)庫(kù)是較新的版本驅(qū)動(dòng)還是老版本握手階段就會(huì)失敗現(xiàn)象是cannot create后面跟著一個(gè)具體的握手異常。解決方式很直接換成匹配版本的驅(qū)動(dòng)并且確認(rèn)驅(qū)動(dòng) jar 在WEB-INF/lib下而不是只在你本地 IDEA 的庫(kù)路徑里。其二是應(yīng)用啟動(dòng)時(shí)數(shù)據(jù)庫(kù)還沒(méi)準(zhǔn)備好。容器編排場(chǎng)景下這很常見(jiàn)數(shù)據(jù)庫(kù)容器起來(lái)比應(yīng)用慢幾秒。連接池初始化就失敗整個(gè)應(yīng)用啟動(dòng)中斷。我的做法是把initialSize設(shè)成 0 或者很小的值讓它懶加載同時(shí)配好connectionTimeout和失敗重試別讓啟動(dòng)階段的一次失敗把應(yīng)用整個(gè)拖死。其三是賬號(hào)權(quán)限或者網(wǎng)絡(luò)不通這類用telnet或者數(shù)據(jù)庫(kù)客戶端從 Tomcat 所在機(jī)器上連一次就能確認(rèn)。配好之后建議加一條validationQuery讓連接池在借出連接前做一次探活。這一步帶來(lái)的開(kāi)銷很小但能擋住大量連接已被服務(wù)端關(guān)閉的詭異報(bào)錯(cuò)。# Druid 參考配置 initialSize0 minIdle1 maxActive20 validationQuerySELECT 1 testWhileIdletrue connectionTimeout3000提示maxActive不要拍腦袋設(shè)大。數(shù)據(jù)庫(kù)端有最大連接數(shù)限制應(yīng)用側(cè)配得再大超過(guò)數(shù)據(jù)庫(kù)限制照樣連不上而且會(huì)掩蓋真正的慢 SQL 問(wèn)題。5.5 編碼、SSL 與安全加固相關(guān)報(bào)錯(cuò)中文亂碼分三種位置處理方式完全不同。請(qǐng)求參數(shù)亂碼看Connector上的URIEncodingTomcat 8 以后默認(rèn)就是 UTF-8如果被顯式改成了ISO-8859-1中文參數(shù)就會(huì)亂同時(shí)確認(rèn)conf/server.xml里 Connector 的useBodyEncodingForURI設(shè)置它決定 POST body 的編碼是否也應(yīng)用到 URI 上。響應(yīng)亂碼看Content-Type里的charset或者response.setCharacterEncoding?？刂婆_(tái)和日志亂碼看 JVM 啟動(dòng)參數(shù)里的-Dfile.encodingUTF-8以及conf/logging.properties的編碼設(shè)置。三處都對(duì)上中文才不會(huì)到處出問(wèn)題。SSL 相關(guān)的報(bào)錯(cuò)集中在握手階段。java.io.IOException: keystore password was incorrect是最直白的——密碼錯(cuò)了。更隱蔽的是unable to find valid certification path to requested target這出現(xiàn)在雙向認(rèn)證場(chǎng)景服務(wù)端要求客戶端提供證書(shū)而客戶端沒(méi)有或者證書(shū)鏈不完整。雙向認(rèn)證需要服務(wù)端配keystoreFile和keystorePass同時(shí)配truststoreFile和truststorePass來(lái)校驗(yàn)客戶端證書(shū)還要把clientAuth設(shè)成true。少配任何一個(gè)握手都會(huì)失敗而且不同配置錯(cuò)誤對(duì)應(yīng)的報(bào)錯(cuò)信息差別很大建議一項(xiàng)一項(xiàng)對(duì)照著配。如果項(xiàng)目對(duì)加密算法有特定合規(guī)要求通常需要引入對(duì)應(yīng)的加密套件實(shí)現(xiàn)并調(diào)整 Connector 的協(xié)議配置這部分建議照著中間件廠商的官方文檔逐項(xiàng)核對(duì)不要憑經(jīng)驗(yàn)猜。關(guān)于安全加固有三件事值得每年做一次把 Tomcat 升到當(dāng)前維護(hù)的最新穩(wěn)定版刪掉webapps下所有用不到的默認(rèn)應(yīng)用尤其是管理端把管理端口的訪問(wèn)來(lái)源限制在可信網(wǎng)段。這些動(dòng)作成本極低但能擋掉絕大多數(shù)自動(dòng)化掃描。6. 調(diào)優(yōu)要點(diǎn)與容器替換的取舍6.1 Connector 與 JVM 的關(guān)鍵參數(shù)Connector上真正需要關(guān)注的參數(shù)不多我列幾個(gè)最常動(dòng)的參數(shù)作用參考值maxThreads處理請(qǐng)求的最大線程數(shù)200 起步按壓測(cè)調(diào)acceptCount隊(duì)列滿后的等待隊(duì)列長(zhǎng)度100maxConnections允許的最大連接數(shù)10000connectionTimeout連接超時(shí)毫秒20000compression是否壓縮響應(yīng)on僅對(duì)小文本有效調(diào)maxThreads的正確方式是壓測(cè)不是抄別人的數(shù)字。線程數(shù)加大的收益是有上限的因?yàn)橄掠蔚臄?shù)據(jù)庫(kù)連接池、外部接口都有承載極限。我見(jiàn)過(guò)把maxThreads調(diào)到 2000 結(jié)果數(shù)據(jù)庫(kù)連接池只有 50最后瓶口全卡在數(shù)據(jù)庫(kù)上線程全在等連接內(nèi)存反而被線程棧撐爆。JVM 層面堆大小建議-Xms和-Xmx設(shè)成一樣避免運(yùn)行期擴(kuò)容帶來(lái)的停頓。元空間設(shè)個(gè)上限-XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m防止動(dòng)態(tài)生成類太多把內(nèi)存吃光。垃圾回收器在 JDK 8 上可以用 G1JDK 17 上直接用默認(rèn)的就行沒(méi)必要折騰。部署時(shí)在setenv.shLinux或者setenv.batWindows里配置這些參數(shù)這樣升級(jí) Tomcat 的時(shí)候參數(shù)不會(huì)丟。6.2 內(nèi)嵌容器的替換思路現(xiàn)在越來(lái)越多項(xiàng)目用 Spring Boot 內(nèi)嵌容器不再單獨(dú)部署 war。內(nèi)嵌場(chǎng)景下?lián)Q容器比傳統(tǒng)部署簡(jiǎn)單得多本質(zhì)上就是換一個(gè) starter 依賴。比如要換成 Undertow先在 web starter 里排掉 Tomcat再引 Undertowdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId /exclusion /exclusions /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-undertow/artifactId /dependency換 Jetty 也是同樣的套路把 artifactId 換成spring-boot-starter-jetty即可。需要注意的坑有兩個(gè)一是有些代碼直接依賴了 Tomcat 特有的類比如org.apache.catalina.*下的工具類換容器后編譯不過(guò)得先清理掉二是配置屬性的前綴會(huì)變從server.tomcat.*變成server.undertow.*參數(shù)名也不一樣遷移時(shí)要逐項(xiàng)對(duì)應(yīng)。如果項(xiàng)目有使用其他中間件產(chǎn)品的需求替換思路類似——多數(shù)商業(yè)中間件都會(huì)提供適配 Spring Boot 的 starter 或者遷移文檔關(guān)鍵是先確認(rèn)它對(duì) Servlet 規(guī)范的兼容程度以及是否有用到的 Tomcat 私有 API。這類替換我建議先在測(cè)試環(huán)境完整跑一遍回歸不要上來(lái)就改生產(chǎn)因?yàn)槿萜鞑町愅w現(xiàn)在一些邊緣行為上比如 Cookie 的默認(rèn)屬性、URL 編碼的處理細(xì)節(jié)、靜態(tài)資源的緩存頭這些平時(shí)不顯眼的地方最容易出事。6.3 我踩過(guò)的幾個(gè)坑第一個(gè)是 IDEA 里配置 Tomcat 運(yùn)行配置。不同版本的菜單路徑會(huì)變但核心永遠(yuǎn)是三件事指定 JDK、指定服務(wù)器安裝目錄、在 Deployment 里添加 Artifact。如果啟動(dòng)后報(bào) 404八成是 Artifact 的上下文路徑配的是/還是/項(xiàng)目名沒(méi)對(duì)上去看運(yùn)行配置里的 Application context 那一欄。另外新版 IDEA 里有些配置項(xiàng)挪到了Settings的Build Tools下找不到的時(shí)候直接在設(shè)置里搜 Tomcat 比翻菜單快。第二個(gè)是熱部署的錯(cuò)覺(jué)。改了 Java 代碼點(diǎn)重新部署有時(shí)候改動(dòng)沒(méi)生效原因是 classes 沒(méi)有重新編譯或者輸出目錄指向了舊的路徑。最穩(wěn)的做法是 Build 之后再 Run不要依賴 IDE 的自動(dòng)編譯。第三個(gè)是日志級(jí)別。排查問(wèn)題時(shí)把conf/logging.properties里的級(jí)別從INFO調(diào)到FINE能看到大量?jī)?nèi)部狀態(tài)信息比如類加載過(guò)程、URL 匹配過(guò)程。問(wèn)題解決后記得調(diào)回來(lái)否則日志文件會(huì)迅速膨脹磁盤被寫(xiě)滿又是另一個(gè)故障。我個(gè)人在實(shí)際操作中的體會(huì)是Tomcat 的問(wèn)題十有八九不是 Tomcat 本身的問(wèn)題而是環(huán)境、依賴、配置這三者之間的錯(cuò)位。所以排查時(shí)別急著改配置先把報(bào)錯(cuò)鏈條完整讀一遍找到它落在哪一層再動(dòng)手。手寫(xiě)一遍迷你容器之后我對(duì)這條鏈路的感知明顯變強(qiáng)了——現(xiàn)在看到報(bào)錯(cuò)第一反應(yīng)不再是搜關(guān)鍵詞而是先問(wèn)自己這是網(wǎng)絡(luò)層、協(xié)議層還是容器層的事