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

本文档用于指导在目标项目中完成
digitalhainan-ms-devtools-mbg模块集成。执行顺序:
- 先完成「14.1.2 快速集成」的全部步骤(必须)
- 根据业务需求,查阅「14.1.3 核心模型参考」构造生成参数
- 查阅「14.1.4 核心功能使用」完成代码生成调用
- 出现异常时查阅「14.1.6 常见问题」
代码约定: 所有代码示例均包含完整
import路径,可直接复制使用。
ms-devtools-mbg 是数字海南框架的 代码生成器组件,基于 Apache Velocity 模板引擎,连接 MySQL 数据库读取表结构信息,自动生成标准分层代码骨架并打包为 ZIP 输出:
information_schema 获取表/列信息DynamicRoutingDataSource 使用主数据源,或传入自定义连接信息DatabasesFactory 根据数据库类型返回对应实现(当前仅支持 MySQL)Maven 坐标:
<dependency>
<groupId>cn.com.digitalhainan</groupId>
<artifactId>ms-devtools-mbg</artifactId>
</dependency>前置依赖:
| 依赖 | 说明 |
|---|---|
digitalhainan-pom | 父 POM(管理版本) |
mybatis-spring-boot-starter | MyBatis 集成 |
digitalhainan-tools | 工具集(DateUtils / ApplicationContextUtils) |
| Apache Velocity 1.7 | 模板引擎 |
| commons-io 2.4 | IO 工具 |
当前版本: 3.1.0-SNAPSHOT
<parent>
<groupId>cn.com.digitalhainan</groupId>
<artifactId>digitalhainan-pom</artifactId>
<version>3.1.0-SNAPSHOT</version>
</parent><dependency>
<groupId>cn.com.digitalhainan</groupId>
<artifactId>ms-devtools-mbg</artifactId>
</dependency>MbgAutoConfiguration 自动注册 MysqlDatabases Bean,无需额外配置:
cn.com.digitalhainan.devtools.mbg.conifg.MbgAutoConfiguration注意: 包名为
conifg(非config),这是源码中的拼写,引用时需注意。
在测试类中注入 IDatabases 验证:
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;
}
}| 类名 | 包路径 | 职责 | 使用场景 |
|---|---|---|---|
MbgInfo | cn.com.digitalhainan.devtools.mbg.common | 代码生成参数 | 构造生成请求 |
DatabasesInfo | cn.com.digitalhainan.devtools.mbg.common | 数据库连接信息 | 指定外部数据源 |
IDatabases | cn.com.digitalhainan.devtools.mbg.factory | 代码生成接口 | 调用生成方法 |
AbstractDatabases | cn.com.digitalhainan.devtools.mbg.factory | 抽象基类(核心逻辑) | 扩展新数据库类型 |
MysqlDatabases | cn.com.digitalhainan.devtools.mbg.factory | MySQL 实现 | 默认实现,直接使用 |
DatabasesFactory | cn.com.digitalhainan.devtools.mbg.factory | 数据库类型工厂 | 按类型获取实现 |
MbgContext | cn.com.digitalhainan.devtools.mbg.context | Bean 获取上下文 | Spring/非 Spring 环境兼容 |
DbTypeEnum | cn.com.digitalhainan.devtools.mbg.constants | 数据库类型枚举 | 校验数据库类型 |
MbgOfBusinessExceptionCodeEnum | cn.com.digitalhainan.devtools.mbg.constants | 异常码枚举 | 异常处理 |
TableInfo | cn.com.digitalhainan.devtools.mbg.common | 表元数据 | 内部使用 |
ColumnInfo | cn.com.digitalhainan.devtools.mbg.common | 列元数据 | 内部使用 |
ColumnTransformConstants | cn.com.digitalhainan.devtools.mbg.common | 类型映射常量 | 内部使用 |
MbgAutoConfiguration | cn.com.digitalhainan.devtools.mbg.conifg | 自动配置 | 框架内部 |
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;
}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;
}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);
}当项目已配置 DynamicRoutingDataSource(含 master 数据源)时,直接使用主数据源:
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");
}
}连接外部数据库生成代码,返回 ZIP 字节数组:
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);
}
}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);代码生成器按以下目录结构打包 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模板中可使用的上下文变量:
| 变量名 | 类型 | 说明 |
|---|---|---|
tableName | String | 原始表名 |
comments | String | 表注释 |
pk | ColumnInfo | 主键列信息 |
className | String | 类名(首字母大写,如 SysUser) |
classname | String | 类名(首字母小写,如 sysUser) |
pathName | String | 路径名(全小写,如 sysuser) |
columns | List<ColumnInfo> | 列信息列表(不含基础字段) |
hasBigDecimal | boolean | 是否包含 BigDecimal 类型 |
hasList | boolean | 是否包含 List 类型 |
package | String | 基础包名 |
moduleName | String | 模块名 |
author | String | 作者 |
datetime | String | 生成日期 |
| MySQL 类型 | Java 类型 |
|---|---|
| tinyint / smallint / mediumint / int / integer | Integer |
| bigint | Integer |
| float | Float |
| double | Double |
| decimal / numeric | BigDecimal |
| bit | Boolean |
| char / varchar / tinytext / text / mediumtext / longtext | String |
| date / datetime / timestamp | Date |
| long / int8 | Long |
| blob / longblob / clob | String |
以下字段在生成 Entity 时会被自动跳过:
createTime, version, updateTime, creator, updator, disableDbTypeEnum 中添加新枚举值:import cn.com.digitalhainan.devtools.mbg.constants.DbTypeEnum;
// 当前仅支持 mysql,扩展示例:
// postgresql("org.postgresql.Driver")AbstractDatabases 子类: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";
}
}DatabasesFactory 的静态块中注册:import cn.com.digitalhainan.devtools.mbg.factory.DatabasesFactory;
import cn.com.digitalhainan.devtools.mbg.factory.IDatabases;
// dataMap.put("postgresql", PostgresqlDatabases.class);conifg MbgAutoConfiguration 位于 cn.com.digitalhainan.devtools.mbg.conifg 包下(非 config),这是源码原始拼写,引用时需注意。
使用 generatorCode(MbgInfo, String) 方法时,需要项目配置了 DynamicRoutingDataSource 且包含 master 数据源。否则请使用 generatorCode(MbgInfo, DatabasesInfo) 传入连接信息。
DatabasesFactory 目前只注册了 mysql 类型。传入其他类型会抛出 DATABASES_TYPE_ERROR 异常。如需支持其他数据库,参见「14.1.5 扩展新数据库类型」。
模板文件位于 src/main/resources/template/ 下,共 5 个 .vm 文件:
Entity.java.vm → {ClassName}DO.javaMapper.java.vm → {ClassName}Mapper.javaMapper.xml.vm → {ClassName}Mapper.xmlService.java.vm → I{ClassName}Manager.javaServiceImpl.java.vm → {ClassName}ManagerImpl.java如需自定义生成内容,可在 classpath 中覆盖同名模板文件。
检查表字段是否命中了基础字段排除列表(createTime/version/updateTime/creator/updator/disable),这些字段会被自动跳过。
| 版本 | 提交 | 变更内容 |
|---|---|---|
| 3.1.0-SNAPSHOT | a3c2118 | Merge branch v3.0.1 into v3.1.0 |
| 3.0.1 | e6baa28 | init 3.0.1 |
| 3.0.0 | 7eae825 | feat: 更改版本号 |
| 3.0.0 | b13f0ab | v3.0.0 更新 |
| — | 490c26c | 更新版本 |
| 2.1.0 | d1dc0c3 | 升级 2.1.0 |
| — | 3a63193 | 更新版本号 |
| 1.0.0 | 799c0ec | init |
| ms-devtools-mbg | digitalhainan-pom | JDK | Spring Boot | 备注 |
|---|---|---|---|---|
| 3.1.0-SNAPSHOT | 3.1.0-SNAPSHOT | 21 | 3.x | 当前版本 |
| 3.0.x | 3.0.x | 21 | 3.x | v3.0.0 重构 |
| 2.1.0 | 2.1.0 | 8/11 | 2.x | 旧版本 |