# springboot-init

**Repository Path**: zjyxc/springboot-init

## Basic Information

- **Project Name**: springboot-init
- **Description**: 基于鱼皮的后端模板开发的后端项目初始模板，引入JWT
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-04-30
- **Last Updated**: 2025-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpringBoot 项目初始模板（JWT版本）

> 作者：[Nwj](https://gitee.com/zjyxc)
> 
> 创建时间：2025-04-30
> 
本项目基于[鱼皮](https://github.com/liyupi)的后端模板进行二次开发

基于 Java SpringBoot 的项目初始模板，整合了常用框架和主流业务的示例代码。

由于能力有限，项目又很多写的不够标准（~~屎山~~）的地方，可提issue。

## 简介
### src项目结构
```
├─annotation 自定义注解
├─aop 请求日志和鉴权
├─common 通用类
├─component 配置类
├─config 配置类
├─constant 常量
├─controller 接口
├─esdao ES操作
├─exception 异常类
├─fliter 过滤器
├─generate 代码生成
├─job 定时任务
│  ├─cycle 循环
│  └─once 单次
├─listener 监听器
├─manager 管理类，GuaVa限流器等
├─mapper 复杂SQL
├─model 模型层
│  ├─dto 数据传输对象
│  ├─entity 实体类
│  ├─enums 枚举类
│  └─vo 视图对象
├─service 接口及其实现
│  └─impl 实现层
├─utils 工具类
└─wxmp 微信工具类
    └─handler 接口
```
### resources项目结构
```
├─mapper 映射文件,sql语句
├─META-INF Springboot自动配置
├─templates 模板文件
├─applaction.yml 配置文件
├─application-prod.yml 生产环境配置
├─application-test.yml 测试环境配置
└─banner.txt 好看的
```
### 

## 模板特点

### 主流框架 & 特性

- Spring Boot 2.7.x
- Spring MVC
- MyBatis + MyBatis Plus 数据访问（开启分页）
- Spring Boot 调试工具和项目处理器
- Spring AOP 切面编程
- Spring Scheduler 定时任务
- Spring 事务注解
- JWT传输用户数据

### 数据存储

- MySQL 数据库
- Redis 内存数据库
- Elasticsearch 搜索引擎
- Qiniu 对象存储

### 工具类

- Easy Excel 表格处理
- Hutool 工具库
- Apache Commons Lang3 工具类
- Lombok 注解
- JWT 工具类

### 业务特性

- 业务代码生成器（支持自动生成 Service、Controller、数据模型代码）
- Spring Session Redis 分布式登录
- 全局请求响应拦截器（记录日志）
- 全局异常处理器
- 自定义错误码
- 封装通用响应类
- Swagger + Knife4j 接口文档
- 自定义权限注解 + 全局校验
- 全局跨域处理
- 长整数丢失精度解决
- 多环境配置

## 业务功能

- 提供示例 SQL（用户、帖子、帖子点赞、帖子收藏表）
- 集成文件上传
- 用户登录、注册、注销、更新、检索、权限管理
- 帖子创建、删除、编辑、更新、数据库检索、ES 灵活检索
- 帖子点赞、取消点赞
- 帖子收藏、取消收藏、检索已收藏帖子
- 帖子回复、回复嵌套
- 帖子全量同步 ES、增量同步 ES 定时任务
- 支持微信开放平台登录
- 支持微信公众号订阅、收发消息、设置菜单
- 支持分业务的文件上传

### 单元测试

- JUnit5 单元测试
- 示例单元测试类

### 架构设计

- 合理分层


## 快速上手

> 所有需要修改的地方都标记了 `todo`，可以打开全局搜索搜索todo，然后根据自己的需求进行替换

![](doc/todolist.png)

### MySQL 数据库

1）修改 `application.yml` 的数据库配置为你自己的：

```yml
# 示例
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/database?useServerPrepStmts=true
    username: root
    password: 123456
```

2）执行 `sql/create_table.sql` 中的数据库语句，自动创建库表(不带数据)

3）启动项目，访问 `http://localhost:4396/api/doc.html` 即可打开接口文档，不需要写前端就能在线调试接口了~

![](doc/knife4j.png)

### knife4j食用教程
1）用发送按钮调试，非常基础这里不展开

2）访问`http://localhost:4396/api/v2/api-docs` （可在knife4j首页中的分组Url中查看到），访问成功后会返回JSON格式的文件，
此为openapi 规范，可直接导入到其他工具中，如 Postman、ApiFox 等，方便调试。
![](doc/apifox.png)

3）基于上述Json文档，前端可以集成[openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)可以**一行代码不写**封装完所有接口，可以直接调用，具体流程可看这个项目的[README](https://github.com/ferdikoomen/openapi-typescript-codegen/blob/main/README.md)。

### 文件上传配置教程(七牛云)
1）在七牛云官网登陆注册后获取密钥，并配置到 `qiniu_oss_config` 数据库中：
```yml
# 请参照改格式在数据库中进行更改
qiniu:
  accessKey: todo
  secretKey: todo
  bucketName: todo
  domain: http://todo.com/
```
最后修改

2）默认只支持图片上传，可以在`util`包下的`FileUtil`类进行配置
![](doc/fileutil.png)
### 拦截器开启
1）在 `WebConfig` 注释，可关闭拦截器，默认开启，若处于开发阶段可关闭便于测试
![](doc/webconfig.png)

### 启动时会出文档地址和周杰伦
1）启动成功样式

![](doc/hello.png)

2）自拍一张

![](doc/jay.png)
### Elasticsearch 搜索引擎
ps:非必须，主要用于文本搜索，数据量较小可略过

1）修改 `application.yml` 的 Elasticsearch 配置为你自己的：

```yml
spring:
  elasticsearch:
    uris: http://localhost:9200
    username: root
    password: 123456
```

2）复制 `sql/post_es_mapping.json` 文件中的内容，通过调用 Elasticsearch 的接口或者 Kibana Dev Tools 来创建索引（相当于数据库建表）

```
PUT post_v1
{
 参数见 sql/post_es_mapping.json 文件
}
```

这步不会操作的话需要补充下 Elasticsearch 的知识，或者自行百度一下~

3）开启同步任务，将数据库的帖子同步到 Elasticsearch

找到 job 目录下的 `FullSyncPostToEs` 和 `IncSyncPostToEs` 文件，取消掉 `@Component` 注解的注释，再次执行程序即可触发同步：

```java
// todo 取消注释开启任务
//@Component
```

### 业务代码生成器

支持自动生成 Service、Controller、数据模型代码，配合 MyBatisX 插件，可以快速开发增删改查等实用基础功能。

找到 `generate.CodeGenerator` 类，修改生成参数和生成路径，并且支持注释掉不需要的生成逻辑，然后运行即可。

```
// 指定生成参数
String packageName = "com.zjyxc.springboot-jwt-init";
String dataName = "用户评论";
String dataKey = "userComment";
String upperDataKey = "UserComment";
```

生成代码后，可以移动到实际项目中，并且按照 `// todo` 注释的提示来针对自己的业务需求进行修改。