# springboot4x-template **Repository Path**: mi9688-wine/springboot4x-template ## Basic Information - **Project Name**: springboot4x-template - **Description**: 一个基于springboot4.1的后端开发模板。集成xbatis框架，以及CRUD代码生成器(仅有实体类、和控制器，极简代码实现通用crud),接口版本管理，接口文档管理，jwt，登录拦截器，文件上传，全局异常处理，全局响应格式包装等。代码精简，适用于新项目搭建，学习xbatis框架(一个mapper走天下，最优雅的ORM框架)、springboot4学习者使用。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: v1.0 - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 1 - **Created**: 2026-06-21 - **Last Updated**: 2026-07-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

SpringBoot4x Template

基于 Spring Boot 4.1 + X-Batis 的现代化 Java 后端快速开发脚手架

Java 21 Spring Boot 4.1.0 X-Batis 1.10.5-M2 Knife4j 5.0.10 PostgreSQL 16+ MIT License

--- ## 简介 **springboot4x-template** 是一个基于 Spring Boot 4.1 的 Java 后端快速开发脚手架，专为现代 Java 21 环境打造。项目采用 **X-Batis**（MyBatis 增强框架）单 Mapper 模式，集成 **Knife4j Next** API 文档、**Hutool JWT** 鉴权、**FreeMarker** 代码生成器等主流技术栈，开箱即用。 项目遵循"简洁、高效、可维护"的设计理念，提供了统一响应包装、全局异常处理、API 版本控制、多环境配置等企业级功能，帮助开发者快速搭建高质量的后端服务。 ## 技术栈 | 技术 | 版本 | 说明 | |------|------|------| | Java | 21 | 使用虚拟线程（Virtual Threads） | | Spring Boot | 4.1.0 | 基于 Spring Framework 7.x，Jakarta EE 11 | | X-Batis | 1.10.5-M2-spring-boot4 | MyBatis 增强框架，单 Mapper 模式 | | PostgreSQL | 16+ | 数据库 | | Knife4j Next | 5.0.10 | API 文档，专为 Spring Boot 4.x 适配 | | Hutool | 5.8.46 | 工具库（JWT、JSON 等） | | FreeMarker | 2.3.32 | 代码生成模板引擎 | | Lombok | - | 简化 Java Bean 编写 | | HikariCP | - | 数据库连接池 | ## 核心特性 ### 开箱即用的脚手架 - **统一响应包装** — 通过 `@ResponseWrapper` 注解标记，自动将返回值包装为统一格式的 `R` 响应体 - **全局异常处理** — 统一捕获业务异常、数据库异常（防止 SQL 注入信息泄露）、参数校验异常等，返回友好的错误消息 - **API 版本控制** — 基于 Spring Boot 4 原生路径式版本控制，支持 `v1/v2` 多版本共存 ### 安全与鉴权 - **JWT 鉴权** — 基于 Hutool JWT 的 Token 鉴权体系，拦截器自动校验、解析并注入用户上下文 - **用户上下文** — 通过 `ThreadLocal` 持有当前登录用户信息（用户 ID、角色、部门等），方便业务层获取 ### 高效开发 - **代码生成器** — 基于 X-Batis Generator + FreeMarker 模板，一键生成 Controller、Entity 代码（适配单 Mapper 模式） - **文件上传** — 支持单文件/多文件/带元数据上传，自动按年月分子目录存储 - **虚拟线程** — 启用 Java 21 Virtual Threads，提升高并发下 I/O 密集型任务的吞吐量 ### 运维友好 - **多环境配置** — 支持 dev/test/prod 三套环境，Maven 打包时通过 `-P` 参数自由切换 - **启动信息打印** — 启动时自动打印应用名、耗时、接口文档地址、当前配置环境 - **日志分级** — Logback 按 DEBUG/INFO/ERROR 分级输出到独立文件，自动清理历史日志 - **跨域支持** — 内置 CORS 配置，方便前后端分离开发 ## 快速开始 ### 环境要求 - JDK 21+ - Maven 3.9+ - PostgreSQL 16+ ### 1. 初始化数据库 ```sql -- 创建数据库 CREATE DATABASE streamline_db; -- 执行初始化脚本 psql -U postgres -d streamline_db -f sql/postgres_init.sql ``` > 初始化脚本包含系统用户表（`sys_user`）等基础表结构及示例数据。 ### 2. 修改配置 根据本地环境修改数据库连接信息： **开发环境** — `src/main/resources/application-dev.yaml` ```yaml spring: datasource: url: jdbc:postgresql://localhost:5432/streamline_db username: postgres password: 你的密码 ``` ### 3. 启动项目 ```bash # 方式一：IDE 中直接运行 StreamlineServer.java # 方式二：Maven 打包后运行 mvn clean package -P dev java -jar target/springboot4x-template-2026-06-21.jar ``` ### 4. 访问文档 启动后访问：http://localhost:8080/doc.html ![Knife4j 接口文档](src/main/resources/static/api-doc.png) ## Maven 打包 项目内置三套环境配置，通过 `-P` 参数指定： ```bash # 开发环境（默认） mvn clean package -P dev # 测试环境 mvn clean package -P test # 生产环境 mvn clean package -P prod ``` 打包后的 JAR 名称格式为 `springboot4x-template-yyyy-MM-dd.jar`（如 `springboot4x-template-2026-06-21.jar`）。 生产环境部署时，敏感信息（数据库密码、JWT 密钥等）通过环境变量注入： ```bash export DB_PASSWORD=your_password export JWT_SECRET=your_jwt_secret java -jar springboot4x-template-2026-06-21.jar ``` ## 项目结构 项目采用经典的 Spring Boot 分层架构，代码按功能模块组织在 `com.mijiupro.streamline` 包下： - **common/** — 公共基础模块，包含注解、配置、异常、处理器、拦截器、统一响应体、工具类等通用组件 - **modules/** — 业务模块目录，按子系统分包（如 `sys` 系统管理），各模块内含 `controller`、`entity`、`mapper` 等子包 - **generationCode/** — 代码生成器入口，基于 X-Batis Generator 快速生成 CRUD 代码 ``` springboot4x-template ├── sql/ # SQL 初始化脚本 │ └── postgres_init.sql ├── src/ │ ├── main/ │ │ ├── java/com/mijiupro/streamline/ │ │ │ ├── StreamlineServer.java # 启动类 │ │ │ ├── common/ │ │ │ │ ├── annotation/ │ │ │ │ │ └── ResponseWrapper.java # 统一响应包装注解 │ │ │ │ ├── config/ │ │ │ │ │ ├── WebConfig.java # Web 配置（拦截器、CORS、版本控制） │ │ │ │ │ └── SpringDocConfig.java # Knife4j/SpringDoc 分组配置 │ │ │ │ ├── exception/ │ │ │ │ │ └── BusinessException.java # 业务异常 │ │ │ │ ├── handler/ │ │ │ │ │ ├── GlobalExceptionHandler.java # 全局异常处理 │ │ │ │ │ └── ResponseWrapperHandler.java # 响应包装处理 │ │ │ │ ├── interceptor/ │ │ │ │ │ └── LoginInterceptor.java # 登录拦截器 │ │ │ │ ├── result/ │ │ │ │ │ ├── R.java # 统一响应体 │ │ │ │ │ └── Page.java # 分页封装 │ │ │ │ ├── upload/ │ │ │ │ │ └── FileUploadController.java # 文件上传接口 │ │ │ │ └── util/ │ │ │ │ ├── JwtUtils.java # JWT 工具类 │ │ │ │ ├── StartupLogger.java # 启动信息打印 │ │ │ │ └── context/ │ │ │ │ ├── LoginUser.java # 登录用户 POJO │ │ │ │ └── UserContextHolder.java # 用户上下文持有者 │ │ │ ├── generationCode/ │ │ │ │ └── BaseCodeGen.java # 代码生成器入口 │ │ │ └── modules/ │ │ │ └── sys/ │ │ │ ├── controller/ │ │ │ │ └── SysUserController.java # 系统用户示例控制器 │ │ │ ├── entity/ │ │ │ │ └── SysUser.java # 系统用户实体 │ │ │ └── mapper/ │ │ │ └── MybatisBasicMapper.java # 单 Mapper 接口 │ │ └── resources/ │ │ ├── application.yaml # 主配置文件 │ │ ├── application-dev.yaml # 开发环境 │ │ ├── application-test.yaml # 测试环境 │ │ ├── application-prod.yaml # 生产环境 │ │ ├── logback.xml # 日志配置 │ │ └── templates/ # 代码生成模板 │ │ ├── action.ftl # Controller 模板 │ │ ├── entity.ftl # 实体模板 │ │ ├── service.ftl # Service 接口模板 │ │ ├── service.impl.ftl # Service 实现模板 │ │ ├── dao.ftl # DAO 接口模板 │ │ ├── dao.impl.ftl # DAO 实现模板 │ │ ├── mapper.ftl # Mapper 接口模板 │ │ ├── mapper.xml.ftl # Mapper XML 模板 │ │ └── TEMPLATE_DATA_REFERENCE.md # 模板参数参考 │ └── test/ │ └── java/ # 测试代码 ├── .gitignore ├── .gitattributes ├── pom.xml └── README.md ``` ## API 文档 项目集成了 Knife4j Next（基于 SpringDoc 4.x），启动后访问： - **Knife4j UI**: http://localhost:8080/doc.html - **OpenAPI JSON**: http://localhost:8080/v3/api-docs 接口按 API 版本分组展示： - **v1 版本** — 稳定版接口 - **v2 版本** — 新版实验接口 ### 文件上传接口 | 接口 | 方法 | 说明 | |------|------|------| | `/api/v1/upload/file` | POST | 单文件上传 | | `/api/v1/upload/files` | POST | 多文件上传 | | `/api/v1/upload/fileWithMeta` | POST | 带元数据的单文件上传 | | `/api/v1/upload/filesWithMeta` | POST | 带元数据的多文件上传 | ### 系统用户接口 | 接口 | 方法 | 版本 | 说明 | |------|------|------|------| | `/api/v1/sysUser/page` | GET | v1 | 分页查询 | | `/api/v1/sysUser/all` | GET | v1 | 查询所有 | | `/api/v1/sysUser/all` | GET | v2 | 查询所有（v2 版本） | | `/api/v1/sysUser/save` | POST | v1 | 新增用户 | | `/api/v1/sysUser/update` | POST | v1 | 修改用户 | | `/api/v1/sysUser/delete` | DELETE | v1 | 删除用户 | ## 许可证 本项目基于 [MIT License](LICENSE) 开源。 ## 作者 - **mijiupro** — 项目创建者 ---

如果你觉得这个项目有帮助，欢迎 Star ⭐