34 KiB
34 KiB
references
| references | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
改造模块场景提示词指南
本文档提供完整的提示词模板，用于指导 AI 改造现有模块的架构或逻辑。
目录
场景说明
何时需要改造模块
模块改造通常发生在以下场景：
| 改造类型 | 触发条件 | 典型示例 |
|---|---|---|
| 重构代码结构 | 代码腐化、可维护性差 | 拆分大Service、提取公共组件 |
| 优化性能 | 响应慢、资源消耗高 | 优化数据库查询、引入缓存 |
| 更换技术栈 | 技术升级、框架迁移 | 升级Spring版本、更换ORM框架 |
| 修改业务逻辑 | 需求变更、规则调整 | 修改订单状态流转、调整审批流程 |
| 添加新特性 | 功能扩展、新需求 | 添加多租户支持、增加审计日志 |
改造前置条件
在发起改造前，请确认：
- 已阅读目标模块的 Skill 文档：了解模块的设计理念、架构设计、数据模型
- 已识别改造范围：明确需要修改的文件、表、接口
- 已评估影响面：了解上下游依赖关系
- 已制定回滚方案：确保可安全回退
改造分析框架
在编写改造提示词前，建议按以下框架进行分析：
一、现状分析
1. 当前架构
- 模块分层结构
- 核心类和接口
- 数据表和关系
2. 存在问题
- 性能瓶颈
- 代码坏味道
- 架构缺陷
3. 依赖关系
- 上游调用方
- 下游被调用方
- 外部系统集成
二、目标分析
1. 改造目标
- 要解决什么问题？
- 期望达到什么效果？
2. 约束条件
- 向后兼容性要求
- 性能要求
- 时间约束
3. 成功标准
- 可量化的指标
- 验收条件
三、方案设计
1. 改造方案
- 具体实施步骤
- 技术选型
- 关键代码变更
2. 影响评估
- 接口变更影响
- 数据迁移影响
- 配置变更影响
3. 风险预案
- 潜在风险点
- 应对措施
提示词模板
模板一：改造分析提示词
# 改造分析任务
## 角色定义
你是一个资深的企业级 Java 应用架构师，精通 DDD 领域驱动设计和 Spring Boot 生态。
## 目标模块
模块名称：{模块名}
Skill 文档位置：skills/modules/{模块}/skill-{模块}.yaml
## 改造需求
{详细描述改造需求，包括：}
- 当前存在的问题
- 期望达到的目标
- 约束条件
## 分析要求
请按以下维度进行分析：
### 1. 现状分析
- 分析当前模块的架构设计（参考 Skill 文档的 architecture 部分）
- 识别与改造需求相关的核心类和接口
- 分析数据模型（参考 Skill 文档的 data_model 部分）
### 2. 影响范围评估
- 列出需要修改的文件清单
- 识别受影响的 API 接口（参考 Skill 文档的 communication.apis 部分）
- 识别受影响的上下游模块（参考 Skill 文档的 dependencies 部分）
### 3. 改造方案设计
- 提出改造方案（如涉及设计模式，参考 skills/patterns/ 目录）
- 给出关键代码变更示例
- 说明数据迁移方案（如需要）
### 4. 风险评估
- 列出潜在风险点
- 提出风险应对措施
- 评估改造优先级
## 输出格式
请按以下格式输出分析报告：
```yaml
analysis:
current_state:
architecture: "当前架构描述"
core_components: ["核心组件列表"]
data_model: "相关数据模型"
impact_scope:
files_to_modify: ["文件路径列表"]
apis_affected: ["受影响的API列表"]
modules_affected: ["受影响的模块列表"]
solution:
approach: "改造方案描述"
key_changes:
- file: "文件路径"
change: "变更说明"
code_example: |
// 代码示例
data_migration: "数据迁移方案（如需要）"
risks:
- risk: "风险描述"
probability: "高/中/低"
impact: "高/中/低"
mitigation: "应对措施"
priority: "P0/P1/P2"
### 模板二：代码改造提示词
```markdown
# 代码改造任务
## 改造背景
{描述改造背景，引用分析报告的关键结论}
## 目标模块 Skill 文档
{粘贴相关模块的 Skill 文档内容，或指定文件路径}
## 改造任务
### 任务一：{任务名称}
**目标**：{任务目标}
**涉及文件**：
- `{文件路径1}` - {变更说明}
- `{文件路径2}` - {变更说明}
**实现要求**：
1. 遵循项目代码规范（参考 Skill 文档的 code_patterns 部分）
2. 保持向后兼容性（如需要）
3. 添加必要的单元测试
**期望输出**：
- 完整的代码变更
- 变更说明
### 任务二：{任务名称}
{同上格式}
## 代码规范提醒
在编写代码时，请遵循以下规范：
### Controller 层
```java
@Tag(name = "管理后台 - XXX")
@RestController
@RequestMapping("/xxx")
@Validated
public class XxxController {
// 使用 @PreAuthorize 进行权限控制
// 使用 CommonResult 统一返回
}
Service 层
@Service
@Validated
public class XxxServiceImpl implements XxxService {
// 使用 @Transactional 标记事务方法
// 使用 @Resource 注入依赖
}
数据访问层
@Mapper
public interface XxxMapper extends BaseMapperX<XxxDO> {
// 使用 LambdaQueryWrapper 构建查询
}
异常处理
// 使用统一错误码
throw exception(ERROR_CODE, params);
// 错误码格式：1-XXX-XXX-XXX
验证要求
请提供：
- 关键代码的单元测试用例
- 接口测试的请求示例
- 数据迁移脚本（如需要）
### 模板三：影响评估提示词
```markdown
# 改造影响评估任务
## 改造内容
{描述具体的改造内容}
## 评估维度
### 1. API 兼容性评估
请分析：
- 哪些 API 接口签名会发生变化？
- 是否会导致调用方报错？
- 是否需要版本兼容处理？
### 2. 数据兼容性评估
请分析：
- 数据表结构是否需要变更？
- 历史数据是否需要迁移？
- 是否需要数据回填？
### 3. 配置兼容性评估
请分析：
- 是否需要新增配置项？
- 现有配置是否需要修改？
- 配置迁移方案是什么？
### 4. 性能影响评估
请分析：
- 改造对性能的影响（正面/负面）
- 是否需要性能测试？
- 预期性能指标是什么？
### 5. 运维影响评估
请分析：
- 是否需要重启服务？
- 是否需要停机维护？
- 发布顺序有什么要求？
## 输出格式
```yaml
compatibility_report:
api:
breaking_changes: ["破坏性变更列表"]
compatible_changes: ["兼容性变更列表"]
version_strategy: "版本兼容策略"
data:
schema_changes: ["表结构变更列表"]
migration_required: true/false
migration_script: "迁移脚本路径"
configuration:
new_configs: ["新增配置项列表"]
modified_configs: ["修改配置项列表"]
performance:
impact: "正面/负面/无影响"
test_required: true/false
expected_metrics: "预期性能指标"
operations:
restart_required: true/false
downtime_required: true/false
deployment_sequence: ["发布顺序列表"]
### 模板四：改造计划生成提示词
```markdown
# 改造计划生成任务
## 改造需求
{描述改造需求}
## 分析报告
{引用或粘贴改造分析报告}
## 计划生成要求
请生成详细的改造实施计划，包括：
### 1. 任务分解
将改造任务分解为可执行的最小单元，每个任务包含：
- 任务名称
- 任务描述
- 涉及文件
- 预估工时
- 前置依赖
### 2. 实施顺序
确定任务执行顺序，考虑：
- 依赖关系
- 风险优先级
- 可验证性
### 3. 里程碑定义
定义关键里程碑：
- 里程碑名称
- 验收标准
- 预计完成时间
### 4. 回滚方案
为每个关键步骤制定回滚方案：
- 回滚触发条件
- 回滚操作步骤
- 数据恢复方案
## 输出格式
```yaml
refactor_plan:
tasks:
- id: "T001"
name: "任务名称"
description: "任务描述"
files: ["涉及文件列表"]
estimated_hours: 4
dependencies: ["前置任务ID列表"]
risks: ["风险列表"]
rollback: "回滚方案"
milestones:
- name: "里程碑名称"
tasks: ["包含的任务ID列表"]
acceptance_criteria: "验收标准"
execution_sequence:
- phase: "阶段名称"
tasks: ["任务ID列表"]
duration: "预估时长"
rollback_plan:
trigger_conditions: ["触发条件列表"]
steps: ["回滚步骤列表"]
data_recovery: "数据恢复方案"
### 模板五：代码变更清单生成提示词
```markdown
# 代码变更清单生成任务
## 改造内容
{描述改造内容}
## 相关 Skill 文档
{指定相关模块的 Skill 文档路径}
## 生成要求
请生成完整的代码变更清单，按以下格式：
### 变更清单模板
```yaml
change_list:
summary:
total_files: 0
new_files: 0
modified_files: 0
deleted_files: 0
changes:
# 新增文件
- type: "NEW"
path: "文件路径"
purpose: "文件用途"
module: "所属模块"
layer: "所属层级（controller/service/dal等）"
description: |
详细描述文件内容
dependencies: ["依赖的其他文件"]
tests_required: true/false
# 修改文件
- type: "MODIFY"
path: "文件路径"
purpose: "修改目的"
changes:
- location: "变更位置（类名/方法名）"
before: |
修改前代码
after: |
修改后代码
reason: "修改原因"
compatibility: "兼容性说明"
# 删除文件
- type: "DELETE"
path: "文件路径"
reason: "删除原因"
migration: "功能迁移去向"
database_changes:
- type: "DDL"
sql: "SQL语句"
purpose: "变更目的"
rollback_sql: "回滚SQL"
config_changes:
- file: "配置文件路径"
additions: ["新增配置项"]
modifications: ["修改配置项"]
deletions: ["删除配置项"]
api_changes:
- type: "NEW/MODIFY/DELETE"
endpoint: "API路径"
method: "HTTP方法"
description: "变更说明"
breaking: true/false
---
## 实际示例
### 示例一：将单模块拆分为微服务
**改造需求**：将 `yudao-module-pay` 支付模块拆分为独立的微服务。
**使用提示词**：
```markdown
# 改造分析任务
## 角色定义
你是一个资深的企业级 Java 应用架构师，精通 DDD 领域驱动设计和 Spring Cloud 微服务架构。
## 目标模块
模块名称：pay
Skill 文档位置：skills/modules/pay/skill-pay.yaml
## 改造需求
当前支付模块作为单体应用的一部分运行，需要拆分为独立的微服务，以实现：
1. 独立部署和扩展
2. 与其他业务模块解耦
3. 支持多团队并行开发
约束条件：
- 保持 API 接口向后兼容
- 最小化数据迁移
- 支持灰度发布
## 分析要求
请按以下维度进行分析：
### 1. 现状分析
参考 Skill 文档，分析当前模块的：
- 分层架构设计
- 核心服务组件
- 数据模型设计
- 模块间通信方式
### 2. 微服务拆分方案
- 定义服务边界
- 设计服务间通信方案
- 数据库拆分策略
- 分布式事务方案
### 3. 影响范围评估
- 列出受影响的 API 接口
- 识别需要修改的调用方
- 评估数据迁移工作量
### 4. 实施计划
- 分阶段实施步骤
- 灰度发布方案
- 回滚预案
## 输出格式
按模板一要求的 YAML 格式输出分析报告。
预期分析输出：
analysis:
current_state:
architecture: |
支付模块采用标准分层架构：
- api层：PayOrderApi, PayRefundApi, PayWalletApi
- controller层：PayOrderController, PayRefundController等
- service层：PayOrderServiceImpl, PayRefundServiceImpl等
- dal层：PayOrderMapper, PayRefundMapper等
- framework层：PayClient工厂和策略实现
core_components:
- "PayClient: 支付客户端接口，支持多渠道策略"
- "PayOrderService: 订单核心服务"
- "PayRefundService: 退款核心服务"
- "PayClientFactory: 客户端工厂"
data_model: |
核心表：pay_order, pay_refund, pay_channel, pay_app, pay_wallet
关系：pay_app 1:N pay_channel 1:N pay_order 1:N pay_refund
impact_scope:
files_to_modify:
- "pom.xml: 添加 Spring Cloud 依赖"
- "application.yaml: 添加 Nacos 配置"
- "PayOrderApi.java: 改为 Feign 接口"
- "PayRefundApi.java: 改为 Feign 接口"
apis_affected:
- "PayOrderApi.createOrder: 调用方式从本地改为远程"
- "PayRefundApi.createRefund: 调用方式从本地改为远程"
- "PayWalletApi.addBalance: 需要考虑分布式事务"
modules_affected:
- "yudao-module-order: 通过 PayOrderApi 调用支付模块"
- "yudao-module-member: 通过 PayWalletApi 调用钱包功能"
solution:
approach: |
分阶段微服务拆分方案：
阶段一：基础设施准备
- 添加 Spring Cloud 依赖
- 配置 Nacos 注册中心
- 配置 Sentinel 限流熔断
阶段二：API 层改造
- 将 Api 接口改为 Feign 接口
- 添加 fallback 降级处理
- 保持接口签名不变
阶段三：服务部署
- 独立部署支付服务
- 配置网关路由
- 灰度发布验证
key_changes:
- file: "yudao-module-pay-api/pom.xml"
change: "添加 Spring Cloud OpenFeign 依赖"
code_example: |
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
- file: "PayOrderApi.java"
change: "改为 Feign 接口"
code_example: |
@FeignClient(name = "pay-service", fallback = PayOrderApiFallback.class)
public interface PayOrderApi {
@PostMapping("/rpc/pay/order/create")
CommonResult<Long> createOrder(@RequestBody PayOrderCreateReqDTO reqDTO);
}
- file: "PayOrderApiFallback.java"
change: "新增降级处理类"
code_example: |
@Component
public class PayOrderApiFallback implements PayOrderApi {
@Override
public CommonResult<Long> createOrder(PayOrderCreateReqDTO reqDTO) {
return CommonResult.error("支付服务不可用，请稍后重试");
}
}
data_migration: |
数据库无需迁移，保持现有表结构
仅需配置独立的数据库连接
risks:
- risk: "分布式事务一致性问题"
probability: "高"
impact: "高"
mitigation: "使用 Seata 分布式事务框架，或采用最终一致性方案"
- risk: "服务间调用超时"
probability: "中"
impact: "中"
mitigation: "配置合理的超时时间和重试策略，添加 fallback 降级处理"
- risk: "灰度发布期间数据不一致"
probability: "中"
impact: "高"
mitigation: "采用蓝绿部署，确保流量切换的原子性"
priority: "P1"
示例二：优化数据库查询性能
改造需求：优化 yudao-module-system 模块中用户查询的性能问题。
使用提示词：
# 性能优化改造任务
## 目标模块
模块名称：system
Skill 文档位置：skills/modules/system/skill-system.yaml
## 改造需求
当前用户列表查询接口响应慢（平均 2s+），需要优化：
- 问题现象：分页查询用户列表，关联部门名称显示，响应时间超过 2 秒
- 数据规模：用户表 10 万+ 数据，部门表 1000+ 数据
- 期望目标：响应时间降低到 200ms 以内
约束条件：
- 不能改变接口签名
- 不能影响数据权限功能
## 分析要求
### 1. 性能瓶颈分析
- 分析当前 SQL 执行计划
- 识别慢查询原因
- 评估索引使用情况
### 2. 优化方案设计
- 索引优化建议
- 查询语句优化
- 缓存策略设计
### 3. 影响评估
- 评估优化对现有功能的影响
- 评估缓存一致性问题
## 输出格式
按模板一要求的 YAML 格式输出分析报告。
预期分析输出：
analysis:
current_state:
architecture: |
用户查询流程：
1. Controller 接收分页请求
2. Service 调用 Mapper 查询用户列表
3. Service 循环查询部门名称（N+1 问题）
4. Convert 转换为 VO 返回
core_components:
- "AdminUserMapper: 用户数据访问"
- "DeptApi: 部门信息查询"
- "AdminUserServiceImpl: 用户业务逻辑"
data_model: |
system_users 表：10万+ 数据
system_dept 表：1000+ 数据
关联关系：system_users.dept_id -> system_dept.id
impact_scope:
files_to_modify:
- "AdminUserMapper.java: 优化查询语句"
- "AdminUserServiceImpl.java: 修改查询逻辑"
- "AdminUserPageReqVO.java: 可能需要调整参数"
apis_affected: []
modules_affected: []
solution:
approach: |
性能优化三步走：
1. 索引优化：为 dept_id 添加索引
2. 查询优化：改为 JOIN 查询，避免 N+1 问题
3. 缓存优化：部门信息使用 Redis 缓存
key_changes:
- file: "AdminUserMapper.java"
change: "优化分页查询，使用 JOIN 代替循环查询"
code_example: |
// 优化前：先查用户，再循环查部门
// 优化后：JOIN 查询
@Mapper
public interface AdminUserMapper extends BaseMapperX<AdminUserDO> {
default PageResult<AdminUserDO> selectPage(AdminUserPageReqVO reqVO) {
MPJLambdaWrapper<AdminUserDO> wrapper = new MPJLambdaWrapper<AdminUserDO>()
.selectAll(AdminUserDO.class)
.selectAs(DeptDO::getName, AdminUserDO::getDeptName)
.leftJoin(DeptDO.class, DeptDO::getId, AdminUserDO::getDeptId)
.likeIfPresent(AdminUserDO::getUsername, reqVO.getUsername())
.likeIfPresent(AdminUserDO::getNickname, reqVO.getNickname())
.eqIfPresent(AdminUserDO::getStatus, reqVO.getStatus())
.betweenIfPresent(AdminUserDO::getCreateTime, reqVO.getCreateTime())
.orderByDesc(AdminUserDO::getId);
return selectJoinPage(reqVO, AdminUserDO.class, wrapper);
}
}
- file: "system_users 表索引"
change: "添加 dept_id 索引"
code_example: |
-- 添加索引
CREATE INDEX idx_dept_id ON system_users(dept_id);
-- 复合索引（根据查询条件）
CREATE INDEX idx_status_dept ON system_users(status, dept_id);
- file: "DeptApiImpl.java"
change: "添加 Redis 缓存"
code_example: |
@Service
public class DeptApiImpl implements DeptApi {
@Resource
private DeptService deptService;
@Cacheable(value = "dept", key = "#id")
@Override
public DeptRespDTO getDept(Long id) {
return deptService.getDept(id);
}
@Cacheable(value = "dept:list", key = "#ids.hashCode()")
@Override
public List<DeptRespDTO> getDeptList(Collection<Long> ids) {
return deptService.getDeptList(ids);
}
}
data_migration: "无需数据迁移"
risks:
- risk: "JOIN 查询可能影响数据权限过滤"
probability: "中"
impact: "高"
mitigation: "确保 @DataPermission 注解正确应用于新查询方法"
- risk: "缓存一致性问题"
probability: "中"
impact: "中"
mitigation: "部门修改时清除缓存 @CacheEvict"
- risk: "索引创建期间锁表"
probability: "低"
impact: "中"
mitigation: "在低峰期执行索引创建，或使用 ONLINE DDL"
priority: "P0"
performance_optimization:
before:
response_time: "2000ms+"
sql_count: "N+1"
index_usage: "部分索引"
after:
response_time: "<200ms"
sql_count: "1"
index_usage: "完全索引"
cache_strategy:
type: "Redis + Spring Cache"
ttl: "30 minutes"
eviction: "on update"
示例三：添加多租户支持
改造需求：为 yudao-module-pay 支付模块添加多租户支持。
使用提示词：
# 多租户改造任务
## 目标模块
模块名称：pay
Skill 文档位置：skills/modules/pay/skill-pay.yaml
## 改造需求
当前支付模块不支持多租户，需要改造以支持：
1. 租户数据隔离：不同租户的支付订单完全隔离
2. 租户配置隔离：不同租户可配置不同的支付渠道
3. 租户统计独立：各租户独立的订单统计
约束条件：
- 兼容现有单租户部署模式
- 保持 API 接口不变
- 历史数据需要迁移
## 分析要求
### 1. 多租户架构分析
- 参考 system 模块的 TenantBaseDO 实现
- 分析哪些表需要租户隔离
- 分析哪些数据不需要租户隔离
### 2. 改造方案设计
- 实体类改造
- Mapper 改造
- Service 层改造
- 数据迁移方案
### 3. 影响评估
- API 接口影响
- 数据迁移影响
- 配置变更影响
## 输出格式
按模板一要求的 YAML 格式输出分析报告。
预期分析输出：
analysis:
current_state:
architecture: |
支付模块当前不支持多租户：
- 所有 DO 继承 BaseDO（不含 tenant_id）
- 无租户上下文传递
- 无租户数据隔离
core_components:
- "PayOrderDO: 支付订单实体"
- "PayChannelDO: 支付渠道配置实体"
- "PayAppDO: 支付应用实体"
data_model: |
核心表均无 tenant_id 字段：
pay_order, pay_refund, pay_channel, pay_app, pay_wallet
impact_scope:
files_to_modify:
# 实体类改造
- "PayOrderDO.java: 继承 TenantBaseDO"
- "PayRefundDO.java: 继承 TenantBaseDO"
- "PayChannelDO.java: 继承 TenantBaseDO"
- "PayAppDO.java: 继承 TenantBaseDO"
- "PayWalletDO.java: 继承 TenantBaseDO"
# 数据迁移
- "新增数据迁移脚本"
# 配置文件
- "application.yaml: 添加多租户配置"
apis_affected: []
# API 接口签名不变，租户上下文通过 Header 传递
modules_affected:
- "yudao-module-system: 提供租户上下文"
solution:
approach: |
多租户改造四步走：
1. 实体类改造：DO 继承 TenantBaseDO
2. 数据库改造：添加 tenant_id 字段
3. 历史数据迁移：为现有数据分配租户
4. 测试验证：确保数据隔离正确
key_changes:
- file: "PayOrderDO.java"
change: "继承 TenantBaseDO"
code_example: |
// 改造前
@TableName("pay_order")
@Data
@EqualsAndHashCode(callSuper = true)
public class PayOrderDO extends BaseDO {
// ...
}
// 改造后
@TableName("pay_order")
@Data
@EqualsAndHashCode(callSuper = true)
public class PayOrderDO extends TenantBaseDO {
// ...
}
- file: "PayChannelDO.java"
change: "继承 TenantBaseDO"
code_example: |
// 支付渠道配置需要租户隔离
@TableName("pay_channel")
@Data
@EqualsAndHashCode(callSuper = true)
public class PayChannelDO extends TenantBaseDO {
// ...
}
- file: "数据库迁移脚本"
change: "添加 tenant_id 字段"
code_example: |
-- 为所有表添加 tenant_id 字段
ALTER TABLE pay_order ADD COLUMN tenant_id BIGINT NOT NULL DEFAULT 1 COMMENT '租户编号';
ALTER TABLE pay_refund ADD COLUMN tenant_id BIGINT NOT NULL DEFAULT 1 COMMENT '租户编号';
ALTER TABLE pay_channel ADD COLUMN tenant_id BIGINT NOT NULL DEFAULT 1 COMMENT '租户编号';
ALTER TABLE pay_app ADD COLUMN tenant_id BIGINT NOT NULL DEFAULT 1 COMMENT '租户编号';
ALTER TABLE pay_wallet ADD COLUMN tenant_id BIGINT NOT NULL DEFAULT 1 COMMENT '租户编号';
-- 添加索引
ALTER TABLE pay_order ADD INDEX idx_tenant_id (tenant_id);
ALTER TABLE pay_refund ADD INDEX idx_tenant_id (tenant_id);
ALTER TABLE pay_channel ADD INDEX idx_tenant_id (tenant_id);
ALTER TABLE pay_app ADD INDEX idx_tenant_id (tenant_id);
ALTER TABLE pay_wallet ADD INDEX idx_tenant_id (tenant_id);
-- 历史数据迁移（假设默认租户ID为1）
UPDATE pay_order SET tenant_id = 1 WHERE tenant_id IS NULL;
UPDATE pay_refund SET tenant_id = 1 WHERE tenant_id IS NULL;
UPDATE pay_channel SET tenant_id = 1 WHERE tenant_id IS NULL;
UPDATE pay_app SET tenant_id = 1 WHERE tenant_id IS NULL;
UPDATE pay_wallet SET tenant_id = 1 WHERE tenant_id IS NULL;
data_migration: |
数据迁移步骤：
1. 创建数据库备份
2. 添加 tenant_id 字段（允许 NULL）
3. 为历史数据设置默认租户ID
4. 设置 NOT NULL 约束
5. 添加索引
6. 验证数据完整性
risks:
- risk: "数据迁移期间服务不可用"
probability: "高"
impact: "高"
mitigation: "选择低峰期执行，预估迁移时间，提前通知用户"
- risk: "历史数据租户归属不明确"
probability: "中"
impact: "高"
mitigation: "与业务方确认历史数据归属，制定明确的数据分配规则"
- risk: "跨租户数据泄露"
probability: "低"
impact: "高"
mitigation: "严格测试租户隔离，添加集成测试用例"
- risk: "性能下降（tenant_id 过滤）"
probability: "低"
impact: "中"
mitigation: "为 tenant_id 添加索引，确保查询计划使用索引"
priority: "P1"
tenant_isolation_strategy:
implementation: "TenantLineInnerInterceptor (MyBatis-Plus)"
context_propagation: "TenantContextHolder (ThreadLocal)"
header_name: "tenant-id"
tables_to_isolate:
- "pay_order"
- "pay_refund"
- "pay_channel"
- "pay_app"
- "pay_wallet"
- "pay_wallet_transaction"
- "pay_transfer"
tables_to_ignore:
# 以下表不需要租户隔离
- "pay_notify_task" # 通知任务按业务隔离即可
风险提示
高风险场景
| 风险场景 | 风险等级 | 应对措施 |
|---|---|---|
| 修改核心数据表结构 | 高 | 必须有数据备份和回滚脚本 |
| 修改对外 API 签名 | 高 | 版本兼容处理，渐进式迁移 |
| 分布式事务改造 | 高 | 充分测试，准备补偿方案 |
| 大规模数据迁移 | 高 | 分批迁移，灰度验证 |
中风险场景
| 风险场景 | 风险等级 | 应对措施 |
|---|---|---|
| 引入新依赖 | 中 | 评估依赖稳定性，锁定版本 |
| 性能优化改造 | 中 | 性能基准测试，监控告警 |
| 缓存策略变更 | 中 | 缓存穿透/雪崩预案 |
| 定时任务改造 | 中 | 幂等性设计，失败重试 |
风险检查清单
在执行改造前，请逐项检查：
## 改造前检查清单
### 代码层面
- [ ] 已阅读目标模块的 Skill 文档
- [ ] 已识别所有需要修改的文件
- [ ] 已评估对现有测试用例的影响
- [ ] 已准备新的测试用例
### 数据层面
- [ ] 已备份相关数据表
- [ ] 已准备数据迁移脚本
- [ ] 已准备数据回滚脚本
- [ ] 已评估数据迁移时间
### 接口层面
- [ ] 已确认 API 兼容性
- [ ] 已通知调用方（如有破坏性变更）
- [ ] 已准备 API 文档更新
### 运维层面
- [ ] 已制定发布计划
- [ ] 已准备回滚方案
- [ ] 已配置监控告警
- [ ] 已通知相关干系人
回滚策略
回滚原则
- 快速回滚优先：优先恢复服务可用性，再排查问题
- 数据优先保护：回滚代码前，确保数据可恢复
- 分步回滚：按依赖关系逆序回滚
回滚方案模板
rollback_plan:
# 基本信息meta:
change_id: "CHANGE-001"
change_name: "XXX改造"
rollback_owner: "负责人"
# 回滚触发条件trigger_conditions:
- "服务错误率超过 5%"
- "接口响应时间超过 5s"
- "出现数据不一致问题"
- "核心功能不可用"
# 回滚步骤steps:
# 第一阶段：流量切换
- phase: "流量切换"
order: 1
actions:
- action: "切换流量到旧版本服务"
command: "kubectl rollout undo deployment/xxx-service"
verify: "kubectl get pods -l app=xxx-service"
timeout: "60s"
rollback_point: "流量切换完成"
# 第二阶段：代码回滚
- phase: "代码回滚"
order: 2
actions:
- action: "回滚代码到上一版本"
command: "git revert <commit-hash>"
verify: "git log -1"
timeout: "30s"
- action: "重新构建部署"
command: "mvn clean package && kubectl apply -f deployment.yaml"
verify: "kubectl get pods -l app=xxx-service"
timeout: "300s"
rollback_point: "代码回滚完成"
# 第三阶段：数据回滚
- phase: "数据回滚"
order: 3
condition: "涉及数据变更时执行"
actions:
- action: "执行数据回滚脚本"
command: "mysql -h host -u user -p < rollback.sql"
verify: "SELECT COUNT(*) FROM xxx_table"
timeout: "600s"
- action: "清除缓存"
command: "redis-cli FLUSHDB"
verify: "redis-cli DBSIZE"
timeout: "30s"
rollback_point: "数据回滚完成"
# 验证步骤verification:
- "服务健康检查通过"
- "核心接口调用成功"
- "监控指标恢复正常"
- "数据一致性校验通过"
# 数据恢复脚本data_recovery:
file: "rollback/V20240318__rollback_xxx.sql"
content: |
-- 回滚表结构变更
ALTER TABLE xxx_table DROP COLUMN new_column;
-- 恢复数据
UPDATE xxx_table SET status = old_status WHERE id IN (SELECT id FROM backup_table);
# 联系人contacts:
- name: "技术负责人"
phone: "138xxxxxxxx"
- name: "DBA"
phone: "139xxxxxxxx"
- name: "运维负责人"
phone: "137xxxxxxxx"
数据回滚脚本模板
-- =====================================================
-- 数据回滚脚本
-- 变更ID: CHANGE-001
-- 变更名称: XXX改造
-- 创建时间: 2024-03-18
-- 执行前请先备份数据
-- =====================================================
-- 开启事务
START TRANSACTION;
-- 1. 回滚表结构变更（如需要）
-- ALTER TABLE xxx_table DROP COLUMN new_column;
-- 2. 恢复数据（如有数据迁移）
-- 方式一：从备份表恢复
-- INSERT INTO xxx_table SELECT * FROM xxx_table_backup_20240318;
-- 方式二：执行反向更新
-- UPDATE xxx_table SET status = 0 WHERE status = 1;
-- 3. 清理临时数据
-- DROP TABLE IF EXISTS xxx_table_backup_20240318;
-- 验证数据
SELECT COUNT(*) AS total_count FROM xxx_table;
-- SELECT SUM(amount) AS total_amount FROM xxx_table;
-- 确认无误后提交
-- COMMIT;
-- 如有问题，执行回滚
-- ROLLBACK;
回滚演练检查清单
## 回滚演练检查清单
### 演练前准备
- [ ] 已准备回滚脚本并验证语法
- [ ] 已准备数据备份
- [ ] 已通知相关干系人
- [ ] 已准备监控大盘
### 演练执行
- [ ] 执行代码回滚
- [ ] 执行数据回滚（如需要）
- [ ] 执行配置回滚（如需要）
- [ ] 验证服务可用性
- [ ] 验证数据一致性
### 演练后总结
- [ ] 记录回滚耗时
- [ ] 记录遇到的问题
- [ ] 优化回滚脚本
- [ ] 更新文档
附录
相关文档
参考命令
# 查看 Skill 文档
cat skills/modules/{module}/skill-{module}.yaml
# 查看设计模式文档
cat skills/patterns/{pattern}-pattern.yaml
# 数据库备份
mysqldump -h host -u user -p database > backup_$(date +%Y%m%d).sql
# 数据库恢复
mysql -h host -u user -p database < backup_20240318.sql
# Git 回滚
git log --oneline -10
git revert <commit-hash>
文档版本: 1.0.0 最后更新: 2026-03-18 维护者: 技术文档团队