# java-boilerplate

**Repository Path**: sunlightzxl/java-boilerplate

## Basic Information

- **Project Name**: java-boilerplate
- **Description**: java脚手架
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业级管理平台脚手架

## 项目简介

企业级管理平台是一个基于SpringBoot 2.7.x和Vue 2.6.14的前后端分离脚手架工程，提供完整的RBAC权限管理、用户管理、组织机构管理、菜单管理、操作日志等核心功能，为快速开发企业级应用提供标准化基础架构。

## 技术栈

### 后端技术栈
- **JDK**: 1.8.0_202
- **SpringBoot**: 2.7.18
- **Spring Security**: 5.7.x (JWT鉴权)
- **MyBatis**: 3.5.13
- **MySQL**: 5.7+
- **Redis**: 6.x
- **Maven**: 3.6+
- **Lombok**: 1.18.30
- **Hutool**: 5.8.22
- **JWT**: 0.11.5
- **Fastjson**: 2.0.43

### 前端技术栈（独立项目）
- **Vue**: 2.6.14
- **Vue Router**: 3.5.x
- **Vuex**: 3.6.x
- **Element UI**: 2.15.13
- **Axios**: 0.27.2

## 项目结构

```
enterprise-management-platform/
├── enterprise-common/          # 通用模块
│   ├── constant/              # 常量定义
│   ├── exception/             # 异常处理
│   ├── result/               # 统一响应结果
│   └── utils/                # 工具类
├── enterprise-server/          # 服务主模块
│   ├── config/               # 配置类
│   └── EnterpriseApplication.java  # 启动类
├── enterprise-rbac/           # RBAC模块
│   ├── entity/               # 实体类（用户、组织、菜单、角色、权限）
│   ├── mapper/               # MyBatis Mapper
│   ├── service/              # 服务层
│   └── controller/           # 控制器
├── enterprise-auth/           # 认证模块
│   ├── entity/               # 实体类（操作日志）
│   ├── mapper/               # MyBatis Mapper
│   ├── service/              # 认证和日志服务
│   └── controller/           # 认证和日志控制器
├── enterprise-web/            # 前端项目
│   ├── src/                  # 源代码
│   ├── public/               # 静态资源
│   └── package.json          # 依赖配置
├── scripts/                   # 启动脚本
│   ├── windows/              # Windows启动脚本
│   │   ├── start-backend.bat      # 后端启动脚本(支持dev/prod参数)
│   │   ├── start-frontend.bat     # 前端启动脚本
│   │   ├── stop-backend.bat       # 后端停止脚本
│   │   ├── stop-frontend.bat      # 前端停止脚本
│   │   └── stop-all.bat           # 一键停止脚本
│   └── linux/                # Linux启动脚本
│       ├── start-backend.sh       # 后端启动脚本(支持dev/prod参数)
│       ├── start-frontend.sh      # 前端启动脚本
│       ├── stop-backend.sh        # 后端停止脚本
│       ├── stop-frontend.sh       # 前端停止脚本
│       └── stop-all.sh            # 一键停止脚本
├── logs/                      # 日志目录
│   ├── app.pid               # 后端PID文件
│   ├── frontend.pid          # 前端PID文件
│   ├── backend.log           # 后端日志
│   └── frontend.log          # 前端日志
└── docs/                     # 文档目录
    ├── database/            # 数据库文档
    ├── api/                 # API接口文档
    └── deployment/          # 部署文档
```

## 核心功能

### 1. 用户管理
- 用户注册（手机/邮箱）
- 用户登录/登出
- 用户信息管理
- 密码修改和重置
- 用户状态管理

### 2. 组织机构管理
- 树形组织机构管理
- 部门CRUD操作
- 用户-部门关联
- 组织层级管理

### 3. RBAC权限管理
- 菜单管理（左侧菜单栏）
- 角色管理
- 权限点管理
- 用户-角色关联
- 角色-菜单关联
- 角色-权限关联

### 4. 认证授权
- JWT令牌管理
- 权限验证拦截器
- 接口权限控制
- 数据权限控制
- Spring Security集成
- 自定义权限注解

### 5. 操作日志
- 操作记录
- 日志查询
- 日志导出
- 日志清理

## 鉴权机制

### 认证流程
```
用户登录 → 验证用户名密码 → 生成JWT令牌 → 返回令牌
          ↓
后续请求携带令牌 → JWT过滤器验证 → 设置认证上下文 → 访问受保护资源
```

### 授权机制
- **方法级权限控制**：使用 `@PreAuthorize` 注解
- **自定义权限注解**：使用 `@RequirePermission` 注解
- **权限表达式**：支持 `hasAuthority()`、`isAuthenticated()` 等

### 公开接口
以下接口无需认证即可访问：
- `/auth/login` - 用户登录
- `/auth/register` - 用户注册
- `/auth/captcha` - 验证码
- `/swagger-ui/**` - Swagger文档
- `/actuator/**` - 监控端点

### 权限注解使用

#### Spring Security 标准注解
```java
@PreAuthorize("hasAuthority('user:create')")
public Result<Boolean> createUser(@RequestBody UserEntity user) {
    // 只有拥有 user:create 权限的用户才能访问
}

@PreAuthorize("isAuthenticated()")
public Result<List<MenuEntity>> getUserMenuTree(@PathVariable Long userId) {
    // 已登录用户才能访问
}
```

#### 自定义权限注解
```java
@RequirePermission("user:delete")
public Result<Boolean> deleteUser(@PathVariable Long id) {
    // 需要特定权限才能访问
}
```

### 权限标识规范
```yaml
user:create    # 创建用户
user:update    # 更新用户
user:delete    # 删除用户
user:view      # 查看用户
user:reset     # 重置用户密码
role:create    # 创建角色
role:update    # 更新角色
role:delete    # 删除角色
role:view      # 查看角色
role:assign    # 分配角色
menu:create    # 创建菜单
menu:update    # 更新菜单
menu:delete    # 删除菜单
menu:view      # 查看菜单
org:create     # 创建组织
org:update     # 更新组织
org:delete     # 删除组织
org:view       # 查看组织
```

### 安全特性
| 特性 | 说明 |
|--------|------|
| **JWT令牌** | 无状态认证，支持分布式部署 |
| **令牌刷新** | 支持访问令牌和刷新令牌双令牌机制 |
| **密码加密** | BCrypt加密存储密码 |
| **CORS支持** | 支持跨域请求 |
| **CSRF防护** | 禁用CSRF（JWT不需要） |
| **会话管理** | 无状态会话（STATELESS） |

### 配置说明
```yaml
jwt:
  secret: enterprise-management-platform-secret-key-2026  # JWT密钥
  expiration: 86400000  # 访问令牌过期时间（毫秒）
```

## 快速开始

### 环境要求
- JDK 1.8+
- MySQL 5.7+
- Redis 6.x+
- Maven 3.6+

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd enterprise-management-platform
```

2. **创建数据库**
```bash
mysql -u root -p < docs/database/init.sql
```

3. **修改配置**
编辑 `enterprise-server/src/main/resources/application-dev.yml`，修改数据库和Redis连接信息：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/enterprise_db
    username: your_username
    password: your_password
  redis:
    host: localhost
    port: 6379
```

4. **编译项目**
```bash
mvn clean install
```

5. **启动项目**

**方式一：使用启动脚本（推荐）**

Windows系统：
```bash
# 启动后端服务（默认开发环境）
scripts\windows\start-backend.bat

# 启动开发环境
scripts\windows\start-backend.bat dev

# 启动生产环境
scripts\windows\start-backend.bat prod

# 启动前端服务
scripts\windows\start-frontend.bat
```

Linux系统：
```bash
# 添加执行权限
chmod +x scripts/linux/*.sh

# 启动后端服务（默认开发环境）
./scripts/linux/start-backend.sh

# 启动开发环境
./scripts/linux/start-backend.sh dev

# 启动生产环境
./scripts/linux/start-backend.sh prod

# 启动前端服务
./scripts/linux/start-frontend.sh
```

**方式二：手动启动**
```bash
# 开发环境
cd enterprise-server
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 生产环境
cd enterprise-server
mvn clean package -Dmaven.test.skip=true
java -jar target/enterprise-server-1.0.0.jar --spring.profiles.active=prod
```

**方式三：通过环境变量指定环境**
```bash
# Windows
set SPRING_PROFILES_ACTIVE=prod
java -jar enterprise-server-1.0.0.jar

# Linux/Mac
export SPRING_PROFILES_ACTIVE=prod
java -jar enterprise-server-1.0.0.jar
```

**停止服务**

Windows系统：
```bash
# 一键停止所有服务
scripts\windows\stop-all.bat

# 或单独停止
scripts\windows\stop-backend.bat   # 停止后端
scripts\windows\stop-frontend.bat  # 停止前端
```

Linux系统：
```bash
# 一键停止所有服务
./scripts/linux/stop-all.sh

# 或单独停止
./scripts/linux/stop-backend.sh   # 停止后端
./scripts/linux/stop-frontend.sh  # 停止前端
```

**PID文件说明**
- 后端PID文件：`logs/app.pid`
- 前端PID文件：`logs/frontend.pid`
- 日志文件目录：`logs/`

6. **访问接口文档**
浏览器访问：http://localhost:8080/api/swagger-ui/index.html

### 默认账号
- 用户名：admin
- 密码：admin123

## API接口

### 认证接口
- POST `/api/auth/login` - 用户登录
- POST `/api/auth/logout` - 用户登出
- POST `/api/auth/refresh` - 刷新令牌
- GET `/api/auth/validate` - 验证令牌

### 用户管理接口
- POST `/api/user/create` - 创建用户
- PUT `/api/user/update` - 更新用户
- DELETE `/api/user/delete/{id}` - 删除用户
- GET `/api/user/get/{id}` - 查询用户
- GET `/api/user/list` - 查询用户列表
- GET `/api/user/page` - 分页查询用户
- POST `/api/user/change-password` - 修改密码
- POST `/api/user/reset-password` - 重置密码

### 鉴权机制
详细的鉴权机制说明请参考：[鉴权机制API文档](docs/api/security-api.md)

## 开发指南

### 代码规范
- 遵循阿里巴巴Java开发规范
- 使用Lombok简化代码
- 统一异常处理
- 统一日志格式
- 所有代码添加中文JavaDoc注释

### 调用链路
```
HTTP请求 → Controller → Service接口 → ServiceImpl → Mapper接口 → Mapper XML → 数据库
```

### 响应格式
```json
{
  "code": "0000",
  "message": "成功",
  "data": {},
  "timestamp": 1646640000000
}
```

### 错误码规范
- 0000: 成功
- 1000-1999: 用户相关错误
- 2000-2999: 权限相关错误
- 3000-3999: 数据相关错误
- 4000-4999: 系统相关错误
- 5000-5999: 业务相关错误

## 部署指南

### 开发环境
```bash
mvn spring-boot:run -Dspring.profiles.active=dev
```

### 生产环境
```bash
mvn clean package -Dmaven.test.skip=true
java -jar enterprise-server/target/enterprise-server-1.0.0.jar --spring.profiles.active=prod
```

## 文档

- [数据库设计文档](docs/database/schema.md)
- [API接口文档](docs/api/)
- [部署指南](docs/deployment/)
- [工程结构文档](.idea/steering/工程结构.md)

## 常见问题

### 1. 数据库连接失败
- 检查MySQL服务是否启动
- 检查数据库连接配置是否正确
- 检查数据库用户权限

### 2. Redis连接失败
- 检查Redis服务是否启动
- 检查Redis连接配置是否正确

### 3. JWT令牌无效
- 检查令牌是否过期
- 检查令牌格式是否正确
- 检查密钥配置是否一致

## 联系方式

- 项目负责人: 企业平台开发团队
- 邮箱: dev@enterprise.com

## 许可证

MIT License