# java-example

**Repository Path**: caoerlei/java-example

## Basic Information

- **Project Name**: java-example
- **Description**: Java Example — 微生物平台后端

基于 Spring Boot 4.0.2 的后端服务，已实现 JWT 双 Token 认证体系（Access Token + Refresh Token），采用前后端分离、无状态会话架构。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-05
- **Last Updated**: 2026-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java Example 后端

基于 Spring Boot 的 RBAC 后端示例项目，提供认证、用户、角色、菜单权限管理。

## 技术栈

- Java 17
- Spring Boot 4.0.2
- Spring Security + JWT（双 Token）
- Spring Data JPA + MySQL
- Maven

## 核心功能

- 认证：注册、登录、刷新 Token、登出
- 权限：基于角色的菜单路由和按钮权限控制
- 管理：用户管理、角色管理、菜单管理
- 基础：统一响应结构、全局异常处理、健康检查接口

## 快速启动

### 1) 初始化数据库

```bash
mysql -u root -p < src/database/认证相关/sys_user.sql
mysql -u root -p < src/database/认证相关/sys_refresh_token.sql
```

### 2) 开发环境启动

```bash
export SPRING_PROFILES_ACTIVE=dev
export DB_URL='jdbc:mysql://127.0.0.1:3306/microbe_new?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true'
export DB_USERNAME='root'
export DB_PASSWORD='your_password'
export JWT_ACCESS_SECRET='your_access_secret_at_least_32_chars'
export JWT_REFRESH_SECRET='your_refresh_secret_at_least_32_chars'
export REFRESH_TOKEN_HASH_SECRET='your_refresh_token_hash_secret'

./mvnw spring-boot:run
```

## 自动化测试

项目已支持接口自动化测试（认证、菜单、用户、角色），默认采用 **Web 层测试 + 模拟服务数据** 方案：

- 不依赖本地 MySQL
- 不依赖 Docker
- 通过 `MockMvc` 验证接口状态码、响应体、参数校验、业务异常与边界条件
- 测试执行后会输出“测试结果摘要”（用例、接口、参数、是否通过、HTTP 状态、响应）

### 运行测试

```bash
# 一次运行全部测试
mvn test

# 仅运行认证测试
mvn -Dtest=AuthControllerWebMvcTest test

# 运行菜单、用户、角色测试
mvn -Dtest=MenuControllerWebMvcTest,UserControllerWebMvcTest,RoleControllerWebMvcTest test
```

### 查看测试报告

- 控制台直接查看执行结果与“测试结果摘要”
- 详细报告目录：`target/surefire-reports`

常见报告文件：

- `TEST-*.xml`：CI 解析用
- `*.txt`：失败堆栈与异常详情

### 当前测试覆盖范围（接口层）

- **认证**：注册、登录、刷新、登出；正常/异常/参数边界
- **菜单**：用户菜单、菜单树、详情、创建、更新、删除；校验失败与业务冲突
- **用户**：分页、创建、更新、删除、重置密码、角色分配；越界与非法参数
- **角色**：分页、创建、更新、删除、菜单分配；编码校验与业务保护

## 必填环境变量

- `DB_URL`
- `DB_USERNAME`
- `DB_PASSWORD`
- `JWT_ACCESS_SECRET`
- `JWT_REFRESH_SECRET`
- `REFRESH_TOKEN_HASH_SECRET`

> 敏感信息必须通过环境变量注入，不要写入仓库。

## 主要目录

```text
src/main/java/cn/caoerlei/java_example/
├── controller    # 接口层
├── service       # 业务层
├── repository    # 数据访问
├── entity        # 实体映射
├── config        # 安全与过滤器配置
├── exception     # 全局异常处理
├── common        # 通用响应与错误码
├── dto           # 请求对象
└── vo            # 响应对象
```

## 相关文档

- [开发环境启动文档](src/docs/开发环境启动文档.md)
- [JWT 认证方案说明](src/docs/JWT%20认证方案详细说明.md)
- [统一响应格式说明](src/docs/统一响应格式说明.md)
- [菜单路由权限方案详细说明](src/docs/菜单路由权限方案详细说明.md)
- [菜单角色用户管理模块设计方案](src/docs/菜单角色用户管理模块设计方案.md)