# spring-vip-starter

**Repository Path**: heyevan/spring-vip-starter

## Basic Information

- **Project Name**: spring-vip-starter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# spring-vip-starter

基于 [spring-vip-framework](https://github.com/liuwei01/spring-vip-framework)（`com.vip.framework`，parent `2.7.18-SNAPSHOT`，Java 8）搭建的多模块基础应用脚手架，作为新业务项目的起步模板。框架能力全部来自依赖，不复制框架代码。

## 模块说明

| 模块 | 说明 |
|---|---|
| `starter-admin` | 启动模块：`StarterApplication`、`application.yml`、全局异常处理 `GlobalExceptionHandler`、MyBatis-Plus 配置 `MybatisPlusConfig`，唯一 `spring-boot-maven-plugin` 打包模块 |
| `starter-common` | 通用能力：错误码常量 `ErrorCode`（统一返回复用框架 `com.vip.framework.common.R`） |
| `starter-biz` | 业务示例：MyBatis-Plus 持久化 + Redisson 缓存/分布式锁（实体/Mapper/Service/Controller） |
| `starter-idaas` | IDaaS SSO 客户端：依赖 `vip-framework-starter-idaas-client-satoken`，SSO 登录 + token 验证示例 |
| `starter-ui` | 前端工程（Vue3 + Element Plus + Vite），独立 npm 工程，不参与 Maven reactor |

## 技术栈

- Spring Boot 2.7.18 / Java 8
- MyBatis-Plus 3.5.5（框架基类/拦截器）
- Redisson 3.25.2（缓存注解 `@RedisCacheable` / `@RedisCacheEvict`、分布式锁 `@RedisLock`）
- IDaaS SSO（Sa-Token JWT 混入 Mixin，前端主导 OAuth2 带 state）
- SkyWalking 链路追踪（框架 `vip-framework-starter-trace-skywalking`：VipTracer SPI + 线程池 trace 传递；logback 输出 traceId）
- Logback（logback-spring.xml：控制台 + 滚动文件 + 异步）
- Vue3 + Element Plus + Vite + Vue Router + Pinia + Axios

## 后端启动

```bash
# 1. 全量编译（必须 clean，避免 target 残留）
mvn clean compile -DskipTests

# 2. 安装到本地 .m2（供 spring-boot:run 使用）
mvn install -DskipTests

# 3. 启动（local profile）
mvn spring-boot:run -pl starter-admin -Dspring-boot.run.profiles=local
# 或打包后运行
java -jar starter-admin/target/starter-admin-1.0.0-SNAPSHOT.jar --spring.profiles.active=local
```

本地联调环境变量（DB 从 `~/.claude/.env.local` 的 `IWMS_TEST_217_56_*` 读取；Redis 密码 `phoenix_admin` 通过 `REDIS_PASSWORD` 注入，不落明文）：

```bash
set -a && . ~/.claude/.env.local && set +a
export REDIS_HOST=172.31.217.56 REDIS_PORT=6379 REDIS_PASSWORD=phoenix_admin REDIS_DATABASE=0
```

端口：后端 `8081`（8080 被 IDaaS server 占用）。

## 前端启动

```bash
cd starter-ui
npm install
npm run dev        # http://localhost:2048，/api 代理到 http://localhost:8081
```

## 依赖引入说明

框架坐标均由 `vip-framework-parent` 的 dependencyManagement 管理版本，应用内无需写版本号：

| 依赖 | 引入位置 | 用途 |
|---|---|---|
| `vip-framework-starter`（聚合） | `starter-common` | 基础能力：common/lang/spring-core（Jackson/线程池/actuator/openapi） |
| `vip-framework-starter-redisson` | `starter-common` | Redisson 缓存/锁自动配置 |
| `vip-framework-starter-mybatis` | `starter-biz` / `starter-admin` | MyBatis-Plus 基类/分页拦截器/审计填充（需自建 `@MapperScan` 与分页插件） |
| `vip-framework-starter-eventbus-starter` / `-mybatis` | `starter-biz` | 事件总线：SchemaManager 自动建表 + MyBatis 仓储实现（VipEvents 记录事件） |
| `vip-framework-starter-idaas-client-satoken` | `starter-idaas` | IDaaS SSO 客户端（配置 `idaas.client.server-url` 激活 `/api/idaas/app/*`） |
| `mysql-connector-java` | `starter-admin` | MySQL 驱动 |
| `vip-framework-starter-trace-skywalking` | `starter-common` | SkyWalking 链路追踪：VipTracer SPI + 线程池 trace 传递（传递引入 apm-toolkit-trace 与 apm-toolkit-logback-1.x，logback 布局按需使用） |

## 已验证能力

- 健康检查 actuator `/actuator/health`、OpenAPI `/v3/api-docs`、swagger-ui
- 示例 CRUD `/api/biz/*`（新增/分页/详情(Redis 缓存)/修改/删除 + `/api/biz/lock/{id}` 分布式锁；分页查询 `/api/biz/page` 会经事件总线异步记录事件）
- IDaaS SSO 登录：`/sso/login` 发起 → IDaaS server 授权 → `/sso/callback` 换 token → 存 token 跳首页

## 日志与 SkyWalking 链路追踪

- 日志配置：`starter-admin/src/main/resources/logback-spring.xml`（控制台 + 滚动文件 + 异步），文件输出到 `./logs/`（`sys-info.log` / `sys-error.log` / `sys-console.log`）
- 日志格式含 `[%tid]`（SkyWalking traceId）：未挂 agent 输出为空，挂 agent 后自动输出当前链路 traceId
- 链路追踪：框架 `vip-framework-starter-trace-skywalking` 提供 `VipTracer` SPI（`traceId()`/`wrap()`/`startNewSpan()`）与线程池 trace 上下文传递
- 挂载 SkyWalking agent 启动（可选，OAP 地址由启动参数注入）：
  ```bash
  java -javaagent:/path/to/skywalking-agent.jar \
       -Dskywalking.agent.service_name=starter-admin \
       -Dskywalking.collector.backend_service=<OAP 地址>:11800 \
       -jar starter-admin/target/starter-admin-1.0.0-SNAPSHOT.jar
  ```

## 环境配置说明

- 数据源/Redis：`application.yml` 用 `${DB_HOST}`/`${REDIS_HOST}` 等占位符；`application-local.yml` 本地联调引用 `IWMS_TEST_217_56_*`，无明文密码
- 示例表：Flyway 迁移 `db/migration/V1__ddl_init_starter_schema.sql` 创建 `starter_schema` 表
- SSO：需在 IDaaS server（ruoyi-plus-flowable）注册客户端 `starter-demo`（`idaas_app_metadata` 表，migration `V20260728_003`）