ccdemo/README.md

# 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 开源协议。