March 9, 2026 开发教程, 技术文章

WooCommerce 定制开发完全指南






WooCommerce 定制开发完全指南



WooCommerce 定制开发完全指南

引言

WooCommerce 作为全球最受欢迎的开源电商插件，为开发者提供了强大的定制能力。通过掌握其核心架构和 API，你可以构建高度个性化的电商解决方案。本文将带你深入 WooCommerce 定制开发的世界，从基础概念到实战技巧，全方位解析。

💡 核心要点： WooCommerce 的定制开发主要围绕 REST API、Hooks 系统和 Filter/Action 钩子展开，合理利用这些机制可以大幅提升开发效率。

WooCommerce 架构概览

WooCommerce 采用模块化设计，每个功能模块都有独立的职责。了解其架构对于高效开发至关重要。


graph TD
    A[WooCommerce 核心架构] --> B[核心组件]
    A --> C[扩展机制]
    A --> D[API 系统]

    B --> B1[订单管理]
    B --> B2[支付网关]
    B --> B3[配送系统]
    B --> B4[产品管理]

    C --> C1[Hooks 系统]
    C --> C2[Filte/Action 钩子]
    C --> C3[扩展点 API]

    D --> D1[REST API]
    D --> D2[WC API 客户端]
    D --> D3[GraphQL 支持]

1.1 核心组件

  • 订单管理模块：处理订单创建、状态流转、退款等核心业务
  • 支付网关模块：支持多种支付方式集成，包括 PayPal、Stripe 等
  • 配送系统模块：计算运费、管理物流、支持多种配送方式
  • 产品管理模块：产品分类、属性、变体管理

1.2 扩展机制

  • Hooks 系统：提供标准化的扩展接口，允许开发者在不修改核心代码的情况下扩展功能
  • Filter/Action 钩子：提供前后置处理机会，实现功能的动态注入
  • 扩展点 API：官方提供的接口，支持插件间通信和功能集成

REST API 完全指南

WooCommerce REST API 是开发者和第三方系统集成的核心工具。它提供了完整的 CRUD 操作，支持认证、过滤和分页。

2.1 API 基础配置

首先，确保 WooCommerce REST API 已启用：

wp plugin deactivate woocommerce
wp plugin activate woocommerce

flowchart LR
    A[客户端请求] --> B{认证方式}
    B --> C[OAuth 2.0]
    B --> D[Basic Auth]
    B --> E[应用密码]
    C --> F[获取 Token]
    D --> G[直接访问]
    E --> H[密码认证]
    F --> I[调用 API]
    G --> I
    H --> I

2.2 产品 API 操作

通过 REST API 管理产品是电商集成的常见需求：

创建产品

POST /wp-json/wc/v3/products
Content-Type: application/json

{
  "name": "高级产品套餐",
  "type": "variable",
  "status": "publish",
  "description": "包含所有高级功能的订阅套餐",
  "short_description": "限时优惠：仅限前100名",
  "regular_price": "299.99",
  "sale_price": "199.99",
  "categories": [
    {"id": 5}
  ],
  "tags": [
    {"id": 12}
  ],
  "meta_data": [
    {"key": "_is_premium", "value": true}
  ]
}

查询产品列表

GET /wp-json/wc/v3/products?status=publish&per_page=10&page=1

# 响应示例
{
  "products": [
    {
      "id": 123,
      "name": "高级产品套餐",
      "type": "variable",
      "status": "publish",
      "price": "199.99",
      "stock_quantity": 50
    }
  ],
  "total": 1,
  "total_pages": 1,
  "total_items": 1
}

2.3 订单 API 操作

订单管理是电商系统的核心功能，REST API 提供了完整的订单操作接口：

创建订单

POST /wp-json/wc/v3/orders
Content-Type: application/json

{
  "payment_method": "bacs",
  "payment_method_title": "银行转账",
  "set_paid": false,
  "billing": {
    "first_name": "张三",
    "last_name": "李四",
    "email": "[email protected]",
    "phone": "13800138000",
    "address_1": "北京市朝阳区建国路88号",
    "city": "北京",
    "state": "北京市",
    "postcode": "100000",
    "country": "CN"
  },
  "shipping": {
    "first_name": "张三",
    "last_name": "李四",
    "address_1": "上海市浦东新区",
    "city": "上海",
    "state": "上海市",
    "postcode": "200000",
    "country": "CN"
  },
  "line_items": [
    {
      "product_id": 123,
      "quantity": 2,
      "total": "399.98"
    }
  ]
}

查询订单详情

GET /wp-json/wc/v3/orders/456?fields=id,status,total,created_at

2.4 Webhook 开发

Webhook 允许你监听 WooCommerce 事件并自动触发回调，是自动化流程的关键：


flowchart LR
    A[用户下单] --> B[WooCommerce 触发事件]
    B --> C[创建 Webhook]
    C --> D[POST 请求到回调 URL]
    D --> E[接收者处理请求]
    E --> F[返回成功响应]
    F --> G[删除或更新 Webhook]

    event1[订单创建]
    event2[订单更新]
    event3[订单支付]
    event4[产品更新]

    B --> event1
    B --> event2
    B --> event3
    B --> event4

创建 Webhook

POST /wp-json/wc/v3/webhooks
Authorization: Basic {token}

{
  "name": "订单创建通知",
  "topic": "order.created",
  "delivery": "api",
  "secret": "your-secret-key",
  "status": "active",
  "resource": "order"
}

Webhook 回调处理示例

<?php
// webhook.php
header('Content-Type: application/json');

// 验证签名
$secret = get_option('webhook_secret');
$sig = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

if (hash_hmac('sha256', $body, $secret) !== $sig) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// 解析订单数据
$order_data = json_decode($body, true);

// 处理订单逻辑
$order_id = $order_data['id'];
$order = wc_get_order($order_id);

// 发送通知
send_notification($order);

// 返回成功响应
echo json_encode(['success' => true]);
exit;

function send_notification($order) {
    // 这里可以实现发送邮件、短信、调用第三方 API 等
    // 例如：同步到 CRM 系统、触发物流接口等
}
?>

Hooks 系统深入解析

Hooks 是 WooCommerce 扩展的核心机制，理解它对于高效定制开发至关重要。

3.1 Filter 和 Action 的区别

特性 Filter Action
用途 修改数据 执行操作
返回值 必须返回值 无返回值
使用场景 数据过滤、转换 日志记录、发送邮件

Filter 钩子示例

<?php
/**
 * 过滤订单金额显示
 * @param string $formatted_price 格式化后的价格
 * @param WC_Order $order 订单对象
 * @return string 修改后的价格
 */
function custom_order_price_display($formatted_price, $order) {
    // 在价格前添加货币符号
    return '¥ ' . $formatted_price;

}
add_filter('woocommerce_get_formatted_order_total', 'custom_order_price_display', 10, 2);

Action 钩子示例

<?php
/**
 * 在订单创建后执行自定义操作
 */
function custom_after_order_created($order_id) {
    $order = wc_get_order($order_id);

    // 记录日志
    error_log("订单 {$order_id} 已创建，金额: " . $order->get_total());

    // 发送通知邮件
    $to = '[email protected]';
    $subject = '新订单通知';
    $message = "订单 #{$order_id} 创建成功，总金额: {$order->get_total()}";
    wp_mail($to, $subject, $message);

    // 调用第三方 API
    sync_order_to_third_party($order);
}
add_action('woocommerce_new_order', 'custom_after_order_created');

3.2 常用 Hooks 列表

  • 产品相关：
    • woocommerce_product_options_general_settings
    • woocommerce_product_data_tabs
    • woocommerce_variation_options_pricing
  • 订单相关：
    • woocommerce_order_status_changed
    • woocommerce_payment_gateway.process_payment
    • woocommerce_thankyou
  • 前端相关：
    • woocommerce_before_single_product
    • woocommerce_after_single_product_summary
    • woocommerce_cart_calculate_fees
  • 邮件相关：
    • woocommerce_email_before_order_table
    • woocommerce_email_order_details
    • woocommerce_email_after_order_table

3.3 高级 Hooks 应用

动态添加商品属性

<?php
/**
 * 动态添加产品属性选项
 * @param array $options 属性选项数组
 * @param WC_Product $product 产品对象
 * @return array 修改后的选项
 */
function custom_product_attribute_options($options, $product) {
    // 添加自定义选项
    $options[] = '定制选项';

    // 根据产品类型动态调整选项
    if ($product->get_type() === 'variable') {
        $options[] = '高级定制';
    }

    return $options;
}
add_filter('woocommerce_variation_option_names', 'custom_product_attribute_options', 10, 2);

自定义运费计算

<?php
/**
 * 自定义运费计算逻辑
 * @param array $rates 运费费率数组
 * @param WC_Cart $cart 购物车对象
 * @return array 修改后的运费费率
 */
function custom_shipping_rates($rates, $cart) {
    // 添加自定义运费规则
    $custom_rate = [
        'method_id' => 'custom_shipping',
        'instance_id' => 1,
        'label' => '特别快递',
        'cost' => 29.99,
        'taxes' => [],
        'meta_data' => []
    ];

    // 如果购物车金额超过500元，免除运费
    if ($cart->get_subtotal() > 500) {
        unset($rates['custom_shipping']);
    } else {
        $rates['custom_shipping'] = $custom_rate;
    }

    return $rates;
}
add_filter('woocommerce_package_rates', 'custom_shipping_rates', 10, 2);

实战开发案例

4.1 开发自定义支付网关

创建一个自定义支付网关需要实现多个接口和方法：

<?php
if (!defined('ABSPATH')) {
    exit;
}

/**
 * 自定义支付网关类
 */
class WC_Gateway_Custom_Payment extends WC_Payment_Gateway {

    /**
     * 构造函数
     */
    public function __construct() {
        $this->id = 'custom_payment';
        $this->icon = 'https://example.com/icon.png';
        $this->has_fields = true;
        $this->method_title = '自定义支付';
        $this->method_description = '支持多种支付方式的自定义网关';

        // 加载设置
        $this->init_form_fields();
        $this->init_settings();

        // 从设置中获取值
        $this->title = $this->get_option('title');
        $this->description = $this->get_option('description');
        $this->enabled = $this->get_option('enabled');
        $this->testmode = 'yes' === $this->get_option('testmode');

        // 保存设置
        add_action('woocommerce_update_options_payment_gateways_' . $this->id, array($this, 'process_admin_options'));

        // 处理支付
        add_action('woocommerce_api_' . $this->id, array($this, 'webhook_handler'));
    }

    /**
     * 初始化表单字段
     */
    public function init_form_fields() {
        $this->form_fields = array(
            'enabled' => array(
                'title'   => '启用/禁用',
                'type'    => 'checkbox',
                'label'   => '启用自定义支付',
                'default' => 'yes'
            ),
            'title' => array(
                'title'       => '网关标题',
                'type'        => 'text',
                'description' => '用户看到的支付方式名称',
                'default'     => '自定义支付'
            ),
            'description' => array(
                'title'       => '描述',
                'type'        => 'textarea',
                'description' => '支付方式描述信息',
                'default'     => '支持多种支付方式'
            ),
            'testmode' => array(
                'title'       => '测试模式',
                'type'        => 'checkbox',
                'label'       => '启用测试模式',
                'default'     => 'yes'
            )
        );
    }

    /**
     * 支付表单显示
     */
    public function payment_fields() {
        if ($this->description) {
            echo wpautop(wptexturize($this->description));
        }
        ?>

        

            

            

                

                    
                

                

                    
                

            

        


        process_payment_request($order, $card_number, $expiry, $cvc);

        if ($response['status'] === 'success') {
            // 标记订单为待支付
            $order->update_status('on-hold', __('等待自定义支付', 'woocommerce'));
            $order->reduce_order_stock();

            // 清空购物车
            WC()->cart->empty_cart();

            // 返回成功响应
            return array(
                'result'   => 'success',
                'redirect' => $this->get_return_url($order)
            );
        } else {
            wc_add_notice($response['message'], 'error');
            return false;
        }
    }

    /**
     * 调用第三方支付接口
     */
    private function process_payment_request($order, $card_number, $expiry, $cvc) {
        // 这里实现实际的支付逻辑
        // 例如：调用第三方支付 API

        // 模拟API调用
        $result = $this->call_payment_api($order->get_total(), $card_number, $expiry, $cvc);

        return $result;
    }

    /**
     * Webhook 处理
     */
    public function webhook_handler() {
        $raw_post = file_get_contents('php://input');
        $data = json_decode($raw_post, true);

        // 验证 Webhook 签名
        $signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
        $expected_signature = hash_hmac('sha256', $raw_post, $this->get_option('webhook_secret'));

        if ($signature !== $expected_signature) {
            header('HTTP/1.1 401 Unauthorized');
            exit;
        }

        // 处理支付结果
        $transaction_id = $data['transaction_id'] ?? '';
        $status = $data['status'] ?? '';

        if ($transaction_id && $status) {
            // 更新订单状态
            $order = wc_get_order_by_meta_value('_transaction_id', $transaction_id);

            if ($order) {
                if ($status === 'success') {
                    $order->payment_complete();
                    $order->add_order_note(__('支付成功', 'woocommerce'));
                } else {
                    $order->update_status('failed', __('支付失败', 'woocommerce'));
                }
            }
        }

        // 返回成功响应
        header('HTTP/1.1 200 OK');
        exit;
    }

    /**
     * 调用支付 API
     */
    private function call_payment_api($amount, $card_number, $expiry, $cvc) {
        // 这里实现实际的 API 调用逻辑
        // 返回格式示例
        return [
            'status' => 'success',
            'transaction_id' => 'TXN123456789',
            'message' => '支付成功'
        ];
    }
}

// 注册支付网关
function add_custom_payment_gateway($methods) {
    $methods[] = 'WC_Gateway_Custom_Payment';
    return $methods;
}
add_filter('woocommerce_payment_gateways', 'add_custom_payment_gateway');

4.2 开发自定义通知系统

创建一个灵活的通知系统，支持邮件、短信和推送通知：

<?php
/**
 * 通知管理器类
 */
class WC_Notification_Manager {

    private static $instance = null;

    private $notifications = [];

    public static function get_instance() {
        if (null === self::$instance) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    /**
     * 注册通知
     */
    public function register_notification($name, $callback, $priority = 10) {
        $this->notifications[$name] = [
            'callback' => $callback,
            'priority' => $priority
        ];

        // 按优先级排序
        uasort($this->notifications, function($a, $b) {
            return $a['priority'] - $b['priority'];
        });
    }

    /**
     * 发送通知
     */
    public function send($name, $data = []) {
        if (isset($this->notifications[$name])) {
            return call_user_func($this->notifications[$name]['callback'], $data);
        }
        return false;
    }

    /**
     * 发送邮件通知
     */
    private function send_email_notification($data) {
        $to = $data['to'] ?? '[email protected]';
        $subject = $data['subject'] ?? '通知';
        $message = $data['message'] ?? '';

        $headers = ['Content-Type: text/html; charset=UTF-8'];
        $message = $this->format_email_message($message, $data);

        return wp_mail($to, $subject, $message, $headers);
    }

    /**
     * 格式化邮件消息
     */
    private function format_email_message($message, $data) {
        $template = "
            <div style='font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;'>
                <h2 style='color: #333;'>{$data['subject']}</h2>
                <div style='padding: 20px; background-color: #f5f5f5;'>
                    {$message}
                </div>
                <div style='margin-top: 20px; color: #666;'>
                    <p>发送时间：{$data['time']}</p>
                </div>
            </div>
        ";
        return $template;
    }

    /**
     * 发送短信通知
     */
    private function send_sms_notification($data) {
        // 这里实现短信发送逻辑
        // 可以集成阿里云短信、腾讯云短信等服务
        $phone = $data['phone'] ?? '';
        $message = $data['message'] ?? '';

        if ($phone) {
            return $this->call_sms_api($phone, $message);
        }

        return false;
    }

    /**
     * 调用短信 API
     */
    private function call_sms_api($phone, $message) {
        // 实现短信 API 调用
        return true;
    }
}

// 初始化通知管理器
function init_notification_manager() {
    $manager = WC_Notification_Manager::get_instance();

    // 注册邮件通知
    $manager->register_notification('order_created', function($data) {
        return $manager->send_email_notification([
            'to' => $data['customer_email'],
            'subject' => '订单已创建',
            'message' => '您的订单 #{$data['order_id']} 已成功创建，我们将尽快处理。',
            'time' => current_time('mysql')
        ]);
    });

    // 注册短信通知
    $manager->register_notification('payment_complete', function($data) {
        return $manager->send_sms_notification([
            'phone' => $data['customer_phone'],
            'message' => "【商城通知】您的订单 #{$data['order_id']} 已支付成功，发货中。",
            'time' => current_time('mysql')
        ]);
    });

    // 注册推送通知
    $manager->register_notification('inventory_low', function($data) {
        // 实现推送通知逻辑
        return true;
    });
}

// 在支付完成时触发通知
add_action('woocommerce_payment_complete', function($order_id) {
    $manager = WC_Notification_Manager::get_instance();
    $order = wc_get_order($order_id);

    // 触发订单创建通知
    $manager->send('order_created', [
        'order_id' => $order_id,
        'customer_email' => $order->get_billing_email(),
        'customer_phone' => $order->get_billing_phone()
    ]);

    // 触发支付完成通知
    $manager->send('payment_complete', [
        'order_id' => $order_id,
        'customer_phone' => $order->get_billing_phone()
    ]);
});

// 初始化通知系统
add_action('plugins_loaded', 'init_notification_manager');

常见错误与解决方案

5.1 性能问题

电商网站容易出现性能瓶颈，以下是一些常见问题和优化方案：

问题 原因 解决方案
页面加载慢 数据库查询过多、未使用缓存
  • 使用 Redis/Memcached 缓存查询结果
  • 启用页面缓存插件
  • 优化数据库查询
API 响应慢 Webhook 处理复杂、未异步化
  • 将耗时操作放入后台队列
  • 使用数据库锁优化并发
  • 实现请求限流机制
内存不足 处理大量订单数据、循环效率低
  • 分批处理数据
  • 使用内存效率更高的数据结构
  • 增加 PHP 内存限制

优化示例：批量订单处理

<?php
/**
 * 分批处理订单，避免内存溢出
 * @param int $batch_size 每批处理数量
 */
function batch_process_orders($batch_size = 50) {
    $processed = 0;

    // 获取待处理的订单
    $args = [
        'post_type' => 'shop_order',
        'post_status' => ['wc-pending', 'wc-processing'],
        'posts_per_page' => $batch_size,
        'paged' => 1
    ];

    $query = new WP_Query($args);

    while ($query->have_posts()) {
        $query->the_post();
        $order_id = get_the_ID();
        $order = wc_get_order($order_id);

        // 处理订单
        process_order($order);

        $processed++;
        wp_reset_postdata();
    }

    wp_reset_query();

    // 继续处理下一页
    if ($processed > 0) {
        batch_process_orders($batch_size);
    }
}

function process_order($order) {
    // 订单处理逻辑
    // 例如：同步到 CRM、更新库存、发送通知等
}

5.2 安全问题

电商网站是黑客攻击的主要目标，安全性至关重要：

1. SQL 注入防护

<?php
// ❌ 错误示例 - 可能被 SQL 注入
$order_id = $_GET['order_id'];
$order = $wpdb->get_row("SELECT * FROM {$wpdb->prefix}posts WHERE ID = {$order_id}");

// ✅ 正确示例 - 使用参数化查询
$order_id = intval($_GET['order_id']);
$order = $wpdb->get_row($wpdb->prepare(
    "SELECT * FROM {$wpdb->prefix}posts WHERE ID = %d",
    $order_id
));

2. XSS 防护

<?php
// ❌ 错误示例 - 未转义输出
echo $order->get_title();

// ✅ 正确示例 - 使用 wp_kses_post 进行 HTML 过滤
echo wp_kses_post($order->get_title());

// 或使用 sanitize_text_field 进行文本过滤
echo esc_html($order->get_title());

3. CSRF 防护

<?php
// 生成 CSRF 令牌
function generate_csrf_token() {
    if (!isset($_SESSION['csrf_token'])) {
        $_SESSION['csrf_token'] = wp_generate_password(32, true, true);
    }
    return $_SESSION['csrf_token'];
}

// 验证 CSRF 令牌
function verify_csrf_token() {
    if (!isset($_POST['csrf_token']) || 
        !isset($_SESSION['csrf_token']) ||
        $_POST['csrf_token'] !== $_SESSION['csrf_token']) {
        wp_nonce_verb_check('', '');
        wp_die('无效的 CSRF 令牌');
    }
}

// 在表单中添加令牌
function add_csrf_token_to_form() {
    $token = generate_csrf_token();
    echo '';
}
add_action('woocommerce_after_order_notes', 'add_csrf_token_to_form');

5.3 API 安全

保护 WooCommerce REST API 避免未授权访问：

<?php
/**
 * 限制 REST API 访问
 */
add_action('rest_api_init', function () {
    register_rest_route('woodev/v1', '/protected-endpoint', [
        'methods' => 'GET',
        'callback' => 'my_protected_endpoint',
        'permission_callback' => function () {
            return is_user_logged_in() && current_user_can('edit_posts');
        }
    ]);
}, 0);

function my_protected_endpoint() {
    return new WP_REST_Response(['message' => '受保护的 API'], 200);
}

最佳实践

6.1 代码组织

  • 使用命名空间：避免全局命名空间污染
  • 遵循 PSR 规范：提高代码可维护性
  • 编写文档注释：为函数和类添加文档
  • 使用 Composer：管理依赖关系
<?php
namespace WC_Gateway;

use WC_Payment_Gateway;

/**
 * 自定义支付网关类
 * 
 * @package WC_Gateway
 */
class Custom_Gateway extends WC_Payment_Gateway {

    /**
     * 构造函数
     */
    public function __construct() {
        // 类实现
    }

    /**
     * 处理支付请求
     *
     * @param int $order_id 订单 ID
     * @return array 支付结果
     */
    public function process_payment($order_id) {
        // 实现代码
    }
}

6.2 测试策略

  • 单元测试：测试独立的函数和类方法
  • 集成测试：测试组件间的交互
  • E2E 测试：模拟完整用户流程
  • 性能测试：评估系统性能指标

6.3 日志记录

<?php
/**
 * 记录调试日志
 */
function wc_debug_log($message, $data = []) {
    if (WP_DEBUG === true) {
        $log_entry = sprintf(
            "[%s] %sn%sn",
            current_time('mysql'),
            $message,
            is_array($data) ? print_r($data, true) : $data
        );

        error_log($log_entry);
    }
}

// 使用示例
wc_debug_log('订单处理开始', [
    'order_id' => 123,
    'amount' => 299.99,
    'currency' => 'CNY'
]);

总结

WooCommerce 定制开发是一个涉及多个层面的复杂过程。通过掌握 REST API、Hooks 系统和 Filter/Action 机制，你可以构建高度定制的电商解决方案。记住要遵循最佳实践，注重代码质量和安全性，并持续优化性能。

🎯 关键要点： WooCommerce 定制开发的核心是理解其架构和扩展机制，合理使用 API 和 Hooks 可以大大提高开发效率。持续学习新技术，关注性能优化和安全防护，是成为一名优秀 WooCommerce 开发者的关键。

参考资料

  • WooCommerce 官方文档 – https://woocommerce.com/documentation/
  • WordPress REST API 文档 – https://developer.wordpress.org/rest-api/
  • WooCommerce Hooks 参考 – https://developer.woocommerce.com/reference/hooks/
  • WC REST API 文档 – https://woocommerce.github.io/woocommerce-rest-api-docs/


Leave a Reply

Your email address will not be published. Required fields are marked *