如何将WordPress的WooCommerce插件对接基于Spring Security OAuth2 JWT的Spring Boot API

流程优化（替换原梳理的握手流程） #

服务端之间通信优先采用OAuth2客户端凭据（Client Credentials）模式，相比原流程可大幅减少冗余请求，流程如下：

• Spring Boot端提前为WooCommerce分配唯一的client_id、client_secret，仅开放订单上报所需的最小权限
• WordPress端加密存储client_id、client_secret，同时本地缓存JWT令牌和过期时间
• 订单触发上报时，先校验本地JWT是否在有效期内：有效则直接携带令牌发起业务请求；无效则先调用令牌接口获取新的JWT，再发起业务请求
• Spring端校验JWT合法后处理业务，返回成功/失败标识，支持幂等校验避免重复处理

Spring Boot端适配要点 #

• 直接基于OAuth2客户端凭据模式实现鉴权逻辑，无需适配密码模式
• JWT过期时间建议设置为12~24小时，既减少令牌申请频次，也控制泄露风险
• 订单上报接口必须做幂等校验，以WooCommerce订单号作为唯一幂等键，重复上报相同订单号直接返回成功，不重复处理业务
• 接口异常时返回标准HTTP状态码：401对应令牌失效、400对应请求参数错误、500对应服务端异常，方便WordPress端做针对性处理

WordPress端实现方案 #

不要直接使用WooCommerce原生Webhook，原生Webhook不支持自定义动态鉴权头，需通过自定义插件实现逻辑，无侵入不影响WooCommerce核心代码升级：

1. 凭据存储 #

在WordPress后台新增自定义设置项，将client_id、client_secret存入wp_options表，不要明文写在代码中，可配合WordPress内置的加密函数存储敏感信息。

2. 钩子绑定 #

绑定WooCommerce的woocommerce_order_status_processing动作钩子，订单状态变更为处理中时自动触发上报逻辑。

3. 核心代码示例 #

// 绑定订单状态变更触发器
add_action('woocommerce_order_status_processing', 'wc_sync_order_to_springboot', 10, 1);

// 订单同步主逻辑
function wc_sync_order_to_springboot($order_id) {
    $order = wc_get_order($order_id);
    if (empty($order)) return;

    // 获取有效JWT
    $jwt = wc_get_springboot_jwt();
    if (empty($jwt)) {
        error_log('Spring Boot令牌获取失败，待同步订单ID：' . $order_id);
        // 存入待重试队列
        update_option('wc_sync_fail_order_' . $order_id, time());
        return;
    }

    // 组装上报数据
    $sync_data = [
        'order_sn' => $order->get_order_number(),
        'goods_list' => []
    ];
    foreach ($order->get_items() as $item) {
        $sync_data['goods_list'][] = [
            'goods_id' => $item->get_product_id(),
            'buy_num' => $item->get_quantity()
        ];
    }

    // 发起业务请求
    $response = wp_remote_post('https://你的SpringBoot服务地址/api/order/receive', [
        'headers' => [
            'Authorization' => 'Bearer ' . $jwt,
            'Content-Type' => 'application/json'
        ],
        'body' => json_encode($sync_data),
        'timeout' => 15
    ]);

    $http_code = wp_remote_retrieve_response_code($response);
    if ($http_code === 200) {
        $order->add_order_note('订单数据已成功同步至业务系统');
        // 清理可能存在的失败记录
        delete_option('wc_sync_fail_order_' . $order_id);
    } elseif ($http_code === 401) {
        // 令牌失效，清除缓存后重试1次
        delete_option('springboot_jwt_token');
        delete_option('springboot_jwt_expire_time');
        wc_sync_order_to_springboot($order_id);
    } else {
        error_log('订单同步失败，订单ID：' . $order_id . '，HTTP状态码：' . $http_code);
        update_option('wc_sync_fail_order_' . $order_id, time());
    }
}

// 通用JWT获取工具函数
function wc_get_springboot_jwt() {
    $cached_token = get_option('springboot_jwt_token');
    $expire_time = get_option('springboot_jwt_expire_time');
    // 提前10分钟过期，避免边界时间点请求失败
    if (!empty($cached_token) && !empty($expire_time) && time() < $expire_time) {
        return $cached_token;
    }

    $client_id = get_option('springboot_client_id');
    $client_secret = get_option('springboot_client_secret');
    if (empty($client_id) || empty($client_secret)) {
        error_log('Spring Boot客户端凭据未配置');
        return false;
    }

    // 请求令牌接口
    $token_resp = wp_remote_post('https://你的SpringBoot服务地址/oauth2/token', [
        'body' => [
            'grant_type' => 'client_credentials',
            'client_id' => $client_id,
            'client_secret' => $client_secret
        ],
        'timeout' => 10
    ]);

    if (wp_remote_retrieve_response_code($token_resp) !== 200) {
        error_log('JWT申请失败：' . wp_remote_retrieve_body($token_resp));
        return false;
    }

    $token_data = json_decode(wp_remote_retrieve_body($token_resp), true);
    if (isset($token_data['access_token'], $token_data['expires_in'])) {
        update_option('springboot_jwt_token', $token_data['access_token']);
        update_option('springboot_jwt_expire_time', time() + $token_data['expires_in'] - 600);
        return $token_data['access_token'];
    }

    return false;
}

4. 失败重试机制 #

新增WordPress Cron定时任务，每隔15分钟扫描待重试的失败订单，最多重试7天，重试次数达到上限后发送邮件通知管理员人工处理。

注意事项 #

• 所有接口请求必须走HTTPS协议，禁止明文传输敏感信息
• 不要修改WooCommerce核心代码，所有自定义逻辑都封装在独立插件中
• JWT令牌不要存储在明文文件中，存入WordPress系统表即可，到期自动更新无需人工干预
• 生产环境关闭接口请求的详细错误日志输出，避免泄露敏感信息

内容的提问来源于stack exchange，提问作者Leonard-Riccardo Wecke