# platform-base

**Repository Path**: alenzhai/platform-base

## Basic Information

- **Project Name**: platform-base
- **Description**: 微服务基础框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Platform Base · 企业级 SaaS 多租户全栈基础框架

基于 **Spring Cloud Alibaba + MyBatis Plus + ShardingSphere-JDBC** 的后端微服务脚手架，配套 **Vue3 + Element Plus** 管理后台。集成 **Nacos / Gateway / Sentinel / Dubbo / Seata / Redis**，并内置**多租户数据隔离**与**乐观锁**范式。

---

## 1. 架构概览

```
浏览器 / web-admin(Vue3)
      │  HTTP + JWT(Bearer)
      ▼
platform-gateway  (路由 + JWT校验 + Redis黑名单 + X-Tenant-Id注入 + Sentinel网关流控)
      │  /auth/**  /user/**+ /tenant/**  /order/**
      ▼
┌─────────────┬─────────────┬─────────────┐
│ platform-auth│ platform-user│ platform-order│
└──────┬──────┴──────┬──────┴──────┬──────┘
       │ Dubbo@Ref   │ Dubbo@Ref   │ Dubbo@Ref
       │────────────►│             │─────────►│
       │             │ @GlobalTransactional (Seata)
       │             │◄────────────│
   Redis(黑名单/用户缓存)   MySQL(主从, ShardingSphere读写分离)   Nacos(注册/配置)
                                                        Seata TC(分布式事务)
```

| 模块 | 端口 | 职责 |
| --- | --- | --- |
| platform-gateway | 8080 | 唯一入口：鉴权、黑名单、租户头注入、Sentinel 网关流控 |
| platform-auth | 9200 | 登录校验（Dubbo 调 user）→ 写 Redis 缓存 → 签发 JWT；登出/踢人 |
| platform-user | 9201 | Dubbo Provider + HTTP CRUD + 租户 CRUD + ShardingSphere 读写分离 |
| platform-order | 9202 | 下单演示：Dubbo 调 user + `@GlobalTransactional` 跨服务事务 |
| platform-common | — | 统一响应/异常/JWT/Redis/多租户工具 |
| platform-api | — | Dubbo 接口与共享 DTO |

---

## 2. 技术栈

- Java 17 · Maven 多模块父子工程
- Spring Boot 2.7.18 · Spring Cloud 2021.0.5 · Spring Cloud Alibaba 2021.0.5.0
- 注册/配置：Nacos 2.x
- 网关：Spring Cloud Gateway + Sentinel 网关流控适配器
- 内部 RPC：**Dubbo 3.x**（注册中心复用 Nacos）
- 限流/熔断：Sentinel（网关 + 各服务 `@SentinelResource`）
- 分布式事务：Seata（AT 模式，TC 由 docker-compose 提供）
- 持久层：MyBatis Plus 3.5.5（多租户 + 分页 + 乐观锁 + 自动填充）
- 分库分表：ShardingSphere-JDBC 5.4.1（读写分离启用 + 分库分表注释模板）
- 缓存/登录态：Redis 7 + `spring-boot-starter-data-redis` + lettuce
- 安全：jjwt 0.11.5 + BCrypt
- 前端：Vite 5 + Vue3.4 + TypeScript + Element Plus 2.7 + Vue Router 4 + Pinia 2 + Axios

---

## 3. 目录结构

```
platform-base/
├── pom.xml                  # 父工程，统一依赖版本
├── docker-compose.yml       # Nacos / MySQL / Redis / Seata（Sentinel 可选）
├── sql/
│   ├── user_db.sql          # 业务库：tenant / sys_user / t_order / undo_log + 种子
│   └── seata.sql            # Seata Server 库表（db 模式参考）
├── platform-common/         # 公共：R / 异常 / JWT / Redis / 多租户
├── platform-api/            # Dubbo 接口与 DTO
├── platform-gateway/        # 网关
├── platform-auth/           # 认证服务
├── platform-user/           # 用户/租户业务服务
├── platform-order/          # 订单业务服务
└── web-admin/               # 前端 Vue3 工程
```

---

## 4. 快速开始

### 4.1 启动基础设施（Docker）

```bash
docker-compose up -d
```

启动：Nacos(8848) · MySQL(3306) · Redis(6379) · Seata(8091)。
（Sentinel-Dashboard 默认注释，按需放开。）

> 本机未安装 Docker 时，可另行安装 MySQL/Redis/Nacos/Seata，并把各服务 `*.yml` 中的
> `NACOS_ADDR / REDIS_HOST / MYSQL_* / JWT_SECRET` 等环境变量指向你的实例。

### 4.2 初始化数据库

MySQL 容器已挂载 `./sql` 目录自动执行 `user_db.sql`（建库 `platform`、建表、种子数据）。
手动执行：在 `platform` 库执行 `sql/user_db.sql` 即可。

默认管理员：**admin / 123456**（密码 BCrypt 加密，种子数据已写入）。

### 4.3 启动后端（IDE 或 Maven）

建议启动顺序：Nacos → Gateway → Auth → User → Order。

```bash
# 各模块分别运行 Application，或整体打包
mvn clean package -DskipTests
java -jar platform-gateway/target/platform-gateway-1.0.0.jar &
java -jar platform-auth/target/platform-auth-1.0.0.jar &
java -jar platform-user/target/platform-user-1.0.0.jar &
java -jar platform-order/target/platform-order-1.0.0.jar &
```

### 4.4 启动前端

```bash
cd web-admin
npm install
npm run dev        # http://localhost:3000
```

前端通过 Vite 代理把 `/api` 转发到网关 `http://localhost:8080`。
浏览器打开 `http://localhost:3000`，使用 `admin / 123456` 登录。

---

## 5. 关键设计

### 5.1 多租户隔离（共享库共享表 + `tenant_id` 行级）

- 策略：业务表增加 `tenant_id` 列；MyBatis Plus `TenantLineInnerInterceptor` 自动拼接 `tenant_id = ?`。
- 平台表 `tenant` 在忽略列表，不参与过滤；超级租户（tenant_id = 0 / PLATFORM）跳过过滤，可跨租户管理。
- 上下文透传：
  - HTTP：网关注入 `X-Tenant-Id` 头 → 服务 `TenantInterceptor` 写入 `TenantContext`。
  - Dubbo：`TenantDubboFilter`（@Activate 双向）经 `RpcContext` attachment 透传。
  - 写入：`TenantMetaObjectHandler` 在 insert 时自动填充 `tenant_id`。
- 如需更强隔离，可改为 ShardingSphere 按租户分库（本脚手架已留分库分表模板）。

### 5.2 Redis 登录态（JWT 黑名单 + 用户/权限缓存）

| Key | 内容 | TTL |
| --- | --- | --- |
| `auth:token:blacklist:{jti}` | "" | token 剩余有效期 |
| `auth:user:{userId}` | UserDTO(JSON) | 与 token 对齐 |
| `auth:user:tokens:{userId}` | Set\<jti\> | 与 token 对齐 |

- 登录：Dubbo 校验用户 → 写用户缓存 → 生成含 `jti/tenantId` 的 JWT。
- 网关每请求：验签 + 查黑名单（命中 → 401）+ 注入 `X-User-Id/X-Username/X-Tenant-Id`。
- 登出 `/auth/logout`：当前 jti 进黑名单 + 清缓存。
- 强制下线 `/auth/kick/{userId}`：该用户所有 jti 进黑名单 + 清空。
- 优点：无状态 JWT 验签不查库；Redis 仅一次 O(1) 黑名单查询；用户缓存减少每次鉴权的 Dubbo/DB 调用；支持服务端主动作废 token。

### 5.3 Sentinel 限流/熔断

- 网关：`sentinel-spring-cloud-gateway-adapter` 路由级流控，被限流返回 429 JSON。
- 服务：核心方法加 `@SentinelResource`（如 auth 登录），支持降级。
- 规则可经 Nacos 动态下发；`docker-compose` 含 Sentinel-Dashboard（可选，端口 8080）。

### 5.4 Seata 分布式事务（AT 模式）

- `platform-order` 的 `createOrder` 标记 `@GlobalTransactional`：写 `t_order` + Dubbo 调 user 增加下单次数（分支事务）。
- 任一环节抛异常，两个服务**同时回滚**。前端「订单演示」页勾选「模拟失败」即可观察回滚。
- Seata `tx-service-group` 对齐为 `my_test_tx_group`（Seata 默认分组），TC 由 docker-compose 提供。

### 5.5 ShardingSphere 读写分离 + 分库分表模板

- `platform-user` 已启用读写分离（write=master，read=slave，负载均衡 ROUND_ROBIN）。
- `UserService.readFromMaster()` 演示用 `HintManager` 强制读主（主从延迟场景）。
- 分库分表以 `application.yml` 注释模板保留，放开即生效。
- 本地开发默认从库指向同一 MySQL 实例，开箱即用；接真实从库时调整 `MYSQL_SLAVE_*` 环境变量并放开 `docker-compose` 中 `mysql-slave`。

### 5.6 乐观锁（@Version）

- 全局启用 `OptimisticLockerInnerInterceptor`；仅在 `Order` 实体加 `@Version` 作为示例范式。
- 其他表按需加 `@Version` 字段即可生效，避免无谓开销。

### 5.7 Dubbo 内部 RPC

- 注册中心复用 Nacos。`platform-user` 用 `@DubboService` 暴露 `UserRpcService`；`auth`/`order` 用 `@DubboReference` 调用。
- 租户上下文经 `TenantDubboFilter` 跨服务透传。

---

## 6. 注意事项

1. 生产环境务必在 Nacos 中修改 `jwt.secret`（各服务保持一致）与数据库密码。
2. Seata 若关闭 `enable-auto-data-source-proxy`，需自行包裹数据源；与 ShardingSphere 共存时代理顺序已按推荐配置。
3. 多租户下，超级管理员（PLATFORM 租户）跨租户操作会跳过租户过滤——生产可按需在业务层补充租户归属校验。
4. 本脚手架在 Windows 下验证代码结构与配置；完整运行依赖 Docker 启动 Nacos/MySQL/Redis/Seata。
5. SQL 表结构建议在 `docker-compose up` 后用 MySQL 客户端（或通过 MCP MySQL 工具）校验 `tenant/sys_user/t_order/undo_log` 及 `tenant_id` 列。
```