# pcm-springboot-foundation

**Repository Path**: XuWuJing/pcm-springboot-foundation

## Basic Information

- **Project Name**: pcm-springboot-foundation
- **Description**: 一个轻量级、基础框架的Springboot项目，适合项目的初版框架
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PCM SpringBoot Foundation

> 一个纯净、轻量、开箱即用的 Spring Boot 2.x 基础框架项目。

## 简介

`pcm-springboot-foundation` 的目标不是把所有技术一次性堆进来，而是先沉淀一套能长期演进的基础工程：

- 默认使用 `SQLite`，本地零依赖即可启动
- 核心保留 `Spring Boot + Web + MyBatis + Flyway + Cache + Auth` 这一条最常用链路
- 预留 MySQL、PostgreSQL、多数据源、MongoDB、Elasticsearch、Redis、Kafka、RocketMQ、Spring Cloud 的扩展边界
- 同时兼顾服务端模板渲染和前后端分离场景

当前仓库已经具备直接作为新项目基础工程的能力，而不是停留在一个只有配置文件的空壳脚手架。

**核心特性：**

- Spring Boot `2.7.18`
- SQLite 默认数据源，Flyway 自动迁移
- MyBatis 数据访问与统一分页模型
- Caffeine 本地缓存
- Sa-Token 轻量认证骨架
- 默认管理员初始化
- Swagger / OpenAPI 接口文档
- Actuator 健康检查与基础监控
- 统一响应结构、全局异常处理、TraceId 透传
- 跨域配置与前后端联调支持
- MockMvc 集成测试与 HTTP 调试示例

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 2.7.18 | 应用框架 |
| MyBatis | 2.3.2 | 关系型数据库访问 |
| Dynamic Datasource | 3.5.2 | 多数据源扩展边界 |
| Flyway | 9.22.3 | 数据库版本迁移 |
| SQLite JDBC | 3.45.3.0 | 默认本地数据库 |
| Caffeine | 跟随 Spring Boot | 默认本地缓存 |
| Sa-Token | 1.28.0 | 登录态管理 |
| Spring Security Crypto | 5.7.x | BCrypt 密码加密 |
| Springdoc OpenAPI | 1.8.0 | 接口文档 |
| Thymeleaf | 跟随 Spring Boot | 服务端模板 |
| Actuator | 跟随 Spring Boot | 健康检查与监控端点 |

## 快速开始

### 环境要求

- JDK 8+
- Maven 3.6+

### 方式一：SQLite 模式（推荐首次体验）

```bash
git clone https://gitee.com/XuWuJing/pcm-springboot-foundation.git
cd pcm-springboot-foundation

mvn clean package -DskipTests
java -jar target/pcm-springboot-foundation-0.1.0-SNAPSHOT.jar
```

默认启动后：

- 服务地址：`http://localhost:8080`
- 接口文档：`http://localhost:8080/swagger-ui.html`
- OpenAPI JSON：`http://localhost:8080/v3/api-docs`
- 健康检查：`http://localhost:8080/actuator/health`

SQLite 数据文件默认生成在：

```text
./data/foundation.db
```

### 方式二：MySQL / PostgreSQL 模式

项目已经内置对应配置模板和 Flyway 迁移脚本。

#### MySQL

先修改：

```text
src/main/resources/application-mysql.yml
```

然后启动：

```bash
java -jar target/pcm-springboot-foundation-0.1.0-SNAPSHOT.jar --spring.profiles.active=mysql
```

#### PostgreSQL

先修改：

```text
src/main/resources/application-postgresql.yml
```

然后启动：

```bash
java -jar target/pcm-springboot-foundation-0.1.0-SNAPSHOT.jar --spring.profiles.active=postgresql
```

### 方式三：按需启用扩展依赖

基础运行态默认尽量轻，只在需要时再通过 Maven Profile 增加中间件依赖。

示例：

```bash
mvn clean package -Pwith-redis
mvn clean package -Pwith-mongodb
mvn clean package -Pwith-elasticsearch
mvn clean package -Pwith-kafka
mvn clean package -Pwith-rocketmq
mvn clean package -Pwith-spring-cloud
```

## 使用指南

### 默认管理员

项目首次启动后会自动初始化一个管理员账号：

- 用户名：`admin`
- 密码：`Admin@123456`

对应配置：

```yaml
app:
  foundation:
    auth:
      bootstrap-admin:
        enabled: true
        username: admin
        password: Admin@123456
        display-name: Foundation Admin
```

建议真实环境接入后第一时间改为自己的管理员信息，或者初始化完成后关闭自动初始化。

### 第一步：查看系统信息

```bash
curl http://localhost:8080/api/system/info
```

这个接口会返回：

- 当前应用名
- 默认数据源与缓存类型
- TraceId 请求头名
- Swagger 地址
- 认证是否启用
- 默认初始化管理员用户名

### 第二步：登录获取 Token

```bash
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"Admin@123456\"}"
```

登录成功后会返回：

- `tokenName`
- `tokenPrefix`
- `tokenValue`
- `authorizationValue`

后续直接把 `authorizationValue` 放到请求头即可：

```http
Authorization: Bearer xxxxxxxxxx
```

### 第三步：查询当前登录用户

```bash
curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer <token>"
```

### 第四步：创建用户

```bash
curl -X POST http://localhost:8080/api/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"demo\",\"displayName\":\"示例用户\",\"password\":\"Demo@123456\",\"enabled\":true}"
```

### 第五步：分页查询用户

```bash
curl "http://localhost:8080/api/users?pageNum=1&pageSize=10&keyword=demo" \
  -H "Authorization: Bearer <token>"
```

### 第六步：退出登录

```bash
curl -X POST http://localhost:8080/api/auth/logout \
  -H "Authorization: Bearer <token>"
```

### Swagger 调试

项目已经接入 OpenAPI 3，并增加了 Bearer Token 安全方案。

调试步骤：

1. 打开 `http://localhost:8080/swagger-ui.html`
2. 先调用 `/api/auth/login`
3. 复制返回结果里的 `authorizationValue`
4. 点击 Swagger 页面上的 `Authorize`
5. 粘贴 `Bearer xxx` 后调试其他受保护接口

### HTTP 调试示例

仓库已经提供 HTTP Client 示例文件：

```text
docs/http/foundation-api.http
```

适合直接在 IntelliJ IDEA / WebStorm / VS Code REST Client 中打开调试，里面已经覆盖：

- 系统信息
- 健康检查
- 登录
- 当前用户
- 创建用户
- 分页查询用户
- 用户详情
- 退出登录

## 核心接口

### 系统与认证接口

| 接口 | 方法 | 说明 | 是否需要登录 |
|------|------|------|------|
| `/api/system/info` | GET | 查看框架元信息 | 否 |
| `/api/auth/login` | POST | 登录 | 否 |
| `/api/auth/me` | GET | 获取当前登录用户 | 是 |
| `/api/auth/logout` | POST | 退出登录 | 是 |

### 用户示例接口

| 接口 | 方法 | 说明 | 是否需要登录 |
|------|------|------|------|
| `/api/users` | GET | 分页查询用户 | 是 |
| `/api/users/{username}` | GET | 按用户名查询用户 | 是 |
| `/api/users` | POST | 创建用户 | 是 |

### 监控接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/actuator/health` | GET | 健康检查 |
| `/actuator/info` | GET | 自定义应用信息 |
| `/actuator/metrics` | GET | 运行时指标 |

## 项目结构

```text
pcm-springboot-foundation/
├── data/                                      # SQLite 本地数据文件
├── docs/
│   └── http/
│       └── foundation-api.http               # HTTP 调试示例
├── src/main/java/com/pcm/foundation/
│   ├── common/
│   │   ├── exception/                        # 业务异常
│   │   └── web/                              # 统一响应、分页、TraceId、异常处理
│   ├── config/                               # 配置绑定、认证、OpenAPI、Web 配置
│   ├── controller/                           # REST / MVC 入口
│   ├── domain/                               # 领域对象
│   ├── mapper/                               # MyBatis Mapper
│   ├── query/                                # 查询模型
│   ├── service/                              # 服务接口
│   └── service/impl/                         # 服务实现
├── src/main/resources/
│   ├── application.yml                       # 主配置
│   ├── application-local.yml                 # SQLite 本地配置
│   ├── application-test.yml                  # 测试配置
│   ├── application-mysql.yml                 # MySQL 配置模板
│   ├── application-postgresql.yml            # PostgreSQL 配置模板
│   ├── application-multi-datasource.yml      # 多数据源配置模板
│   ├── application-redis.yml                 # Redis 配置模板
│   ├── application-mongodb.yml               # MongoDB 配置模板
│   ├── application-elasticsearch.yml         # Elasticsearch 配置模板
│   ├── application-kafka.yml                 # Kafka 配置模板
│   ├── application-rocketmq.yml              # RocketMQ 配置模板
│   ├── application-cloud.yml                 # Spring Cloud 配置模板
│   ├── db/migration/                         # Flyway 迁移脚本
│   └── templates/                            # Thymeleaf 页面
├── src/test/java/com/pcm/foundation/         # 集成测试
├── pom.xml
└── README.md
```

## 配置说明

### 核心配置项

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `spring.profiles.active` | `local` | 默认运行环境，走 SQLite |
| `spring.datasource.dynamic.primary` | `master` | 主数据源名称 |
| `spring.flyway.locations` | `classpath:db/migration/sqlite` | 默认 Flyway 迁移目录 |
| `spring.cache.type` | `caffeine` | 默认缓存实现 |
| `sa-token.token-name` | `Authorization` | Token 请求头名 |
| `sa-token.token-prefix` | `Bearer` | Token 前缀 |
| `app.foundation.auth.enabled` | `true` | 是否启用接口鉴权 |
| `app.foundation.auth.include-paths` | `/api/**` | 需要鉴权的路径 |
| `app.foundation.request-log.trace-header-name` | `X-Trace-Id` | TraceId 请求头名 |
| `app.foundation.request-log.slow-request-threshold-ms` | `1000` | 慢请求阈值 |
| `app.foundation.cors.allowed-origins` | `localhost:3000/5173` | 本地联调跨域来源 |

### 默认放行的公开路径

项目默认对 `/api/**` 开启登录校验，但以下路径默认公开：

- `/api/auth/login`
- `/api/system/info`
- `/swagger-ui.html`
- `/swagger-ui/**`
- `/v3/api-docs/**`
- `/actuator/health`
- `/actuator/info`
- `/actuator/metrics`

### 扩展配置文件

运行时配置模板：

- `application-local.yml`
- `application-mysql.yml`
- `application-postgresql.yml`
- `application-multi-datasource.yml`
- `application-redis.yml`
- `application-mongodb.yml`
- `application-elasticsearch.yml`
- `application-kafka.yml`
- `application-rocketmq.yml`
- `application-cloud.yml`

## 数据库与迁移

### 默认数据库策略

- 默认主数据源：`SQLite`
- 默认连接串：`jdbc:sqlite:./data/foundation.db`
- 默认迁移目录：`db/migration/sqlite`

这样做的目的只有一个：确保项目在新机器上不依赖 MySQL、Redis、MQ，也能先跑起来。

### 已包含的 Flyway 迁移

#### SQLite

- `V1__init_demo_user.sql`
- `V2__add_auth_columns.sql`

#### MySQL

- `V1__init_demo_user.sql`
- `V2__add_auth_columns.sql`

#### PostgreSQL

- `V1__init_demo_user.sql`
- `V2__add_auth_columns.sql`

`V2` 主要补齐了认证骨架所需字段：

- `password`
- `enabled`
- `updated_at`
- `last_login_at`

### 多数据源说明

仓库已经预留：

```text
src/main/resources/application-multi-datasource.yml
```

示例里给出了 `master + reporting` 的结构，但默认没有启用 Flyway。

原因很直接：

- 单数据源需要先保证稳定可运行
- 多数据源迁移策略必须按业务单独设计
- 样例从库不应该拖垮整个基础工程

## 测试说明

### 运行测试

```bash
mvn test
```

### 只跑当前集成测试类

```bash
mvn -Dtest=FoundationApplicationTests test
```

### 当前已覆盖的测试场景

- 应用上下文启动
- Flyway 自动迁移
- `/api/system/info` 元数据输出
- `/actuator/info` 自定义信息输出
- 登录成功
- 登录失败
- 禁用用户登录失败
- 未登录访问受保护接口被拦截
- TraceId 请求头复用
- 参数校验失败
- 当前登录用户查询
- 退出登录后访问失效
- 用户创建
- 用户分页查询
- 用户详情查询
- 重复用户冲突处理
- 密码字段不对外暴露
- OpenAPI 文档接口
- 跨域预检请求

### 调试示例

除了 JUnit 集成测试之外，仓库还提供了可直接执行的 HTTP 示例文件：

```text
docs/http/foundation-api.http
```

如果你想做接口联调，比起手工拼 `curl`，这个文件更省事。

## 扩展能力

### 运行时配置扩展

项目已经预留以下扩展方向：

- MySQL / PostgreSQL
- 多数据源
- Redis
- MongoDB
- Elasticsearch
- Kafka
- RocketMQ
- Spring Cloud
- Vue / React 等前端框架联调

### Maven Profile 扩展依赖

| Profile | 作用 |
|------|------|
| `with-redis` | 引入 Redis 依赖 |
| `with-mongodb` | 引入 MongoDB 依赖 |
| `with-elasticsearch` | 引入 Elasticsearch 依赖 |
| `with-kafka` | 引入 Kafka 依赖 |
| `with-rocketmq` | 引入 RocketMQ 依赖 |
| `with-spring-cloud` | 引入 Spring Cloud Bootstrap / LoadBalancer |

## 常见问题

### 没有 MySQL 能启动吗？

可以。默认就是 SQLite 模式，零外部依赖可运行。

### 没有 Redis 能启动吗？

可以。默认缓存是 Caffeine，本地即可运行。

### 如何切换到 PostgreSQL？

修改 `application-postgresql.yml` 后，启动时指定：

```bash
--spring.profiles.active=postgresql
```

### 如何调试完整接口流程？

建议优先用这两种方式：

1. `Swagger UI`
2. `docs/http/foundation-api.http`

这两种方式比手写请求更直观。

### 默认管理员密码是否每次启动都会重置？

不会。

当前逻辑是：

- 没有 `admin` 用户时自动创建
- 老数据缺少密码字段时自动补齐
- 已经存在且结构完整时，不会每次覆盖你的密码

### 多数据源是不是已经能直接用于生产？

还不是。

当前仓库只是把多数据源边界预留出来了，真正上线前仍然需要你根据业务补：

- 数据源切换策略
- 每个数据源的迁移策略
- 事务边界
- 读写分离或报表库约定

## 版本

| 版本 | 说明 |
|------|------|
| v0.1.0 | 基础骨架、SQLite、缓存、分页、Swagger、Actuator |
| v0.2.0 | 登录认证骨架、Flyway 认证字段迁移、中文文档、HTTP 示例、增强测试 |

## 开源协议

MIT License