Tomcat DataSource (JNDI) 配置完整指南：從原理到實戰

Tomcat DataSource (JNDI) 配置完整指南：從原理到實戰

Tomcat 內建的資料源（DataSource）透過 JNDI 註冊，實現資料庫連接池的容器化管理。本文系統講解 JDBC 2.0 DataSource 規範、連接池原理、JNDI 綁定機制、server.xml/web.xml 雙重配置與程式碼獲取全流程。

核心概念：為什麼需要 DataSource？

JNDI 與 Tomcat 資源工廠

• JNDI：命名與目錄介面，將物件（DataSource）綁定到名稱（jdbc/BookDB）
• Context 介面：bind(name, obj) 綁定、lookup(name) 查找
• Tomcat 工廠類：org.apache.commons.dbcp.BasicDataSourceFactory（DBCP 1.x）或 org.apache.tomcat.dbcp.dbcp2.BasicDataSourceFactory（DBCP 2.x / Tomcat 8+）

配置全流程

1. server.xml 定義全域/應用級資源

<Context path="/bookstore" docBase="bookstore" reloadable="true">
  <Resource name="jdbc/BookDB" 
            auth="Container" 
            type="javax.sql.DataSource" 
            maxActive="100" maxIdle="30" maxWait="10000"
            username="dbuser" password="123456"
            driverClassName="com.mysql.jdbc.Driver"
            url="jdbc:mysql://localhost:3306/BookDB?autoReconnect=true"
            factory="org.apache.commons.dbcp.BasicDataSourceFactory" />
</Context>

關鍵屬性：

• auth="Container"：容器管理生命週期（推薦）
• maxActive：最大活躍連接數（0=無限制）
• maxIdle：最大空閒連接數
• maxWait：獲取連接最長等待毫秒數（-1=無限等待）
• validationQuery：連接有效性檢測 SQL（如 SELECT 1）
• testOnBorrow：借用時檢測（效能與安全的權衡）

2. web.xml 宣告資源引用

<resource-ref>
  <description>DB Connection</description>
  <res-ref-name>jdbc/BookDB</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
</resource-ref>

作用：宣告 Web 應用依賴此 JNDI 資源，res-ref-name 需與 server.xml 中 name 一致（不含 jdbc/ 前綴時自動補全）。

程式碼獲取與使用

// 標準 JNDI 查找
Context ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("java:comp/env/jdbc/BookDB");

// 獲取連接（從池借用）
Connection conn = ds.getConnection();
try {
    // 業務操作
} finally {
    // 關鍵：歸還連接池，而非真正關閉物理連接
    conn.close();  
}

進階配置與最佳實務

常見問題排查

• NameNotFoundException：檢查 java:comp/env/ 前綴、res-ref-name 拼寫、Context 路徑
• 連接獲取超時：調大 maxWait、檢查連接洩漏、擴大池大小
• 「Connection closed」異常：驗證 validationQuery、檢查防火牆/資料庫 wait_timeout
• 類載入衝突：Tomcat 內建 DBCP 與應用引入 DBCP 版本不一致 → 使用 Tomcat 8+ 內建 tomcat-dbcp 或排除應用依賴

現代替代方案

Spring Boot 等框架透過 @ConfigurationProperties 直接配置 DataSource Bean，無需 JNDI 配置，更適合微服務/容器化部署。但理解 Tomcat JNDI DataSource 機制，對排查遷移老專案、理解容器管理資源本質仍有重要價值。