# why-backend

**Repository Path**: dev_why/why-backend

## Basic Information

- **Project Name**: why-backend
- **Description**: 这个项目是一个Java后端业务使用的基本框架，项目开发时可以在这个框架的基础上快速开发对应的业务功能，这样就节省了初始化配置项目的时间，是一个通用的开发框架。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2023-10-13
- **Last Updated**: 2025-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# why-backend: Web后端快速开发工程模板
> 一个基于 Spring Boot 的后端系统，支持用户登录注册、用户信息增删改查、认证授权、邮箱验证、接口幂等、Redis 限流等项目基础功能，是一个Java后端业务使用的基本框架，开发时可以在这个框架的基础上快速开发对应的业务功能，充分节省初始化配置项目的时间。



## 📜 why-backend 项目目录结构

    src/main/java/com/way/backend/
    |
     ------common/                       # 通用工具 & 基础模块
    |      |
    |      |------exception/             # 全局异常处理与自定义业务异常处理
    |      |------utils/                 # 工具类（日期、字符串、文件、随机值等）
    |      |------result/                # 统一返回结果包装（ResponseResult、AppHttpCodeEnum）
    |      |------constant/              # 通用常量
    |      |------config/                # 通用配置类（跨域、Json、编码等）
    |      |    
    |------core/                         # 核心业务层（业务逻辑）
    |      |    
    |      |------user/                  # 用户业务模块（其它业务模块以此类推）
    |      |      |
    |      |------|----entity/           # 实体类（对应数据库表）
    |      |------|----constant/         # 常量封装
    |      |------|----dto/              # 数据传输对象（入参/出参）
    |      |------|----vo/               # 视图对象（返回前端）
    |      |------|----mapper/           # MyBatis Mapper 接口
    |      |------|----service/          # 业务逻辑接口
    |      |------|----service/impl/     # 业务逻辑实现类
    |      |------|----controller/       # 控制器层
    |      |      |
    |      |------aop/                   # 自定义注解与切面增强
    |      |      |
    |      |------|----annotation/       # 自定义注解
    |      |------|----aspect/           # 切面增强（日志、幂等、限流等）
    |      |    
    |------infra/                        # 基础设施层（Redis、数据库、消息队列、鉴权等）
    |      |
    |      |------cache/                 # Redis 缓存相关
    |      |------auth/                  # Sa-Token 认证授权相关
    |      |------db/                    # 数据库相关
    |      |------mq/                    # 消息队列相关，比如 RabbitMQ，有需要可以引入
    |      |------storage/               # 对象存储（MinIO / OSS），有需要可以引入
    |      |------search/                # 搜索引擎（ElasticSearch / Milvus），有需要可以引入
    |      |    
    |------api/                          # 对外接口层
    |      |
    |      |------openapi/               # 对外提供 Restful API
    |      |------client/                # 调用外部第三方服务
    |      |
    |------notification/                 # 通讯能力集成
    |      |
    |      |------mail/                  # 邮件系统
    |
    BackendApplication.java              # SpringBoot 启动类
---

## 📦 技术栈

本项目后端采用 **SpringBoot 3.5.6、JDK 21** 构建，整体架构清晰、轻量高效，核心技术栈如下：

### 核心框架

* **Spring Boot 3.5.6**：快速构建 Java 后端应用
* **Spring AOP**：切面编程，用于日志记录、幂等校验、接口限流等横切逻辑
* **MyBatis Plus 3.5.9**：增强型 ORM 框架，提供 CRUD、分页及条件构造器

### 安全与认证

* **Sa-Token 1.39.0**：轻量级权限认证与会话管理
* **Sa-Token Redis**：支持将权限、会话数据存储到 Redis
* **Spring Security Crypto**：BCrypt 加密算法，用于密码加密

### 数据存储

* **MySQL**：关系型数据库存储核心业务数据
* **Redis**：缓存、分布式锁、幂等 Token 存储

### 消息与通知

* **Spring Boot Mail**：邮件发送功能，可用于注册验证、密码重置等

### Web 与 API 文档

* **Spring Web**：构建 RESTful API
* **Knife4j 4.6.0**：接口文档和调试工具

### JSON 与 HTTP 工具

* **Fastjson2 2.0.52**：高性能 JSON 序列化与反序列化
* **OkHttp 4.12.0**：HTTP 客户端，支持访问第三方接口

### 参数校验与工具类

* **Hibernate Validator / Spring Boot Validation**：请求参数校验
* **Lombok**：减少 Java 核心类样板代码，提高开发效率
* **Apache Commons Lang3**：提供丰富的 Java 基础工具类
* **Apache Commons Codec**：提供 MD5、SHA1、Hex 等编码工具

### 测试

* **Spring Boot Starter Test**：单元测试和集成测试支持

---

## 📝 功能列表

本项目为后端服务，核心功能包括：

### 用户与认证

* **用户注册**：支持邮箱验证、密码加密（BCrypt）、幂等注册
* **用户登录**：账号密码登录
* **权限管理**：基于 **Sa-Token** 的角色与权限控制
* **会话管理**：支持 Redis 存储的分布式会话

### 幂等与限流

* **接口幂等**：通过 Redis 保存 token，防止重复提交
* **接口限流**：基于注解限制单接口访问频率

### 邮件服务

* **注册邮箱验证码**：发送邮箱验证码，支持 Redis 缓存与过期

### 数据管理

* **用户信息存储**：MySQL 数据库
* **缓存管理**：Redis 缓存用户数据、Token、验证码等
* **分页查询**：基于 MyBatis Plus 分页插件

### 日志与监控

* **请求日志**：统一记录接口访问日志，包括 IP、IP属地等
* **异常处理**：全局统一异常处理和参数校验提示

### API 与文档

* **RESTful API**：标准化接口设计
* **接口文档**：Knife4j 提供在线可视化接口文档

### 工具与扩展

* **参数校验**：Hibernate Validator 注解
* **密码加密**：BCrypt
* **HTTP 调用**：OkHttp 用于第三方接口访问
* **JSON 处理**：Fastjson2 高性能序列化/反序列化

---

## 🚀 快速运行

1. 克隆项目

```bash
git clone https://gitee.com/dev_why/why-backend.git
cd why-backend
```

2. 修改配置文件 `application.yml`、`application-dev.yml`

3. 创建数据库和表（可使用 `create_table.sql`）

4. 启动项目

```bash
mvn spring-boot:run
```

5. 访问接口文档：

```
http://localhost:8000/doc.html
```

---

## 🔑 注意事项

### 幂等功能

为防止重复提交，使用幂等功能时，前端需在提交表单前调用以下接口获取唯一 **Idempotent Token**：

```
GET /api/idempotent/token
```

随后，在访问被幂等保护的接口时，将该 Token 添加到请求头中，实现幂等控制：

```
Headers:
  Idempotent-Token: <token>
```

> 后端会校验该 Token 是否已使用，确保同一请求不会被重复处理。

### 用户认证与登录

用户登录成功后，系统将通过 **Sa-Token** 生成唯一的身份标识 Token。
前端在后续请求接口时，需在请求头中携带该 Token 以验证用户身份：

```
Headers:
  Authorization: <token>
```

> 未携带或 Token 无效的请求将被拒绝访问。

---

## 📬 联系方式
如果你有任何问题，欢迎与我交流！如果觉得项目不错，也欢迎给我一个 Star ~ 非常感谢！
* 作者：TheSea
* 邮箱：[dev_why1024@163.com](mailto:dev_why1024@163.com)

---