# trae-demo

**Repository Path**: radish40/trae-demo

## Basic Information

- **Project Name**: trae-demo
- **Description**: No description available
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RBAC 权限系统框架

基于 Spring Boot 3.2.x 实现的 RBAC（Role-Based Access Control）权限管理系统框架，提供用户、角色、权限、菜单的完整管理功能。

## 技术栈

- **语言**: Java 17
- **框架**: Spring Boot 3.2.0
- **数据库**: MySQL 5.7+ / H2 (测试)
- **ORM**: MyBatis Plus 3.5.5
- **安全**: Spring Security + JWT
- **构建工具**: Maven

## 项目结构

```
src/
├── main/
│   ├── java/com/example/demo/
│   │   ├── controller/          # REST API 控制层
│   │   ├── service/             # 业务逻辑层
│   │   ├── mapper/              # 数据访问层
│   │   ├── entity/              # 数据库实体
│   │   ├── dto/                 # 数据传输对象
│   │   ├── security/            # 安全配置（JWT、过滤器）
│   │   ├── config/              # 应用配置
│   │   ├── exception/           # 异常处理
│   │   └── TraeDemoApplication.java
│   └── resources/
│       ├── application.yml      # 主配置文件（环境切换）
│       ├── application-dev.yml  # 开发环境配置
│       ├── application-test.yml # 测试环境配置
│       ├── application-master.yml # 生产环境配置
│       ├── mapper/              # MyBatis 映射文件
│       └── schema.sql           # 数据库初始化DDL
└── test/
    ├── java/com/example/demo/    # 单元测试
    └── resources/
        ├── application.yml       # 测试配置
        ├── schema.sql            # 测试数据库DDL
        └── data.sql              # 测试数据初始化
```

## 多环境配置

### 环境配置文件

| 配置文件 | 环境 | 说明 |
|----------|------|------|
| `application.yml` | 主配置 | 环境切换入口，默认启用dev环境 |
| `application-dev.yml` | 开发环境 | 开发调试使用，日志级别DEBUG |
| `application-test.yml` | 测试环境 | 测试验证使用，日志级别DEBUG |
| `application-master.yml` | 生产环境 | 生产部署使用，日志级别WARN，开启连接池优化 |

### 默认环境

```yaml
# application.yml
spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}  # 默认dev环境
```

### 环境变量

所有敏感配置均可通过环境变量覆盖，以下是支持的环境变量：

| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `SPRING_PROFILES_ACTIVE` | 激活的环境 | dev |
| `SERVER_PORT` | 服务端口 | 8080 |
| `DB_URL` | 数据库连接URL | jdbc:mysql://117.72.153.78:7752/testdb |
| `DB_USERNAME` | 数据库用户名 | root |
| `DB_PASSWORD` | 数据库密码 | 776235974.LUObo |
| `JWT_SECRET` | JWT签名密钥 | trae-demo-jwt-secret-key-2024-trae-demo-jwt-secret-key-2024 |
| `JWT_EXPIRATION` | JWT过期时间(毫秒) | 86400000 |

### 切换环境

#### 方式一：修改配置文件
```yaml
# application.yml
spring:
  profiles:
    active: test  # 切换到测试环境
```

#### 方式二：命令行参数
```bash
# 开发环境
java -jar trae-demo-1.0.0.jar --spring.profiles.active=dev

# 测试环境
java -jar trae-demo-1.0.0.jar --spring.profiles.active=test

# 生产环境
java -jar trae-demo-1.0.0.jar --spring.profiles.active=master
```

#### 方式三：环境变量
```bash
# Linux/Mac
export SPRING_PROFILES_ACTIVE=test
java -jar trae-demo-1.0.0.jar

# Windows PowerShell
$env:SPRING_PROFILES_ACTIVE="test"
java -jar trae-demo-1.0.0.jar
```

### 敏感数据管理

生产环境建议通过环境变量注入敏感配置：

```bash
# Linux/Mac 生产环境启动示例
export DB_PASSWORD="your-secure-password"
export JWT_SECRET="your-strong-jwt-secret"
export SPRING_PROFILES_ACTIVE=master
java -jar trae-demo-1.0.0.jar
```

### 各环境配置差异

| 配置项 | dev | test | master |
|--------|-----|------|--------|
| 数据库 | testdb | testdb_test | testdb_prod |
| 日志级别 | DEBUG | DEBUG | WARN |
| MyBatis日志 | 开启 | 开启 | 关闭 |
| 连接池 | 默认 | 默认 | 优化配置 |
| SSL | false | false | true |

## 数据库配置

### 开发环境

```yaml
# application-dev.yml
spring:
  datasource:
    url: ${DB_URL:jdbc:mysql://117.72.153.78:7752/testdb?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false}
    username: ${DB_USERNAME:root}
    password: ${DB_PASSWORD:776235974.LUObo}
```

### 生产环境

```yaml
# application-master.yml
spring:
  datasource:
    url: ${DB_URL:jdbc:mysql://117.72.153.78:7752/testdb_prod?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=true}
    username: ${DB_USERNAME:root}
    password: ${DB_PASSWORD:your-secure-password}
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      idle-timeout: 30000
```

## 数据库表设计

### 核心表

| 表名 | 说明 |
|------|------|
| sys_user | 用户表 |
| sys_role | 角色表 |
| sys_permission | 权限表 |
| sys_menu | 菜单表 |
| sys_user_role | 用户-角色关联表 |
| sys_role_permission | 角色-权限关联表 |
| sys_role_menu | 角色-菜单关联表 |

### ER 关系

```
用户 (1) ↔ (*) 角色 (1) ↔ (*) 权限
           ↓
        (1) ↔ (*) 菜单
```

## API 接口文档

### 认证接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/auth/login | 用户登录 |
| POST | /api/auth/register | 用户注册 |

#### 登录请求

```json
POST /api/auth/login
{
  "username": "admin",
  "password": "123456"
}
```

#### 登录响应

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "nickname": "超级管理员",
      "email": "admin@example.com"
    }
  }
}
```

### 用户管理接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/users | 获取用户列表 |
| GET | /api/users/{id} | 获取用户详情 |
| POST | /api/users | 创建用户 |
| PUT | /api/users/{id} | 更新用户 |
| DELETE | /api/users/{id} | 删除用户 |

### 角色管理接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/roles | 获取角色列表 |
| GET | /api/roles/{id} | 获取角色详情 |
| POST | /api/roles | 创建角色 |
| PUT | /api/roles/{id} | 更新角色 |
| DELETE | /api/roles/{id} | 删除角色 |

### 权限管理接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/permissions | 获取权限列表 |
| GET | /api/permissions/{id} | 获取权限详情 |
| POST | /api/permissions | 创建权限 |
| PUT | /api/permissions/{id} | 更新权限 |
| DELETE | /api/permissions/{id} | 删除权限 |

### 菜单管理接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/menus | 获取菜单列表 |
| GET | /api/menus/{id} | 获取菜单详情 |
| POST | /api/menus | 创建菜单 |
| PUT | /api/menus/{id} | 更新菜单 |
| DELETE | /api/menus/{id} | 删除菜单 |
| GET | /api/menus/tree | 获取菜单树 |

## 运行方式

### 开发环境运行

```bash
cd trae-demo
mvn spring-boot:run
```

### 指定环境运行

```bash
# 测试环境
mvn spring-boot:run -Dspring-boot.run.profiles=test

# 生产环境
mvn spring-boot:run -Dspring-boot.run.profiles=master
```

### 打包构建

```bash
mvn clean package
```

### 运行打包后的 Jar

```bash
# 默认开发环境
java -jar target/trae-demo-1.0.0.jar

# 指定环境
java -jar target/trae-demo-1.0.0.jar --spring.profiles.active=test

# 使用环境变量
export DB_PASSWORD="your-password"
java -jar target/trae-demo-1.0.0.jar
```

## 单元测试

### 测试架构

项目包含以下测试类：

| 测试类 | 测试范围 |
|--------|----------|
| AuthControllerTest | 认证控制器测试 |
| SysUserControllerTest | 用户控制器测试 |
| SysUserServiceTest | 用户服务测试 |
| SysRoleServiceTest | 角色服务测试 |
| SysPermissionServiceTest | 权限服务测试 |
| SysMenuServiceTest | 菜单服务测试 |
| JwtTokenProviderTest | JWT令牌提供者测试 |

### 运行测试

```bash
# 运行所有测试
mvn test

# 运行指定测试类
mvn test -Dtest=JwtTokenProviderTest

# 运行多个测试类
mvn test -Dtest="SysUserServiceTest,SysRoleServiceTest"
```

### 测试数据初始化

测试使用 H2 内存数据库，测试前会自动执行：
1. `src/test/resources/schema.sql` - 创建表结构
2. `src/test/resources/data.sql` - 初始化测试数据

### 测试覆盖范围

- **认证模块**: JWT令牌生成、验证、解析
- **用户模块**: 用户增删改查、密码加密、状态管理
- **角色模块**: 角色增删改查、角色-权限-菜单关联
- **权限模块**: 权限增删改查、权限继承
- **菜单模块**: 菜单增删改查、菜单树结构
- **安全模块**: 未授权访问控制

## 安全特性

### JWT 认证

- Token 有效期：24小时（可配置）
- Token 签名算法：HS256
- Token 包含信息：用户ID、用户名

### 密码安全

- 使用 BCrypt 算法加密密码
- 密码强度验证
- 支持密码重置

### 权限控制

- 基于角色的访问控制
- 细粒度权限管理
- 菜单级别的权限控制

## 配置说明

### JWT 配置

```yaml
jwt:
  secret: ${JWT_SECRET:trae-demo-jwt-secret-key-2024-trae-demo-jwt-secret-key-2024}
  expiration: ${JWT_EXPIRATION:86400000}  # 24小时（毫秒）
```

### MyBatis Plus 配置

```yaml
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
  mapper-locations: classpath:mapper/*.xml
```

## 代码规范

- 使用 Lombok 简化实体类
- 使用 Spring Data JPA 命名规范
- 异常统一处理
- 返回结果统一封装

## 许可证

MIT License