Testcontainers Java 集成 Oracle Database Free使用 gvenzl/oracle-free 镜像搭建可丢弃的 Oracle 测试数据库【免费下载链接】testcontainers-javaTestcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.项目地址: https://gitcode.com/GitHub_Trending/te/testcontainers-javaTestcontainers 为 Java 生态提供了 Oracle Database Free 模块testcontainers-oracle-free它基于 Docker Hub 上的gvenzl/oracle-free镜像可在测试中启动轻量、一次性、可自动销毁的 Oracle 数据库容器。本文围绕 docs/modules/databases/oraclefree.md 展开结合仓库源码与测试用例完整讲解依赖引入、容器启动、连接参数、JDBC/R2DBC URL 快速接入以及底层实现细节帮助你在 JUnit 测试中真正跑通 Oracle 数据库集成测试。模块概览为什么选择 Oracle Database FreeOracle Database Free 是 Oracle 官方提供的免费开发版数据库镜像仓库中通过gvenzl/oracle-free引用。Testcontainers 的该模块在JdbcDatabaseContainer之上实现了针对该镜像的容器封装核心实现位于 OracleContainer.java。从源码OracleContainer.java可以看到模块的默认事实项默认值默认镜像gvenzl/oracle-free默认标签tagslim暴露端口1521Oracle 监听端口默认数据库名PDBfreepdb1默认 SIDfree系统用户system另有sys测试应用用户test/ 密码test启动超时60 秒连接超时60 秒该模块的 Gradle 描述为Testcontainers :: JDBC :: Oracle Database Free见 modules/oracle-free/build.gradle并同时提供 R2DBC 支持属于 Testcontainers 数据库容器家族的一员。关于所有关系型数据库容器共通的用法可参阅 Database containers。添加模块依赖按照原文档需要把testcontainers-oracle-free加入测试依赖 Gradlegroovy testImplementation org.testcontainers:testcontainers-oracle-free:{{latest_version}} Mavenxml dependency groupIdorg.testcontainers/groupId artifactIdtestcontainers-oracle-free/artifactId version{{latest_version}}/version scopetest/scope /dependency!!! hint 引入该 Testcontainers 库 JAR 并不会自动引入数据库驱动 JAR。你还需要在项目中显式添加合适的 Oracle JDBC 驱动。从 modules/oracle-free/build.gradle 可以看出模块自身依赖关系testcontainers-jdbc是 API 依赖因此 JDBC 支持开箱即用testcontainers-r2dbc与com.oracle.database.r2dbc:oracle-r2dbc为compileOnly需要时才引入测试则使用com.oracle.database.jdbc:ojdbc11驱动验证真实连接。实践中你需要在测试类路径中准备 Oracle JDBC 驱动例如 Gradlegroovy testImplementation com.oracle.database.jdbc:ojdbc11:23.26.2.0.0 Mavenxml dependency groupIdcom.oracle.database.jdbc/groupId artifactIdojdbc11/artifactId version23.26.2.0.0/version scopetest/scope /dependency若使用 R2DBC 方式则还需要额外引入testcontainers-r2dbc与com.oracle.database.r2dbc:oracle-r2dbc见下文 R2DBC 章节。快速上手从任何 Java 应用启动 Oracle-Free 容器原文档给出的核心用法是直接实例化容器。仓库测试 SimpleOracleTest.java 展示了最小可运行示例try ( // container { OracleContainer oracle new OracleContainer(gvenzl/oracle-free:slim-faststart) // } ) { // 容器启动后即可获取连接信息 String jdbcUrl oracle.getJdbcUrl(); String username oracle.getUsername(); String password oracle.getPassword(); // 执行一条基础查询验证连通性 ResultSet resultSet performQuery(oracle, SELECT 1 FROM dual); assertThat(resultSet.getInt(1)).isEqualTo(1); }要点说明OracleContainer有两个构造重载接收字符串镜像名内部调用DockerImageName.parse或直接接收DockerImageName对象见 OracleContainer.java。构造时会调用dockerImageName.assertCompatibleWith(DEFAULT_IMAGE_NAME)因此传入的镜像必须是gvenzl/oracle-free系列否则直接抛出异常避免误用其他镜像。镜像名中建议带slim-faststart标签faststart是gvenzl/oracle-free提供的加速启动变体可显著缩短首次启动耗时测试与示例均使用该标签。使用 try-with-resources 可在测试结束时自动关闭容器实现用完即焚。默认账号与连接信息不进行任何额外配置时容器提供如下默认连接参数见 OracleContainer.java数据库名freepdb1一个可插拔数据库 PDB用户名test密码test生成的 JDBC URL 形如jdbc:oracle:thin:localhost:PORT/freepdb1常用配置项数据库名、用户与密码原文档直接引用了容器创建代码而仓库测试 SimpleOracleTest.java 进一步展示了各类定制场景指定可插拔数据库名OracleContainer oracle new OracleContainer(gvenzl/oracle-free:slim-faststart) .withDatabaseName(testDB);同时指定自定义用户与密码OracleContainer oracle new OracleContainer(gvenzl/oracle-free:slim-faststart) .withDatabaseName(testDB) .withUsername(testUser) .withPassword(testPassword);上述场景下测试断言getDatabaseName()返回testDB、getUsername()返回testUser、getPassword()返回testPassword且能成功执行SELECT 1 FROM dual。校验规则源码级约束从 OracleContainer.java 的实现看withUsername、withPassword、withDatabaseName均有严格校验用户名不能为空且不能是system或sys不区分大小写。因为应用用户被绑定在具体数据库上无法用 SID 方式认证源码注释An application user is tied to the database, and therefore not authenticated to connect to SID。密码不能为空。数据库名不能为空且不能设置为默认值freepdb1不区分大小写。这些错误路径在 SimpleOracleTest.java 的testErrorPaths中有完整验证。容器环境变量configure 阶段容器启动前configure()方法OracleContainer.java会设置以下环境变量与gvenzl/oracle-free镜像约定保持一致环境变量值说明ORACLE_PASSWORD设置的密码系统用户密码ORACLE_DATABASE自定义数据库名仅当数据库名不同于默认freepdb1时才设置APP_USER应用用户名默认testAPP_USER_PASSWORD应用用户密码默认test连接模式PDBService Name与 SIDOracle 的连接方式分为两种通过服务名PDB或通过 SID。模块默认使用 PDB 方式也可通过usingSid()切换到 SID 方式OracleContainer.java// PDB 方式默认jdbc:oracle:thin:host:port/databasename jdbc:oracle:thin:localhost:32768/freepdb1 // SID 方式jdbc:oracle:thin:host:port:sid OracleContainer oracle new OracleContainer(gvenzl/oracle-free:slim-faststart).usingSid(); // 此时 JDBC URL 形如jdbc:oracle:thin:localhost:32768:free两种模式的关键差异PDB 模式getJdbcUrl()使用/数据库名结尾getUsername()返回应用用户名如test数据库名可通过withDatabaseName定制。SID 模式getJdbcUrl()使用:SID结尾SID 固定为freegetSid()返回DEFAULT_SID free由于应用用户无法连接 SIDgetUsername()强制返回系统用户system。对应测试见 SimpleOracleTest.java其中断言 PDB 模式 URL 以freepdb1结尾、SID 模式 URL 以free结尾。其他与连接相关的实现细节驱动类名getDriverClassName()优先返回oracle.jdbc.OracleDriver若类路径上不存在则回退到旧驱动名oracle.jdbc.driver.OracleDriverOracleContainer.java。连通性探针getTestQueryString()返回 Oracle 经典探针语句SELECT 1 FROM DUAL。URL 参数Oracle 驱动不支持 JDBC URL 拼接额外参数withUrlParam()会直接抛出UnsupportedOperationException。端口可通过getOraclePort()获取容器映射到宿主机的 1521 端口。Testcontainers JDBC URL零代码改造接入原文档给出 Oracle 的 Testcontainers JDBC URL 形式jdbc:tc:oracle:21-slim-faststart:///databasename这是 Testcontainers JDBC URL 方案详见 JDBC support只要类路径上有 Testcontainers 和对应的 JDBC 驱动把普通 JDBC URL 中jdbc:之后插入tc:即可Testcontainers 会自动启动容器并在应用连接时提供数据库无需实例化任何容器对象。注意其中host:port与数据库名会被忽略可用///无主机 URI强调这一点。其底层由OracleContainerProviderOracleContainerProvider.java支撑它注册了数据库类型oracle未指定 tag 时使用默认标签slim从而把jdbc:tc:oracle:...解析为对应的OracleContainer。仓库测试 OracleJDBCDriverTest.java 验证了无版本号写法同样可用performSimpleTest(jdbc:tc:oracle://hostname/databasename);测试内部通过 HikariCP 连接池拿到数据源后执行SELECT 1 FROM dual并断言结果等于 1OracleJDBCDriverTest.java。JDBC URL 还支持TC_INITSCRIPT类路径脚本或file:前缀文件与TC_INITFUNCTION自定义 Java 初始化函数等参数用于在连接建立前完成建表、迁移等初始化具体参见 JDBC support。R2DBC 支持响应式接入 Oracle若使用响应式栈模块同样提供支持。R2DBC 的 URL 形式为见 R2DBC supportr2dbc:tc:oracle:///?TC_IMAGE_TAG21-slim-faststart与 JDBC URL 不同R2DBC 必须在查询参数TC_IMAGE_TAG中显式指定镜像标签无法在 scheme 中指定并且除了testcontainers-oracle-free类路径上还需要org.testcontainers:testcontainers-r2dbc和 Oracle 的 R2DBC 驱动。实现上OracleR2DBCDatabaseContainer.java 实现了R2DBCDatabaseContainer接口configure(options)会将HOST、PORT映射后的 1521 端口、DATABASE、USER、PASSWORD写入ConnectionFactoryOptions容器生命周期start/stop/close则委托给内部的OracleContainer。测试 OracleR2DBCDatabaseContainerTest.java 使用r2dbc:tc:oracle:///db?TC_IMAGE_TAGslim-faststart验证了SELECT ... from dual查询。启动等待策略与镜像兼容性Oracle 数据库冷启动较慢模块对此做了专门处理等待策略默认等待容器日志中出现DATABASE IS READY TO USE!出现 1 次即认为就绪启动超时 60 秒OracleContainer.java。连接超时withConnectTimeoutSeconds(60)设置 JDBC 连接建立超时上限。存活检查端口getLivenessCheckPortNumbers()返回映射后的 1521 端口作为容器健康探针。镜像兼容性assertCompatibleWith确保只能使用gvenzl/oracle-free镜像防止误用其他 Oracle 镜像导致行为异常。需要说明的是DEFAULT_TAG为slim见 OracleContainer.java但示例与测试普遍推荐slim-faststart标签以获得更快的启动体验faststart变体以首次启动时预创建 PDB 为代价换取更短的就绪时间适合测试场景。小结Testcontainers 的 Oracle Database Free 模块让你在测试中随时获得一个真实、干净、可丢弃的 Oracle 数据库通过OracleContainer类可直接编程式启动通过jdbc:tc:oracle:/r2dbc:tc:oracle:URL 可零代码接入现有应用配合freepdb1默认 PDB、test/test默认账号、SID 切换以及严格的参数校验能够在 DAO 单元测试与端到端集成测试中替代 H2 等模拟数据库获得 100% 的 Oracle 兼容性。数据库容器的通用特性如waitingFor自定义等待、withEnv环境变量注入、try-with-resources 生命周期管理等可继续查阅 Database containers 与 JDBC support、R2DBC support 获得系统化说明。【免费下载链接】testcontainers-javaTestcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.项目地址: https://gitcode.com/GitHub_Trending/te/testcontainers-java创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考