wp-migration-upgrade-review

WordPress 迁移与升级审查技能

概述

系统地审查 WordPress 插件和主题的升级流程。核心原则： 升级应可重复执行、能识别版本、循序渐进，并确保真实生产数据安全。审查范围包括架构变更、选项迁移、版本标记、启用时升级、后台回填、幂等性、回滚风险和向后兼容性。

适用场景

适用于：

• 审查架构或选项迁移
• 审计 dbDelta() 的使用
• 检查带版本管理的升级流程
• 审查后台回填或一次性修复任务
• 为现有安装准备高风险版本发布

不适用于：

• 不涉及迁移逻辑的纯性能审查
• 不涉及升级的常规插件架构审查
• 与产品升级无关的一次性内容导入

代码审查工作流

1. 识别迁移范围

   • 启用钩子设置
   • 版本比较升级流程
   • 后台回填
   • 手动修复工具

2. 优先检查安全性

   • 存在版本保护
   • 流程具备幂等性
   • 明确说明并论证破坏性操作
   • 大规模数据处理采用分批方式

3. 审查架构和数据流

   • dbDelta() 与原始 SQL 的使用
   • 选项重命名、复制和删除的顺序
   • 回填的持久性和进度跟踪
   • 升级完成标记

4. 判定严重级别

   • 严重： 没有版本保护、未经检查的破坏性写入、在页面加载时运行耗时的升级
   • 警告： 缺少分批处理、未考虑回滚、部分状态未跟踪
   • 信息： 可使用更清晰的迁移注册表或日志记录

特定文件类型检查

带版本管理的升级流程

• 严重：升级逻辑在每次请求中运行，且不比较版本
• 警告：包含多个迁移步骤，但没有有序的升级映射
• 信息：可集中管理迁移注册表

架构变更

• 严重：不顾及现有安装，直接使用原始 CREATE TABLE 或 ALTER TABLE
• 警告：使用 dbDelta()，但不跟踪表版本
• 信息：可将架构迁移阶段与数据迁移阶段分开

数据回填

• 严重：在常规页面加载时执行全表回填
• 警告：没有分批处理或进度选项
• 警告：没有重试或可恢复的设计
• 信息：可支持 Action Scheduler 或 WP-CLI

快速检测搜索模式（MIG-21）

使用以下 rg 命令快速扫描迁移相关内容。

严重模式

# Version comparisons and upgrade flags
rg -n "version_compare|get_option\s*\(.*version|update_option\s*\(.*version" . -g '*.php'

# Schema changes
rg -n "dbDelta|CREATE TABLE|ALTER TABLE|DROP TABLE" . -g '*.php'

# Activation and upgrade hooks
rg -n "register_activation_hook|upgrader_process_complete|admin_init|init" . -g '*.php'

警告模式

# Batch candidates and large loops
rg -n "foreach|while" . -g '*.php'

# Background processing and schedulers
rg -n "wp_schedule_event|as_schedule_single_action|WP_CLI" . -g '*.php'

# Delete or rename operations
rg -n "delete_option|rename|migrate|backfill" . -g '*.php'

信息模式

# Upgrade classes or managers
rg -n "Migration|Upgrade|Installer|Schema" . -g '*.php'

参考文件

• references/versioned-upgrades.md - 版本标记、有序迁移和幂等升级流程
• references/schema-and-backfill-guide.md - dbDelta()、表变更、回填、分批处理和发布安全性

输出格式（MIG-23）

对于每项发现，请包含严重级别、文件引用、迁移风险和安全的修复方案。明确说明该问题是否可能导致生产环境超时、数据处于部分状态或发生不可逆的数据丢失。