Apache Empire-db 3.5.0 介绍与选型指南

目标：基于官方网站、官方发行目录与项目仓库联网溯源（查询日期 2026-10-18），完成 Apache Empire-db 最新稳定版 3.5.0 的认知与选型评估。本文属认知篇（A1），关键论断均随文标注来源，不做本地安装实测。

一、信息基准

1.1 查询日期与版本依据

• 查询日期：2026-10-18（本文所有版本号、活跃度与发版数据均以该日联网实查为准）。
• 本次介绍版本：Apache Empire-db 3.5.0。版本依据：官网首页明确标注"Version 3.5.0 Released 2026-07-21"（empire-db.apache.org，2026-10-18 实查）；官方发行目录 https://downloads.apache.org/empire-db/ 当前在架 3.5.0（目录时间戳 2026-07-21，2026-10-18 实查）。
• 版本线说明：3.4.x（Maven Central 在架 3.4.0）为上一稳定线；3.5.0 为当前最新（来源：Maven Central 与官方发行目录交叉印证，2026-10-18 实查）。
• 说明：Empire-db 属于 Java 库（无独立进程），本文按库/框架形态撰写，三、四章以核心概念与工作方式为主。

1.2 官方来源清单

二、软件概述

本文介绍的是 Apache Empire-db 3.5.0：一个轻量级的 Java 关系数据库访问库，强调"用纯 Java API 完整表达 SQL"，采用 Apache License 2.0 许可，运行于 JVM（来源：官网首页与仓库 LICENSE，2026-10-18 实查）。

官网以"Full SQL Freedom for Java"概括其定位：让 Java 应用不受限制地使用关系数据库的能力。其口号式主张包括：忘掉 OR-Mapping、Entity Beans、懒加载/急加载、字节码代理与"黑盒魔法"；没有注解轰炸、没有映射文件，只有简单直接的 Java API；用代码以最直观的方式表达复杂 SQL（"No Strings attached"，即无需手拼 SQL 字符串）；提升编译期安全与可维护性，编写与具体 DBMS 无关的代码，并内置标识管理、并发控制（乐观锁）、DDL 操作与元数据访问（来源：官网首页 Why? 段落原文归纳，2026-10-18 实查）。

它要解决的核心问题是：全功能 ORM（如 JPA/Hibernate）为对象关系映射引入大量抽象与运行时魔法，而手拼 SQL 字符串又丧失类型安全与可维护性。Empire-db 选择中间路线——以强类型的 Java API 直接构造 SQL 命令（DBCommand），由库负责生成对应方言的 SQL 并安全绑定参数，既保留对 SQL 的完全控制，又获得编译期检查与跨数据库可移植性（来源：官网首页定位与示例，2026-10-18 实查）。

三、核心概念与工作方式

3.1 强类型数据模型（DBTable/DBColumn）

使用前需以 Java 代码声明数据模型：每个表是一个 DBTable 对象，字段是 DBColumn 对象（含类型、长度、必填等元信息）。官方提供 codegen 模块（empire-db-codegen 与 empire-db-maven-plugin）从既有数据库 schema 反向生成模型类，模型一经定义即可在全工程中以编译期可检查的方式引用（来源：官网与 Maven Central org.apache.empire-db 构件列表，2026-10-18 实查）。

3.2 DBCommand：以 API 构造 SQL

查询/更新以 DBCommand 链式 API 表达：select、join/joinLeft、where、groupBy、having、orderBy 等一一对应 SQL 子句；表达式对象（count、avg、round、minus 等）负责算术与聚合，参数以 PreparedStatement 绑定而非字符串拼接，规避注入风险。官方首页示例中，一个含多表连接、条件聚合、差值四舍五入的查询与最终生成 SQL 逐行对应（来源：官网首页 Natural selection 示例，2026-10-18 实查）。

3.3 DBContext 与读写器

DBContext 封装一个连接上的会话（事务、方言、选项）；读取用 DBReader（逐行遍历或映射 Bean/Record），写入用 DBWriter（insert/update/delete 与乐观锁校验），DDL 与元数据由对应工具类提供。数据可映射为普通 Java Bean（需要匹配的构造器或 setter），官方强调"这只是获取与处理查询结果的若干选项之一"（来源：官网首页示例注释与文档结构，2026-10-18 实查）。

3.4 方言体系与 DBMS 无关

同一份 DBCommand 由所选 DBMS 方言（ Empire-db 术语为 DBMS capability/driver 层）生成目标 SQL。官网列出的支持数据库包括 Oracle、SQL Server、PostgreSQL、MySQL、HsqlDB、Derby、H2 等（来源：官网首页 Support for… 原文，2026-10-18 实查）。

四、功能特性

五、快速上手

以下示例引自官网首页《Natural selection》示例（来源：https://empire-db.apache.org/ ，2026-10-18 实查；本文不本地运行）。该示例展示一个"车型销售"查询：按品牌与规格统计销量与均价，并计算均价与基准价之差。

官方 Java 代码（官方原文）：

// create a command
DBCommand cmd = context.createCommand()
   .select  (BRAND.NAME, MODEL.SPECIFICATION, MODEL.BASE_PRICE)
   .select  (SALES.MODEL_ID.count(), SALES.PRICE.avg())
   .select  (SALES.PRICE.avg().minus(MODEL.BASE_PRICE.avg()).round(2).as("DIFFERENCE"))
   .join    (MODEL.WMI.on(BRAND.WMI))
   .joinLeft(MODEL.ID.on(SALES.MODEL_ID).and(SALES.YEAR.is(2021)))  // only year 2021
   .where   (MODEL.ENGINE_TYPE.in(EngineType.P, EngineType.H, EngineType.E)) // Petrol, Hybrid, Electric
   .where   (MODEL.BASE_PRICE.isGreaterThan(30000))
   .groupBy (BRAND.NAME, MODEL.SPECIFICATION, MODEL.BASE_PRICE)
   .having  (SALES.MODEL_ID.count().isGreaterThan(5))   // more than 5 sales
   .orderBy (BRAND.NAME.desc(), MODEL.SPECIFICATION.asc());
// Return a list of Java beans (needs matching fields constructor or setter methods)
// This is just one of several options to obtain and process query results
List<QueryResult> list = context.getUtils().queryBeanList(cmd, QueryResult.class, null);
log.info("queryBeanList returned {} items", list.size());

官方给出的对应生成 SQL（官方原文）：

SELECT t1.NAME, t2.SPECIFICATION, t2.BASE_PRICE
   , count(t5.MODEL_ID), avg(t5.PRICE)
   , round(avg(t5.PRICE)-avg(t2.BASE_PRICE),2) AS DIFFERENCE
FROM MODEL t2
     INNER JOIN BRAND t1 ON t1.WMI = t2.WMI
     LEFT JOIN SALES t5 ON t5.MODEL_ID = t2.ID AND t5.YEAR=2021
WHERE t2.ENGINE_TYPE IN ('P', 'H', 'E') AND t2.BASE_PRICE>30000
GROUP BY t1.NAME, t2.SPECIFICATION, t2.BASE_PRICE
HAVING count(t5.MODEL_ID)>5
ORDER BY t1.NAME DESC, t2.SPECIFICATION

依赖引入：Maven Central 坐标 org.apache.empire-db:empire-db（最新 3.5.0；官方发行目录 https://downloads.apache.org/empire-db/3.5.0/ 同时提供二进制与源码包，2026-10-18 实查）。

六、适用场景与限制

6.1 适用场景

• 以 SQL 为中心的报表与查询密集系统：需要精确控制 SQL 形态（连接、聚合、窗口）又想要类型安全与可移植（来源：官网首页定位，2026-10-18 实查）。
• 不愿引入全功能 ORM 的轻量服务：无注解、无映射文件、无字节码代理，适合对包体与运行时行为可控性敏感的应用（来源：官网首页 No annotation madness… 原文，2026-10-18 实查）。
• 多数据库产品适配：同一套数据访问代码需在 Oracle/SQL Server/PostgreSQL/MySQL/H2 等间切换或共存（来源：官网支持列表，2026-10-18 实查）。

6.2 限制与注意事项

• 社区与生态规模较小：相较 JPA/Hibernate、MyBatis、jOOQ，第三方教程、集成与人才储备有限；发行节奏以年计（3.4.0→3.5.0 约 9 个月，来源：Maven Central 时间戳，2026-10-18 实查）。
• 需自行维护数据模型类：模型即代码带来编译期安全，但 schema 演进需配合 codegen 重新生成（来源：官方 codegen 模块说明，2026-10-18 实查）。
• 不提供对象关系映射：多表关联结果的组装、懒加载、级联持久化等 ORM 特性不在其目标内，复杂对象图需自行组织（来源：官网"忘掉 OR-Mapping…"主张的对称推论，2026-10-18 实查）。

七、同类选型对比

对比对象：jOOQ（类型安全 SQL DSL 的代表）、QueryDSL（通用类型安全查询 DSL）、MyBatis 动态 SQL（SQL 模板映射框架）。数据来源：Maven Central/GitHub，2026-10-18 实查。

选型建议一句话：要"完全掌控 SQL + Apache-2.0 全许可 + 轻量无魔法"且团队能接受小众库，选 Empire-db；追求最强类型安全与 IDE 补全、可接受商业许可边界选 jOOQ；需要 JPA 生态内统一查询抽象选 QueryDSL；存量 SQL 治理与 DBA 协作流以 SQL 本体为中心则用 MyBatis 动态 SQL。

八、参考链接

1. 官网首页（含示例与版本公告）：https://empire-db.apache.org/
2. 官方发行目录：https://downloads.apache.org/empire-db/
3. GitHub 只读副本仓库：https://github.com/apache/empire-db
4. Maven Central 构件：https://repo1.maven.org/maven2/org/apache/empire-db/
5. Apache 项目页：https://projects.apache.org/project.html?empire-db