ezadmin

从零开始使用 EzAdmin

2026-07-21 12:52:57 4 0

ezadmin

从零开始使用 EzAdmin：第一个学生管理页面

这篇教程假设你只会一点点 Java，目标是从安装 Java 开始，最后在浏览器看到一个“学生列表”和“学生表单”。EzAdmin 的页面主要用 JSON DSL 描述，因此你不用先学习复杂的前端框架。

本文使用项目当前验证过的版本：Java 17、Spring Boot 3.5.x、Maven、EzAdmin Starter 3.1.2。空 Spring Boot 项目本身不会自动拥有列表数据；还需要数据库表、查询语句和 DSL 配置。

一、先准备工具

1. 安装 JDK 17

打开 Adoptium 或 Oracle 官网，下载 JDK 17。安装后打开终端：

java -version
echo $JAVA_HOME
Windows PowerShell 可用：
java -version
$env:JAVA_HOME

看到版本号以 17 开头就可以。若提示“不是内部或外部命令”，说明 JAVA_HOME 或 PATH 尚未配置；先重启终端，再检查环境变量。

2. 安装 Maven 和开发工具

安装 Maven 3.9 或更高版本，再安装 IntelliJ IDEA Community。验证：

mvn -version

输出中同时出现 Maven 版本和 Java 17，说明工具链准备完成。

二、新建 Spring Boot 项目

打开 start.spring.io，选择 Maven、Java、Spring Boot 3.5.x，填写：

Group：com.example
Artifact：student-demo
Packaging：Jar
Java：17
依赖：Spring Web、Thymeleaf、JDBC API、H2 Database

点击 Generate 下载并解压，用 IDEA 打开项目。先运行一次：

mvn spring-boot:run

看到 Started StudentDemoApplication 才算启动成功。按 Ctrl+C 停止。

三、加入 EzAdmin Starter

打开 pom.xml，在 <dependencies> 内加入：

<dependency>
  <groupId>io.github.ezadmin126</groupId>
  <artifactId>ezadmin-java17-spring-starter</artifactId>
  <version>3.1.2</version>
</dependency>

再打开启动类，增加 EzAdmin 注解：

package com.example.studentdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import top.ezadmin.annotations.EnableEzadmin;

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

如果 IDEA 找不到 EnableEzadmin，先执行 mvn clean package，确认依赖下载成功；不要手动复制 jar。

四、准备学生数据

在 H2 数据库中建立最小表：

CREATE TABLE T_STUDENT (
  ID BIGINT AUTO_INCREMENT PRIMARY KEY,
  STUDENT_NO VARCHAR(32) NOT NULL,
  STUDENT_NAME VARCHAR(64) NOT NULL,
  GENDER INT DEFAULT 0,
  MAJOR VARCHAR(128),
  DELETE_FLAG INT DEFAULT 0
);
INSERT INTO T_STUDENT(STUDENT_NO,STUDENT_NAME,GENDER,MAJOR)
VALUES ('2026001','张小明',1,'计算机科学与技术');

在 application.yml 中配置数据库。下面的地址是本项目示例地址；练习时换成你自己的数据库：

spring:
  datasource:
    url: jdbc:h2:tcp://localhost:9092/test;MODE=MySQL;DATABASE_TO_UPPER=false;CASE_INSENSITIVE_IDENTIFIERS=TRUE;NON_KEYWORDS=VALUE
    username: sa
    password: 
    driver-class-name: org.h2.Driver

真实项目请把密码放在本机环境变量或安全配置中，不要提交到公开代码仓库。

五、写第一个学生列表 DSL

创建文件 src/main/resources/topezadmin/config/layui/dsl/list/student/student-list.json：

{
  "id": "student-list",
  "name": "学生列表",
  "dataSource": "dataSource",
  "search": [{"row": [
    {"item_name":"STUDENT_NAME","label":"姓名","component":"input","operator":"like"},
    {"item_name":"MAJOR","label":"专业","component":"input","operator":"like"}
  ]}],
  "column": [
    {"item_name":"STUDENT_NO","label":"学号","component":"tdText"},
    {"item_name":"STUDENT_NAME","label":"姓名","component":"tdText"},
    {"item_name":"GENDER","label":"性别","component":"tdSelect","initData":{"dataJson":[{"value":1,"label":"男"},{"value":2,"label":"女"}]}},
    {"item_name":"MAJOR","label":"专业","component":"tdText"}
  ],
  "tableButton": [{"item_name":"新增","label":"新增","component":"button-table","props":{"url":"form/page-student/student-form","opentype":"MODAL","windowname":"新增学生"}}],
  "rowButton": [{"item_name":"编辑","label":"编辑","component":"button-normal","props":{"url":"form/page-student/student-form?ID={{= d.ID}}","opentype":"MODAL","windowname":"编辑学生"}}],
  "express": {"main":"@import(student-list.ql)","orderBy":"ORDER BY A.ID DESC","groupBy":""}
}

记住三个规则：search 是搜索栏，column 是表格列，tableButton/rowButton 分别是顶部和行操作。tdSelect 把数据库中的数字映射成人能看懂的文字。

六、为列表提供查询 SQL

在同一目录创建 student-list.ql：

StringBuilder sql = new StringBuilder();
sql.append("SELECT A.ID,A.STUDENT_NO,A.STUDENT_NAME,A.GENDER,A.MAJOR ");
sql.append("FROM T_STUDENT A WHERE A.DELETE_FLAG=0");
return search(sql);

七、写学生表单 DSL

创建 src/main/resources/topezadmin/config/layui/dsl/form/student/student-form.json：

{
  "id":"student-form", "name":"学生表单", "dataSource":"dataSource",
  "cardList":[{"type":"card","label":"基本信息","fieldList":[{"row":[
    {"item_name":"STUDENT_NO","label":"学号","component":"input","props":{"validate":{"rule":{"required":true},"message":{"required":"请输入学号"}}}},
    {"item_name":"STUDENT_NAME","label":"姓名","component":"input","props":{"validate":{"rule":{"required":true},"message":{"required":"请输入姓名"}}}},
    {"item_name":"GENDER","label":"性别","component":"radio","initData":{"dataJson":[{"value":1,"label":"男"},{"value":2,"label":"女"}]}},
    {"item_name":"MAJOR","label":"专业","component":"input"}
  ]}],"buttonList":[]}],
  "buttonList":[],
  "initExpress":"@import(student-form-init.ql)",
  "submitExpress":"@import(student-form-submit.ql)"
}

新增页需要先显示空表单，编辑页需要回显数据，所以把初始化 SQL 和保存逻辑分别放到 QL 文件中。

student-form-init.ql：

StringBuilder sql = new StringBuilder();
sql.append("SELECT ID,STUDENT_NO,STUDENT_NAME,GENDER,MAJOR ");
sql.append("FROM T_STUDENT WHERE ID=${ID} AND DELETE_FLAG=0");
return select(sql).get(0);

student-form-submit.ql：

import top.ezadmin.plugins.express.jdbc.InsertParam;
import top.ezadmin.plugins.express.jdbc.UpdateParam;

if (isBlank("ID")) {
    param = new InsertParam();
    param.table("T_STUDENT");
    param.add("#{STUDENT_NO}");
    param.add("#{STUDENT_NAME}");
    param.add("#{GENDER}");
    param.add("#{MAJOR}");
    param.add("#{DELETE_FLAG,value=0}");
    return insertSimple(param);
}
param = new UpdateParam();
param.table("T_STUDENT");
param.add("#{STUDENT_NO}");
param.add("#{STUDENT_NAME}");
param.add("#{GENDER}");
param.add("#{MAJOR}");
param.where("WHERE ID=#{ID}");
updateSimple(param);
return $("ID");

八、启动并打开页面

在项目根目录执行：

mvn clean spring-boot:run

日志出现 Started StudentDemoApplication 后，在浏览器打开：

http://localhost:8080：应用首页或登录页。
/topezadmin/list/page-student/student-list：学生列表路由（以项目实际路由约定为准）。

九、遇到问题怎么办

端口被占用：在 application.yml 加 server.port: 8081，然后用新端口访问。
找不到组件：确认组件名称拼写，优先参照项目已有 DSL，不要自行发明名称。
列表 500：先把 QL SQL 复制到 H2 控制台执行，确认表名、字段名和数据库连接。
表单能打开但保存失败：检查 submitExpress 是否返回主键，检查必填字段和 SQL 参数。
新增页子列表报 400：iframe 参数必须放在 iframe.params，不要只靠隐藏样式。

十、下一步练习

先给学生表单增加班级下拉，再增加详情页；每次只新增一个字段，保存后立刻在列表和表单各验证一次。等你熟悉 JSON 结构后，再学习上传、级联、弹窗选择和父子 iframe。

用户留言