# springboot-base-framework **Repository Path**: ck/springboot-base-framework ## Basic Information - **Project Name**: springboot-base-framework - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-07 - **Last Updated**: 2026-06-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SpringBoot 基础框架 > 基于 **Spring Boot 3.x + Jimmer ORM + Spring Security + JWT** 构建的企业级后台管理基础框架。 --- ## 环境要求 | 工具 | 版本 | 说明 | | ----- | ---- | ------------------------------ | | JDK | 17+ | 必须，Spring Boot 3.x 最低要求 | | MySQL | 8.x | 主数据库 | | Redis | 6+ | 缓存 / Token 黑名单 / 限流 | | Maven | 3.8+ | 项目构建 | --- ## 快速启动 ### 1. 初始化中间件(任选一) #### 方式 A:Docker Compose 一键拉起(推荐) 需要本地安装 Docker Desktop / Docker Engine。 ```bash # 1) 复制环境变量样板(默认 root / 空 Redis 密码,与 application-dev.yml 一致,可不改) cp .env.example .env # 2) 一键启动 MySQL 8.0 + Redis 7,schema.sql 会自动导入到 base_framework 库 docker compose up -d # 3) 观察 MySQL 是否就绪 docker compose logs -f mysql # 出现 "ready for connections" 即可 ``` 包含组件: - **MySQL 8.0**(`localhost:3306`,库 `base_framework`,首次启动自动执行 `sql/schema.sql`) - **Redis 7**(`localhost:6379`,AOF 持久化,默认无密码) - 命名卷 `sbf-mysql-data` / `sbf-redis-data` 持久化,`docker compose down -v` 才会清除 #### 方式 B:本地已装 MySQL/Redis ```bash mysql -u root -p < sql/schema.sql ``` Redis 自行启动即可。 ### 2. 配置环境（任选一种） #### 方式 A：修改配置文件（推荐开发环境） 编辑 `framework-app/src/main/resources/application-dev.yml`，修改数据库和 Redis 密码： ```yaml spring: datasource: password: 你的MySQL密码 # 第13行 data: redis: password: 你的Redis密码 # 无密码则留空 ``` #### 方式 B：环境变量（推荐测试/生产环境） ```bash # 设置环境变量后启动，配置文件中使用 ${VAR:default} 引用 export DB_PASSWORD=your_password export REDIS_PASSWORD=your_redis_password export JWT_SECRET=your-256bit-secret-key ``` ### 3. 启动 **命令行（多环境切换）：** ```bash # 开发环境（默认） mvn clean spring-boot:run # 指定环境 mvn spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=dev" java -jar target/springboot-base-framework-1.0.0-SNAPSHOT.jar --spring.profiles.active=prod # 打包后运行 mvn clean package -DskipTests java -jar target/springboot-base-framework-1.0.0-SNAPSHOT.jar --spring.profiles.active=dev ``` **Windows IDEA 中：** 方式一：VM Options（适用于所有配置） 1. `Run` → `Edit Configurations...` 2. 选择或新建一个 `Spring Boot` 运行配置 3. 在 `Build and Run` 中选择 `framework-app` 模块 4. `Environment variables` 中填入所有变量： ``` DB_USERNAME=root;DB_PASSWORD=你的MySQL密码;REDIS_HOST=localhost;REDIS_PORT=6379;REDIS_PASSWORD=;JWT_SECRET=dev-secret-key-do-not-use-in-production-at-least-256-bits ``` 5. `Active profiles` 填入：`dev` > 注意：Windows 环境变量用 `;` 分隔，Unix 系统用 `:` 分隔。 方式二：环境变量文件（更推荐，本地独享） 在 `framework-app/` 目录下新建 `application-env-dev-local.yml`（此文件已加入 `.gitignore`，不会上传）： ```yaml spring: datasource: username: root password: 你的MySQL密码 data: redis: host: localhost port: 6379 password: # 无密码留空 jwt: secret: dev-secret-key-do-not-use-in-production-at-least-256-bits ``` 然后在 IDEA 的 `Active profiles` 填入：`dev,env-dev-local`（`env-dev-local` 优先级更高，会覆盖 dev 中的默认值）。 ### 4. 验证启动 - API 根地址：`http://localhost:8080/api` - Knife4j 文档：`http://localhost:8080/api/doc.html` - OpenAPI JSON：`http://localhost:8080/api/v3/api-docs` ### 默认账号 | 用户名 | 密码 | 角色 | | ------ | --------- | ---------- | | admin | Admin@123 | 超级管理员 | --- ## 多环境配置 配置文件位于 `framework-app/src/main/resources/`： | 文件 | 用途 | SQL日志 | Knife4j | 日志级别 | | ---------------------- | ---------------- | ------- | ------- | -------- | | `application.yml` | 公共基础配置 | - | - | - | | `application-dev.yml` | 开发环境（默认） | ✅ 开启 | ✅ 开启 | debug | | `application-test.yml` | 测试环境 | ❌ 关闭 | ✅ 开启 | info | | `application-prod.yml` | 生产环境 | ❌ 关闭 | ❌ 关闭 | warn | ### 生产环境必须配置的环境变量 ```bash # 数据库 DB_HOST=prod-db.internal DB_PORT=3306 DB_NAME=base_framework DB_USERNAME=prod_user DB_PASSWORD= # Redis REDIS_HOST=prod-redis.internal REDIS_PORT=6379 REDIS_PASSWORD= REDIS_DATABASE=0 # JWT（必须使用强随机密钥，至少256位） JWT_SECRET= # 可选 SYSTEM_CAPTCHA_ENABLED=true LOG_LEVEL=warn KNIFE4J_ENABLE=false ``` --- ## 部署指南 ### JAR 打包部署 > 后端 JAR **不包含**前端资源。`framework-ui` 是独立的前端工程，生产环境由 Nginx 单独托管 `framework-ui/dist/`，并反向代理后端 API（见下方 Nginx 配置）。 ```bash mvn clean package -DskipTests # 上传到服务器 scp target/springboot-base-framework-1.0.0-SNAPSHOT.jar user@server:/opt/app/ # 生产环境启动（推荐使用 systemd） nohup java -Xms512m -Xmx1024m \ -jar springboot-base-framework-1.0.0-SNAPSHOT.jar \ --spring.profiles.active=prod \ > app.log 2>&1 & # 或使用 systemd 服务（/etc/systemd/system/springboot-app.service） ``` ### Nginx 反向代理配置（前后端分离部署） ```nginx server { listen 80; server_name your-domain.com; # 前端静态资源 location / { root /var/www/springboot-vue-framework/dist; try_files $uri $uri/ /index.html; } # 后端 API 代理 location /api { proxy_pass http://127.0.0.1:8080/api; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket 支持（如有） proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } ``` ### Docker 部署（可选） ```dockerfile FROM eclipse-temurin:17-jre-alpine COPY target/springboot-base-framework-1.0.0-SNAPSHOT.jar app.jar COPY sql/schema.sql /docker-entrypoint-initdb.d/ EXPOSE 8080 ENTRYPOINT ["java", "-jar", "/app.jar", "--spring.profiles.active=prod"] ``` ```bash docker build -t springboot-base-framework:latest . docker run -d -p 8080:8080 \ -e SPRING_PROFILES_ACTIVE=prod \ -e DB_PASSWORD=xxx \ -e REDIS_PASSWORD=xxx \ -e JWT_SECRET=xxx \ --name sbf-backend \ springboot-base-framework:latest ``` --- ## 项目结构 ``` springboot-base-framework/ ├── framework-common/ # 公共基础模块 │ └── src/main/java/com/example/framework/common/ │ ├── annotation/ # 自定义注解（@Log, @DataScope） │ ├── config/ # 配置类（Redis、Knife4j） │ ├── constant/ # 常量定义 │ ├── exception/ # 异常处理（BusinessException, GlobalExceptionHandler） │ ├── result/ # 统一响应（R, ResultCode） │ └── utils/ # 工具类（JwtUtils） ├── framework-system/ # 业务系统模块 │ └── src/main/java/com/example/framework/ │ ├── common/ # 系统级公共代码（SecurityConfig, JwtFilter, LogAspect） │ └── system/ # 核心业务 │ ├── controller/ # 接口层（Auth, User, Dept, Role, Menu） │ ├── domain/ # Jimmer 不可变实体 │ ├── dto/ # 数据传输对象 │ ├── repository/ # Jimmer Repository │ └── service/ # 业务层 ├── framework-app/ # 启动入口模块 │ └── src/main/java/com/example/framework/ │ └── FrameworkApplication.java ├── framework-ui/ # 前端模块（Vue + TDesign） │ └── ... ├── sql/ │ └── schema.sql # 单文件 schema(开发阶段;接入 Flyway 后拆为 V*__*.sql) └── pom.xml # 父聚合 POM ``` > ⚠️ **Jimmer ORM 首次编译**：IDE 会报红（找不到 `XxxDraft`、`XxxTable` 类），这是正常的 APT 生成延迟。执行一次 `mvn compile` 即可生成所有辅助类，刷新 IDE 项目后错误消失。 --- ## API 响应格式 所有接口统一返回： ```json { "code": 200, "msg": "操作成功", "data": {} } ``` | code | 含义 | | ---- | ------------------- | | 200 | 成功 | | 400 | 参数错误 | | 401 | 未认证 / Token 过期 | | 403 | 无权限 | | 404 | 资源不存在 | | 500 | 服务器内部错误 | 分页响应： ```json { "code": 200, "msg": "success", "data": { "total": 100, "list": [] } } ``` --- ## 核心功能模块 | 模块 | 接口前缀 | 说明 | | ---- | --------------- | -------------------------------- | | 认证 | `/auth/` | 登录 / 登出 / 验证码 / 刷新Token | | 用户 | `/system/user/` | CRUD + 状态切换 + 重置密码 | | 部门 | `/system/dept/` | 树形结构 + CRUD | | 角色 | `/system/role/` | CRUD + 菜单权限分配 | | 菜单 | `/system/menu/` | 树形结构 + 目录/菜单/按钮管理 | --- ## Jimmer ORM 注意事项 本框架使用 [Jimmer ORM](https://babyfish-ct.github.io/jimmer-doc/zh/)： - **不可变实体**：通过 APT 编译期生成 `Draft`、`Table`、`Fetcher` 等辅助类 - **类型安全查询**：`JSqlClient` + 自动生成的 `Table` 类进行动态条件查询 - **关联映射**：支持 `@ManyToOne`、`@OneToMany`、`@ManyToMany` - **分页查询**：`fetchPage(pageIndex, pageSize)` 返回 `Page` - **草稿 API**：`XxxDraft.$.produce(base, draft -> {...})` 函数式修改不可变对象 --- ## Git 分支规范 ``` main # 主分支（生产环境） develop # 开发分支 feature/xxx # 功能分支 hotfix/xxx # 热修复分支 release/xxx # 发布分支 ``` **Commit 规范：** | 前缀 | 用途 | | ----------- | ------------- | | `feat:` | 新功能 | | `fix:` | 修复 bug | | `docs:` | 文档更新 | | `refactor:` | 代码重构 | | `chore:` | 构建/工具变更 | | `perf:` | 性能优化 | --- ## License MIT