WooCommerce 插件总被 HPOS 搞崩?woo-guard 八条规则保订单代码安全上线
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
三种使用姿势:
- Guard 模式(推荐):让代理先写代码,写完说"用 $woo-guard 审查这份 WooCommerce 改动",它会对 diff 跑规则并在交付前自检
- 实时模式:写代码前就声明"实现时应用 woo-guard",规则全程生效
- 审查模式:只审不改,按 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 存在的意义:不是教它怎么写,而是在交付前设一道质量闸门。八条规则全部通过后,你的订单代码才算真正具备上线资格。