Java EE 6 數據源定義新範式：註解與部署描述符雙軌制

前言：從「容器專有配置」到「標準化可移植定義」

Java EE 6 (JSR 316) 前，數據源定義深度綁定應用服務器：WebLogic 用 `config.xml`、JBoss 用 `-ds.xml`、GlassFish 用 `sun-resources.xml`、Tomcat 用 `context.xml` — **遷移即重寫配置**。Java EE 6 引入標準化註解 `@DataSourceDefinition` / `@DataSourceDefinitions` 並擴展 `web.xml`/`ejb-jar.xml`/`application.xml` `` 元素，實現**「寫一次，部署到任何 Java EE 6+ 兼容容器」**。本文系統講解註解屬性、命名空間作用域、部署描述符語法、優先級規則、以及遷移實戰建議。

1. 註解式定義：@DataSourceDefinition / @DataSourceDefinitions

1.1 單個數據源 @DataSourceDefinition

可標註於：**Servlet、EJB、ServletContextListener、WebService Endpoint、Application-scoped CDI Bean** 等組件類上。

@DataSourceDefinition(
    name = "java:app/env/MyAppDataSource",      // JNDI 名稱 (必須)
    className = "org.postgresql.ds.PGSimpleDataSource", // 驅動 DataSource 實現類
    user = "app_user",
    password = "s3cr3t",
    databaseName = "myapp",
    serverName = "db.internal",
    portNumber = 5432,
    minPoolSize = 5,
    maxPoolSize = 20,
    properties = { "ssl=true", "connectTimeout=5000" }, // 驅動特定屬性
    description = "核心業務數據源",
    isolationLevel = Connection.TRANSACTION_READ_COMMITTED,
    transactional = true
)
@Stateless
public class OrderService { ... }

1.2 多個數據源 @DataSourceDefinitions

@DataSourceDefinitions({
    @DataSourceDefinition(name = "java:app/env/PrimaryDS", ...),
    @DataSourceDefinition(name = "java:comp/env/LocalDS", ...)
})
@Singleton
@Startup
public class AppInitializer { ... }

1.3 核心屬性速查表

2. JNDI 命名空間作用域與可見性

Java EE 6 引入**應用組件命名空間**，決定數據源可被哪些組件查找：

最佳實踐：內部數據源用 `java:app/env/`；需跨 WAR/EJB 模塊共享時用 `java:app/env/`；極少數跨應用共享才用 `java:global/`。

3. 部署描述符定義： 元素

適用於 `web.xml`、`ejb-jar.xml`、`application.xml`、`application-client.xml`。語法統一：

<data-source>
    <name>java:app/env/ApplicationLevelDS</name>
    <class-name>org.apache.derby.jdbc.ClientXADataSource</class-name>
    <server-name>localhost</server-name>
    <port-number>1527</port-number>
    <database-name>testdb</database-name>
    <user>APP</user>
    <password>APP</password>
    <property>
        <name>connectionAttributes</name>
        <value>;create=true</value>
    </property>
    <!-- 可選屬性 -->
    <min-pool-size>5</min-pool-size>
    <max-pool-size>20</max-pool-size>
    <transactional>true</transactional>
    <isolation-level>TRANSACTION_READ_COMMITTED</isolation-level>
</data-source>

4. 優先級規則：部署描述符 > 註解

若同一應用中，**同名 JNDI** 同時由註解和部署描述符定義 → **部署描述符生效**，註解被忽略。

這符合 Java EE 「部署時覆蓋開發時」的約定，允許運維在不修改代碼的情況下調整數據源參數 (密碼、URL、池大小)。

5. 實戰遷移指南：從容器專有配置到標準化

1. 盤點現狀：列出所有環境 (Dev/Test/Staging/Prod) 的容器專有配置文件、JNDI 名稱、池參數、驅動版本。
2. 統一 JNDI 命名：採用 `java:app/env/` 規範，邏輯名與業務域對齊 (如 `OrderDS`、`ReportingDS`)。
3. 選擇定義方式：
   • **註解優先** (開發期)：EJB/Servlet 類上加 `@DataSourceDefinition`，版本控制、代碼評審友好。
   • **部署描述符覆蓋** (運維期) ：`web.xml`/`ejb-jar.xml` 覆蓋密碼、URL、池大小，敏感信息不入代碼庫。
4. 驗證矩陣：在目標容器 (GlassFish/Payara、WildFly/JBoss、WebLogic、WebSphere、Liberty) 部署測試，確認 JNDI 綁定、連接池參數、事務加入行為一致。
5. CI/CD 集成：Maven Profile / Kubernetes ConfigMap / Helm Values 注入環境差異參數，構建產出無環境綁定的 WAR/EAR。

6. 進階：動態數據源與多租戶

• 標準註解/描述符定義的是**靜態**數據源。運行時動態創建/切換數據源 (如 SaaS 多租戶按租戶路由) 需：
• 實現 `javax.sql.DataSource` 包裝器，委托給 `AbstractRoutingDataSource` (Spring) 或自定義路由邏輯。
• 或使用容器專有 API (如 WildFly `ManagementClient`、WebLogic `JDBCSystemResourceMBean`) 動態創建數據源並綁定 JNDI。
• Java EE 8 / Jakarta EE 9 尚未標準化動態數據源 API，關注 JSR 372 / Jakarta EE 10 進展。

結語

Java EE 6 的標準化數據源定義 (`@DataSourceDefinition` + ``) 是**可移植雲原生 Java 應用**的基石之一。它消除了「容器鎖定」的配置層面，讓開發者專注於業務邏輯，運維專注於環境參數注入。採用「註解開發期默認 + 描述符運維期覆蓋」的雙軌制，配合 CI/CD 環境參數化注入，可構建真正**「構建一次，部署任意 Java EE 兼容平台」**的企業級應用。