# frame_parent

**Repository Path**: therefore-and/frame_parent

## Basic Information

- **Project Name**: frame_parent
- **Description**: 后端搭建
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-12-02
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Frame Parent - 企业级后端开发脚手架

## 项目简介

Frame Parent 是一个基于 Spring Boot 3.x 的企业级后端开发脚手架，提供了完整的基础设施和开箱即用的功能模块，帮助开发者快速构建高质量的企业应用。

### 核心特性

- 🚀 基于 Spring Boot 3.4.5 + JDK 21，拥抱最新技术栈
- 🔐 完善的权限管理体系（RBAC 模型）
- 📦 模块化设计，高内聚低耦合
- 🛠️ 开箱即用的基础设施（Redis、MyBatis-Plus、Security）
- 📝 完善的代码生成器，提升开发效率
- 🔄 支持多数据源动态切换
- 📊 集成 Druid 监控，实时掌握数据库性能
- 🎯 统一异常处理和响应格式

## 技术栈

### 后端框架

| 技术                 | 版本      | 说明        |
|--------------------|---------|-----------|
| Spring Boot        | 3.4.5   | 应用框架      |
| Spring Security    | 6.x     | 安全框架      |
| MyBatis-Plus       | 3.5.8   | ORM 框架    |
| Dynamic Datasource | 4.3.1   | 多数据源      |
| Redisson           | 3.x     | Redis 客户端 |
| Druid              | 1.2.23  | 数据库连接池    |
| Knife4j            | 4.x     | API 文档    |
| Hutool             | 5.8.26  | 工具类库      |
| MapStruct          | 1.6.2   | 对象映射      |
| Lombok             | 1.18.34 | 简化代码      |

### 数据库

- MySQL 8.0+
- Redis 5.0+

### 开发工具

- JDK 21
- Maven 3.8+
- Git

## 项目结构

```
frame_parent/
├── frame-dependencies/              # 依赖版本管理（BOM）
├── frame-framework/                 # 框架层
│   ├── module-common/               # 通用模块（工具类、常量、异常等）
│   ├── frame-spring-boot-starter-mybatis/    # MyBatis 增强
│   ├── frame-spring-boot-starter-redis/      # Redis 缓存
│   ├── frame-spring-boot-starter-security/   # 安全认证
│   ├── frame-spring-boot-starter-web/        # Web 增强
│   └── frame-spring-boot-starter-test/       # 测试支持
├── frame-module-infra/              # 基础设施模块
│   ├── frame-module-infra-api/      # 基础设施 API
│   └── frame-module-infra-server/   # 基础设施实现
├── frame-module-system/             # 系统管理模块
│   ├── frame-module-system-api/     # 系统 API
│   └── frame-module-system-server/  # 系统实现
└── frame-server/                    # 应用启动模块
```

## 模块说明

### frame-dependencies

依赖版本统一管理模块，采用 BOM（Bill of Materials）方式管理所有第三方依赖版本，确保版本一致性。

### frame-framework

框架层，提供各种开箱即用的 Starter：

- **module-common**：通用工具类、常量、枚举、异常定义
- **frame-spring-boot-starter-mybatis**：MyBatis-Plus 增强，提供通用 Mapper、字段自动填充、多数据源等
- **frame-spring-boot-starter-redis**：Redis 缓存支持，提供 RedisTemplate、缓存注解等
- **frame-spring-boot-starter-security**：Spring Security 集成，提供认证、授权、Token 验证等
- **frame-spring-boot-starter-web**：Web 增强，提供统一响应、异常处理、参数校验等
- **frame-spring-boot-starter-test**：测试支持

### frame-module-infra

基础设施模块，提供文件存储、短信、邮件等基础服务。

### frame-module-system

系统管理模块，提供用户、角色、权限、菜单、部门、字典等核心功能。

### frame-server

应用启动模块，整合所有模块，提供统一的启动入口。

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.8+
- MySQL 8.0+
- Redis 5.0+

### 安装步骤

1. **克隆项目**

```bash
git clone https://gitee.com/your-repo/frame_parent.git
cd frame_parent
```

2. **创建数据库**

```sql
CREATE DATABASE `frame-pro` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

3. **导入数据库脚本**

```bash
# 执行 SQL 脚本
mysql -u root -p frame-pro < script/sql/init.sql
```

4. **修改配置文件**

编辑 `frame-server/src/main/resources/application-local.yaml`：

```yaml
spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://localhost:3306/frame-pro?useSSL=false&serverTimezone=Asia/Shanghai
          username: root
          password: your-password
  data:
    redis:
      host: localhost
      port: 6379
      password: your-redis-password
```

5. **启动项目**

```bash
# 方式一：Maven 启动
mvn clean install
cd frame-server
mvn spring-boot:run

# 方式二：IDE 启动
# 直接运行 frame-server 模块的 Application 主类
```

6. **访问应用**

- 后端接口：http://localhost:1205
- API 文档：http://localhost:1205/doc.html
- Druid 监控：http://localhost:1205/druid

### 默认账号

- 管理员：admin / admin123

## 核心功能

### 用户管理

- 用户列表、新增、编辑、删除
- 用户角色分配
- 用户状态管理
- 密码重置

### 角色管理

- 角色列表、新增、编辑、删除
- 角色权限分配
- 角色数据权限

### 菜单管理

- 菜单列表、新增、编辑、删除
- 菜单权限配置
- 菜单图标管理

### 部门管理

- 部门树形结构
- 部门新增、编辑、删除

### 字典管理

- 字典类型管理
- 字典数据管理

### 租户管理

- 租户列表、新增、编辑、删除
- 租户套餐管理

## 开发规范

### Git 提交规范

#### 分支命名

- **master 分支**：主分支，用于部署到生产环境，需要确保 master 分支的稳定性。master 分支一般由 release 以及 hotfix
  分支合并，任何时间都不能直接修改代码
- **develop 分支**：开发分支，始终保持最新完成以及 bug 修复后的代码、用于前后端联调。一般开发新功能时，feature 分支都是基于
  develop 分支创建的
- **feature/xxx 分支**：功能分支，用于开发新功能，命名可自行定义，只要以 feature/ 开头，后面加上开发的功能模块名称
    - 命名示例：`feature/frame-framework/frame-common/新增功能`
- **test 分支**：测试分支，用于测试环境，一般由 develop 分支合并，不建议直接在 test 分支上直接修改代码
- **release/xxx 分支**：预发布分支，UAT 测试阶段使用，一般由 test 或者 hotfix 分支合并，不建议直接在 release 分支上直接修改代码
- **hotfix 分支**：线上出现紧急问题时，需要及时修复，以 master 分支为基线，创建 hotfix 分支。修复完成后，需要合并到 master 分支和
  develop 分支
    - 命名示例：以 hotfix/ 开头的为修复分支，它的命名规则与 feature 分支类似

#### Commit 消息规范

采用 Angular 规范：

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型：**

- `feat`: 新功能
- `fix`: 修复 Bug
- `docs`: 文档更新
- `style`: 代码格式调整（不影响代码运行）
- `refactor`: 重构（既不是新增功能，也不是修复 Bug）
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动

**示例：**

```bash
feat(user): 新增用户导出功能

- 支持导出 Excel
- 支持自定义导出字段

Closes #123
```

#### 分支与环境对应关系

| 环境  | 说明       | 对应分支      |
|-----|----------|-----------|
| DEV | 开发环境     | feature/* |
| FAT | 功能验收测试环境 | develop   |
| UAT | 用户验收测试环境 | release/* |
| PRE | 预生产环境    | release/* |
| PRO | 生产环境     | master    |

### 包命名规范

- **格式**：域名反转 `com.zwf.project`
- **基础组件**：`com.zwf.framework`
- **业务组件**：`com.zwf.module`

**包结构示例：**

```
com.zwf.module.system
├── controller      # 控制器层
├── service         # 服务层
│   └── impl        # 服务实现
├── mapper          # 数据访问层
├── entity          # 实体类
│   ├── dto         # 数据传输对象
│   ├── vo          # 视图对象
│   └── query       # 查询对象
├── convert         # 对象转换
├── enums           # 枚举
└── constants       # 常量
```

### 代码风格规范

#### 基础编码规范

- 遵循 Oracle 官方 Java 编码规范
- 阿里巴巴 Java 开发手册
- Google Java Style Guide

#### 命名规范

**类命名：**

- Controller：`XxxController`
- Service：`XxxService` / `XxxServiceImpl`
- Mapper：`XxxMapper`
- Entity：`XxxDO`（数据库对象）
- DTO：`XxxDTO`（数据传输对象）
- VO：`XxxVO`（视图对象）
- Query：`XxxQuery`（查询对象）

**方法命名：**

- 获取单个对象：`getXxx`
- 获取列表：`listXxx`
- 分页查询：`pageXxx`
- 新增：`createXxx`
- 更新：`updateXxx`
- 删除：`deleteXxx`
- 校验：`validateXxx`

#### 注释规范

**类注释：**

```java
/**
 * 用户服务实现类
 *
 * @author 周文锋
 * @since 2025-01-01
 */
public class UserServiceImpl implements UserService {
}
```

**方法注释：**

```java
/**
 * 根据用户 ID 获取用户信息
 *
 * @param id 用户 ID
 * @return 用户信息
 */
public UserVO getUser(Long id) {
}
```

### 数据库规范

#### 表命名

- 小写字母，单词间用下划线分隔
- 表名前缀：业务模块名
- 示例：`sys_user`、`sys_role`、`sys_menu`

#### 字段命名

- 小写字母，单词间用下划线分隔
- 布尔类型字段：`is_xxx`
- 时间字段：`xxx_time`
- 示例：`user_name`、`is_deleted`、`create_time`

#### 必备字段

所有表必须包含以下字段：

```sql
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
creator VARCHAR(64) COMMENT '创建者',
updater VARCHAR(64) COMMENT '更新者',
deleted BIT NOT NULL DEFAULT 0 COMMENT '是否删除'
```

## 部署说明

### 打包

```bash
# 清理并打包
mvn clean package -DskipTests

# 打包结果
frame-server/target/frame-server.jar
```

### 部署方式

#### 方式一：直接运行 JAR

```bash
java -jar frame-server.jar --spring.profiles.active=prod
```

#### 方式二：Docker 部署

```dockerfile
FROM openjdk:21-jdk-slim
WORKDIR /app
COPY frame-server.jar app.jar
EXPOSE 1205
ENTRYPOINT ["java", "-jar", "app.jar"]
```

```bash
# 构建镜像
docker build -t frame-server:1.0 .

# 运行容器
docker run -d -p 1205:1205 \
  -e SPRING_PROFILES_ACTIVE=prod \
  --name frame-server \
  frame-server:1.0
```

#### 方式三：Docker Compose

```yaml
version: '3.8'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: frame-pro
    ports:
      - "3306:3306"
    volumes:
      - ./mysql-data:/var/lib/mysql

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  app:
    image: frame-server:1.0
    depends_on:
      - mysql
      - redis
    ports:
      - "1205:1205"
    environment:
      SPRING_PROFILES_ACTIVE: prod
```

### 配置文件

生产环境配置 `application-prod.yaml`：

```yaml
server:
  port: 1205

spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://mysql:3306/frame-pro?useSSL=false&serverTimezone=Asia/Shanghai
          username: root
          password: ${MYSQL_PASSWORD}
  data:
    redis:
      host: redis
      port: 6379
      password: ${REDIS_PASSWORD}

logging:
  level:
    root: INFO
    com.zwf: INFO
  file:
    name: logs/frame-server.log
```

## 常见问题

### 1. 启动失败：端口被占用

```bash
# 查看端口占用
netstat -ano | findstr 1205

# 修改端口
# 编辑 application.yaml，修改 server.port
```

### 2. 数据库连接失败

检查配置：

- 数据库地址、端口是否正确
- 用户名、密码是否正确
- 数据库是否已创建
- 防火墙是否开放端口

### 3. Redis 连接失败

检查配置：

- Redis 地址、端口是否正确
- Redis 密码是否正确
- Redis 服务是否启动

### 4. 编译失败：找不到符号

```bash
# 清理并重新编译
mvn clean install -U
```

## 性能优化建议

### 数据库优化

1. 合理使用索引
2. 避免 SELECT *
3. 使用分页查询
4. 开启慢 SQL 日志监控

### 缓存优化

1. 合理设置缓存过期时间
2. 使用缓存预热
3. 避免缓存穿透、击穿、雪崩

### 代码优化

1. 使用异步处理耗时操作
2. 合理使用线程池
3. 避免大事务
4. 使用批量操作

## 技术文档

- [MyBatis Starter 文档](frame-framework/frame-spring-boot-starter-mybatis/README.md)
- [Redis Starter 文档](frame-framework/frame-spring-boot-starter-redis/README.md)
- [Security Starter 文档](frame-framework/frame-spring-boot-starter-security/README.md)

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

### 贡献指南

- 遵循项目的代码规范
- 提交前运行测试确保通过
- 提供清晰的 Commit 消息
- 更新相关文档

## 开源协议

本项目采用 Apache License 2.0 开源协议

## 联系方式

- 作者：周文锋
- 邮箱：1405377877@qq.com
- Gitee：https://gitee.com/therefore-and/

## 更新日志

### v1.0.0 (2025-01-14)

- 初始版本发布
- 完成基础框架搭建
- 实现用户、角色、权限管理
- 集成 MyBatis-Plus、Redis、Security
- 支持多数据源
- 完善 API 文档

---

**如果这个项目对你有帮助，请给个 Star ⭐**