Erupt JDBC 单表数据源

erupt-data-jdbc 模块提供纯 JDBC 数据源支持，无需 JPA / 实体映射即可将 @Erupt 模型绑定到单张数据库表。适用于不想引入 Hibernate、对接遗留库表，或使用只有 JDBC 驱动的数据库（ClickHouse、Doris、TDengine、TiDB、达梦、人大金仓等）的场景。

筛选、排序、分页均下推为 SQL 执行（基于 Spring 的 NamedParameterJdbcTemplate）。条件值始终以命名参数绑定，条件字段与排序字段必须是模型中声明的字段——两者共同防止 SQL 注入。

引入方式

<dependency>
  <groupId>xyz.erupt</groupId>
  <artifactId>erupt-data-jdbc</artifactId>
  <version>${erupt.version}</version>
</dependency>

需自行添加目标数据库的 JDBC 驱动，并提供 DataSource（Spring Boot 通过 spring.datasource.* 自动配置的主数据源，或自定义的命名 Bean）。

@EruptJdbc 注解

属性	默认值	说明
value	—	表名
datasource	""	备用 DataSource 的 Bean 名称，为空使用主数据源

使用示例

@Getter
@Setter
@Erupt(name = "订单", primaryKeyCol = "id")
@EruptJdbc("t_order")
@EruptDataProcessor(EruptJdbcDataService.DATA_PROCESSOR)
public class Order {

    @EruptField(views = @View(title = "ID"))
    private Long id;

    @EruptField(
        views = @View(title = "订单号"),
        edit = @Edit(title = "订单号", notNull = true, search = @Search)
    )
    private String number;

    @EruptField(
        views = @View(title = "金额"),
        edit = @Edit(title = "金额", type = EditType.NUMBER)
    )
    private BigDecimal amount;

    @EruptField(
        views = @View(title = "下单时间"),
        edit = @Edit(title = "下单时间", type = EditType.DATE_TIME)
    )
    private LocalDateTime placedAt;
}

第二数据源

注册任意 DataSource Bean 并按名称引用：

@Configuration
public class ReadOnlyDataSourceConfig {
    @Bean("reporting")
    public DataSource reportingDataSource() { /* 构建 HikariDataSource */ }
}

@EruptJdbc(value = "v_daily_sales", datasource = "reporting")
public class DailySales { ... }

操作支持

完整 CRUD：列表 / 详情 / 新增 / 修改 / 删除。分页使用 LIMIT / OFFSET 语法，MySQL、PostgreSQL、H2、SQLite、MariaDB 均支持。

表在 SQL 中以 Erupt 类名作为别名，因此钻取（Drill）与 @Filter 条件串（如 Order.number = 'x'）可与 JPA 实现下完全一致地使用。

注意

• 列名 = 字段名，Java 字段名需与数据库列名完全一致。
• JDBC 的 Number / Timestamp / Date 与 Java 类型（Integer、LocalDateTime、LocalDate、BigDecimal 等）之间的转换自动完成。

能力边界与限制

上线前请逐条确认

• queryColumn 是无 limit 的 select *。 Excel 导出、下拉选项、OLAP 取数走的都是 queryColumn，它只拼接 where 与参数，不加任何行数上限。对着千万级表点一次导出，就是一次全表扫描 + 全量结果集加载进 JVM。请务必配合 @Erupt(filter = ...)、DataProxy.beforeFetch() 或数据库视图先收窄范围，或直接用 @Erupt(power = @Power(export = false)) 关闭导出。
• 模型必须有无参构造器。 详情查询通过 getDeclaredConstructor().newInstance() 反射实例化模型，只写了带参构造器的类会在打开详情 / 编辑弹窗时抛异常。用 Lombok 时请确认没有只加 @AllArgsConstructor 而漏掉 @NoArgsConstructor。
• 新增时 null 字段会被剔除。 addData 会在拼 insert 前移除所有值为 null 的字段，因此这些列取的是数据库的 DEFAULT 值。如果某列没有默认值且为 NOT NULL，插入会直接失败。
• 修改时 null 字段会被写入。 与新增相反，editData 会把模型上所有非主键字段（含 null）都放进 set 子句。这意味着表单上未展示 / 未填写的字段会被覆盖成 NULL——只暴露部分列的模型请特别当心。
• 分页语法不通用。 分页固定拼接 limit {pageSize} offset {offset}，MySQL、MariaDB、PostgreSQL、H2、SQLite、ClickHouse 均可用，但 Oracle、SQL Server 不支持该语法，列表查询会直接报 SQL 语法错误。这两类数据库请改用 JPA 数据源，或建一个兼容视图。
• conditionStrings 直接拼进 SQL。 @Filter、@Link 下钻等条件串是原样拼接的（值不做参数绑定）。这些内容来自服务端注解而非用户输入，但请勿把用户可控的字符串写进 @Filter 表达式。前端传来的搜索条件不受影响——条件字段会做白名单校验，条件值一律走命名参数绑定。

贡献者

YuePeng

Claude Fable 5.1

页面历史

最后编辑于 4 分钟前

查看完整历史

9d3089d-Split the erupt-tpl module docs and drop the obsolete memory screenshot (#15)