1. 一句话简介
BeetlSQL 是一个国产 ORM（对象关系映射）框架，基于 Beatl 模板引擎构建，主打「内置 CRUD + 灵活 SQL」两条路线。它像 JPA/MyBatis-Plus 一样，通过继承 BaseMapper 接口即可获得 insert、deleteById、updateTemplateById、single、all、createLambdaQuery().page() 等开箱即用的增删改查与分页方法；同时又像 MyBatis 一样，允许用 Beetl 模板语法（Markdown 文件）手写 SQL，灵活处理复杂查询。
核心要解决的问题是：在保持手写 SQL 灵活性的同时，把常规 CRUD 和分页操作从日常编码中解放出来。官方提供 beetl-framework-starter 与 Spring Boot 集成，@Table 注解配实体类、UnderlinedNameConversion 自动完成驼峰字段与下划线列名的映射。
2. 什么时候使用
✅ 适用场景
- 标准 CRUD 为主、偶尔有复杂查询的小型业务：通过
BaseMapper内置方法即可完成，无需为每个表编写映射文件和接口方法。 - 追求模板化、可动态拼接的动态 SQL：Beetl 模板语法（分支、循环、变量）比 XML 拼接更贴近模板语言，适合查询条件动态组合的场景。
- 分页查询：内置
PageQuery+createLambdaQuery()，一行即得总行数与当前页数据，无需额外引入分页插件。 - 偏好中文文档、国产开源组件的团队：BeetlSQL 文档对中文友好，且与 Beatl 模板引擎同源。
- 需要代码生成、希望实体既当 ORM 模型又做模板数据绑定的场景：实体可直接用于 SQL 模板渲染。
❌ 不适用 / 需谨慎
- 与主流 ORM 深度集成的既有项目：集成不够顺畅——官方 starter 无法直接用 Spring Boot 的自动数据源配置，需通过
@Configuration手动创建名为datasource的HikariDataSourceBean，否则启动失败（本 demo 的最大坑点）。 - 团队以 XML Mapper / JPA 生态为技术栈：迁移到 BeetlSQL 需额外学习模板语法，且第三方资料与社区规模远小于 MyBatis 和 JPA。
- 对框架生态和招聘面有要求的团队：国内独立框架，社区活跃度有限，遇到深水区问题可参考的资料少。
- 复杂企业级 / 大规模复杂领域建模：实体与数据库表耦合较紧，缺少 Hibernate 式的继承、关联、乐观锁等丰富语义，复杂领域建模表达力弱。
- 强依赖 Spring Data 自动配置的微服务：BeetlSQL 需显式接管数据源，与「零配置」的 Spring 惯例存在摩擦。
3. 常见业务场景
用户信息 CRUD： 这是本 demo 的核心演示逻辑。UserDao extends BaseMapper<User> 直接获得增删改查能力，userDao.insert(user, true) 插入并自动回填自增主键，userDao.updateTemplateById(user) 做模板更新（只更新非 null 字段，null 字段不会被写成 NULL），single(id)、all() 分别完成单查与列表查询。中小系统用户模块无需写任何 Mapper SQL。
列表分页查询： 后台管理系统的列表页几乎都要分页。userDao.createLambdaQuery().page(currentPage, pageSize) 一行代码返回 PageQuery<User>（含 list 与 totalRow），免去手写 LIMIT/COUNT 与插件配置，适合高频率分页场景。
批量数据写入： 如批量导入、初始化测试数据。userDao.insertBatch(users) 原生支持批量插入，比循环单插效率更高，适合数据迁移、批量灌库类需求。
动态条件查询报表 / 组合筛选： 当筛选条件随参数变化时，用 Beetl 模板在 SQL 中做条件分支与循环动态拼接，比字符串手工拼接更安全易读，比 MyBatis XML 更贴近模板语言，适合查询条件多变的统计与查询页。
4. 同类技术对比
| 维度 | BeetlSQL | MyBatis / MyBatis-Plus | Spring Data JPA |
|---|---|---|---|
| 内置 CRUD | 自带 BaseMapper，免写方法 |
原生无，需 MyBatis-Plus 补充 | 自带 JpaRepository，能力最全 |
| SQL 编写方式 | Beetl 模板语法（Markdown 文件）或注解 | XML Mapper 或注解 | JPQL / 方法名派生查询 / @Query |
| 复杂 SQL 表达力 | 模板语言 + 动态拼接，灵活 | XML 映射成熟，控制力最强 | 复杂 SQL 需 JPQL 推导，较弱 |
| 分页支持 | 内置 PageQuery + Lambda 查询 |
原生需 PageHelper 插件 | 内置 Pageable + Page<T> |
| 命名转换 | 内置 UnderlinedNameConversion |
XML 需配置 mapUnderscoreToCamelCase |
Hibernate ImplicitNamingStrategy |
| 学习成本 | 中等，需懂 Beetl 模板语法 | 中等，需熟 XML 映射 | 较低，多为注解驱动 |
| Spring Boot 集成 | 官方 starter，但需手动配置数据源（坑多） | 无缝集成 | 无缝集成 |
| 分布式 / 大型系统支持 | 一般，生态与资料有限 | 强，全球使用广泛，运维经验多 | 强，Spring 官方维护 |
| 适用规模 | 中小型、以 CRUD + 动态查询为主 | 中大型，复杂查询多 | 中型，领域模型驱动 / 快速开发 |
选型建议：
- 以复杂、可控的 SQL 和报表查询为主，团队熟悉 SQL —— 选 MyBatis（+ MyBatis-Plus），生态成熟、控制力最强。
- 以领域的对象模型为中心，快速开发 CRUD 与关系映射 —— 选 Spring Data JPA，与 Spring 生态融为一体、学习成本低。
- 想要内置 CRUD 开箱即用、又希望用模板语言写动态 SQL，且愿意接受手动数据源配置与较小社区的独立项目 —— 可选 BeetlSQL，尤其适合偏好中文文档、与 Beatl 视图模板同一家的场景。