vjsp-boot-form Rapid Development Framework

Project Introduction

vjsp-boot-form is a backend service project based on Spring Boot, providing form processing, workflow management, and system administration functionalities. This project adopts a modern Java technology stack, supports multiple databases, and offers robust security mechanisms and logging capabilities.

Built-in Modules

1. User Management: Manages system operators, enabling the creation of user accounts, allocation of permissions, and maintenance of user information.

2. Department Management: Configures multi-level organizational structures for companies and departments, displaying them in a tree-like structure with support for data permission isolation.

3. Menu Management: Configures system navigation menus, operation function permissions, and button-level permission identifiers, achieving fine-grained access control.

4. Role Management: Assigns menu and operation permissions to different roles, supporting data permission scope division by organizational structure.

5. Dictionary Management: Maintains common and relatively fixed classification and label data within the system, enhancing data consistency and maintainability.

6. System Logs: Records and queries system operational logs and exception logs, facilitating auditing and fault troubleshooting.

Development Instructions

Runtime Environment

Tool	Version
Java	8
Maven	3.6.3 +
Redis	5 +
PostgreSQL	12.16
IDE	IDEA、Eclipse 、Visual Studio Code等

Project Structure

vjsp-boot-form
├── src
│   ├── main
│   │   ├── java
│   │   │   └── net
│   │   │       └── vjsp
│   │   │           ├── VjspApplication.java        # Application startup entry class
│   │   │           ├── common                      # Common tools and components
│   │   │           ├── framework                   # Framework core components
│   │   │           ├── log                         # Log-related functions
│   │   │           ├── modules                     # Business modules
│   │   │           ├── starter                     # Attachment upload and download configuration module
│   │   │           ├── system                      # System management module
│   │   │           └── workflowprocess             # Workflow processing module
│   │   └── resources
│   │       ├── application.yml                     # Main application configuration file
│   │       ├── application-dev.yml                 # Development environment configuration
│   │       ├── template                            # Page template files
│   │       ├── mapper                              # MyBatis mapping files
│   │       ├── static                              # Static resources
│   │       │   └── vjsphtml                        # Front-end pages
│   │       └── vjsp-mapping                        # VJSP mapping configurations
│   └── test
│       └── java                                    # Test code
└── pom.xml                                         # Maven project configuration file
└── sql                                             # Database scripts

Structure Standards

First-Level Package Path	Description
common	General file package, including global variables, exception classes, enumeration classes, and static utility classes unrelated to business
framework	System file package, including permission framework, configuration files, interceptors, and dependency injection utilities
system	System module, including users, roles, menus, logs, login, etc.
modules	Business modules, all functional modules besides system-provided ones
workflowprocess	Workflow module
resources	Configuration files

Maven Specification

Use the main version of Spring Boot to provide dependency jar packages, no need to write version numbers. For third-party jar packages not provided by the main version of Spring Boot, version numbers should be declared in the properties file.

The following non-Spring Boot main version dependency jar packages used in the current system are as follows:

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
    <skipTests>true</skipTests>
    <druid.version>1.1.10</druid.version>
    <hutool.version>4.5.7</hutool.version>
    <jjwt.version>0.9.0</jjwt.version>
    <maven-jar-plugin.version>3.1.1</maven-jar-plugin.version>
    <mybatis-plus.version>3.3.2</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> 
    <jsqlparser.version>1.4</jsqlparser.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 Package Inventory

Name	Version	Purpose
javax.servlet-api	Not explicitly specified, provided by container	Servlet API (provided)
spring-boot	2.7.18	Core framework version
spring-boot-starter-web	Same as main version	Web container
spring-boot-starter-test	Same as main version	Testing
spring-boot-configuration-processor	Same as main version	Metadata completion
spring-boot-starter-aop	Same as main version	Interceptors
spring-boot-devtools	Same as main version	Hot recompilation tool
spring-boot-starter-security	Same as main version	Authentication and authorization
spring-boot-starter-data-redis	Same as main version	Data caching
spring-boot-starter-validation	Same as main version	Validation framework
lombok	Managed by Spring Boot, defaults to compatible	Development utility library
mybatis-plus-boot-starter	3.3.2	Persistence framework
mybatis-plus-generator	3.3.2	Persistence layer code generator
postgresql	Managed by Spring Boot	PostgreSQL database driver
bcprov-jdk15to18	1.73	Encryption library
jjwt	0.9.0	JWT support
mapstruct	1.5.1.Final	Code generation utility
mapstruct-processor	1.5.1.Final	Code generation utility (annotation processor)
poi	3.9	Excel utility (includes poi-ooxml, poi-scratchpad)
commons-beanutils	1.9.4	General utility classes
commons-collections4	4.4	General utility classes
poi-ooxml	4.1.2	Excel-related tools
commons-io	2.19.0	General utility classes
commons-lang3	3.12.0	General utility classes
fastdfs-client	1.27.2	File storage
aws-java-sdk-s3	1.11.792	File storage

Naming Conventions

All object class names use the PascalCase (UpperCamelCase) naming convention, without underscores, camel case, abbreviations, or other non-standard naming patterns.

Object	Usage	Naming Convention
Entity	Workflow entity object	Append Entity suffix
Controller	Controller component, receives and handles HTTP requests, dispatching to corresponding business logic	Append Controller suffix
Service	Business logic interfaces	Append Service suffix
ServiceImpl	Business logic implementation class, calls Mapper and handles transactions	Append ServiceImpl suffix
Mapper	Persistence layer, defines database operation methods	Append Mapper suffix
Config	System configuration classes	Append Config suffix
Filter	Filter objects	Append Filter suffix
Aspect	Logic aspect implementation objects	Append Aspect suffix
Properties	Property configuration files	Append Properties suffix
Convert	Responsible for conversion between PO ↔ DTO ↔ VO (implemented via MapStruct)	Append Convert suffix
Constants	Constant objects	Append Constants suffix
View	Designed for inter-service calls, encapsulation of complex logic, or cross-layer data transmission	Append View suffix

Request Header Format

Authentication uses JWT implementation. As an example with retrieved user information, the header format is:

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

{
  "loginName": "zhangsan"
}

Code Specification

Controller Layer

1. Mapping rules, per method
2. Audit logging
3. Form validation
4. Return object format
5. Permission control
6. Documentation annotation
7. Method definition
8. Exception handling
9. Access rate limiting
10. Error code specification

Service Layer

1. Inheritance relationships
2. IService method list
3. Global common service addition
4. Business service addition
5. Transaction control
6. Pagination
7. Exception handling
8. Cache annotations

Persistence Layer

1. Inheritance relationships
2. BaseMapper method list
3. Global common Mapper additions
4. Business Mapper additions
5. Use of custom SQL in Mapper
6. Custom SQL in XML
7. Idempotent insert and save operations

Authorization Specification

1. Three usage scenarios:
   1. Login required with authorization
   2. Login required without authorization
   3. No login required (white-listed URL usage)
2. Annotation format
3. Resource identifier maintenance and corresponding table relationships
4. Injection of permission interception methods
5. Permission interception functions

Development Specification

1. Functions or pages belonging directly to a user must have permission validation checks
2. Sensitive user data should not be shown directly; related data should be desensitized before display
3. Any parameters passed by the client must be validated for validity and checked for length
4. Passwords in configuration files must be encrypted
5. Uploaded files must have defined size limits and header signature checks

Database Specification

Table Building Rules

1. Table names and column names must use lowercase letters or numbers, no numeric beginning allowed

2. Table names must avoid plural nouns

3. Business tables must contain default columns

   Column Name	Data Type	Required	Default Value	Description
   id	varchar(40)	Yes		Primary key
   create_user_id	int8	Yes		ID of the creator
   create_time	timestamp(6)	Yes	now()	Creation time
   update_user_id	int8	No		ID of the updater
   update_time	timestamp(6)	No		Update time
   is_delete	int2	Yes	0	Deletion flag (0 normal, 1 deleted)

4. In the database, physical deletion operations should not be used; logical deletion must be applied instead.

5. Business unique fields must have indexes created.

System Configuration Classes

XSS Filter Configuration (XSSFilterConfig.java)

1. RegisterXSSfilter

   ## Prevent XSS attacks
   xss:
      # Filter switch
      enabled: true
      # Exclude links (multiple separated by commas)
      excludes: /wechat/callback
      # Match links
      urlPatterns: /*

Cross-domain Configuration (GlobalCorsConfig.java)

1. Usage Scenarios
2. Configure Cross-domain for Specified Domains

MyBatis Configuration (MyBatisConfig.java)

1. Set Scan Path
2. Plugin Registration

Redis Configuration (RedisConfig.java)

1. Set RedisTemplate Serialization Method

   Use String serialization for keys and JSON serialization for values. For specific usage, see... Redis Utility Class

Security Configuration (SecurityConfig.java)

Configure Security Filter Chain Set URL access permissions, cross-domain, CSRF, session management and other security policies

Dependency Injection Utility Classes

Redis Operation Class

1. Usage Scenarios
2. Method List + Code Examples

Password Utility Class

1. Injection Location and Available Encryption Methods
2. Method List + Code Examples

Static Method Utility Classes

Base64 Utility (Base64.java)

Cross-platform Command Execution Utility (CmdUtil.java)

Date Utility (DateUtils.java)

Email Utility (EmailUtils.java)

Excel Utility (ExcelUtil.java)

Network Utility (HttpKeyUtil.java)

Http Request Utility (HttpUtil.java)

IP Utility (IpUtils.java)

JWT Utility (JwtTokenUtil.java)

Log Cache (LogsPool.java)

MD5 Utility (MD5Util.java)

RSA Utility (RsaUtils.java)

Servlet Utility (ServletUtils.java)

Spring Utility (SpringUtil.java)

SSL Utility (SSLClient.java)

String Utility (StringUtils.java)

3Des Encryption/Decryption Utility (TripleDes.java)

File Utility (VjspFiles.java)

ZIP Utility (Zips.java)

Running

Initialize Database Scripts and Modify Configuration Files

1. Create a new database
2. Import the sql/vjsp_form.sql file
3. Modify the database connection information in the application-dev.yml file
4. Modify the Redis connection information in the application-dev.yml file
5. Process Configuration Modification

Open src\main\resources\application-dev.yml

vjsp:
  run:
    # Process request interface key, corresponding to the partnerpass field in the ts_flow_partner table
    partnerpass: TaXxYGBj1idmf4oCVUOK75QqWsZD2cEy  
    # Process interface URL
    vjspFlowUrl: http://127.0.0.1:9090/
    # vjsp-mapping folder path
    resourcesBaseConfig: 
  # Whether to enable logging
  audit-log:
    # true: Enable; false: Disable
    enabled: true
    # logger: Output using logging framework
    # db: Store in database
    log-type: db
  # rsa password encryption
  # Use the main method of RsaUtils.java to generate a new key

Starting the Application

The main startup class of the project is net.vjsp.VjspApplication, using the standard Spring Boot startup method:

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

Application Workflow

Application Path

expansion-pack/vjsp_workflow

configuration file

expansion-pack\vjsp_workflow\config\application.yml

# Database address
db.url=jdbc:postgresql://xxx.xxx.xxx.xxx:5432/vjsp_form
# Database driver
db.driverClassName=org.postgresql.Driver
# Database username
db.username=postgres
# Database password
db.password=

Launching

Run the run.bat or run.sh file to start the application.

Open the browser and enter: http://localhost:8080/index.html

Default username/password: admin / 888

VSCode Configuration

Encoding Issue

File - Preferences - Settings Check: Auto Guess Encoding

Deployment Instructions

Packaging Instructions

pom.xml has configured a JAR packaging plugin that can exclude files or directories not to be packaged into the JAR. For example:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <configuration>
      <excludes>
         <!-- Example: Exclude specific configuration files -->
         <exclude>**/application.yml</exclude>
         <exclude>**/application-dev.yml</exclude>
         <!-- Example: Exclude the entire directory -->
         <exclude>**/static/**</exclude>
         <exclude>**/vjsp-mapping/**</exclude>
      </excludes>
 </configuration>
</plugin>

Independent JAR Deployment Method

• Modify the database connection information, Redis connection information, and workflow configuration in the application-dev.yml to formal environment information.
• Remove the following sections from pom.xml and then package it with mvn install. The JAR file will contain configuration files, static resource files, and form logic files.

<!-- Example: Exclude specific configuration files -->
<exclude>**/application.yml</exclude>
<exclude>**/application-dev.yml</exclude>
<!-- Example: Exclude the entire directory -->
<exclude>**/static/**</exclude>
<exclude>**/vjsp-mapping/**</exclude>

The packaged JAR file can be run directly, for example：

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

Static HTML Deployed Independently + Backend JAR

Remove application-dev.yml, to prevent the jar from loading static files.

  web:
    resources:
      # Frontend pages, resource files path
      static-locations: classpath:static/vjsphtml/,file:./static/vjsphtml/,

• Change the database connection info, Redis connection info, workflow configuration in the application-dev.yml to info of the production environment.
• Remove the following parts from pom.xml and package it with mvn install. The JAR file will contain the configuration files, static resource files, and form logic files.

<!-- Example: Exclude specific configuration files -->
<exclude>**/application.yml</exclude>
<exclude>**/application-dev.yml</exclude>
<!-- Example: Exclude the entire directory -->
<exclude>**/vjsp-mapping/**</exclude>

Only retain
<exclude>**/static/**</exclude>

Use nginx to proxy both static pages and JAR package access addresses.

Modify the API address in the page requests.

Change the API address in the static/vjsphtml/_vjsp_setting/setting.js

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

Modify to 

var _vjsp_inter_domain = 'Your own address';

The packaged JAR file can be run directly, for example：

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

Configuration files, static files, form logic files, and JAR packages deployed separately

Retain the JAR package plugin configuration in pom.xml. After executing mvn install to package, the JAR package will not contain static files, form logic files, or configuration files.

The deployment directory structure is as follows:

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

Notes

• If static/vjsphtml is proxied by nginx, then the static resource paths must be removed from application-dev.yml, as well as the api address in setting.js

• If the vjsp-mapping directory is not at the same level as the JAR package, the document path of the form logic file under the JAR package must be modified in application-dev.yml

    # vjsp-mapping folder path
    # Modify to the full path of vjsp-mapping (excluding vjsp-mapping itself)
    resourcesBaseConfig: /opt/app/