EzAdmin 低代码开发工具

一、快速开始

Maven 依赖

根据您的 Java 版本选择对应的依赖：

<!-- 最新版本：3.1.2，适用于 Java 17 / Spring Boot 3 -->
<dependency>
    <groupId>io.github.ezadmin126</groupId>
    <artifactId>ezadmin-java17-spring-starter</artifactId>
    <version>3.1.2</version>
</dependency>

<!-- Java 8 -->
<dependency>
    <groupId>io.github.ezadmin126</groupId>
    <artifactId>ezadmin-java8-spring-starter</artifactId>
    <version>3.1.2</version>
</dependency>

启用配置

在 Spring Boot 主类上添加 @EnableEzadmin 注解：

@SpringBootApplication
@EnableEzadmin
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

application.yml 配置

在 application.yml 中配置 EzAdmin 相关参数：

topezadmin:
  # 缓存开关，开发时建议设为 false
  cacheFlag: false

  # 数据源配置（多个用逗号分隔）
  datasourceBeanNames: 'dataSource'

  # 文件上传配置
  uploadPath: /data/upload
  downloadUrl: /core/downloadDesc.html?fileId=
  uploadUrl: /system/upload.html

  # 日志配置
  logType: 1000-10000

  # 界面配置
  adminStyle: layui
  layout: fluid

  # 系统路由配置
  clearUrl: /topezadmin/clearCache.html
  signoutUrl: /login/signout.html
  indexUrl: /doc/index.html
  navUrl: /laynavs.html

  # AI 功能配置（可选）
  apiUrl: https://api.deepseek.com/v1/chat/completions
  apiKey: sk-xxxxxxxxxxxxxxxx
  model: deepseek-chat
  temperature: 0.8
 

二、DSL 总览：可以从哪几个方面理解

对于 src/main/resources/topezadmin/config/layui/dsl 这套配置，建议不要按“字段一个个背”的方式学习，而是按页面搭建的完整链路来理解。用户真正关心的是：页面放哪里、长什么样、查什么数据、怎么交互、怎么扩展。

三、配置格式

JSON 配置文件存放路径：

• 列表配置：topezadmin/config/layui/dsl/list/业务模块/*.json
• 表单配置：topezadmin/config/layui/dsl/form/业务模块/*.json
• 静态字典：topezadmin/config/layui/dsl/data/*.json
• 列表查询表达式：通常与列表同目录，例如 warehouse_express_main.ql
• 表单生命周期表达式：例如 *_initExpress.ql、*_submitExpress.ql、*_deleteExpress.ql
• 页面扩展片段：例如 *_appendHead.html、*_appendFoot.html

1. 目录职责

2. 列表页面要点

列表页通常由五部分组成：页面元信息、搜索区、表格列、按钮区、查询表达式。你可以把它理解成“前端布局 + 后端查询”的一个组合配置。

列表配置结构

{
  "id": "列表ID",
  "name": "列表名称",
  "dataSource": "数据源Bean名称",
  "initApi": "自定义接口(可选)",
  "hideSearch": false,

  "body": {
    "emptyShow": "-",
    "showIndex": true,
    "selectable": true,
    "rowActionWidth": 175
  },

  "tabList": [],
  "search": [{"row": []},{"row": []}],
  "column": [],
  "tableButton": [],
  "rowButton": [],
  "tree": {},

  "express": {
    "main": "查询SQL表达式",
    "orderBy": "order by xxx",
    "groupBy": "group by xxx",
    "count": "自定义count语句"
  }
}

3. 表单页面要点

表单页的重点是“分区 + 字段 + 生命周期”。从现有配置看，EzAdmin 的表单不只用于录入，也常用于详情页、流程页、带 iframe 的复合业务页。

表单配置结构

{
  "id": "表单ID",
  "name": "表单名称",
  "dataSource": "数据源Bean名称",
  "successUrl": "保存成功后跳转URL",

  "cardList": [{
    "type": "card",
    "label": "卡片标题",
    "fieldList": [{"row": []},{"row": []}],
    "buttonList": []
  }],

  "buttonList": [],
  "initExpress": [],
  "submitExpress": [],
  "deleteExpress": [],
  "statusExpress": []
}

4. 数据字典与公共枚举

如果多个页面都会用到同一组选项，不要反复内联写 dataJson。更推荐放到 dsl/data 目录，然后通过 @import 引入。

{
  "item_name": "CHECK_STATUS",
  "label": "审核状态",
  "component": "select",
  "initData": {
    "dataJson": "@import(checkstatus.json)"
  }
}

这样做有三个直接好处：

• 一处维护，多处复用，避免多个页面选项不一致。
• 列表展示组件 tdSelect 和表单输入组件 select 可以共用同一份字典。
• 更适合 AI 生成后再人工整理，把通用枚举沉淀成公共资源。

5. 一个典型页面通常由哪些文件组成

四、组件配置

基本结构

无论是搜索项、表格列还是表单字段，本质上都是“字段元信息 + 组件类型 + 数据初始化 + 展示属性”四部分的组合。先理解这个最小单元，再看具体组件会容易很多。

{
  "item_name": "字段名（大写）",
  "label": "显示名称",
  "component": "组件类型",
  "alias": "SQL别名(可选)",
  "jdbcType": "数据类型(可选)",
  "operator": "操作符(可选)",

  "initData": {
    "dataJson": [{"label":"选项1","value":"1"}],
    "dataSql": "SELECT value,label FROM table",
    "dataSource": "数据源名称"
  },

  "props": {
    // Layui 原生属性或自定义属性
  }
}

props 通用属性

所有组件的 props 都支持以下通用属性：

jQuery Validate 验证配置

通过 props.validate 可以配置更复杂的表单验证规则：

{
  "props": {
    "validate": {
      "rule": {
        "required": true,
        "minlength": 2,
        "maxlength": 20,
        "range": [0, 100],
        "email": true,
        "url": true,
        "number": true,
        "digits": true
      },
      "message": {
        "required": "此字段不能为空",
        "minlength": "至少输入2个字符",
        "maxlength": "最多输入20个字符",
        "range": "请输入0-100之间的数字",
        "email": "请输入有效的邮箱地址",
        "url": "请输入有效的URL",
        "number": "请输入数字",
        "digits": "请输入整数"
      }
    }
  }
}

常用验证规则：

• required: 必填验证
• email: 邮箱格式
• url: URL格式
• number: 数字
• digits: 整数
• minlength / maxlength: 长度限制
• min / max: 数值范围
• range: 数值范围（数组形式）
• uploadMin / uploadMax: 上传文件数量限制（仅 upload 组件）

组件类型

点击组件名称可查看详细文档 （展开/收起）

{
  "item_name": "NAME",
  "label": "姓名",
  "component": "input",
  "props": {
    "placeholder": "请输入姓名",
    "lay-verify": "required",
    "maxlength": 20
  }
}

{
  "item_name": "AGE",
  "label": "年龄",
  "component": "input",
  "props": {
    "placeholder": "请输入年龄",
    "type": "number",
    "validate": {
      "rule": {
        "required": true,
        "range": [0, 150],
        "digits": true
      },
      "message": {
        "required": "年龄不能为空",
        "range": "请输入0-150之间的数字",
        "digits": "请输入整数"
      }
    }
  }
}

{
  "item_name": "REMARK",
  "label": "备注",
  "component": "textarea",
  "props": {
    "placeholder": "请输入备注",
    "rows": 5
  }
}

{
  "item_name": "ID",
  "label": "ID",
  "component": "hidden",
}

{
  "item_name": "CONTENT",
  "label": "内容",
  "component": "tinymce",
  "props": {
    "height": 400
  }
}

{
  "item_name": "STATUS",
  "label": "状态",
  "component": "select",
  "initData": {
    "dataJson": [
      {"label": "启用", "value": "1"},
      {"label": "禁用", "value": "0"}
    ]
  },
  "props": {
    "lay-verify": "required",
    "placeholder": "请选择状态"
  }
}

{
  "item_name": "TAGS",
  "label": "标签",
  "component": "select-multiple",
  "operator": "in",
  "initData": {
    "dataSource": "dataSource",
    "dataSql": "SELECT id value, name label FROM tags"
  }
}

{
  "item_name": "REGION_ID",
  "label": "地区",
  "component": "cascader",
  "initData": {
    "dataJson": [
      {
        "label": "北京市",
        "value": "110000",
        "children": [
          {"label": "东城区", "value": "110101"}
        ]
      }
    ]
  }
}

{
  "item_name": "GENDER",
  "label": "性别",
  "component": "radio",
  "initData": {
    "dataJson": [
      {"label": "男", "value": "1"},
      {"label": "女", "value": "2"}
    ]
  }
}

{
  "item_name": "HOBBIES",
  "label": "爱好",
  "component": "checkbox",
  "initData": {
    "dataJson": [
      {"label": "阅读", "value": "1"},
      {"label": "运动", "value": "2"},
      {"label": "旅游", "value": "3"}
    ]
  }
}

{
  "item_name": "CREATE_TIME",
  "label": "创建时间",
  "component": "date",
  "props": {
    "type": "datetime",
    "format": "yyyy-MM-dd HH:mm:ss"
  }
}

{
  "item_name": "AVATAR",
  "label": "头像",
  "component": "upload",
  "props": {
    "accept": "images",
    "multiple": false,
    "size": 2048,
    "description": "支持jpg、png格式，大小不超过2MB"
  }
}

{
  "item_name": "PRODUCT_IMAGES",
  "label": "产品图片",
  "component": "upload",
  "props": {
    "accept": "images",
    "multiple": true,
    "validate": {
      "rule": {
        "uploadMin": 1,
        "uploadMax": 10
      },
      "message": {
        "uploadMin": "至少上传1张图片",
        "uploadMax": "最多上传10张图片"
      }
    }
  }
}

{
  "item_name": "EDIT",
  "label": "编辑",
  "component": "button-normal",
  "props": {
    "opentype": "MODAL",
    "windowname": "编辑用户",
    "url": "/topezadmin/form/page-user-form?id={{=d.ID}}",
    "area": ["60%", "80%"]
  }
}

{
  "item_name": "ADD",
  "label": "新增",
  "component": "button-toolbar",
  "props": {
    "opentype": "MODAL",
    "windowname": "新增用户",
    "url": "/topezadmin/form/page-user-form",
    "area": ["60%", "80%"]
  }
}

{
  "item_name": "STATUS",
  "label": "状态",
  "component": "tdSelect",
  "initData": {
    "dataJson": [
      {"label": "启用", "value": "1"},
      {"label": "禁用", "value": "0"}
    ]
  }
}

按钮 opentype 属性

从页面搭建角度，组件可以分成 5 类

五、表达式系统

DSL 里的 JSON 负责“页面长什么样”，QLExpress 负责“页面的数据和行为怎么跑起来”。实际项目中，这两部分通常是一一配套的。

内置函数

表达式在页面生命周期中的职责

搜索条件是如何自动拼接的

列表页中真正节省工作量的点，是你不需要在 QL 里手动拼每一个查询条件。只要在 search 配置中声明了 item_name 和 operator，再在主查询里调用 search(sql)，系统就会按字段和值自动补条件。

{
  "item_name": "ADD_TIME",
  "label": "变动时间",
  "component": "date",
  "operator": "between",
  "props": {
    "range": true
  }
}

StringBuilder sql = new StringBuilder();
sql.append("SELECT * FROM T_WMS_LOG A WHERE A.DELETE_FLAG = 0");
return search(sql);

这时用户在页面输入的时间范围、下拉值、文本模糊查询，都会围绕这个基础 SQL 自动拼接。

表达式示例

列表查询：

StringBuilder sql = new StringBuilder();
sql.append("SELECT ID, NAME, STATUS FROM users WHERE delete_flag=0");
return search(sql); // 系统会自动拼接搜索条件

表单保存：

if(!isNotBlank("ID")) {
    // 新增
    param = new InsertParam();
    param.table("users");
    param.add("#{NAME}");
    param.add("#{STATUS}");
    param.add("#{CREATE_TIME,value=NOW()}");
    return insertSimple(param);
} else {
    // 更新
    param = new UpdateParam();
    param.table("users");
    param.add("#{NAME}");
    param.add("#{STATUS}");
    param.where("id=#{ID}");
    return updateSimple(param);
}

推荐的表达式拆分方式

• 列表页优先把 SQL 写到独立 *_express_main.ql 文件中，JSON 里通过 @import 引用，避免 JSON 过长。
• 表单页把初始化、保存、删除分成独立文件，便于后续扩展业务逻辑。
• 复杂页面优先使用 InsertParam / UpdateParam，比直接拼接 SQL 更易维护。
• 需要取登录人、公司、租户信息时，优先通过 $$("...") 从 session 取值。

六、完整示例

最小列表配置

{
  "id": "user-list",
  "name": "用户列表",
  "dataSource": "dataSource",

  "body": {
    "showIndex": true,
    "selectable": true
  },

  "search": [

             {"row": [{
    "item_name": "NAME",
    "label": "姓名",
    "component": "input",
    "operator": "like"
  }, {
    "item_name": "STATUS",
    "label": "状态",
    "component": "select",
    "operator": "eq",
    "initData": {
      "dataJson": [
        {"label": "启用", "value": "1"},
        {"label": "禁用", "value": "0"}
      ]
    }
  }]}
                ],

  "column": [{
    "item_name": "ID",
    "label": "ID",
    "props": {"width": 80}
  }, {
    "item_name": "NAME",
    "label": "姓名"
  }, {
    "item_name": "STATUS",
    "label": "状态",
    "component": "tdSelect",
    "initData": {
      "dataJson": [
        {"label": "启用", "value": "1"},
        {"label": "禁用", "value": "0"}
      ]
    }
  }],

  "tableButton": [{
    "item_name": "add",
    "label": "新增",
    "component": "button-toolbar",
    "props": {
      "opentype": "MODAL",
      "windowname": "新增用户",
      "url": "/topezadmin/form/page-user-form",
      "area": ["60%", "80%"]
    }
  }],

  "rowButton": [{
    "item_name": "edit",
    "label": "编辑",
    "component": "button-normal",
    "props": {
      "opentype": "MODAL",
      "windowname": "编辑用户",
      "url": "/topezadmin/form/page-user-form?id={{=d.ID}}",
      "area": ["60%", "80%"]
    }
  }, {
    "item_name": "delete",
    "label": "删除",
    "component": "button-normal",
    "props": {
      "opentype": "CONFIRM_AJAX",
      "url": "/topezadmin/form/delete-user-form?id={{=d.ID}}"
    }
  }],

  "express": {
    "main": "return search('SELECT ID, NAME, STATUS FROM users WHERE 1=1')",
    "orderBy": "ORDER BY ID DESC"
  }
}

真实项目中的列表页拆分示意

以仓库管理为例，一个可维护的列表页通常会拆成下面几层：

• warehouse.json：定义搜索、列、按钮、跳转关系。
• warehouse_express_main.ql：只关心查询 SQL 和业务过滤条件。
• 公共字典文件：例如状态、审核状态等用 data/*.json 复用。
• 可选 HTML 片段：当页面需要特殊脚本或补充 DOM 时，再加 appendHead / appendFoot。

真实项目中的表单页拆分示意

以采购单详情为例，一个表单不只是一组输入框，还可能包含多张卡片和多个 iframe 子区域：

• purchase-form.json：定义“基本信息、供应商信息、产品管理、单据记录”等区域。
• purchase-form_initExpress.ql：查询主单数据并回填。
• purchase-form_submitExpress.ql：负责新增或更新。
• purchase-form_appendFoot.html：承载自定义按钮脚本和页面联动。

最小表单配置

{
  "id": "user-form",
  "name": "用户表单",
  "dataSource": "dataSource",

  "cardList": [{
    "type": "card",
    "label": "基本信息",
    "fieldList": [
           {"row": [{
      "item_name": "ID",
      "label": "ID",
      "component": "hidden",
    }, {
      "item_name": "NAME",
      "label": "姓名",
      "component": "input",
      "props": {
        "placeholder": "请输入姓名",
        "lay-verify": "required",
        "validate": {
          "rule": {"required": true, "minlength": 2},
          "message": {
            "required": "姓名不能为空",
            "minlength": "姓名至少2个字符"
          }
        }
      }
    }, {
      "item_name": "STATUS",
      "label": "状态",
      "component": "select",
      "initData": {
        "dataJson": [
          {"label": "启用", "value": "1"},
          {"label": "禁用", "value": "0"}
        ]
      },
      "props": {
        "lay-verify": "required"
      }
    }]
  }]}

                ],

  "initExpress": [
    "return selectOne('SELECT ID, NAME, STATUS FROM users WHERE id=${ID}')"
  ],

  "submitExpress": [
    "if(!isNotBlank('ID')) {",
    "  param = new InsertParam();",
    "  param.table('users');",
    "  param.add('#{NAME}');",
    "  param.add('#{STATUS}');",
    "  param.add('#{CREATE_TIME,value=NOW()}');",
    "  return insertSimple(param);",
    "} else {",
    "  param = new UpdateParam();",
    "  param.table('users');",
    "  param.add('#{NAME}');",
    "  param.add('#{STATUS}');",
    "  param.add('#{UPDATE_TIME,value=NOW()}');",
    "  param.where('ID=#{ID}');",
    "  return updateSimple(param);",
    "}"
  ],

  "deleteExpress": [
    "return update('UPDATE users SET delete_flag=1 WHERE ID=#{ID}')"
  ]
}

七、路由规则

路由的核心规则可以概括为一句话：访问路径决定页面类型，{id} 决定要加载哪份 DSL 配置。实际项目里，通常会结合模块目录做命名，例如 page-warehouse/warehouse、page-purchase/purchase-form。

推荐命名方式

• 列表页：模块目录和页面 ID 尽量同名，例如 list/warehouse/warehouse.json 对应仓库主列表。
• 表单页：编辑页、详情页、步骤页建议通过名称区分，例如 purchase-form、saleorder-step1。
• 表达式文件：直接跟随页面主文件命名，例如 warehouse_express_main.ql、purchase-form_submitExpress.ql。
• 扩展 HTML：优先使用 appendHead / appendFoot 后缀，便于快速识别加载时机。

八、注意事项

• 字段命名规范：item_name 必须大写，且与数据库字段名保持一致
• 数据格式：initData 支持 dataJson（静态）和 dataSql（动态）两种方式
• 模板语法：支持 laytpl 模板语法，如 {{=d.field}}
• 属性兼容：props 支持所有 Layui 原生属性及第三方插件属性
• 表达式引擎：基于 QLExpress，支持 Java 语法和 SQL 拼接
• 多数据源：默认使用配置的 dataSource，可在 initData 中指定其他数据源
• 验证规则：支持 jQuery Validate 的所有验证规则

九、AI开发流程说明