quarkus.datasource.db-kind 必须严格设为小写 oracle，否则将导致启动失败或静默降级为 other；必须添加 quarkus-jdbc-oracle 依赖，使用 service-name 格式 JDBC URL，并通过凭据供应商管理用户名密码。
quarkus.datasource.db-kind 必须设为 oracle
Quarkus 对 Oracle 的支持依赖内置驱动扩展，db-kind 值写错会导致启动失败或静默降级为 other——后者在原生镜像中几乎必然报 ClassNotFoundException 或连接超时。必须严格使用 oracle（小写，不可写成 Oracle、ORACLE 或 ojdbc）。
常见错误现象：Unable to determine the correct JDBC URL for database 'other'；或日志中出现 Using fallback driver: org.h2.Driver（说明配置未被识别）。
-
quarkus.datasource.db-kind=oracle是唯一受支持的标识符 - 若用多数据源，命名前缀需一致，例如
quarkus.datasource.primary.db-kind=oracle - 不支持通过
quarkus.datasource.jdbc.driver手动指定oracle.jdbc.driver.OracleDriver——这会绕过 Quarkus 的 JDBC 扩展初始化逻辑，导致事务、健康检查、指标等功能失效
必须添加 quarkus-jdbc-oracle 依赖
仅靠 ojdbc8.jar 或 ojdbc11.jar 自行引入，无法启用 Quarkus 的编译时优化和原生支持。JVM 模式下可能“看似能连”，但缺失连接池管理、自动健康探针、Hibernate ORM 集成等关键能力。
正确做法是在 pom.xml 中声明：
<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-jdbc-oracle</artifactId> </dependency>
- 该扩展已适配 Oracle 12c–23c，兼容 JDK 11–21
- 原生构建（
mvn package -Pnative）时，此依赖会触发 GraalVM 的反射与资源注册，否则运行时报java.sql.SQLException: No suitable driver found - 不要同时引入
com.oracle.database.jdbc:ojdbc8——quarkus-jdbc-oracle已内嵌适配版本，重复引入易引发类加载冲突
JDBC URL 格式必须带 service-name，不能只用 SID
Oracle 连接字符串对格式极其敏感。Quarkus 的 JDBC 扩展要求使用服务名（service name），而非传统 SID。写成 jdbc:oracle:thin:@host:port:SID 会导致连接成功但后续查询失败（如 ORA-12505）或 Hibernate 初始化报 Could not obtain connection metadata。
正确格式为：
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@//host:port/service_name
- 注意双斜杠
//和末尾的/service_name，这是 Oracle 12c+ 推荐的 URL 语法 - 若数据库使用默认服务名（如
ORCLPDB1），务必确认它在监听器中真实注册（可通过lsnrctl status验证） - 开发时可用 Oracle XE 的默认服务名
XEPDB1，但生产环境请以 DBA 提供的服务名为准
用户名密码不能硬编码，优先用凭据供应商
Oracle 生产库通常启用 TDE（透明数据加密）或细粒度审计，直接在 application.properties 写明文密码不仅违反安全规范，还可能触发 Oracle 审计日志告警。
推荐路径是使用凭据供应商（Credential Provider），例如 Vault：
quarkus.datasource.username=${vault-username}
quarkus.datasource.password=${vault-password}
quarkus.vault.server-url=https://vault.example.com
quarkus.vault.authentication.app-role.role-id=xxx
quarkus.vault.authentication.app-role.secret-id=yyy
- 即使不用 Vault，也应通过环境变量注入：
QUARKUS_DATASOURCE_USERNAME+QUARKUS_DATASOURCE_PASSWORD - 避免在 Git 中提交含密码的配置文件；
application.properties应只保留占位符或开发用的 H2/Flyway 测试配置 - Oracle 密码区分大小写，且某些版本对特殊字符（如
@、/）敏感——若必须明文调试，请 URL 编码处理
最容易被忽略的是 Oracle 服务名与监听器注册状态的匹配问题：很多连接失败不是代码或配置错，而是 DBA 创建了 PDB 却忘了在 listener.ora 中显式注册服务名。上线前务必用 sqlplus user/pass@//host:port/service_name 手动验证连通性，而不是只信应用日志里的 “Connected to: Oracle Database”。
