511-frameworks-micronaut-jdbc

Micronaut JDBC — 编程式 SQL

在 Micronaut 中采用编程式 JDBC 模式，使用安全的 SQL 并明确事务边界。

此 Skill 涵盖哪些内容？

• 注入 javax.sql.DataSource（由 micronaut-jdbc-hikari 提供 Hikari 支持），并对 Connection / PreparedStatement 使用 try-with-resources
• 使用 PreparedStatement 和绑定参数——绝不进行字符串拼接
• 将 ResultSet 行映射为 Java record（使用专用的 mapRow 方法）
• 使用 Optional 安全地查询单行；绝不假设 rs.next() 一定成功
• 将 SQLException 转换为领域异常（捕获、转换并重新抛出）
• 使用 setFetchSize 流式读取大型结果集，以避免 OOM
• 使用 addBatch / executeBatch 批量更新，以批量插入数据
• 使用 @Transactional 划分服务边界，并使用 TransactionDefinition.Propagation（例如，使用 REQUIRES_NEW 独立提交）
• 自调用陷阱：通过注入的 Bean 调用事务协作者，而不是使用 this.method()
• 使用 SQL 文本块编写多行 SQL（upsert、特定方言的子句）
• 何时优先选择 Micronaut Data（@512），而不是原始 JDBC

范围： 根据参考规则以及优劣代码示例应用建议。

约束

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

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

何时使用此 skill

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

工作流

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

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

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

明确预期结果、约束，以及要应用的最小安全更改集。

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

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

4. 运行验证并报告结果

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

参考资料

详细指导、示例和约束请参阅 references/511-frameworks-micronaut-jdbc.md。