BeetlSQL 从 2015 年一路迭代到现在，单表 CRUD、Markdown 式 SQL 模板、内置分页、多库切换——这些日常开发高频场景它都覆盖得不错。但有一个痛点一直没彻底解决：多表联合查询时的类型安全。写复杂 JOIN 的 SQL 模板，字段靠字符串拼，改一个列名编译器不会报错，跑到线上才炸。3.40 版本引入 JOOQ 集成，正是要堵这个窟洞——JOOQ 负责"类型安全地拼 SQL"，BeetlSQL 负责"高效地映射结果"，各干各擅长的事。
BeetlSQL 的舒适区与盲区
BeetlSQL 的核心优势集中在两块：
- 开发效率：Markdown 模板写 SQL，
@Table注解映射实体，内置query().selectAll()等链式 API，单表操作几乎不用手写 SQL。 - 维护效率：SQL 和 Java 代码分离，模板可独立修改；多库切换只需改配置，不用动业务代码。
但多表 JOIN 一出场，BeetlSQL 的模板就回到了"字符串拼 SQL"的老路。比如一个三表关联查订单详情：
-- order.md
selectOrderWithDetail
===
SELECT o.id, o.status, u.name, d.product_name
FROM order o
LEFT JOIN user u ON o.user_id = u.id
LEFT JOIN order_detail d ON o.id = d.order_id
WHERE o.status = #status#
u.name 改成 u.nickname？编译器无感，只有运行时才暴露。表名、列名全靠人眼校验——这和 JOOQ 的"Java 编译器替你检查 SQL"思路正好相反。
JOOQ 怎么补位
JOOQ 的强项是用 Java 代码生成类型安全的 SQL。它的代码生成器根据数据库 schema 产出 Java 类，每个表、每个列都是强类型引用：
// JOOQ 生成的表引用
OrderTable O = ORDER;
UserTable U = USER;
OrderDetailTable D = ORDER_DETAIL;
// 类型安全的 JOIN
Result<Record> result = ctx.select(O.ID, O.STATUS, U.NAME, D.PRODUCT_NAME)
.from(O)
.leftJoin(U).on(O.USER_ID.eq(U.ID))
.leftJoin(D).on(O.ID.eq(D.ORDER_ID))
.where(O.STATUS.eq("PAID"))
.fetch();
列名写错？编译直接报红。表结构变了？重新生成一次 JOOQ 代码，所有引用处编译期全部亮红灯，不存在"改了列名忘了改 SQL"的事。
但 JOOQ 自己的结果映射比较啰嗦——result.into(OrderVO.class) 要靠反射，复杂嵌套映射需要手写 RecordMapper，批量操作和分页也没有 BeetlSQL 那么顺手。
3.40 的集成思路就是：JOOQ 拼 SQL，BeetlSQL 映射结果。
实战：JOOQ 拼查询 + BeetlSQL 映射
下面是一个可改造运行的完整示例，展示两者如何配合。假设你已有一个 BeetlSQL 项目，现在要加入 JOOQ 处理复杂 JOIN。
第一步：引入依赖
<!-- pom.xml -->
<dependency>
<groupId>com.ibeetl</groupId>
<artifactId>beetlsql</artifactId>
<version>3.40.0</version>
</dependency>
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq</artifactId>
<version>3.19.0</version>
</dependency>
<!-- JOOQ 代码生成器，开发阶段用 -->
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq-codegen</artifactId>
<version>3.19.0</version>
<scope>provided</scope>
</dependency>
第二步：JOOQ 代码生成配置
在项目根目录放一个 jooq-config.xml，指向你的数据库：
<configuration>
<jdbc>
<driver>com.mysql.cj.jdbc.Driver</driver>
<url>jdbc:mysql://localhost:3306/mydb</url>
<user>root</user>
<password>your_password</password>
</jdbc>
<generator>
<database>
<name>org.jooq.meta.mysql.MySQLDatabase</name>
<includes>order|user|order_detail</includes>
</database>
<target>
<packageName>com.example.jooq</packageName>
<directory>src/main/java</directory>
</target>
</generator>
</configuration>
运行生成：
mvn org.jooq:jooq-codegen-maven:3.19.0:generate -Djooq.configurationFile=jooq-config.xml
生成后你会得到 com.example.jooq.tables.Order、com.example.jooq.tables.User 等强类型表引用类。
第三步：集成代码——JOOQ 拼 SQL，BeetlSQL 接结果
@Service
public class OrderQueryService {
@Autowired
private DSLContext dsl; // JOOQ 的 SQL 执行上下文
@Autowired
private SQLManager sqlManager; // BeetlSQL 的核心入口
/**
* 类型安全的多表 JOIN 查询，
* 用 JOOQ 拼 SQL 并执行，
* 用 BeetlSQL 的映射能力把结果转到自定义 VO
*/
public List<OrderDetailVO> queryPaidOrdersWithDetail() {
// JOOQ 强类型拼 SQL —— 列名、表名都有编译期检查
Order O = ORDER.as("o");
User U = USER.as("u");
OrderDetail D = ORDER_DETAIL.as("d");
String sql = dsl.render(
dsl.select(O.ID, O.STATUS, U.NAME, D.PRODUCT_NAME)
.from(O)
.leftJoin(U).on(O.USER_ID.eq(U.ID))
.leftJoin(D).on(O.ID.eq(D.ORDER_ID))
.where(O.STATUS.eq("PAID"))
);
// BeetlSQL 执行这条 SQL，并用内置映射转成 VO
// 这里假设 OrderDetailVO 的字段名与 SQL 列名一致（BeetlSQL 默认驼峰映射）
List<OrderDetailVO> list = sqlManager.execute(sql, OrderDetailVO.class, null);
return list;
}
}
关键点：
dsl.render(...)只生成 SQL 字符串，不执行——JOOQ 负责拼，不抢执行权。sqlManager.execute(...)是 BeetlSQL 的原生 API，拿 SQL 字符串 + 目标类做映射，支持驼峰、注解、自定义映射策略。- 如果需要传参数，JOOQ 的
Param对象可以先render成带占位符的 SQL，再用 BeetlSQL 的参数 Map 填值：
// JOOQ 拼出带占位符的 SQL
Condition statusCondition = O.STATUS.eq(param("status", "PAID"));
String sql = dsl.render(dsl.select(...).from(O).where(statusCondition));
// BeetlSQL 用自己的参数机制执行
Map<String, Object> params = new HashMap<>();
params.put("status", "PAID");
List<OrderDetailVO> list = sqlManager.execute(sql, OrderDetailVO.class, params);
第四步：简单查询继续用 BeetlSQL 原生 API
不是所有查询都需要 JOOQ。单表 CRUD、简单条件查询，BeetlSQL 的链式 API 和 Markdown 模板依然是最快路径：
// 单表查询——不需要 JOOQ，BeetlSQL 原生就够
List<Order> orders = sqlManager.query(Order.class)
.andEq("status", "PAID")
.select();
原则：简单场景用 BeetlSQL 原生，复杂多表 JOIN 才拉 JOOQ 出场。 两套工具共存，不互斥。
什么时候该引入这套组合
| 场景 | 推荐方案 |
|---|---|
| 单表 CRUD | BeetlSQL 原生 API / Markdown 模板 |
| 两表简单 JOIN，列不多 | BeetlSQL Markdown 模板够用，改列名风险可控 |
| 三表以上 JOIN，列多、经常随 schema 变 | JOOQ 拼 SQL + BeetlSQL 映射 |
| 需要动态条件组合（WHERE 子句不确定） | JOOQ 的 Condition 链式组合比模板 if/else 更安全 |
| 大批量写入 / 分页查询 | BeetlSQL 原生（JOOQ 批量写入性能一般） |
几个需要注意的边界：
- JOOQ 代码生成是开发期步骤，每次 schema 变更要重新跑生成器。CI 流程里建议加一个
mvn generate阶段，确保生成代码和数据库同步。 - JOOQ 的 DSLContext 需要配置数据源。如果 BeetlSQL 已经配了
DataSource，可以让 JOOQ 共用同一个，避免多数据源混乱。 - JOOQ 商业版才支持多 schema 代码生成，开源版单 schema 足够覆盖大多数单库场景。
上手清单
- 现有 BeetlSQL 项目加
jooq和jooq-codegen依赖。 - 写
jooq-config.xml，指向目标数据库，限定表范围（不要全库生成，只生成你 JOIN 涉及的表）。 - CI 或本地跑一次代码生成，确认生成类能编译。
- 在复杂 JOIN 的 Service 方法里，用
dsl.render()拼 SQL，sqlManager.execute()映射结果。 - 单表和简单查询不动，继续用 BeetlSQL 原生 API——不要为了"统一"把简单查询也改成 JOOQ，那只会增加无谓复杂度。
BeetlSQL 3.40 的 JOOQ 集成不是要替代 BeetlSQL 自身的查询能力，而是给"多表类型安全"这个具体痛点开一扇门。用对的场景、用对的工具，比"全统一到一个方案"更务实。