企业官网建设流程全解析

1. 先从整体看：代码生成器到底解决什么问题

真正开始把eladmin这种后台管理框架用进日常开发之后，绝大多数人第一个觉得“真香”的功能就是代码生成器。原因很直接：业务系统里最磨人的不是那些复杂算法，而是大量重复的单表CRUD。一张新表建好，光是把Entity、DTO、VO、Controller、Service、ServiceImpl、Mapper接口、Mapper XML这一套后端代码码完，再补一个前端Vue组件和一套API调用脚本，熟练工也得折腾小半天。要是那种几十个字段的表，光是复制粘贴改字段名都能改到眼花。

eladmin的代码生成器就是专门来解决这个问题的。它做的事情一句话就能概括：根据你选中的数据库表结构，自动生成一套可直接运行、基本符合项目分层风格的前后端代码。不管是用户表、订单表、配置表还是业务明细表，只要表结构清晰，生成结果拿下来之后改改业务逻辑就能用。

这篇文章我不想只讲界面上应该点哪几个按钮，那样到处都有教程，没什么意思。我想把这套生成器背后的完整技术链路拆开，讲清楚几个关键问题：它怎么读取数据库表结构、怎么把数据库字段类型换成Java类型、模板引擎在里面到底起了什么作用、为什么生成出来的代码能直接匹配项目架构，以及为什么有时候你会踩到各种莫名其妙的坑。如果你正在用eladmin做后台系统，或者你打算在自己的框架里写一套类似的代码生成能力，又或者你只是好奇“数据库里一张表是怎么变成一整坨Java和Vue代码的”，这篇内容都适合你。

先给个整体图景。eladmin本身就是基于Spring Boot 2.x搭建的权限管理脚手架，前端用了Vue那套体系。代码生成器是它内置的一个功能模块，入口放在了系统管理的菜单栏里。它的工作方式很“笨”，但非常实用：连上数据库，把库里所有表列出来，你选中一张表点导入，它就先把这张表的元数据存进内置的配置表里；然后你配置好包名、模块名、作者、表前缀这些生成参数；最后它借助模板引擎把表结构和这些配置糅在一起，渲染成一个个文本文件，再打包成压缩包供你下载。整个流程走完，可能就是一两分钟的事情。

对比看下来，它的设计思路其实是当前主流的“模板渲染”派，不是“代码拼接”派。代码拼接就是用一个超长的Java方法不断拼字符串，写起来快，但改起来非常痛苦。模板渲染则是把代码骨架写成一堆后缀为ftl的模板文件，里面埋上占位符和循环、判断指令，运行时把表数据填进去。这样做的好处是生成逻辑和代码模板彻底分离，想调整输出风格，改模板文件就行，不需要动Java代码，可维护性完全不一样。

2. 核心原理拆解：从表结构到Java代码的完整链路

代码生成器看起来像是个黑盒，实际上链路特别清晰，无非四步：读表结构、转类型、装配数据模型、模板渲染输出。下面我按顺序拆开讲。

2.1 第一步：数据库表元数据读取

这一步是整个生成器的数据源头，也是我建议所有想自己写生成器的人最先研究的部分。所谓表元数据，就是数据库自己记录的关于表结构的信息：表名、表注释、字段名、字段类型、字段长度、精度、是否主键、是否自增、是否允许为空、默认值、字段注释等。Java这边不需要你去连数据库写各种information_schema的SQL，JDBC早就把这些能力封装好了，就是java.sql.DatabaseMetaData。

当你在eladmin的代码生成页面上点击“导入表”的时候，后端做的事情其实就是先拿到数据库连接，然后调用几个关键方法。简化出来的逻辑大概是这样的：

DatabaseMetaData metaData = connection.getMetaData(); // 获取所有用户表，注意最后一个参数限定只取表，不取视图 ResultSet tables = metaData.getTables(catalog, schema, "%", new String[]{"TABLE"}); while (tables.next()) { String tableName = tables.getString("TABLE_NAME"); String tableRemark = tables.getString("REMARKS"); System.out.println("发现表: " + tableName + " - " + tableRemark); } // 获取某张表的所有字段信息 ResultSet columns = metaData.getColumns(catalog, schema, "sys_user", "%"); while (columns.next()) { String columnName = columns.getString("COLUMN_NAME"); String columnType = columns.getString("TYPE_NAME"); int size = columns.getInt("COLUMN_SIZE"); String remark = columns.getString("REMARKS"); } // 获取表主键 ResultSet primaryKeys = metaData.getPrimaryKeys(catalog, schema, "sys_user"); while (primaryKeys.next()) { String pkColumnName = primaryKeys.getString("COLUMN_NAME"); }

eladmin的实际源码里针对这些信息封装了自己的元数据对象，比如ColumnInfo、TableInfo，构造函数直接接收ResultSet，把JDBC返回的值一条条抠出来。这一步做完，表结构就在内存里了，后续所有处理都基于这些对象展开。

这里有两个容易被忽略的细节。第一是为什么只取TABLE类型而不取视图。生成器的目标是生成可增删改查的CRUD代码，视图本身没有主键概念，也不适合直接生成可写接口，所以直接过滤掉是合理设计。第二是表名大小写问题，如果你的数据库表名带特殊前缀或者有大写字母，getTables查询时传入的表名模式要用对，否则会返回空结果。很多人第一次导入表时列表是空的，十有八九就卡在这里。

2.2 第二步：数据库类型到Java类型的映射

元数据读到了，但数据库里的字段类型不能直接用，比如MySQL里的bigint不能生成Java的int，不然自增主键涨到21亿后面就溢出了；datetime也不建议统统映射成java.util.Date，现在的项目更倾向于使用LocalDateTime，免去时区换算和格式化的一堆麻烦。

所以每个成熟的生成器内部都维护着一张类型映射表。eladmin这边，据我对这个框架源码的理解，大体规则是：数字类型里bit映射成Boolean，tinyint和int映射成Integer，bigint映射成Long；字符串类型里char、varchar、text这一类都映射成String；金额和精确计算场景的decimal、numeric映射成BigDecimal；时间类型里date映射成LocalDate，datetime和timestamp映射成LocalDateTime。

这套映射在我眼里是生成代码质量的第一个分水岭。表格对照会更清楚：

举一个实际的例子。业务表里有个金额字段，如果建表时用了double，生成器映射出来的就是Double，这在金额累加和比较时很容易出现精度问题。我自己的习惯是，建表时只要语义上是金额，一律用decimal(10,2)，这样生成出来就是BigDecimal，省得生成之后再手工改实体类，还得把相关的运算逻辑一并改掉。

再提醒一个细节：text类型的字段虽然映射成String没问题，但text在MySQL里既不能设置默认值，也不适合加普通索引，还无法直接参与某些查询条件。生成器生成Mapper XML的时候，如果对所有字符串字段都套like查询，遇到大文本字段性能会很难看。所以生成之后我一般会检查一下，把text字段从模糊查询列表里去掉。

2.3 第三步：模板数据装配和FreeMarker渲染

类型映射完成之后，所有字段信息都变成了一堆Java对象，接下来就是模板引擎的活。eladmin用的是FreeMarker，模板文件后缀是ftl。为什么选FreeMarker而不是自己拼字符串？核心原因在于FreeMarker天然适合生成各种文本文件，不管是Java源码、XML配置还是Vue组件，本质上都是文本渲染。而且FreeMarker语法简单，支持<#list>循环、<#if>判断、变量插值，还能直接调用数据模型里对象的getter方法，表达力足够。

FreeMarker的渲染过程不复杂。先用Configuration对象加载模板目录，目录指向classpath下存放ftl文件的文件夹；然后把表信息、列信息、包名、模块名、作者、去除前缀等参数封装成一个Map或对象作为数据模型；最后调用Template.process(dataModel, writer)，把渲染结果写进字符串或者直接写成文件。eladmin在生成代码时，把这些渲染结果收集起来，打包成压缩包，再通过接口返回给前端下载。

举一个最简单也最直观的模板例子，就是实体类模板的核心片段：

package ${packageName}.${moduleName}.entity; import javax.persistence.*; import java.math.BigDecimal; import java.time.LocalDateTime; public class ${className} { <#list columns as column> /** ${column.remark} */ private ${column.javaType} ${column.changeColumnName}; </#list> }

看到这个大家应该一下就明白了。${}是FreeMarker的插值表达式，<#list columns as column>是遍历列信息集合。表结构不同，columns里装的内容就不同，但模板永远不用变。这张表有8个字段就输出8个私有属性，有30个字段就输出30个，完全自动化。

模板引擎真正厉害的地方就在这里：生成逻辑和代码模板分离。你想让实体类字段上加个Swagger注解，改一行模板；你想把包名结构调整一下，改一下模板里的变量引用；你不想生成某个字段的Getter，那就加个<#if>判断。所有的改动都不需要动Java代码，改完模板重新生成一次就行。

2.4 模板设计的关键点

eladmin的模板并不像上面那段示例这么简单，它是把整个项目分层风格都固化进去了。后端不是只生成一个Controller加一个Mapper就完事，而是拆成Entity、DTO、VO、Controller、Service、ServiceImpl、Mapper接口、Mapper XML这套完整的分层结构。前端也不是只给你一个表单页面，而是同时生成Vue组件、API调用JS文件、甚至路由需要的相关配置。

为什么要拆得这么细？如果生成器只生成“一个Controller里堆查询逻辑、一个Mapper里堆SQL”那种代码，拿下来其实没法用，因为项目本身是分层的，强行塞进去反而要重构一遍。eladmin生成器的定位就是“生成的代码要符合项目现有架构”，所以它的模板严格贴着项目规范来做，生成结果基本可以直接编译、直接启动。

模板里还大量使用了条件判断来处理边界情况。主键字段要加@Id和@GeneratedValue注解，普通字段不加；自增字段在插入SQL里不能出现，否则会报主键冲突；逻辑删除字段如果要特殊处理，模板里也会提前判断；时间字段可能需要加@JsonFormat注解，金额字段可能需要加精度控制。这些逻辑如果在生成之后手工去改，几十个表能改吐，而模板里一个<#if>就解决了。

很多人第一次打开ftl文件会觉得头大，因为里面全是<#if>、<#list>嵌套。但其实只要理解了数据模型的结构，比如columns是什么、每个column有哪些属性、primaryKey怎么取，模板里的每一行就都看得懂了。我可以给个建议：读模板的时候不要从头到尾一行行读，先看数据模型有哪些字段，再带着字段去看模板，效率会高很多。

3. 实操环节：我自己怎么用这套生成器

原理讲完就该讲落地。我自己的经验是，代码生成器用得好不好，其实不取决于你对框架多熟悉，而取决于你建表时有没有规矩。所以这一段我会从表设计开始讲，一直讲到生成后的二次修改，把完整的操作思路串起来。

3.1 表设计阶段的准备工作

这个真的值得单独拿出来说。生成器的数据源是表结构，表结构烂，生成代码烂，后面修改的时间可能比手写还长。我总结过三条硬性规范，基本能保证生成结果处于高质量水平：

第一条，每张表必须有主键，而且最好是一个单列自增主键，类型用bigint。联合主键在生成器里能够解析出来，但生成的代码里主键字段会有多个，@Id注解会用@IdClass的方式处理，这对普通业务场景完全是给自己找麻烦。自增主键的意义在于，生成器能自动识别并帮你处理好插入时不带主键、更新时按主键定位这些逻辑，少改很多代码。

第二条，每个字段都要写注释。这不是为了给DBA看，而是因为生成器会把数据库注释直接抠出来当生成代码的注释。你建表时给字段写了注释，生成的实体类属性上就自动有/** 用户姓名 */这样的注释，前端表格的列名、表单的label也会自动使用这些注释。不写注释的话，生成出来的页面全是空白列标题，你还要一个个补。

第三条，字段命名统一用下划线风格。比如user_name、create_time，这样生成器在转驼峰命名的时候非常干净，转出来就是userName、createTime。如果建表时一会儿用驼峰一会儿用下划线，生成的代码命名会非常混乱，你还要手动去对齐。

第四条是我个人补充的，表名尽量加一个统一前缀。比如sys_user、sys_role、sys_menu，前缀在生成配置里设置好之后，会在生成类名时自动去掉，于是sys_user生成的类名是User，而不是SysUser。有没有前缀都能生成，但有前缀的话，类名更干净，Controller路径也更好看，所以我习惯所有业务表都带模块前缀。

3.2 在eladmin里导入并配置生成

表结构准备好之后，剩下的操作就非常顺了。进入“系统管理-代码生成”菜单，点导入表，界面上会列出数据库里当前用户能看到的表，勾选你要的那张表点确定，导入就完成了。这一步背后就是我们前面讲的元数据读取和存储流程，导入成功的表会在生成列表里出现。

紧接着需要编辑生成配置。几个关键项我逐个说：

包名，生成出来的类所在的包头，比如com.company.admin。这决定了整个后端代码的归属。

模块名，这个字段非常关键，它决定生成类的子包目录，比如system、business。如果你把模块名填成system，生成的Controller就在controller/system下，路径就是/system/user这种风格。填错的话，路径风格会乱，后面前端API也要跟着改。

前端路径，生成Vue页面的目标目录。我建议严格按照eladmin项目自己的约定来，页面放在src/views对应模块下，API的JS文件放在src/api对应模块下。这样生成后只要解压到对应目录就能运行，不需要额外改引用关系。

作者，生成类头注释上的作者名，填自己的名字或者团队名都行，这纯粹是信息记录，不影响功能。

去除表前缀，如果有统一前缀就在这儿填，比如填sys_，那么sys_user表生成的类名是User，生成的Controller路径也不会带上sys。

这些配置会被后台存进gen_config表里，跟表结构信息关联在一起。下次再生成这张表，配置自动带出来，不用重复填写。所以第一次配置时稍微认真一点，后面每个表生成都省事。

3.3 生成后的代码结构与二次修改

配置好之后，点预览可以在线看每一类代码的生成结果，点下载则会把所有生成文件打包成zip压缩包，解压后按目录结构放到项目里即可。

我每次拿到生成结果后都会做三件事。第一件是快速扫一遍实体类，重点看主键注解和字段类型有没有问题。因为生成器按元数据类型映射，理论上很稳妥，但如果你建表时用了timestamp类型的字段做逻辑删除标记等特殊用途，生成后可能要微调注解。

第二件是检查Mapper XML里的查询条件。生成器默认会按字段类型生成一套查询条件，字符串字段一般会生成like，时间字段会生成范围查询，整型字段会生成等值查询。但业务上真正需要按哪些字段查询，生成器没法替你决定，所以这个文件是生成后改动最多的一个。

第三件是打开前端Vue组件，看一下表格列、表单字段、编辑弹窗是不是符合页面语义。尤其是有字典需求的字段，比如状态字段、类型字段，生成器只能生成普通文本输入框，需要你自己在Vue组件里补上el-select和字典翻译绑定。

这里必须明确一点：生成器产出的是“高质量初稿”，不是“可直接上线的终稿”。你把它的产物当作一个脚手架，在这个基础上继续改业务逻辑，效率远高于从零手写；但如果你指望生成完一行不改直接交给测试，那基本不可能。对生成结果的定位想清楚之后，你对这套工具的心态和使用方式都会顺畅很多。

4. 排查记录：生成器用多了必然踩的坑

这部分内容全部来自我自己实际用下来的血泪经验。生成器这个东西，用的时候看起来很爽，但出问题的时候排查起来也不少花时间。我把那些高频的问题和对应思路整理出来，基本可以当速查表用。

4.1 导入表失败或看不到表

这是我见过最多的一个问题，甚至不少同学在环境搭建阶段就卡住。常见原因有三个：数据库连接账号权限不够、连接配置里的database和实际库名不一致、表类型限定导致视图表出不来。

排查思路很直接。先用Navicat或命令行工具，用系统里配置的同一套账号密码去连数据库，执行show tables，看能不能看到目标表。看不到就说明是账号权限问题，去把相应库表的select权限补上。看到表但eladmin列表里没有，那就检查连接串里的database配置是否准确，以及应用的数据库连接是否指向了你预期的实例。

我额外提醒一种场景：如果你用的是云数据库RDS，部分云厂商会严格要求账号SELECT权限精确到库表，而且连接串里的库名大小写敏感。之前我遇到过一个问题，表都在，就是列表为空，最后发现是连接串里库名的字母大小写和服务端实际库名不一致导致的，改过来立竿见影。

4.2 主键解析失败导致一系列问题

主键导入失败的典型表现是：生成出来的实体类没有@Id注解，或者ServiceImpl里findById、deleteById这类方法生成不出来，前端删除按钮点击之后直接报错。根本原因是元数据里主键信息没有正确读到。

我遇到过的具体原因有几类。第一，建表时只建了唯一索引没建主键，这种情况数据库层面就没有主键可言；第二，复合主键导致解析逻辑识别异常；第三，主键字段名在框架的约定里不被识别，比如主键叫uuid或code而不是id，虽然能读出来但生成的代码风格会偏。

我的建议前面也说过，建表阶段就用单列自增bigint主键，字段名就叫id，这是最稳妥的姿势。如果是历史遗留表，没有单列主键，那就别指望导入后自动完美生成，需要在生成前先把主键逻辑处理好，或者干脆手动建一个自增id字段，虽然多一步操作，但后续代码改起来会省心很多。

4.3 时间类型映射导致的序列化问题

MySQL的datetime生成LocalDateTime，在JSON序列化时如果项目里配置了全局日期格式，会有两种典型表现。第一种是没有配置JavaTimeModule，LocalDateTime直接序列化成一串数组或者时间戳；第二种是格式不符合预期，比如接口返回2024-03-01T12:00:00这种ISO格式，前端显示很丑。

排查方法不难。先确认项目里是否自定义了Jackson的ObjectMapper，如果自定义了，看有没有注册JavaTimeModule，再看全局日期格式配置是否统一成yyyy-MM-dd HH:mm:ss。eladmin默认的配置一般没问题，但如果你是在别的项目基础上改造的，或者自己加过全局序列化配置，很容易在时间格式上出分歧。

这个问题的正确解决姿势是在全局配置层搞定，而不是生成代码后一个个去实体类加@JsonFormat，否则每个表生成完都要手动改一遍，那就失去了生成器的意义。

4.4 生成的代码编译不过或路径对不上

生成的代码拿下来编译报错，通常集中在两类。一类是Vue前端组件引用了eladmin自己的自定义组件或者全局混入方法，但你当前环境的依赖没装全或者组件名对不上。另一类是后端ModelMapper字段映射找不到对应属性，日志里直接抛ModelMapperException。

排查思路要先看控制台。如果后端编译失败，先检查生成的实体类字段和数据库列是否一一对应，再检查Controller路径和Mapper XML里的SQL id是否匹配。前端编译失败，先确认JS API文件里的URL路径和Controller的@RequestMapping路径是否一致，这个不一致经常在生成配置里模块名填错的时候出现。

通常我修复完生成代码的编译问题之后，会反向去检查自己的配置项有没有填错，而不是怪生成器。说白了，生成器只是照章办事的翻译工具，配置输入的变量错了，输出自然就错了。

4.5 修改模板后预览报FreeMarker错误

如果你动手改过ftl模板，那预览时看到FreeMarker的报错信息是很常见的事。FreeMarker的报错提示其实很友好，会直接指出模板文件名、行号，以及出错的原因，比如变量不存在、循环变量拼写错误、标签未闭合等。

我自己改模板后的经验是，模板里尽量只做简单的循环和条件判断，别把复杂逻辑往模板里塞。比如生成注释时需要根据字段类型做大量分支处理，这种逻辑正确的做法是在Java代码里把结果拼好，模板里只引用变量就行。把逻辑放在代码层、展示放在模板层，这套分工清楚之后，模板基本不会出什么错，即便出错也特别好定位。

5. 经验体会：生成器的边界与正确用法

聊到这儿，原理、实操、排坑都讲完了，最后想说说我对生成器使用边界和正确姿势的理解。这部分没有标准答案，但都是我经历过、思考过之后的真实心得。

5.1 生成器适合什么场景，不适合什么场景

从我的经验来说，eladmin代码生成器最适合的场景是后台管理系统里大量的基础数据维护模块。典型的就是用户管理、部门管理、字典管理、商品管理、订单管理里那些核心数据的增删改查。这类业务的特点是：表结构清晰、字段数量适中、操作模式高度一致，无非就是列表、搜索、新增、编辑、删除这几个动作，加上一些状态流转和字典翻译。这种高度重复的代码，手动写一遍两遍还行，写二十遍三十遍就纯粹是浪费时间。

不适合的场景也很明确。复杂报表统计、跨多张表join出聚合结果、流程引擎相关的数据模型、多租户数据隔离逻辑、以及那种一张表需要同时对接好几个外部系统的接口，这类情况生成器生成的初稿几乎派不上用场，生成了也要大改特改，不如直接手写。

我自己的判断标准是：打开这张表的字段列表，如果字段基本都能直接映射成表单输入框，而且列表页的查询条件不超过五六个字段，那这表就适合用生成器；如果字段里大量是计算字段、关联字段、冗余字段，那基本不用抱太大期望。

5.2 我个人的一套使用习惯

说到底，生成器的质量上限是由你输入的表结构决定的。我现在建表之前会花时间想清楚三件事：主键方案是什么、每个字段注释写什么、字段类型选什么最合理。这些前置工作到位之后，生成器输出质量极高，后续我甚至只需要在新生成的Service里加一两个自定义查询方法就行。所以我常说一句话：表结构规范了，代码生成器就是个优秀的助攻手；表结构乱来，代码生成器只会把混乱放大。

另一个使用习惯是，把默认配置一次性配好。第一次登录eladmin之后，我会先把代码生成的包名、模块名、作者、前端路径这些全局配置填好。因为这些都是存在配置表里的，后续每张表生成都自动带出来，不会因为个人习惯不一致导致每个新表生成出来的代码风格都不一样。

还有一个很实用的技巧。如果你发现生成结果里总有固定要改的地方，比如每个实体类你都要手补一个缓存注解，每个Controller你都要加一个操作日志埋点，那你完全可以直接改模板文件，把这些固定内容变成生成逻辑的一部分。我自己在团队内部就是这么干的：把模板定好之后，维护模板比手动改每个生成结果要省力得多。这种把“事后修饰”变成“事前设置”的思路，才是最省力的正确姿势。