后端脚手架

脚手架

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

概述

digitalhainan-pom

本文档用于指导在目标项目中完成 digitalhainan-pom 模块集成。
执行顺序：
先完成「1.1.2 快速集成」的全部步骤（必须）
根据业务需求，查阅「功能集成决策索引」选择对应路径，逐项实现
遇到配置问题时参考「1.1.3 配置属性参考」
出现异常时查阅「1.1.6 常见问题」
代码约定： 所有代码示例均包含完整 import 路径和类声明，可直接用于代码生成。

1.1.1 模块简介

digitalhainan-pom 是数字海南框架的父 POM（BOM），统一管理所有框架组件的版本号与第三方依赖版本。它提供以下能力：

统一版本管理：所有 digitalhainan-* 组件版本号集中定义
第三方依赖 BOM：Spring Boot、Dubbo、MyBatis Plus、Redisson 等版本统一管控
Maven 构建插件：jasypt 加密、checkstyle 代码规范、spotless 格式化、git-commit-id 构建信息
Maven 仓库配置：私有 Nexus 仓库（release / snapshot / public）
构建 Profile：szhn-checkstyle（代码规范检查）、szhn-code-format（代码格式化）

Maven 坐标：

xml

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

当前版本： 3.1.0-SNAPSHOT

1.1.2 快速集成

目标： 完成以下 4 个步骤后，项目即具备统一依赖管理能力。

1.1.2.1 在项目 pom.xml 中指定 parent

操作： 在项目根 pom.xml 中将 digitalhainan-pom 设为父 POM：

xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

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

    <groupId>com.example</groupId>
    <artifactId>my-project</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</project>

注意： digitalhainan-pom 的 parent 是 spring-boot-starter-parent:3.5.6，项目会自动继承 Spring Boot 的默认配置。

1.1.2.2 添加 Maven 仓库配置

操作： 在项目 pom.xml 或 settings.xml 中配置私有仓库：

xml

<repositories>
    <repository>
        <id>rdc-releases</id>
        <url>https://nexus.digitalhainan.com.cn/repository/digitalhainan-release/</url>
    </repository>
    <repository>
        <id>rdc-snapshots</id>
        <url>https://nexus.digitalhainan.com.cn/repository/digitalhainan-snapshot/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
    </repository>
</repositories>

1.1.2.3 添加框架组件依赖（无需指定版本）

操作： 在 <dependencies> 中直接引用框架组件，版本号由 parent 自动管理：

xml

<dependencies>
    <!-- 无需指定 <version>，由 digitalhainan-pom 统一管理 -->
    <dependency>
        <groupId>cn.com.digitalhainan</groupId>
        <artifactId>digitalhainan-common</artifactId>
    </dependency>
    <dependency>
        <groupId>cn.com.digitalhainan</groupId>
        <artifactId>cache-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>cn.com.digitalhainan</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

1.1.2.4 验证集成成功

操作： 执行以下命令验证依赖解析：

bash

mvn dependency:tree -Dincludes=cn.com.digitalhainan

检查项	预期结果
`mvn dependency:tree`	所有 `cn.com.digitalhainan:*` 版本均为 `3.1.0-SNAPSHOT`
无版本冲突	不存在同一 groupId 不同版本的依赖
Spring Boot 版本	继承自 parent，为 `3.5.6`

如果依赖解析失败，参考「1.1.6 常见问题 Q1」排查仓库配置问题。

1.1.3 配置属性参考

1.1.3.1 框架组件版本属性

属性名	版本	说明
`digitalhainan.version`	`3.1.0-SNAPSHOT`	框架全局版本
`digitalhainan-config.version`	`3.1.0-SNAPSHOT`	配置中心模块
`digitalhainan-tools.version`	`3.1.0-SNAPSHOT`	工具集模块
`digitalhainan-common-v2.version`	`3.1.0-SNAPSHOT`	通用工具模块
`digitalhainan-log.version`	`3.1.0-SNAPSHOT`	日志模块
`digitalhainan-ms-common.version`	`3.1.0-SNAPSHOT`	微服务公共模块
`digitalhainan-mybatis.version`	`3.1.0-SNAPSHOT`	MyBatis 模块
`digitalhainan-cache.version`	`3.1.0-SNAPSHOT`	缓存模块
`digitalhainan-dubbo.version`	`3.1.0-SNAPSHOT`	Dubbo 模块
`digitalhainan-oss.version`	`3.1.0-SNAPSHOT`	OSS 模块
`digitalhainan-elasticsearch.version`	`3.1.0-SNAPSHOT`	ES 模块
`digitalhainan-security.version`	`3.1.0-SNAPSHOT`	安全认证模块
`digitalhainan-user.version`	`3.1.0-SNAPSHOT`	用户管理模块
`digitalhainan-license.version`	`3.1.0-SNAPSHOT`	许可证模块
`digitalhainan-mq.version`	`3.1.0-SNAPSHOT`	消息队列模块
`ms-devtools-mbg.version`	`3.1.0-SNAPSHOT`	代码生成器
`apione-client-boot.version`	`3.1.0-SNAPSHOT`	API 网关客户端

1.1.3.2 第三方依赖版本属性

属性名	版本	说明
`spring-boot.version`	`3.2.4`	Spring Boot 版本
`java.version`	`21`	JDK 版本
`dubbo.version`	`3.3.5`	Apache Dubbo
`mybatis-plus.version`	`3.5.14`	MyBatis Plus
`mybatis-plus-join.version`	`1.5.4`	MyBatis Plus Join
`dynamic-datasource.version`	`4.3.1`	动态数据源
`druid.version`	`1.2.27`	Druid 连接池
`redisson.version`	`3.52.0`	Redisson
`easy-es.version`	`3.0.0`	EasyES
`pagehelper.version`	`2.1.1`	PageHelper 分页
`guava.version`	`33.5.0-jre`	Google Guava
`hutool.verison`	`5.8.40`	Hutool 工具集
`fastjson.version`	`2.0.57`	Fastjson
`jjwt.version`	`0.13.0`	JJWT
`swagger.version`	`2.2.25`	Swagger v3 注解
`knife4j-openapi3.version`	`4.4.0`	Knife4j OpenAPI3
`mapstruct.version`	`1.6.3`	MapStruct
`hibernate-validator.version`	`8.0.3.Final`	Hibernate Validator
`commons-lang3.version`	`3.19.0`	Commons Lang3
`aliyun-oss.version`	`3.8.0`	阿里云 OSS SDK
`nacos.client.version`	`2.3.2`	Nacos Client
`spring-cloud-alibaba-dependencies.version`	`2025.0.0.0-preview`	Spring Cloud Alibaba
`jasypt-spring-boot.version`	`3.0.5`	Jasypt 加密
`easy-captcha.version`	`2.2.3`	验证码
`bouncycastle.version`	`1.68`	BouncyCastle 加密库
`xxl-job.version`	`2.4.1`	XXL-Job 分布式任务
`kingbase8.version`	`8.6.0`	人大金仓数据库驱动
`dameng8.version`	`8.1.0.157`	达梦数据库驱动
`mysql-connector-j.version`	`8.3.0`	MySQL 驱动

1.1.3.3 构建插件

插件	版本	说明
`jasypt-maven-plugin`	`3.0.5`	配置文件加密解密
`maven-checkstyle-plugin`	`3.6.0`	代码规范检查
`spotless-maven-plugin`	`3.0.0`	代码格式化
`flatten-maven-plugin`	`1.1.0`	CI 友好版本展平
`git-commit-id-maven-plugin`	`8.0.2`	构建时注入 Git 信息

1.1.3.4 Maven Profile

Profile ID	说明	激活方式
`szhn-checkstyle`	启用代码规范检查（checkStyle.xml）	`-P szhn-checkstyle`
`szhn-code-format`	启用代码格式化检查（spotless）	`-P szhn-code-format`

1.1.4 核心功能使用

功能集成决策索引

AI 执行指引： 先完成「1.1.2 快速集成」，然后根据业务需求在下表中找到对应路径，跳转到对应小节实现。

业务需求	集成路径	前置条件
项目继承统一版本管理	4.1	完成第二章
仅导入 BOM 不继承 parent	4.2	完成第二章
配置文件加密（数据库密码等）	4.3	完成第二章
构建时注入 Git 版本信息	4.4	完成第二章
启用代码规范检查	4.5	完成第二章
配置 Maven 私有仓库	4.6	完成第二章

1.1.4.1 作为 Parent POM 使用（推荐）

适用场景： 新项目或整体升级的项目，直接继承 digitalhainan-pom 获取全部版本管理。

xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

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

    <groupId>com.example</groupId>
    <artifactId>my-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <dependencies>
        <!-- 版本由 parent 管理，无需指定 -->
        <dependency>
            <groupId>cn.com.digitalhainan</groupId>
            <artifactId>ms-common</artifactId>
        </dependency>
        <dependency>
            <groupId>cn.com.digitalhainan</groupId>
            <artifactId>cache-spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        </dependency>
    </dependencies>
</project>

继承关系：

spring-boot-starter-parent:3.5.6
  └── digitalhainan-pom:3.1.0-SNAPSHOT
        └── my-service:1.0.0-SNAPSHOT

验证： mvn help:effective-pom 中检查 dependencyManagement 包含所有框架组件版本。

1.1.4.2 仅作为 BOM 导入（dependencyManagement）

适用场景： 项目已有自己的 parent POM，仅需导入版本管理。

xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>com.example</groupId>
        <artifactId>my-parent</artifactId>
        <version>1.0.0</version>
    </parent>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>cn.com.digitalhainan</groupId>
                <artifactId>digitalhainan-pom</artifactId>
                <version>3.1.0-SNAPSHOT</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- 版本由 BOM 管理 -->
        <dependency>
            <groupId>cn.com.digitalhainan</groupId>
            <artifactId>digitalhainan-common</artifactId>
        </dependency>
    </dependencies>
</project>

验证： 依赖解析成功，cn.com.digitalhainan:* 版本为 3.1.0-SNAPSHOT。

1.1.4.3 配置文件加密（Jasypt）

适用场景： 数据库密码、Redis 密码等敏感信息需要加密存储。

Step 1: 配置加密密钥

在 application.yml 或启动参数中指定密钥：

yaml

jasypt:
  encryptor:
    password: your-encryption-key  # 或通过环境变量 -Djasypt.encryptor.password=xxx
    algorithm: PBEWithMD5AndDES

Step 2: 加密敏感值

bash

# 使用 Maven 插件加密
mvn jasypt:encrypt-value -Djasypt.encryptor.password="your-key" -Djasypt.plugin.value="my-password"

Step 3: 在配置文件中使用加密值

yaml

spring:
  datasource:
    password: ENC(加密后的密文)

验证： 应用启动时自动解密 ENC(...) 包裹的值，日志中不出现明文。

1.1.4.4 构建时注入 Git 信息

适用场景： 需要在运行时获取构建时的 Git commit ID、分支名、构建时间。

digitalhainan-pom 已内置 git-commit-id-maven-plugin，构建后自动生成 git.properties。

Step 1: 正常构建

bash

mvn clean package

Step 2: 读取 Git 信息

java

package com.example.service;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

@Service
public class BuildInfoService {

    @Value("${git.commit.id.abbrev:unknown}")
    private String commitId;

    @Value("${git.commit.time:unknown}")
    private String commitTime;

    @Value("${git.branch:unknown}")
    private String branch;

    @Value("${git.build.version:unknown}")
    private String buildVersion;

    public String getBuildInfo() {
        return String.format("版本: %s, 分支: %s, Commit: %s, 构建时间: %s",
            buildVersion, branch, commitId, commitTime);
    }
}

生成的属性列表：

属性	示例值
`git.commit.id.abbrev`	`a1b2c3d`
`git.commit.id.full`	`a1b2c3d4e5f6...`
`git.commit.time`	`2024-01-01 12:00:00`
`git.branch`	`v3.1.0`
`git.build.time`	`2024-01-01 12:05:00`
`git.build.version`	`3.1.0-SNAPSHOT`

验证： 启动后调用 getBuildInfo()，返回正确的 Git 信息。

1.1.4.5 启用代码规范检查

适用场景： CI/CD 流程中强制检查代码风格。

方式一：Checkstyle 检查

bash

# 激活 szhn-checkstyle Profile 执行代码规范检查
mvn validate -P szhn-checkstyle

方式二：Spotless 格式化检查

bash

# 激活 szhn-code-format Profile 执行格式化检查
mvn validate -P szhn-code-format

# 自动修复格式问题
mvn spotless:apply -P szhn-code-format

验证： 不符合规范的代码会导致构建失败（BUILD FAILURE）。

1.1.4.6 配置 Maven 私有仓库

适用场景： 项目需要从数字海南私有 Nexus 拉取框架组件。

在 settings.xml 中配置（推荐）：

xml

<settings>
    <servers>
        <server>
            <id>rdc-releases</id>
            <username>your-username</username>
            <password>your-password</password>
        </server>
        <server>
            <id>rdc-snapshots</id>
            <username>your-username</username>
            <password>your-password</password>
        </server>
    </servers>
    <mirrors>
        <!-- 可选：配置公共仓库镜像加速 -->
    </mirrors>
</settings>

仓库地址：

仓库 ID	类型	URL
`rdc-releases`	Release	`https://nexus.digitalhainan.com.cn/repository/digitalhainan-release/`
`rdc-snapshots`	Snapshot	`https://nexus.digitalhainan.com.cn/repository/digitalhainan-snapshot/`
`central`	Public	`https://nexus.digitalhainan.com.cn/repository/digitalhainan-maven-public/`

验证： mvn dependency:resolve 能成功从私有仓库拉取依赖。

1.1.5 版本变更记录

v3.1.0（当前版本）

[新增] 新增 kingbase8（人大金仓）和 Dm8JdbcDriver18（达梦）数据库驱动
[新增] 新增 mybatis-plus-join-boot-starter 依赖管理
[新增] 新增 spotless-maven-plugin 代码格式化插件
[新增] 新增 szhn-code-format Profile
[变更] Spring Boot 升级至 3.5.6（parent 版本）
[变更] Dubbo 升级至 3.3.5
[变更] MyBatis Plus 升级至 3.5.14
[变更] Redisson 升级至 3.52.0
[变更] Fastjson 升级至 2.0.57
[变更] JJWT 升级至 0.13.0
[变更] Hutool 升级至 5.8.40
[变更] JDK 版本 21

v3.0.0

[破坏性变更] 适配 Spring Boot 3.x + JDK 21
[新增] spring-cloud-alibaba-dependencies 版本管理
[新增] knife4j-openapi3-jakarta-spring-boot-starter 依赖
[变更] mybatis-plus-spring-boot-starter 替换为 mybatis-plus-spring-boot3-starter
[变更] dynamic-datasource-spring-boot-starter 替换为 dynamic-datasource-spring-boot3-starter

v2.1.0

[新增] sch-job-spring-boot-starter 调度任务依赖
[新增] checkstyle 代码规范检查支持
[新增] szhn-checkstyle Profile

v2.0.0

[新增] 统一版本管理（digitalhainan.version 属性）
[新增] Jasypt 配置加密插件
[新增] flatten-maven-plugin CI 友好版本
[新增] git-commit-id-maven-plugin 构建信息注入
[新增] Maven 私有仓库配置

v1.0.0（master）

初始版本
Spring Boot 2.2.4.RELEASE
JDK 1.8
基础依赖版本管理

1.1.6 常见问题

Q1: 依赖解析失败，找不到框架组件

排查步骤：

确认 settings.xml 中配置了私有仓库地址（参考 4.6）
确认仓库 URL 可达（curl https://nexus.digitalhainan.com.cn/repository/digitalhainan-release/）
确认仓库中已发布对应版本的组件
如使用 SNAPSHOT 版本，确认 <snapshots><enabled>true</enabled></snapshots> 已配置

Q2: 版本冲突，项目中出现多个版本的同一依赖

排查步骤：

执行 mvn dependency:tree -Dverbose 查看完整依赖树
确认项目 parent 是 digitalhainan-pom（而非直接继承 spring-boot-starter-parent）
如果项目有自己的 dependencyManagement，确认没有覆盖框架版本

Q3: Jasypt 加密解密失败

排查步骤：

确认启动参数或环境变量中设置了 jasypt.encryptor.password
确认加密值格式为 ENC(密文)，括号不能省略
确认加密和解密使用相同的 algorithm（默认 PBEWithMD5AndDES）

Q4: git.properties 未生成

排查步骤：

确认项目目录是 Git 仓库（.git 目录存在）
确认 flatten-maven-plugin 未覆盖 git-commit-id-maven-plugin 的输出
检查 target/classes/git.properties 是否存在
插件配置了 failOnNoGitDirectory=false，非 Git 环境下不会报错但不会生成文件

Q5: 如何覆盖某个依赖的版本

解决方案：

在项目 pom.xml 的 <properties> 中重新定义属性值：

xml

<properties>
    <!-- 覆盖 parent 中定义的版本 -->
    <redisson.version>3.53.0</redisson.version>
</properties>

注意： 仅在必要时覆盖，可能导致框架组件兼容性问题。

1.1.7 版本兼容性矩阵

digitalhainan-pom	Spring Boot (parent)	JDK	备注
3.1.0-SNAPSHOT	3.5.6	21	当前最新；新增信创数据库驱动
3.0.0 ~ 3.0.1	3.2.4	21	适配 Spring Boot 3.x
2.0 ~ 2.1.0	2.2.4.RELEASE	1.8	功能稳定的 2.x 版本
1.0.0（master）	2.2.4.RELEASE	1.8	初始版本

升级提示： 从 2.x 升级到 3.x 需注意：
JDK 需升级至 21
Spring Boot 需升级至 3.x
javax.* 包需迁移至 jakarta.*
MyBatis Plus starter artifactId 变更（spring-boot-starter → spring-boot3-starter）

digitalhainan-pom ​

1.1.1 模块简介 ​

1.1.2 快速集成 ​

1.1.2.1 在项目 pom.xml 中指定 parent ​

1.1.2.2 添加 Maven 仓库配置 ​

1.1.2.3 添加框架组件依赖（无需指定版本） ​

1.1.2.4 验证集成成功 ​

1.1.3 配置属性参考 ​

1.1.3.1 框架组件版本属性 ​

1.1.3.2 第三方依赖版本属性 ​

1.1.3.3 构建插件 ​

1.1.3.4 Maven Profile ​

1.1.4 核心功能使用 ​

功能集成决策索引 ​

1.1.4.1 作为 Parent POM 使用（推荐） ​

1.1.4.2 仅作为 BOM 导入（dependencyManagement） ​

1.1.4.3 配置文件加密（Jasypt） ​

1.1.4.4 构建时注入 Git 信息 ​

1.1.4.5 启用代码规范检查 ​

1.1.4.6 配置 Maven 私有仓库 ​

1.1.5 版本变更记录 ​

v3.1.0（当前版本） ​

v3.0.0 ​

v2.1.0 ​

v2.0.0 ​

v1.0.0（master） ​

1.1.6 常见问题 ​

Q1: 依赖解析失败，找不到框架组件 ​

Q2: 版本冲突，项目中出现多个版本的同一依赖 ​

Q3: Jasypt 加密解密失败 ​

Q4: git.properties 未生成 ​

Q5: 如何覆盖某个依赖的版本 ​

1.1.7 版本兼容性矩阵 ​

digitalhainan-pom

1.1.1 模块简介

1.1.2 快速集成

1.1.2.1 在项目 pom.xml 中指定 parent

1.1.2.2 添加 Maven 仓库配置

1.1.2.3 添加框架组件依赖（无需指定版本）

1.1.2.4 验证集成成功

1.1.3 配置属性参考

1.1.3.1 框架组件版本属性

1.1.3.2 第三方依赖版本属性

1.1.3.3 构建插件

1.1.3.4 Maven Profile

1.1.4 核心功能使用

功能集成决策索引

1.1.4.1 作为 Parent POM 使用（推荐）

1.1.4.2 仅作为 BOM 导入（dependencyManagement）

1.1.4.3 配置文件加密（Jasypt）

1.1.4.4 构建时注入 Git 信息

1.1.4.5 启用代码规范检查

1.1.4.6 配置 Maven 私有仓库

1.1.5 版本变更记录

v3.1.0（当前版本）

v3.0.0

v2.1.0

v2.0.0

v1.0.0（master）

1.1.6 常见问题

Q1: 依赖解析失败，找不到框架组件

Q2: 版本冲突，项目中出现多个版本的同一依赖

Q3: Jasypt 加密解密失败

Q4: git.properties 未生成

Q5: 如何覆盖某个依赖的版本

1.1.7 版本兼容性矩阵