411-frameworks-quarkus-jdbc

Quarkus JDBC — 程序化 SQL

在 Quarkus 中应用程序化 JDBC 模式，确保 SQL 安全、事务清晰。

本技能涵盖哪些内容？

• 注入 javax.sql.DataSource（由 Agroal 提供支持），并对 Connection / PreparedStatement 使用 try-with-resources
• 使用带绑定参数的 PreparedStatement — 绝不拼接字符串
• 将 ResultSet 行映射为 Java 记录（使用专门的 mapRow 方法）
• 使用 Optional 安全查询单行；绝不假设 rs.next() 会成功
• 将 SQLException 转换为领域异常（捕获、转换、重新抛出）
• 使用 setFetchSize 流式处理大型结果集，以避免 OOM
• 使用 addBatch / executeBatch 批量更新，以便批量插入
• 使用 @Transactional 划分服务边界并设置传播类型（使用 TxType.REQUIRES_NEW 独立提交）
• CDI 自调用陷阱：始终通过注入的代理调用事务方法
• 在开发/测试环境中使用数据库 Dev Services
• 何时优先使用 Panache（@412）而非原始 JDBC

范围： 根据参考规则和正反代码示例应用建议。

约束

进行 JDBC 重构前先编译；更改后进行验证。

• 强制要求：应用任何更改前运行 ./mvnw compile 或 mvn compile
• 前置条件：应用 JDBC 改进前，项目必须能够编译
• 安全要求：如果编译失败，立即停止
• 阻止条件：必须由用户解决编译错误后才能继续
• 验证：应用改进后运行 ./mvnw clean verify 或 mvn clean verify
• 应用前：阅读参考资料，了解详细规则和示例

何时使用此技能

• 检查 Quarkus 项目中的 JDBC 或 SQL 数据访问
• 改进 Quarkus JDBC 的事务处理和参数绑定
• 将 SQLException 转换为领域异常，或流式处理大型结果集
• 修复 Quarkus 中绕过 @Transactional 的 CDI 自调用问题
• 检查 Quarkus JDBC 中 Agroal DataSource 的用法

工作流

1. 阅读参考资料并评估项目上下文

阅读 references/411-frameworks-quarkus-jdbc.md，并检查当前项目设置，然后再提出更改建议。

2. 明确范围并确定目标改进

确定所需结果、约束条件，以及要应用的最小安全更改集。

3. 应用符合框架规范的更改

遵循参考模式和项目惯例，实现或重构配置/代码。

4. 运行验证并报告结果

执行适当的构建/测试，并总结更改内容、验证结果及后续操作。

参考资料

详细指南、示例和约束请参阅 references/411-frameworks-quarkus-jdbc.md。