EP08. "wp-woocommerce-dev WooCommerce 开发审查"

• 你的 WooCommerce 插件还在用 get_posts() 抓订单？WC 8.2（2023 年 10 月）之后新店默认开 HPOS（High-Performance Order Storage），这种写法直接在新店铺上炸掉
• wp-woocommerce-dev 是 jorgerosal/wordpress-skills 这套 18 个 skill 里专门审查 WooCommerce 扩展的一个，覆盖 HPOS 兼容性、支付网关安全、模板覆写、cart fragments 性能这几块
• 核心原则一句话：订单数据一律走 WC_Data 的 CRUD API（wc_get_order()/wc_get_orders()），不准直接碰 wp_posts/wp_postmeta
• 支付网关那块尺度最严：卡号/CVV 绝对不能落库或写进 log，这条没有商量余地

重点内容

这个 Skill 是做什么的

wp-woocommerce-dev 针对 WooCommerce 8.2 到当前 10.x 版本的扩展做系统化审查，检查范围包括插件架构、支付网关、运费方式、自定义商品类型、WooCommerce hook 用法、模板覆写质量、cart fragments 性能、Action Scheduler 用法、WC REST API 扩展、WC Blocks 整合、webhook 安全。

适合用在：

• WooCommerce 扩展架构审查
• HPOS 兼容性审计
• 支付网关代码分析
• 运费方式、自定义商品类型审查
• 模板覆写质量检查（有没有删掉关键的 do_action()）
• cart fragments 性能分析、Action Scheduler 用法审查
• WC REST API 扩展、WC Blocks 整合、webhook 安全审查

不适合用在：

• 通用插件架构（交给 wp-plugin-development）
• 全面安全审查（交给 wp-security-review）
• WC 情境之外的 block 开发（交给 wp-block-development）
• 没有 WC 整合的纯主题审查（交给 wp-theme-development）
• 全面性能审查（交给 wp-performance-review）
• PCI 合规审计、店铺搭建或主机配置

严重度分级

审查流程

1. 判断 WooCommerce 情境（扩展、主题、支付网关、运费方式、商品类型、WC Blocks）
2. 检查 HPOS 兼容性声明 + 数据访问是不是全走 CRUD
3. 校验数据访问模式：WC_Data CRUD 而不是直接碰 post/meta
4. 审查支付网关代码有没有安全反模式
5. 分析 WooCommerce hook 用法（生命周期、商品、结账、购物车、订单状态各阶段）
6. 评估模板覆写有没有保留 hook、有没有跟版本
7. 评估性能模式（cart fragments、查询方式、Action Scheduler）
8. 按文件分组输出报告，带行号和严重度

实操示例

// ❌ CRITICAL：直接查 post，HPOS 开启的店铺会直接失效
get_posts( array( 'post_type' => 'shop_order' ) );
update_post_meta( $order_id, 'field', $value );

// ✅ GOOD：全部走 WC_Data CRUD API
$order = wc_get_order( $order_id );
$order->update_meta_data( 'field', $value );
$order->save();

$orders = wc_get_orders( array( 'status' => 'completed' ) );

// ❌ CRITICAL：支付网关把卡号明文落库、写进 log
update_post_meta( $order_id, 'card_number', $_POST['card_number'] );
error_log( 'Card: ' . $_POST['card_number'] );

// ✅ GOOD：SSL 检查 + tokenization，用 payment_complete() 而不是手动改状态
if ( ! is_ssl() && 'yes' !== $this->get_option( 'testmode' ) ) {
    return array( 'result' => 'failure' );
}
$order->payment_complete( $transaction_id );

// ✅ GOOD：模板覆写要保留原本的 action hook，插件生态才接得上
do_action( 'woocommerce_before_shop_loop_item' );
// 自定义内容
do_action( 'woocommerce_after_shop_loop_item' );

// ✅ GOOD：cart fragments 只在 WC 相关页面加载，不要全站加载
if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() ) {
    return null;
}

怎么安装

这个 skill 是 wordpress-skills 这个开源仓库（jorgerosal/wordpress-skills）打包的 18 个技能之一，安装一次，18 个技能一起到位，不用逐个装：

Claude Code：

装完重启 Claude Code，进到一个 WordPress 项目里跑 /wordpress-skills:wp-woo-review 验证有没有装成功（用 marketplace/submodule 方式装的话，指令前面会带插件命名空间 wordpress-skills:；用「只装这一个 skill」的方式则不带命名空间，直接 /wp-woo-review）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传技能文件夹（把 claude-skills/wp-woocommerce-dev 这个文件夹打包上传，里面要包含 SKILL.md）——跟 Claude Code 的 git submodule/marketplace 安装方式不同，Desktop 端是手动上传 UI，装好之后同样能用自然语言或 slash 指令触发。

常见错误

skill 官方文档专门列了一张「看起来像问题、其实不是」的对照表，很多误报都出在这几处：

• ❌ 把 get_posts() 查自定义 post type（不是订单）当成 HPOS 违规——只有 post_type = 'shop_order' 才会在 HPOS 下出问题，扩展自己的 CPT 用 get_posts() 没事
• ❌ WP_Query 查普通文章/页面被误判——只有查商品/订单才该警告，博客文章、其他 CPT 用 WP_Query 完全正常
• ❌ 模板覆写在子主题里出现，只要保留了 do_action() 就是合法自定义，不是问题——只有删掉 hook 才该标记
• ❌ wc-cart-fragments.js 在购物车/结账/商品页加载是预期行为，只有「全站加载」才该警告
• ❌ 非支付相关代码里用 error_log() 属于正常调试，只有支付流程里 log 到敏感数据才是问题
• ❌ 扩展自己建的表用 $wpdb 直接查询没问题，只有查 wp_posts/wp_postmeta 里的订单数据才会被 HPOS 影响
• 💡 apiVersion 2 这类 WC Blocks 相关的写法不属于这个 skill 的范围，该转给 wp-block-development 处理

Sources

官方文档：

1. wordpress-skills（GitHub 仓库）— https://github.com/jorgerosal/wordpress-skills
2. wp-woocommerce-dev SKILL.md — https://github.com/jorgerosal/wordpress-skills/blob/main/claude-skills/wp-woocommerce-dev/SKILL.md