pigx-standard 服务迁移总体规划

一、迁移背景

将独立的 SpringBlade 单体应用 standard_info_backend 整合到 PigX 微服务架构中，作为 pigx-standard 子服务。

原项目信息

• 项目路径: E:\project\java\布雷德boot\standard_info_backend
• 框架: SpringBlade 3.0.1 (基于Spring Boot 2.7.1)
• 架构: 单体应用
• 包名: org.springblade
• Java版本: 1.8

目标项目信息

• 服务名: pigx-standard
• 框架: PigX 5.8.0 (基于Spring Boot 3.4.5, Spring Cloud 2024.0.0)
• 架构: 微服务
• 包名: com.pig4cloud.pigx.standard
• Java版本: 17
• 服务端口: 6064

二、迁移目标

1. 服务集成

• ✅ 作为子服务启动，注册到 Nacos (pigx-register:8848)
• ✅ 通过 Gateway (9999端口) 访问服务
• ✅ 支持 Feign 服务间通信

2. 基础设施替换

• 🔄 鉴权体系: SpringBlade → PigX Security (基于pigx-common-security)
• 🔄 权限管理: SpringBlade → PigX UPMS (pigx-upms服务)
• 🔄 数据权限: SpringBlade → PigX Data Scope
• 🔄 租户体系: SpringBlade TenantEntity → PigX BaseEntity (com.pig4cloud.pigx.audit.entity.BaseEntity)

3. 实体类字段处理

• 🔄 保留原有 BaseEntity/TenantEntity 字段作为冗余
• 🔄 添加新的 BaseEntity 字段
• 🔄 使用 @TenantTable 注解标记租户表
• 🔄 后续根据业务逐步调整

三、核心差异对比

1. BaseEntity 字段对比

SpringBlade BaseEntity (原项目)

- Long id
- LocalDateTime createTime
- Long createUser
- LocalDateTime updateTime
- Long updateUser
- Integer status
- Integer isDeleted

PigX BaseEntity (目标项目)

- Long id (ASSIGN_ID)
- Long tenantId (租户ID，自动填充)
- String delFlag (删除标记，逻辑删除)
- String createBy (创建人)
- LocalDateTime createTime (创建时间)
- String updateBy (更新人)
- LocalDateTime updateTime (更新时间)
- Long createUserId (创建用户ID)
- Long updateUserId (修改用户ID)
- Long createDeptId (创建部门ID)
- Long updateDeptId (修改部门ID)

2. 租户注解对比

SpringBlade

@TableName(value = "table_name", tenantIdColumn = "tenant_id")

PigX

@TenantTable  // 自定义注解
@TableName("table_name")

3. 鉴权体系对比

功能	SpringBlade	PigX
用户服务	blade-user	pigx-upms
安全模块	blade-core-secure	pigx-common-security
权限注解	@PreAuth	@PreAuthorize
用户获取	SecureUtil.getUser()	SecurityUtils.getUser()
租户获取	BladeUser.getTenantId()	TenantContextHolder.getTenantId()

四、迁移策略

阶段一：基础框架适配（已完成）

• ✅ 创建 pigx-standard 服务骨架
• ✅ 配置 Maven 依赖
• ✅ 配置 Nacos 注册和配置中心
• ✅ 配置 Docker 打包

阶段二：实体类迁移（待执行）

• 🔄 复制 BaseEntity 到 pigx-standard-api
• 🔄 迁移所有实体类，继承新的 BaseEntity
• 🔄 保留原有字段作为冗余
• 🔄 添加 @TenantTable 注解

阶段三：业务代码迁移（待执行）

• 🔄 迁移 Service 层代码
• 🔄 迁移 Controller 层代码
• 🔄 迁移 Mapper 和 XML 文件
• 🔄 调整包名和导入

阶段四：安全集成（待执行）

• 🔄 移除 SpringBlade 安全依赖
• 🔄 集成 pigx-common-security
• 🔄 调整用户获取方式
• 🔄 调整权限注解

阶段五：接口适配（待执行）

• 🔄 Gateway 路由配置
• 🔄 Feign 接口定义
• 🔄 API 文档整合 (Swagger/Knife4j)

阶段六：测试验证（待执行）

• 🔄 单元测试迁移
• 🔄 集成测试
• 🔄 端到端测试

五、风险点和注意事项

1. 技术栈差异

• ⚠️ Java 8 → Java 17：语法兼容性
• ⚠️ Spring Boot 2.7 → 3.4：API 变更
• ⚠️ MyBatis Plus 版本差异

2. 数据兼容性

• ⚠️ 租户ID字段类型可能不同
• ⚠️ 删除标记字段类型不同 (Integer → String)
• ⚠️ 用户ID字段名称变化 (createUser → createUserId)

3. 业务逻辑

• ⚠️ 权限校验逻辑需要重新测试
• ⚠️ 数据权限过滤需要验证
• ⚠️ 租户隔离需要确保正确

4. 性能考虑

• ⚠️ Feign 调用相比本地调用有性能损耗
• ⚠️ 网关路由增加一跳
• ⚠️ 需要评估是否需要缓存优化

六、回滚方案

1. 保留原项目代码不删除
2. 数据库使用独立 schema 或表前缀
3. 可以随时切换回原服务
4. 使用 feature toggle 控制新旧服务切换

七、迁移时间线

建议按照以下顺序逐步迁移，每个阶段完成后进行充分测试：

1. 第一周: 实体类迁移 + BaseEntity 适配
2. 第二周: 业务代码迁移 + 安全集成
3. 第三周: 接口适配 + Gateway 配置
4. 第四周: 全面测试 + 问题修复
5. 第五周: 灰度发布 + 监控

八、关键文件清单

需要创建的文件

• [ ] 02-BaseEntity迁移指南.md
• [ ] 03-实体类迁移清单.md
• [ ] 04-Service层迁移指南.md
• [ ] 05-Controller层迁移指南.md
• [ ] 06-安全集成指南.md
• [ ] 07-Gateway路由配置.md
• [ ] 08-Feign接口定义.md
• [ ] 09-测试验证清单.md
• [ ] 10-常见问题FAQ.md

九、负责人和联系方式

阶段	负责人	备注
实体类迁移	-	机械性工作，可批量处理
业务代码迁移	-	需要理解业务逻辑
安全集成	-	需要熟悉两套安全框架
测试验证	-	需要业务人员配合

---

文档版本: v1.0 创建时间: 2025-12-16 最后更新: 2025-12-16 状态: 规划中