UCP连接池初始化必须显式设置setConnectionFactoryClassName，否则抛IllegalStateException；推荐设为"oracle.jdbc.pool.OracleDataSource"，URL需含service_name或SID，初始与最大连接数应协同配置，事务中必须用getConnection()而非getPhysicalConnection()。
UCP连接池初始化必须显式设置 setConnectionFactoryClassName
不设这个，ucp根本不知道该用哪个驱动创建物理连接，会直接抛 java.lang.illegalstateexception: connection factory class name is not set。oracle官方文档里把它藏在“required properties”里，但很多人只扫一眼 seturl 和 setuser 就以为齐了。
实操建议：
-
setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource")是最常用写法；如果用的是 Oracle 21c+ 的 JDBC 24.x，也可以用"oracle.ucp.jdbc.PoolDataSourceFactory"（但实际效果一致，没必要换） - 千万别写成
"oracle.jdbc.driver.OracleDriver"——那是 Driver 类，不是 DataSource 工厂，UCP 会报ClassNotFoundException或运行时类型转换失败 - URL 必须带 service_name 或 SID，例如
"jdbc:oracle:thin:@//host:1521/ORCLPDB1"；用 TNS 别名需提前配置tnsnames.ora并设setConnectionPoolName("my_pool")配合setURL("jdbc:oracle:thin:@MY_TNS")
Druid 的 maxActive 在 UCP 里对应 setInitialPoolSize 和 setMaxPoolSize
UCP 没有“最大活跃数”这个概念，它靠两个独立参数协同控制：初始连接数和硬上限。很多人照搬 Druid 配置，只设 setMaxPoolSize(20)，结果应用启动后连接数为 0，首请求卡顿明显——因为没预热。
实操建议：
- 生产环境建议
setInitialPoolSize(5)+setMaxPoolSize(20)，避免冷启动抖动 -
setMinPoolSize(5)不是必需项（UCP 默认等于initialPoolSize），但显式声明更可控；设为 0 表示连接可彻底归零，适合低峰期节电场景，但再起量时延迟上升 - Druid 的
minIdle在 UCP 中无直接等价项——UCP 只保证至少minPoolSize条空闲连接，不会主动驱逐低于该值的空闲连接；若要模拟，得配合setTimeToLiveConnectionInPoolSeconds+setInactiveConnectionTimeoutSeconds
事务中获取连接必须用 getConnection()，不能用 getPhysicalConnection()
这是最隐蔽的坑：后者返回的是底层 OracleConnection，绕过 UCP 的连接生命周期管理，导致连接无法归还、泄露、甚至事务上下文错乱。现象是连接数缓慢上涨，pool.getAvailableConnectionsCount() 持续下降，日志里反复出现 UCP-40000: Connection borrow timed out。
立即学习“Java免费学习笔记（深入）”；
实操建议：
- 所有业务代码统一走
pool.getConnection()，哪怕你只是想执行一条SELECT 1 FROM DUAL - Spring 项目中，别在
@Transactional方法里手动 newOracleConnection或调getPhysicalConnection()；UCP 与 Spring 的DataSourceTransactionManager兼容良好，只要注入的是UniversalConnectionPool包装的PoolDataSource实例即可 - 调试时可用
pool.getBorrowedConnectionsCount()和pool.getAvailableConnectionsCount()实时观察连接状态，比看日志更快定位泄漏点
关闭连接池要调 close()，且必须确保所有连接已释放
Druid 的 close() 是幂等的，UCP 不是。如果还有未关闭的 Connection 对象被持有（比如流没关、ResultSet 没 close、try-with-resources 漏写），调 pool.close() 会阻塞直到超时（默认 30 秒），然后强行中断并打印警告：UCP-40001: Forcefully closing connections in pool。
实操建议：
- 应用 shutdown hook 或 Spring
@PreDestroy中先遍历检查pool.getBorrowedConnectionsCount() == 0，不为 0 则记录堆栈（可用Thread.getAllStackTraces()找出谁持有着） - UCP 本身不提供“优雅等待”开关，只能靠外部控制：加个循环重试 + 短延时，最多等 5 秒，超时则强制
close()并告警 - 开发期建议开启 UCP 日志：
System.setProperty("oracle.ucp.level", "FINEST")，配合java.util.logging输出到文件，能清晰看到每条连接的 borrow/return/close 时间戳
UCP 替换 Druid 的核心差异不在 API 多复杂，而在于它把连接生命周期完全交由池自身管理——任何试图绕过 getConnection()/close() 的操作，都会让池失去控制权。这点在分布式事务或异步回调场景里尤其致命。
