VJSP-Boot-Form快速开发框架

项目简介

VJSP-Boot-Form是一个基于Spring Boot的后端服务项目，提供表单处理、工作流管理、系统管理等功能。该项目采用现代化的Java技术栈，支持多种数据库，并提供了完善的安全机制和日志记录功能。

内置模块

用户管理：管理系统操作人员，完成用户账号的创建、权限分配和信息维护。
部门管理：配置公司、部门的多级组织架构，以树形结构直观展示，并支持按数据权限进行隔离。
菜单管理：配置系统导航菜单、操作功能权限及按钮级权限标识，实现精细化访问控制。
角色管理：为不同角色分配菜单和操作权限，支持按组织架构划分数据权限范围。
字典管理：维护系统中常用且相对固定的分类、标签等基础数据，提升数据一致性和可维护性。
系统日志：记录和查询系统的正常操作日志与异常信息日志，便于审计与故障排查。

开发说明

运行环境

工具	版本
Java	1.8、17
Maven	3.6.3 +
Redis	5 +
PostgreSQL	12.16
IDE	IDEA、Eclipse 、Visual Studio Code

工程结构

vjsp-boot-form
├── src
│   ├── main
│   │   ├── java
│   │   │   └── net
│   │   │       └── vjsp
│   │   │           ├── VjspApplication.java        # 应用启动入口类
│   │   │           ├── common                      # 通用工具和组件
│   │   │           ├── framework                   # 框架核心组件
│   │   │           ├── log                         # 日志相关功能
│   │   │           ├── modules                     # 业务模块
│   │   │           ├── starter                     # 附件上传下载配置模块
│   │   │           ├── system                      # 系统管理模块
│   │   │           └── workflowprocess             # 工作流处理模块
│   │   └── resources
│   │       ├── application.yml                     # 应用主配置文件
│   │       ├── application-dev.yml                 # 开发环境配置
│   │       ├── template                            # 页面模板文件
│   │       ├── mapper                              # MyBatis映射文件
│   │       ├── static                              # 静态资源
│   │       │   └── vjsphtml                        # 前端页面
│   │       └── vjsp-mapping                        # VJSP映射配置
│   └── test
│       └── java                                    # 测试代码
└── pom.xml                                         # Maven项目配置文件
└── sql                                         # 数据库脚本

结构规范

一级包名路径	说明
common	通用文件包，全局变量，异常类，枚举类，静态工具类等和业务无关的全局文件
framework	系统文件包，权限框架，配置文件，拦截器，依赖注入工具类
system	系统模块，用户，角色，菜单，日志，登录等
modules	业务模块，除系统自带模块外其他功能模块
workflowprocess	工作流模块
resources	配置文件

Maven规范

使用springboot主版本提供依赖的jar包，不需要写版本号，非springboot主版本提供依赖得jar包，版本号声明提取到属性文件中

当前系统中使用到得非springboot主版本提供依赖得jar包如下：

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
        <file.encoding>UTF-8</file.encoding>
        <java.version>8</java.version>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <skipTests>true</skipTests>
        <druid.version>1.1.10</druid.version>
        <hutool.version>5.8.41</hutool.version>
        <jjwt.version>0.11.5</jjwt.version>
        <maven-jar-plugin.version>3.1.1</maven-jar-plugin.version>
        <mybatis-plus.version>3.5.6</mybatis-plus.version>
        <fileupload.version>1.5</fileupload.version>
        <poi.version>3.9</poi.version>
        <zip4j.version>1.3.2</zip4j.version>
        <beanutils.version>1.9.4</beanutils.version>
        <collections4.version>4.4</collections4.version>
        <bcprov.version>1.73</bcprov.version>
        <mail.version>1.6.2</mail.version>
        <xmlbeans.version>3.1.0</xmlbeans.version> 
        <jexl3.version>3.0</jexl3.version> 
        <vjsp-form.version>3.0-RELEASE</vjsp-form.version>
        <fastdfs.version>1.27.2</fastdfs.version>
		    <s3.version>1.11.792</s3.version>
        <mapstruct.version>1.5.1.Final</mapstruct.version>
    </properties>

JAR包清单

名称	版本	用途
javax.servlet-api	未显式指定，由容器提供	Servlet API（provided）
spring-boot	2.7.18	框架主版本
spring-boot-starter-web	同主框架版本	Web容器
spring-boot-starter-test	同主框架版本	测试
spring-boot-configuration-processor	同主框架版本	元数据补全
spring-boot-starter-aop	同主框架版本	拦截器
spring-boot-devtools	同主框架版本	热编译工具
spring-boot-starter-security	同主框架版本	安全认证
spring-boot-starter-data-redis	同主框架版本	数据缓存
spring-boot-starter-validation	同主框架版本	校验框架
lombok	由 Spring Boot 管理，默认兼容	开发工具库
mybatis-plus-boot-starter	3.5.6	持久层框架
mybatis-plus-generator	3.5.6	持久层代码生成
postgresql	由 Spring Boot 管理	数据库驱动（PostgreSQL）
bcprov-jdk15to18	1.73	加密库
jjwt	0.11.5	JWT支持
mapstruct	1.5.1.Final	代码生成工具
mapstruct-processor	1.5.1.Final	代码生成工具（注解处理器）
poi	3.9	Excel 工具（含 poi-ooxml、poi-scratchpad）
commons-beanutils	1.9.4	常用工具类
commons-collections4	4.4	常用工具类
poi-ooxml	4.1.2	excel工具
commons-io	2.19.0	常用工具类
commons-lang3	3.12.0	常用工具类
fastdfs-client	1.27.2	文件存储
aws-java-sdk-s3	1.11.792	文件存储

命名规范

所有对象类名使用大驼峰命名法（PascalCase），不允许使用下划线、小驼峰、缩写等非标准命名。

对象	使用场景	命名规范
Entity	工作流实体对象	以Entity为后缀
Controller	控制器组件，接收和处理HTTP请求，将请求分发给相应的业务逻辑	以Controller为后缀
Service	业务逻辑接口	以Service为后缀
ServiceImpl	业务逻辑实现类，调用 Mapper 并处理事务	以ServiceImpl为后缀
Mapper	持久层,定义数据库操作方法	以Mapper为后缀
Config	系统配置类对象	以Config为后缀
Filter	过滤器对象	以Filter为后缀
Aspect	逻辑切面实现对象	以Aspect为后缀
Properties	属性配置文件	以Properties为后缀
Convert	负责 PO ↔ DTO ↔ VO 之间的转换 (MapStruct实现)	以Convert为后缀
Constants	常量对象	以Constants为后缀
View	用于服务间调用、复杂逻辑封装或跨层数据传输	以View为后缀

请求头格式

身份验证使用JWT实现，已查询用户为例，传递格式：

POST http://127.0.0.1/system/users/listAll
Content-Type: application/json
Authorization: Bearer_<jwt_token>

{
  "loginName": "zhangsan"
}

代码规范

控制层

映射规则全局，每个方法
审计日志
表单校验
返回对象格式
权限控制
文档注解
方法定义
异常处理
访问限流
错误码

业务层

继承关系
IService方法清单
全局通用service添加
业务service添加
事务控制
分页
异常处理
缓存注解

持久层

继承关系
BaseMapper方法清单
全局通用Mapper添加
业务Mapper添加
Mappper中使用自定义SQL
在XML中使用自定义SQL
幂等新增和保存

权限规范

三种使用场景
1. 登录并需要授权
2. 登录不需要授权
3. 不需要登录（链接：白名单的使用说明）
注解格式
资源标识的维护和表对应关系
权限拦截方法的注入
权限拦截的函数

开发规范

隶属于用户个人的页面或者功能必须进行权限控制校验
用户敏感数据禁止直接展示，必须对展示数据进行脱敏
用户请求传入的任何参数必须做有效性验证和长度校验
配置文件中的密码需要加密
上传文件定义大小限制和头部特征码检测

数据库规范

建表规范

表名、字段名必须使用小写字母或数字，禁止出现数字开头。
表名不允许使用复数名词。

业务表必须包含默认字段。

字段名称	数据类型	是否必填	默认值	描述
id	varchar(40)	是		主键
create_user_id	int8	是		创建人ID
create_time	timestamp(6)	是	now()	创建时间
update_user_id	int8	否		修改人ID
update_time	timestamp(6)	否		修改时间
is_delete	int2	是	0	删除标志（0正常 1删除）

在数据库中不能使用物理删除操作，要使用逻辑删除。
业务唯一字段必须创建索引。

系统配置类

XSS过滤器配置(XSSFilterConfig.java)

## 防止XSS攻击
xss:
   # 过滤开关
   enabled: true
   # 排除链接（多个用逗号分隔）
   excludes: /wechat/callback
   # 匹配链接
   urlPatterns: /*

跨域配置(GlobalCorsConfig.java)

使用场景
配置指定域名的跨域

MyBatis配置(MyBatisConfig.java)

设置扫描路径
插件注册

Redis配置(RedisConfig.java)

设置RedisTemplate序列化方式
使用String序列化key，使用JSON序列化value。具体使用方式见。。。Redis工具类

安全配置(SecurityConfig.java)

配置安全过滤器链设置URL访问权限、跨域、CSRF、会话管理等安全策略

依赖注入工具类

Redis操作类

使用场景
方法清单+代码示例

密码工具类

注入位置，有哪些加密方式
方法清单+代码示例

静态方法工具类

Base64工具(Base64.java)

跨平台命令执行工具(CmdUtil.java)

日期工具(DateUtils.java)

邮件工具(EmailUtils.java)

Excel工具(ExcelUtil.java)

网络工具(HttpKeyUtil.java)

Http请求工具(HttpUtil.java)

IP工具(IpUtils.java)

JWT工具(JwtTokenUtil.java)

日志缓存(LogsPool.java)

MD5工具(MD5Util.java)

RSA工具(RsaUtils.java)

Servlet工具(ServletUtils.java)

Spring工具(SpringUtil.java)

SSL工具(SSLClient.java)

字符串工具(StringUtils.java)

3Des加解密工具(TripleDes.java)

文件工具(VjspFiles.java)

ZIP工具(Zips.java)

运行

初始化数据库脚本、修改配置文件

新建数据库
导入 sql/postgresql/vjsp_form.sql 文件：如使用其他数据库，请在相应数据库文件夹中找到初始化脚本，例如 sql/mysql/vjsp_form.sql
修改 application-dev.yml 文件中的数据库连接信息
修改 application-dev.yml 文件中的Redis连接信息
流程配置修改

打开 src\main\resources\application-dev.yml

yml

vjsp:
  run:
    # 流程请求接口密钥，对应 ts_flow_partner 表的 partnerpass 字段
    partnerpass: TaXxYGBj1idmf4oCVUOK75QqWsZD2cEy  
    # 流程接口url
    vjspFlowUrl: http://127.0.0.1:9090/
    # vjsp-mapping 文件夹路径
    resourcesBaseConfig: 
  # 是否开启日志
  audit-log:
    # true 开启 false 关闭
    enabled: true
    # logger 使用日志框架输出
    # db 存储到数据库中
    log-type: db
  # rsa 密码加密
  # 使用 RsaUtils.java 的main方法生成新key

密码等敏感信息加密配置

配置文件中，敏感信息可使用加密方式配置

密钥生成方式：SM4Utils.java 的 generateHexKey() 方法生成密钥，配置到 application-dev.yml 中。敏感信息加密方式： SM4Utils.java 的 encrypt("要加密字符串", "密钥") 方法加密。

properties


# ENC加密配置
jasypt:
  encryptor:
    # SM4密钥（32位十六进制字符串）
    sm4-key: 2fe4a2696b85208e81d30a71c44fb482
    # 加密类
    bean: jasyptStringEncryptor
    
使用 ENC(xxxx) 格式配置密码，例如：

# 数据库密码
db.password=ENC(xxxxx)

只有用ENC(xxxx)格式配置的密码，才会被解密。

启动应用

项目的主启动类是 net.vjsp.VjspApplication，使用标准的Spring Boot启动方式：

java

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

启动应用工作流

应用路径

expansion-pack/vjsp_workflow

配置文件

expansion-pack\vjsp_workflow\config\application.yml

properties

# 数据库地址，与应用平台数据库相同
db.url=jdbc:postgresql://xxx.xxx.xxx.xxx:5432/vjsp_form
# 数据库驱动
db.driverClassName=org.postgresql.Driver
# 数据库用户名
db.username=postgres
# 数据库密码
db.password=

启动

执行 run.bat 或者 run.sh 启动应用

# cmd
run.bat 

# vscode 、idea 、 powershell 
.\run.bat

打开浏览器，输入：http://localhost:8070/index.html

默认账户/密码： admin / 888

VS Code 配置

乱码问题

文件 - 首选项 - 设置勾选： Auto Guess Encoding

部署

打包说明

pom.xml 中配置了jar打包插件，可以排除不需要打包到jar里的文件或目录。例如：

xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <configuration>
      <excludes>
         <!-- 示例：排除特定的配置文件 -->
         <exclude>**/application.yml</exclude>
         <exclude>**/application-dev.yml</exclude>
         <!-- 示例：排除整个目录 -->
         <exclude>**/static/**</exclude>
         <exclude>**/vjsp-mapping/**</exclude>
      </excludes>
 </configuration>
</plugin>

独立jar部署方式

将 application-dev.yml 中的数据库连接信息、Redis连接信息、流程配置等修改为正式环境信息。
删除掉pom.xml中的以下部分，使用mvn install打包，jar包里会包含配置文件，静态资源文件，窗体逻辑文件

xml

<!-- 示例：排除特定的配置文件 -->
<exclude>**/application.yml</exclude>
<exclude>**/application-dev.yml</exclude>
<!-- 示例：排除整个目录 -->
<exclude>**/static/**</exclude>
<exclude>**/vjsp-mapping/**</exclude>

打包后的jar包可以直接运行，例如：

java -jar vjsp-boot-form-1.0.2.jar

静态页面独立部署 + 后端jar包

删除 application-dev.yml 中的 ,不让jar包加载静态文件

yml

  web:
    resources:
      # 前端页面，资源文件 路径
      static-locations: classpath:static/vjsphtml/,file:./static/vjsphtml/,

将 application-dev.yml 中的数据库连接信息、Redis连接信息、流程配置等修改为正式环境信息。
删除掉pom.xml中的以下部分，使用mvn install打包，jar包里会包含配置文件，窗体逻辑文件

xml

<!-- 示例：排除特定的配置文件 -->
<exclude>**/application.yml</exclude>
<exclude>**/application-dev.yml</exclude>
<!-- 示例：排除整个目录 -->
<exclude>**/vjsp-mapping/**</exclude>

仅保留
<exclude>**/static/**</exclude>

使用 nginx 代理静态页面和 jar包的访问地址

修改页面请求的接口地址

修改 static/vjsphtml/_vjsp_setting/setting.js 中的接口地址


var _vjsp_inter_domain = getRootPath() + (_vjsp_is_path != 0 ? getContextPath() : '');

修改成 

var _vjsp_inter_domain = '你自己的地址';

打包后的jar包可以直接运行，例如：

java -jar vjsp-boot-form-1.0.2.jar

配置文件、静态资源、窗体逻辑文件、jar 包分开部署

保留 pom.xml 中的 jar打包插件的配置，mvn install 打包后，jar包里不会包含静态文件、窗体逻辑文件以及配置文件

部署目录结构如下：

yml


├── config
│   ├── application-dev.yml
│   └── application.yml
├── static
│   └── vjsphtml
├── vjsp-boot-form-1.0.2.jar
└── vjsp-mapping

注意事项

如果static/vjsphtml 由 nginx 代理，则需要删除 application-dev.yml 中的静态资源路径 , 以及 setting.js 中的接口地址
如果 vjsp-mapping 与 jar包不是同级目录，需要修改 application-dev.yml 中的窗体逻辑文件路径

yml

    # vjsp-mapping 文件夹路径
    # 修改为vjsp-mapping全路径（不包含 vjsp-mapping 本身）
    resourcesBaseConfig: /opt/app/

VJSP-Boot-Form快速开发框架

项目简介 ​

内置模块 ​

开发说明 ​

运行环境 ​

工程结构 ​

结构规范 ​

Maven规范 ​

JAR包清单 ​

命名规范 ​

请求头格式 ​

代码规范 ​

控制层 ​

业务层 ​

持久层 ​

权限规范 ​

开发规范 ​

数据库规范 ​

建表规范 ​

系统配置类 ​

XSS过滤器配置(XSSFilterConfig.java) ​

跨域配置(GlobalCorsConfig.java) ​

MyBatis配置(MyBatisConfig.java) ​

Redis配置(RedisConfig.java) ​

安全配置(SecurityConfig.java) ​

依赖注入工具类 ​

Redis操作类 ​

密码工具类 ​

静态方法工具类 ​

Base64工具(Base64.java) ​

跨平台命令执行工具(CmdUtil.java) ​

日期工具(DateUtils.java) ​

邮件工具(EmailUtils.java) ​

Excel工具(ExcelUtil.java) ​

网络工具(HttpKeyUtil.java) ​

Http请求工具(HttpUtil.java) ​

IP工具(IpUtils.java) ​

JWT工具(JwtTokenUtil.java) ​

日志缓存(LogsPool.java) ​

MD5工具(MD5Util.java) ​

RSA工具(RsaUtils.java) ​

Servlet工具(ServletUtils.java) ​

Spring工具(SpringUtil.java) ​

SSL工具(SSLClient.java) ​

字符串工具(StringUtils.java) ​

3Des加解密工具(TripleDes.java) ​

文件工具(VjspFiles.java) ​

ZIP工具(Zips.java) ​

运行 ​

初始化数据库脚本、修改配置文件 ​

密码等敏感信息加密配置 ​

启动应用 ​

启动应用工作流 ​

应用路径 ​

配置文件 ​

启动 ​

VS Code 配置 ​

乱码问题 ​

部署 ​

打包说明 ​

独立jar部署方式 ​

静态页面独立部署 + 后端jar包 ​

配置文件、静态资源、窗体逻辑文件、jar 包分开部署 ​

注意事项 ​