Skip to content
返回

后端脚手架

脚手架

DigitalHainan Spring 微服务框架脚手架与集成指南,覆盖 POM、缓存、MyBatis、认证、OSS 等核心模块。

概述
后端脚手架

digitalhainan-ms-devtools-mbg 代码生成器 ​

本文档用于指导在目标项目中完成 digitalhainan-ms-devtools-mbg 模块集成。

执行顺序:

  1. 先完成「14.1.2 快速集成」的全部步骤(必须)
  2. 根据业务需求,查阅「14.1.3 核心模型参考」构造生成参数
  3. 查阅「14.1.4 核心功能使用」完成代码生成调用
  4. 出现异常时查阅「14.1.6 常见问题」

代码约定: 所有代码示例均包含完整 import 路径,可直接复制使用。


14.1.1 模块简介 ​

ms-devtools-mbg 是数字海南框架的 代码生成器组件,基于 Apache Velocity 模板引擎,连接 MySQL 数据库读取表结构信息,自动生成标准分层代码骨架并打包为 ZIP 输出:

  • 数据库元数据读取 — 通过 JDBC 连接数据库,读取 information_schema 获取表/列信息
  • Velocity 模板渲染 — 使用 5 套内置模板生成 Entity / Mapper / Service / ServiceImpl / Mapper.xml
  • 多数据源兼容 — 支持通过 DynamicRoutingDataSource 使用主数据源,或传入自定义连接信息
  • 工厂模式 — DatabasesFactory 根据数据库类型返回对应实现(当前仅支持 MySQL)
  • ZIP 打包输出 — 生成结果自动打包为 ZIP 字节数组或写入指定文件路径

Maven 坐标:

xml
<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>ms-devtools-mbg</artifactId>
</dependency>

前置依赖:

依赖说明
digitalhainan-pom父 POM(管理版本)
mybatis-spring-boot-starterMyBatis 集成
digitalhainan-tools工具集(DateUtils / ApplicationContextUtils)
Apache Velocity 1.7模板引擎
commons-io 2.4IO 工具

当前版本: 3.1.0-SNAPSHOT


14.1.2 快速集成 ​

14.1.2.1 确认父 POM ​

xml
<parent>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>digitalhainan-pom</artifactId>
    <version>3.1.0-SNAPSHOT</version>
</parent>

14.1.2.2 添加依赖 ​

xml
<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>ms-devtools-mbg</artifactId>
</dependency>

14.1.2.3 确认自动配置 ​

MbgAutoConfiguration 自动注册 MysqlDatabases Bean,无需额外配置:

cn.com.digitalhainan.devtools.mbg.conifg.MbgAutoConfiguration

注意: 包名为 conifg(非 config),这是源码中的拼写,引用时需注意。

14.1.2.4 验证集成 ​

在测试类中注入 IDatabases 验证:

java
import cn.com.digitalhainan.devtools.mbg.factory.IDatabases;
import cn.com.digitalhainan.devtools.mbg.factory.MysqlDatabases;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class MbgIntegrationTest {

    @Autowired
    private MysqlDatabases mysqlDatabases;

    @Test
    void contextLoads() {
        assert mysqlDatabases != null;
    }
}

14.1.3 核心模型参考 ​

14.1.3.1 类清单与决策索引 ​

类名包路径职责使用场景
MbgInfocn.com.digitalhainan.devtools.mbg.common代码生成参数构造生成请求
DatabasesInfocn.com.digitalhainan.devtools.mbg.common数据库连接信息指定外部数据源
IDatabasescn.com.digitalhainan.devtools.mbg.factory代码生成接口调用生成方法
AbstractDatabasescn.com.digitalhainan.devtools.mbg.factory抽象基类(核心逻辑)扩展新数据库类型
MysqlDatabasescn.com.digitalhainan.devtools.mbg.factoryMySQL 实现默认实现,直接使用
DatabasesFactorycn.com.digitalhainan.devtools.mbg.factory数据库类型工厂按类型获取实现
MbgContextcn.com.digitalhainan.devtools.mbg.contextBean 获取上下文Spring/非 Spring 环境兼容
DbTypeEnumcn.com.digitalhainan.devtools.mbg.constants数据库类型枚举校验数据库类型
MbgOfBusinessExceptionCodeEnumcn.com.digitalhainan.devtools.mbg.constants异常码枚举异常处理
TableInfocn.com.digitalhainan.devtools.mbg.common表元数据内部使用
ColumnInfocn.com.digitalhainan.devtools.mbg.common列元数据内部使用
ColumnTransformConstantscn.com.digitalhainan.devtools.mbg.common类型映射常量内部使用
MbgAutoConfigurationcn.com.digitalhainan.devtools.mbg.conifg自动配置框架内部

14.1.3.2 MbgInfo — 代码生成参数 ​

java
package cn.com.digitalhainan.devtools.mbg.common;

import lombok.Builder;
import lombok.Data;
import lombok.experimental.Accessors;
import java.io.Serializable;
import java.util.List;

@Data
@Accessors(chain = true)
public class MbgInfo implements Serializable {
    /** 表前缀(生成类名时去除) */
    private String tablePrefix;
    /** 基础包名(如 "cn.com.digitalhainan.project") */
    private String basePackage;
    /** 模块名(如 "system",用于子包路径和 mapper xml 目录) */
    private String model;
    /** 指定生成的表名列表(null 则生成全部表) */
    private List<String> tables;
    /** 作者名(写入生成文件注释) */
    private String author;
}

14.1.3.3 DatabasesInfo — 数据库连接信息 ​

java
package cn.com.digitalhainan.devtools.mbg.common;

import lombok.Builder;
import lombok.Data;
import lombok.experimental.Accessors;
import java.io.Serializable;

@Data
@Accessors(chain = true)
public class DatabasesInfo implements Serializable {
    /** 数据库 JDBC 地址 */
    private String url;
    /** 数据库用户名 */
    private String userName;
    /** 数据库密码(AES 加密) */
    private String password;
    /** 数据库类型(目前仅支持 "mysql") */
    private String dbType;
}

14.1.3.4 IDatabases — 代码生成接口 ​

java
package cn.com.digitalhainan.devtools.mbg.factory;

import cn.com.digitalhainan.devtools.mbg.common.DatabasesInfo;
import cn.com.digitalhainan.devtools.mbg.common.MbgInfo;

public interface IDatabases {
    /** 生成代码并返回 ZIP 字节数组 */
    byte[] generatorCode(MbgInfo gmbVO, DatabasesInfo databasesDO);

    /** 生成代码并写入指定文件路径 */
    void generatorCode(MbgInfo gmbVO, DatabasesInfo databasesDO, String file);

    /** 使用主数据源生成代码并写入文件(需 DynamicRoutingDataSource) */
    void generatorCode(MbgInfo gmbVO, String file);
}

14.1.4 核心功能使用 ​

14.1.4.1 方式一:使用主数据源生成代码(推荐) ​

当项目已配置 DynamicRoutingDataSource(含 master 数据源)时,直接使用主数据源:

java
import cn.com.digitalhainan.devtools.mbg.factory.MysqlDatabases;
import cn.com.digitalhainan.devtools.mbg.common.MbgInfo;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.Arrays;

@Service
public class CodeGeneratorService {

    @Autowired
    private MysqlDatabases mysqlDatabases;

    public void generateCode() {
        MbgInfo mbgInfo = new MbgInfo()
                .setTablePrefix("t_")                          // 表前缀,生成类名时去除
                .setBasePackage("cn.com.digitalhainan.myapp")  // 基础包名
                .setModel("system")                            // 模块名
                .setTables(Arrays.asList("t_sys_user", "t_sys_role")) // 指定表
                .setAuthor("dev-team");

        // 写入文件
        mysqlDatabases.generatorCode(mbgInfo, "D:/output/code.zip");
    }
}

14.1.4.2 方式二:使用自定义数据源生成代码 ​

连接外部数据库生成代码,返回 ZIP 字节数组:

java
import cn.com.digitalhainan.devtools.mbg.factory.MysqlDatabases;
import cn.com.digitalhainan.devtools.mbg.common.MbgInfo;
import cn.com.digitalhainan.devtools.mbg.common.DatabasesInfo;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.Arrays;

@Service
public class ExternalCodeGeneratorService {

    @Autowired
    private MysqlDatabases mysqlDatabases;

    public byte[] generateFromExternalDB() {
        // 1. 构造生成参数
        MbgInfo mbgInfo = new MbgInfo()
                .setTablePrefix("biz_")
                .setBasePackage("cn.com.digitalhainan.newmodule")
                .setModel("order")
                .setTables(Arrays.asList("biz_order", "biz_order_item"))
                .setAuthor("code-gen");

        // 2. 构造数据库连接信息
        DatabasesInfo dbInfo = new DatabasesInfo()
                .setUrl("jdbc:mysql://192.168.1.100:3306/target_db?useSSL=false&characterEncoding=utf8")
                .setUserName("root")
                .setPassword("encrypted_password")
                .setDbType("mysql");

        // 3. 生成代码(返回 ZIP 字节数组)
        return mysqlDatabases.generatorCode(mbgInfo, dbInfo);
    }
}

14.1.4.3 方式三:通过 DatabasesFactory 获取实现 ​

java
import cn.com.digitalhainan.devtools.mbg.factory.DatabasesFactory;
import cn.com.digitalhainan.devtools.mbg.factory.IDatabases;
import cn.com.digitalhainan.devtools.mbg.common.MbgInfo;
import cn.com.digitalhainan.devtools.mbg.common.DatabasesInfo;

// 工厂方式获取(通过 MbgContext 兼容 Spring/非 Spring 环境)
IDatabases databases = DatabasesFactory.getDatabases("mysql");

MbgInfo mbgInfo = new MbgInfo()
        .setTablePrefix("")
        .setBasePackage("cn.com.digitalhainan.demo")
        .setModel("demo")
        .setAuthor("dev");

DatabasesInfo dbInfo = new DatabasesInfo()
        .setUrl("jdbc:mysql://localhost:3306/demo_db")
        .setUserName("root")
        .setPassword("password");

byte[] zipBytes = databases.generatorCode(mbgInfo, dbInfo);

14.1.4.4 生成文件结构 ​

代码生成器按以下目录结构打包 ZIP:

├── main/java/{basePackage}/domain/{model}/model/
│   └── {ClassName}DO.java              ← Entity 实体类
├── main/java/{basePackage}/domain/{model}/mapper/
│   └── {ClassName}Mapper.java          ← Mapper 接口
├── main/java/{basePackage}/business/{model}/manager/
│   └── I{ClassName}Manager.java        ← Manager 接口
├── main/java/{basePackage}/business/{model}/manager/impl/
│   └── {ClassName}ManagerImpl.java     ← Manager 实现类
└── main/resources/mapper/{model}/
    └── {ClassName}Mapper.xml           ← MyBatis XML 映射文件

示例(basePackage=cn.com.digitalhainan.myapp, model=system, table=t_sys_user, tablePrefix=t_):

├── main/java/cn/com/digitalhainan/myapp/domain/system/model/SysUserDO.java
├── main/java/cn/com/digitalhainan/myapp/domain/system/mapper/SysUserMapper.java
├── main/java/cn/com/digitalhainan/myapp/business/system/manager/ISysUserManager.java
├── main/java/cn/com/digitalhainan/myapp/business/system/manager/impl/SysUserManagerImpl.java
└── main/resources/mapper/system/SysUserMapper.xml

14.1.4.5 Velocity 模板变量 ​

模板中可使用的上下文变量:

变量名类型说明
tableNameString原始表名
commentsString表注释
pkColumnInfo主键列信息
classNameString类名(首字母大写,如 SysUser)
classnameString类名(首字母小写,如 sysUser)
pathNameString路径名(全小写,如 sysuser)
columnsList<ColumnInfo>列信息列表(不含基础字段)
hasBigDecimalboolean是否包含 BigDecimal 类型
hasListboolean是否包含 List 类型
packageString基础包名
moduleNameString模块名
authorString作者
datetimeString生成日期

14.1.4.6 MySQL 类型映射 ​

MySQL 类型Java 类型
tinyint / smallint / mediumint / int / integerInteger
bigintInteger
floatFloat
doubleDouble
decimal / numericBigDecimal
bitBoolean
char / varchar / tinytext / text / mediumtext / longtextString
date / datetime / timestampDate
long / int8Long
blob / longblob / clobString

14.1.4.7 自动排除的基础字段 ​

以下字段在生成 Entity 时会被自动跳过:

java
createTime, version, updateTime, creator, updator, disable

14.1.5 扩展新数据库类型 ​

14.1.5.1 新增数据库支持 ​

  1. 在 DbTypeEnum 中添加新枚举值:
java
import cn.com.digitalhainan.devtools.mbg.constants.DbTypeEnum;

// 当前仅支持 mysql,扩展示例:
// postgresql("org.postgresql.Driver")
  1. 创建对应的 AbstractDatabases 子类:
java
import cn.com.digitalhainan.devtools.mbg.factory.AbstractDatabases;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class PostgresqlDatabases extends AbstractDatabases {

    @Override
    public ResultSet getTableResultSet(Statement statement) throws SQLException {
        // 实现 PostgreSQL 查询表信息的 SQL
        return statement.executeQuery(
            "SELECT table_name as \"tableName\", obj_description(relfilenode, 'pg_class') as \"tableComment\" " +
            "FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace " +
            "WHERE c.relkind = 'r' AND n.nspname = 'public'"
        );
    }

    @Override
    public ResultSet getColumnResultSet(Statement statement) throws SQLException {
        // 实现 PostgreSQL 查询列信息的 SQL
        return statement.executeQuery(
            "SELECT column_name, data_type, column_default, is_nullable " +
            "FROM information_schema.columns WHERE table_schema = 'public'"
        );
    }

    @Override
    protected String transformColumnAttrType(String columnType) {
        // 实现 PostgreSQL 类型到 Java 类型的映射
        return columnType;
    }

    @Override
    protected String driverClassName() {
        return "org.postgresql.Driver";
    }
}
  1. 在 DatabasesFactory 的静态块中注册:
java
import cn.com.digitalhainan.devtools.mbg.factory.DatabasesFactory;
import cn.com.digitalhainan.devtools.mbg.factory.IDatabases;

// dataMap.put("postgresql", PostgresqlDatabases.class);

14.1.6 常见问题 ​

FAQ 1:包名拼写错误 conifg ​

MbgAutoConfiguration 位于 cn.com.digitalhainan.devtools.mbg.conifg 包下(非 config),这是源码原始拼写,引用时需注意。

FAQ 2:datasource is null ​

使用 generatorCode(MbgInfo, String) 方法时,需要项目配置了 DynamicRoutingDataSource 且包含 master 数据源。否则请使用 generatorCode(MbgInfo, DatabasesInfo) 传入连接信息。

FAQ 3:仅支持 MySQL ​

DatabasesFactory 目前只注册了 mysql 类型。传入其他类型会抛出 DATABASES_TYPE_ERROR 异常。如需支持其他数据库,参见「14.1.5 扩展新数据库类型」。

FAQ 4:模板渲染异常 ​

模板文件位于 src/main/resources/template/ 下,共 5 个 .vm 文件:

  • Entity.java.vm → {ClassName}DO.java
  • Mapper.java.vm → {ClassName}Mapper.java
  • Mapper.xml.vm → {ClassName}Mapper.xml
  • Service.java.vm → I{ClassName}Manager.java
  • ServiceImpl.java.vm → {ClassName}ManagerImpl.java

如需自定义生成内容,可在 classpath 中覆盖同名模板文件。

FAQ 5:生成结果中缺少字段 ​

检查表字段是否命中了基础字段排除列表(createTime/version/updateTime/creator/updator/disable),这些字段会被自动跳过。


14.1.7 版本变更记录 ​

版本提交变更内容
3.1.0-SNAPSHOTa3c2118Merge branch v3.0.1 into v3.1.0
3.0.1e6baa28init 3.0.1
3.0.07eae825feat: 更改版本号
3.0.0b13f0abv3.0.0 更新
—490c26c更新版本
2.1.0d1dc0c3升级 2.1.0
—3a63193更新版本号
1.0.0799c0ecinit

14.1.8 版本兼容性矩阵 ​

ms-devtools-mbgdigitalhainan-pomJDKSpring Boot备注
3.1.0-SNAPSHOT3.1.0-SNAPSHOT213.x当前版本
3.0.x3.0.x213.xv3.0.0 重构
2.1.02.1.08/112.x旧版本

Power By 数字海南