generated from youfool-project/youfool-prj-springboot-template
194 lines
4.5 KiB
Markdown
194 lines
4.5 KiB
Markdown
# CCDemo - Spring Boot 基础项目模板
|
||
|
||
基于 youfool-framework-springboot 3.3.1 的 Spring Boot 项目模板，集成常用功能和最佳实践。
|
||
|
||
## 项目特性
|
||
|
||
- 🛡️ **安全防护**：集成 XSS 防护、SM3 加密、RSA 加密
|
||
- 🔐 **认证授权**：基于 Sa-Token 的权限管理
|
||
- 📊 **API 文档**：集成 Knife4j (Swagger) 接口文档
|
||
- 📈 **监控日志**：集成 Druid 数据源监控和 REST 日志记录
|
||
- 🚦 **限流控制**：内置漏桶算法限流器
|
||
- 🗄️ **数据源**：支持动态数据源切换
|
||
- 📁 **文件管理**：支持文件上传功能
|
||
|
||
## 技术栈
|
||
|
||
- **框架**：Spring Boot 2.3.5
|
||
- **基础框架**：youfool-framework-springboot 3.3.1
|
||
- **数据库**：PostgreSQL / MySQL
|
||
- **安全**：Sa-Token、RSA、SM3
|
||
- **工具**：Lombok、Junit
|
||
- **文档**：Knife4j (Swagger)
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/main/java/io/lroyia/ccdemo/
|
||
├── annotation/ # 自定义注解
|
||
│ └── RateLimit.java # 限流注解
|
||
├── aspect/ # AOP 切面
|
||
│ └── RateLimiterAspect.java # 限流切面
|
||
├── config/ # 配置类
|
||
│ ├── PrjDataSource.java # 数据源配置
|
||
│ ├── RateLimiterConfig.java # 限流器配置
|
||
│ ├── SpringMvcConfig.java # MVC 配置
|
||
│ └── SwaggerKnife4j.java # Swagger 配置
|
||
├── controller/ # 控制器
|
||
│ └── LoginController.java # 登录相关接口
|
||
├── common/ # 通用组件
|
||
│ ├── constants/ # 常量定义
|
||
│ └── util/ # 工具类
|
||
│ ├── StringUtils.java
|
||
│ └── LeakyBucketRateLimiter.java # 漏桶限流器
|
||
├── exception/ # 异常处理
|
||
│ └── RateLimitExceededException.java
|
||
└── dev/ # 开发工具
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
### 1. 数据源管理
|
||
|
||
当前版本使用了`苞米豆`的[动态数据源](https://github.com/baomidou/dynamic-datasource-spring-boot-starter)。
|
||
|
||
**注意事项**：使用事务时需使用 `@DSTransactional` 代替 `@Transactional`。
|
||
|
||
### 2. 限流控制
|
||
|
||
实现了基于漏桶算法的限流器，支持：
|
||
|
||
- 桶容量配置
|
||
- 流出速率配置
|
||
- 自定义异常处理
|
||
- AOP 无侵入式集成
|
||
|
||
**使用方式**：
|
||
```java
|
||
@RateLimit
|
||
public RestResult<?> doLogin(String username, String password, Boolean encrypt) {
|
||
// 方法实现
|
||
}
|
||
```
|
||
|
||
**配置参数**：
|
||
```yaml
|
||
rate:
|
||
limiter:
|
||
enabled: true # 是否启用限流
|
||
capacity: 100 # 桶容量
|
||
rate: 10 # 每秒处理数量
|
||
rate-interval: 1 # 时间间隔(秒)
|
||
```
|
||
|
||
### 3. 认证授权
|
||
|
||
基于 Sa-Token 实现的认证授权系统：
|
||
|
||
- Token 认证
|
||
- 权限管理
|
||
- 会话管理
|
||
- 登录状态控制
|
||
|
||
### 4. 安全防护
|
||
|
||
- **XSS 防护**：过滤恶意脚本，保护应用安全
|
||
- **SM3 加密**：用户密码加密存储
|
||
- **RSA 加密**：敏感数据传输加密
|
||
- **CSP 策略**：内容安全策略配置
|
||
|
||
### 5. API 文档
|
||
|
||
集成 Knife4j (Swagger) 提供在线 API 文档：
|
||
|
||
- 自动生成接口文档
|
||
- 支持在线测试
|
||
- 权限控制访问
|
||
|
||
## 配置说明
|
||
|
||
### 主要配置项
|
||
|
||
```yaml
|
||
# 应用配置
|
||
spring:
|
||
application:
|
||
name: youfool-prj-springboot-template
|
||
|
||
# 数据源配置
|
||
datasource:
|
||
dynamic:
|
||
primary: master
|
||
datasource:
|
||
master:
|
||
# 主数据源配置
|
||
youfool:
|
||
# 框架数据源配置
|
||
|
||
# 限流器配置
|
||
rate:
|
||
limiter:
|
||
enabled: true
|
||
capacity: 100
|
||
rate: 10
|
||
rate-interval: 1
|
||
|
||
# Sa-Token 配置
|
||
sa-token:
|
||
token-name: satoken
|
||
timeout: 2592000
|
||
is-concurrent: true
|
||
is-share: false
|
||
token-style: uuid
|
||
|
||
# 安全配置
|
||
security:
|
||
xss:
|
||
enabled: true
|
||
validate-input: true
|
||
sanitize-output: true
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 启动项目
|
||
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
### 访问地址
|
||
|
||
- **应用首页**：http://localhost:8080/prj
|
||
- **API 文档**：http://localhost:8080/prj/doc.html
|
||
- **Druid 监控**：http://localhost:8080/prj/druid
|
||
|
||
### 代码规范
|
||
|
||
项目集成了 CheckStyle 代码风格检查：
|
||
|
||
```bash
|
||
mvn checkstyle:check
|
||
```
|
||
|
||
### 构建部署
|
||
|
||
```bash
|
||
# 编译打包
|
||
mvn clean package
|
||
|
||
# 跳过测试打包
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **事务管理**：使用 `@DSTransactional` 而非 `@Transactional`
|
||
2. **安全配置**：生产环境请修改默认密码和密钥
|
||
3. **限流配置**：根据业务需求调整限流参数
|
||
4. **数据源**：确保数据库连接配置正确
|
||
5. **权限管理**：根据实际业务配置用户权限
|
||
|
||
## 许可证
|
||
|
||
本项目遵循 Apache License 2.0 开源协议。 |