JeecgBoot 元数据驱动的低代码引擎（Online 模块）

JeecgBoot 元数据驱动的低代码引擎（Online 模块）

学习目标

通过本章学习，你将能够：

• 理解 Online 模块的元数据驱动架构
• 掌握 cgform 配置表如何驱动运行时 CRUD
• 了解代码生成器的工作流程与模板机制
• 了解表单设计器与 23 种控件的底层实现

---

项目实践

元数据驱动架构

Online 模块的核心理念是配置即代码：通过数据库配置表存储表单结构定义，运行时动态解析并生成增删改查功能，无需手写代码。

核心配置表

Online 模块的元数据存储在以下配置表中：

配置表	职责
onl_cgform_head	表单头部定义（表名、描述、作者等）
onl_cgform_field	字段定义（字段名、类型、控件类型、校验规则等）
onl_cgform_index	索引定义
onl_cgform_button	按钮配置（查询按钮、操作按钮等）
onl_cgform_enhance_java	Java 增强代码
onl_cgform_enhance_sql	SQL 增强代码
onl_cgform_enhance_js	JS 增强代码

字段定义示例：

onl_cgform_field
├── cgform_head_id     # 关联的表单 ID
├── field_name         # 字段名（如 user_name）
├── field_txt          # 字段显示名（如 用户名）
├── field_type         # 数据库类型（VARCHAR, INT, DATE 等）
├── field_length       # 字段长度
├── is_show            # 是否显示（Y/N）
├── is_query           # 是否可查询（Y/N）
├── query_mode         # 查询模式（=, LIKE, >=, <= 等）
├── field_table_type   # 控件类型（text, select, date, radio, checkbox 等 23 种）
├── default_value      # 默认值
├── is_readonly        # 是否只读
├── is_required        # 是否必填
└── ... 更多配置

运行时 CRUD 引擎

Online 表单的核心能力是无需生成代码即可运行：

// 伪代码：Online CRUD 引擎
@PostMapping("/online/cgform/api/{code}")
public Result<?> doAdd(@PathVariable String code, @RequestBody Map<String, Object> data) {
    // 1. 根据 code 查询表单配置
    CgFormHead head = cgFormHeadService.queryByTableName(code);
    List<CgFormField> fields = cgFormFieldService.queryByCgformHeadId(head.getId());

    // 2. 动态构建 SQL
    StringBuilder sql = new StringBuilder("INSERT INTO " + code + " (");
    for (field : fields) {
        if (data.containsKey(field.getFieldName())) {
            sql.append(field.getFieldName()).append(", ");
        }
    }
    // ... 构建完整 SQL

    // 3. 执行增强（如果有）
    enhanceService.executeJavaEnhance(head.getJavaEnhanceCode(), data);

    // 4. 执行 SQL
    jdbcTemplate.update(sql.toString(), params);

    return Result.OK();
}

查询过滤器自动构建：

// HTTP 查询参数 → SQL WHERE 条件
GET /online/cgform/api/user_info?userName=张三&age_=&age_=30

// 自动转换为：
// WHERE user_name LIKE '%张三%' AND age >= ? AND age <= ?

QueryGenerator.initQueryWrapper() 自动将 HTTP 参数解析为查询条件，支持：

• 精确匹配：fieldName=value
• 模糊匹配：fieldName*=value
• 范围查询：fieldName_>=value1&fieldName_<=value2
• IN 查询：fieldName_in=val1,val2,val3

代码生成器

当 Online 表单需要更高性能或定制化时，可通过代码生成器生成完整代码：

代码生成器输入：表单配置（cgform_* 表）
    ↓
模板引擎（Freemarker / Velocity）
    ↓
生成内容：
├── Entity.java          # 实体类（@TableName, @TableId 等注解）
├── Mapper.java          # Mapper 接口（继承 BaseMapper）
├── Mapper.xml           # MyBatis XML 映射文件
├── Service.java         # Service 接口
├── ServiceImpl.java     # Service 实现
├── Controller.java      # Controller（继承 JeecgController）
├── index.vue            # 前端页面
└── xxx.api.ts           # 前端 API 调用
    ↓
下载 ZIP 或在线建表

四套风格模板：

风格	适用场景	模板特点
单表风格一	简单 CRUD	最基础的增删改查
单表风格二	带导入导出的单表	增加 Excel 导入导出功能
树模型	树形数据	递归查询、层级展示
一对多	主子表	主表 + 子表的联合操作

模板自定义：

jeecg-boot-module-online/template/
├── java/                    # Java 模板
│   ├── controller.ftl
│   ├── service.ftl
│   └── ...
├── vue/                     # 前端模板
│   ├── list.vue.ftl
│   └── ...
└── sql/                     # SQL 模板
    └── create_table.ftl

用户可以替换模板文件，自定义生成代码的风格和结构。

23 种表单控件

Online 表单设计器支持 23 种控件类型：

分类	控件类型
文本类	text、textarea、password、editor（富文本）
选择类	select、radio、checkbox、listbox
日期类	date、datetime、time
特殊类	popup（弹窗选择）、file（文件上传）、image（图片上传）、switch
业务类	user_select（用户选择）、dept_select（部门选择）、dict（字典选择）
高级类	markdown、code_editor、subtable（子表）

每种控件在 field_table_type 字段中标识，前端根据类型渲染对应的 Vue 组件。

在线增强

Online 表单支持在配置界面直接编写增强代码：

增强类型	执行时机	语言
Java 增强	增删改查前后	Java
SQL 增强	数据操作前后执行 SQL	SQL
JS 增强	前端表单提交前后	JavaScript
表单校验增强	前端提交时校验	JavaScript

增强执行顺序：

前端 JS 增强（提交前）
    ↓
后端 Java 增强（操作前）
    ↓
执行 CRUD 操作
    ↓
后端 Java 增强（操作后）
    ↓
SQL 增强（操作后）

---

问题与规避

陷阱	表现	对策
配置表与实际表结构不一致	运行时字段缺失或类型不匹配	生成表单时同步创建/修改实际业务表
控件类型与数据库类型不匹配	select 控件但数据库存 INT	表单设计器校验控件类型与字段类型的兼容性
Online 增强代码异常影响全局	Java 增强抛出未捕获异常	增强代码使用 try-catch 包裹，异常不影响主流程
大量字段时表单性能差	50+ 字段的表单渲染慢	前端按需渲染可见字段，隐藏字段延迟加载

---

设计取舍

配置存数据库 vs 配置存文件

JeecgBoot 选择：配置存数据库。

方案	优势	代价
存数据库（当前方案）	运行时可直接读取，支持热更新，多实例共享	配置变更无版本控制（需手动导出备份）
存文件	版本控制友好，代码审查	需要重启或额外的热更新机制

低代码平台的核心价值是”业务人员可配置”，配置存数据库更符合实时生效的需求。

运行时解析 vs 代码生成

JeecgBoot 选择：两者共存。

方案	适用场景
运行时解析	快速原型、简单 CRUD、频繁变更的表单
代码生成	性能要求高、复杂业务逻辑、需深度定制

“Online 配置 → 代码生成 → 手工合并”的渐进式路径，让开发者从低代码平滑过渡到传统编码。

---

参考来源

• JeecgBoot 开发文档
• JeecgBoot 源码 v3.9.2