WooCommerce 插件总被 HPOS 搞崩?woo-guard 八条规则保订单代码安全上线

原创2026-10-13 23:02:571,414 阅读

WooCommerce 插件总被 HPOS 搞崩?woo-guard 八条规则保订单代码安全上线

guard-skills 的 woo-guard 是一款专为 WooCommerce 插件编写的 AI 代码质量守卫(guard skill),在编码代理写完订单、结账、商品相关代码后自动执行八条规则审查,专门拦截 HPOS 兼容、金额计算、结账校验等最常见的 AI 生成代码事故,让你的插件安全上线。

为什么你的 WooCommerce 插件在新店铺上"静默"出 bug?

先说结论:不是你的错,是 AI 代理"记忆"里的 WooCommerce 太老了。

🕰️ WooCommerce 的订单存储已经换引擎——HPOS(High-Performance Order Storage) 把订单从传统的 wp_posts / wp_postmeta 搬进了独立数据表,并且是新店铺默认开启。

而"凭记忆"写出来的代码几乎都在按老存储写:

  • 用 get_post_meta() 读订单 → 在 HPOS 店铺上拿到空值,没有任何报错
  • 用 post_type => 'shop_order' 查订单 → 一条结果都查不到
  • 结账逻辑只挂 woocommerce_checkout_process 钩子 → 在 Blocks 结账的新店上永远不会执行

最危险的是"静默失败":你的演示店是老架构,一切正常;客户开的新店是 HPOS,订单金额、库存、状态全对不上,而且没有任何报错日志可查。

这就是 skills/woo-guard/SKILL.md 里那句话的由来——"在我演示店上能跑"不算上线标准,因为涉及真金白银。

八条规则:woo-guard 到底查什么

woo-guard 把规则分成两档:规则 1–5 是"必须修"(店铺直接坏掉、金额算错),规则 6–8 是"应该修"(上下文崩溃、扩容隐患)。逐条来看。

规则 1:订单不是文章,只走 CRUD API

订单只能通过 wc_get_order()、wc_get_orders()、$order->get_meta() 这类 CRUD 接口访问。以下写法在订单数据上全部禁用:

  • get_post_meta() / update_post_meta()
  • WP_Query / get_posts() 配 post_type => 'shop_order'
  • 直接 $wpdb 连接 postmeta 表

这些代码在老店铺上能跑,在 HPOS 店铺上静默坏掉。背景细节见 references/hpos-and-crud.md。

规则 2:CRUD 对象 + 属性读写 + save()

商品、客户、优惠券统一走各自的 CRUD 对象(如 wc_get_product() + setter + ->save())。直接写 meta 会同时跳过三样东西:

  • 查找表(lookup table)同步
  • 其他插件依赖的钩子
  • 缓存失效

库存变更要走 wc_update_product_stock() 语义,订单状态要走 $order->update_status()——后者才会触发邮件和 woocommerce_order_status_* 钩子,你的店铺其他功能都指望它。

规则 3:老老实实声明功能兼容性

碰订单的扩展必须声明 HPOS 兼容(FeaturesUtil::declare_compatibility( 'custom_order_tables', … ));碰结账的扩展声明 cart_checkout_blocks 兼容或不兼容。

漏了声明会怎样?每个店铺老板都会看到一条带着你插件名字的警告横幅。 但反过来,声明要如实——对还在读 postmeta 的代码谎报兼容,会把"看得见的警告"变成"看不见的数据 bug"。

规则 4:结账校验必须在服务端

JS 校验只是体验(UX),永远不是安全。真正的闸门在服务端:

  • 老式结账:woocommerce_checkout_process 钩子
  • Blocks 结账:Store API 扩展 schema

而且要先搞清楚店铺跑的是哪个结账——两套钩子互不重叠,挂错面就是"代码根本没跑"。示例模式见 references/checkout-and-money.md。

规则 5:钱不是 float

金额处理纪律,一条都不能省:

场景 正确做法
入库 / 运算输入 wc_format_decimal()
展示 wc_price()
税费 / 舍入 用 WooCommerce 自身的设置,别自己重算
金额比较 用格式化后的十进制或整数最小单位,禁止 float 直接 ==

手写 '$' . $amount 的插件,卖到另外 150 种货币的店铺就会翻车;float 运算造成的"分币漂移",会计一查一个准。

规则 6:运行时上下文要设防

WC()->cart 和 WC()->session 在 REST、cron、CLI、后台等上下文里是 null——不检查就访问直接致命错误,而且"本地能跑"。另外:

  • webhook / 支付回调里不能假设"一定有登录客户"
  • 每个 woocommerce_* 钩子和 wc_* 函数都要确认在你支持的版本区间内存在——WooCommerce 大版本间会重命名、废弃钩子
  • 所有 wc_* 调用前先做 class_exists( 'WooCommerce' ) 之类的守卫

规则 7:钩子优先,模板覆盖垫底

优先级从高到低:现有 WooCommerce 钩子/过滤器 → woocommerce_locate_template 过滤器 → 主题级覆盖。

插件里自带模板覆盖文件是审查时的必报项:它把一份复制的文件冻结在某个 WooCommerce 版本上,模板一升级就断。

规则 8:后台任务要扛得住订单量

批量同步、webhook 扇出这类后台工作走 Action Scheduler(WooCommerce 自带),别用裸 WP-Cron 循环。处理器必须幂等——真实店铺里同一个订单事件会触发多次,重试是常态,处理两次不能把订单完结两次。

怎么用:三步接入你的编码代理

woo-guard 属于 guard-skills 仓库,安装一条命令搞定:

npx skills add amElnagdy/guard-skills --skill woo-guard

也可以克隆仓库后按 README.md 的说明用 Skills CLI 安装:

git clone https://gitcode.com/gh_mirrors/gu/guard-skills

三种使用姿势:

  1. Guard 模式(推荐):让代理先写代码,写完说"用 $woo-guard 审查这份 WooCommerce 改动",它会对 diff 跑规则并在交付前自检
  2. 实时模式:写代码前就声明"实现时应用 woo-guard",规则全程生效
  3. 审查模式:只审不改,按 references/review-checklist.md 四遍扫描(HPOS/CRUD → 结账/金额 → 运行时 → 兼容性打包),输出结构化的 What / Risk / Fix 报告,并给出"可合并 / 先修 / 不合并"结论

💡 建议搭配 wp-guard 一起用:woo-guard 管 WooCommerce 层,wp-guard 管 WordPress 底层(转义、nonce、i18n),两者互补不重复。

安全底线:金额代码零容忍

无论走哪种模式,woo-guard 对四条安全底线执行最高严重级别,因为"钱在路上":

  • ✅ 所有输出用上下文正确的 esc_* 转义
  • ✅ 所有请求数据先 wp_unslash() 再按类型净化
  • ✅ 每次状态变更都有权限检查 + nonce
  • ✅ 含变量的查询一律 $wpdb->prepare()

总结:让 AI 写的订单代码"过闸"再上线

📌 一句话记住这套方案:

问题 woo-guard 的拦截点
HPOS 静默失败 规则 1、3:CRUD 访问 + 兼容声明
钩子不触发 规则 4、6:服务端校验 + 上下文守卫
金额算错 规则 5:禁止 float、手写货币符号
升级即坏 规则 7、8:钩子优先 + Action Scheduler

AI 代理写 WooCommerce 代码有系统性的失败模式——这恰恰是 woo-guard 存在的意义:不是教它怎么写,而是在交付前设一道质量闸门。八条规则全部通过后,你的订单代码才算真正具备上线资格。

登录后查看全文
guard-skills