WordPress源码深度解析之：`WordPress`的`Heartbeat API`：如何利用它进行客户端与服务器端的实时通信。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，早上好（或者下午好，晚上好，取决于你什么时候看到这篇文章）。我是你们的老朋友，代码界的郭德纲（自封的），今天咱们来聊聊WordPress里一个挺有意思的东西：Heartbeat API。这玩意儿，说白了，就是让你的WordPress网站能跟服务器眉来眼去，实时聊天的秘密通道。

开场白：心跳，为了证明我还活着

想象一下，你在一个荒岛上，为了让搜救队知道你还活着，你会定时点个烽火狼烟。Heartbeat API在WordPress里就扮演着烽火狼烟的角色。它让浏览器（客户端）定期向服务器发送“心跳”，告诉服务器：“我还在呢，快看看我需不需要干点啥。”

第一幕：Heartbeat API 是个啥？

Heartbeat API 是 WordPress 提供的一个机制，允许浏览器（客户端）定期（默认 15 秒）向 WordPress 服务器发送 AJAX 请求。服务器收到请求后，可以执行一些任务，例如自动保存文章、检查是否有新的评论等等。并将结果返回给客户端。

为啥要有这玩意儿？

自动保存草稿： 妈妈再也不用担心我写文章写一半电脑突然没电了！
实时协作编辑： 多个作者同时编辑文章，告别冲突，拥抱和谐。
会话管理： 保持用户登录状态，防止用户被踢下线。
服务器状态监控： 监控服务器负载，及时发现问题。
自定义功能： 各种脑洞大开的功能，只要你能想到，就能实现。

第二幕：Heartbeat API 的基本构成

Heartbeat API 主要涉及三个部分：

客户端 (浏览器): 负责定期发送心跳请求。
服务器端 (WordPress): 负责接收心跳请求，执行任务，并返回响应。
传输协议: 使用 AJAX (Asynchronous JavaScript and XML) 进行异步通信。

第三幕：客户端 – JavaScript 的戏份

WordPress 已经内置了 Heartbeat API 的客户端 JavaScript 代码。你只需要在你的 JavaScript 代码中引入 wp-heartbeat.js 即可。

// 这是一个简单的例子，展示如何监听 Heartbeat API 的 tick 事件
jQuery(document).ready(function($) {
  $(document).on('heartbeat-tick', function(event, data) {
    // data 中包含了服务器返回的数据
    console.log('服务器返回的数据:', data);

    // 举个例子，如果服务器返回了新的评论数量，更新页面上的显示
    if (data.new_comments) {
      $('#new-comments-count').text(data.new_comments);
    }
  });
});

重要事件：

事件名	触发时机	描述
`heartbeat-send`	在发送心跳请求之前	允许你修改发送到服务器的数据。
`heartbeat-tick`	在收到服务器返回的数据之后	允许你处理服务器返回的数据。
`heartbeat-complete`	在心跳请求完成之后，无论成功还是失败	允许你执行一些清理工作，例如禁用按钮。
`heartbeat-error`	在心跳请求失败时	允许你处理错误情况，例如显示错误消息。

发送自定义数据：

如果你想发送自定义数据到服务器，可以使用 heartbeat-send 事件。

jQuery(document).ready(function($) {
  $(document).on('heartbeat-send', function(event, data) {
    // 添加自定义数据到 data 对象中
    data['my_custom_data'] = 'Hello, server!';
  });
});

第四幕：服务器端 – PHP 的舞台

服务器端需要注册一个 Heartbeat API 的接收器，用来处理客户端发送的请求。

<?php
/**
 * 注册 Heartbeat API 接收器
 */
add_filter( 'heartbeat_received', 'my_heartbeat_received', 10, 2 );

/**
 * 处理 Heartbeat API 请求
 *
 * @param array $response 服务器返回的数据
 * @param array $data     客户端发送的数据
 *
 * @return array 服务器返回的数据
 */
function my_heartbeat_received( $response, $data ) {
  // 检查客户端是否发送了自定义数据
  if ( isset( $data['my_custom_data'] ) ) {
    $custom_data = sanitize_text_field( $data['my_custom_data'] );
    error_log( '客户端发送的自定义数据: ' . $custom_data ); // 记录日志，方便调试
  }

  // 执行一些服务器端任务，例如获取新的评论数量
  $new_comments_count = wp_count_comments()->awaiting_moderation;

  // 将新的评论数量添加到响应数据中
  $response['new_comments'] = $new_comments_count;

  return $response;
}

代码解释：

add_filter( 'heartbeat_received', 'my_heartbeat_received', 10, 2 );：这行代码将 my_heartbeat_received 函数注册为 Heartbeat API 的接收器。heartbeat_received 是 WordPress 提供的一个过滤器钩子。
my_heartbeat_received( $response, $data )：这个函数是实际处理 Heartbeat API 请求的函数。
- $response：服务器返回的数据，初始值为空数组。
- $data：客户端发送的数据。
$response['new_comments'] = $new_comments_count;：将新的评论数量添加到响应数据中，这样客户端就可以在 heartbeat-tick 事件中获取到这个数据。

重要过滤器钩子：

过滤器钩子	触发时机	描述
`heartbeat_received`	在服务器端接收到心跳请求之后	允许你处理客户端发送的数据，并修改服务器返回的数据。
`heartbeat_send`	在客户端发送心跳请求之前	允许你修改发送到服务器的数据。
`heartbeat_settings`	在 Heartbeat API 初始化时	允许你修改 Heartbeat API 的配置，例如修改心跳间隔。
`heartbeat_nopriv_received`	未登录用户接收到心跳请求之后	允许你处理未登录用户发送的数据，并修改服务器返回的数据。(针对未登录用户的`heartbeat_received`过滤器)

第五幕：修改 Heartbeat API 的设置

WordPress 允许你修改 Heartbeat API 的一些设置，例如心跳间隔。

<?php
/**
 * 修改 Heartbeat API 的设置
 */
add_filter( 'heartbeat_settings', 'my_heartbeat_settings' );

/**
 * 修改 Heartbeat API 的设置
 *
 * @param array $settings Heartbeat API 的设置
 *
 * @return array 修改后的 Heartbeat API 设置
 */
function my_heartbeat_settings( $settings ) {
  // 修改心跳间隔为 60 秒
  $settings['interval'] = 60;

  return $settings;
}

代码解释：

$settings['interval'] = 60;：这行代码将心跳间隔修改为 60 秒。默认是15秒。

常用设置：

设置项	描述	默认值
`interval`	心跳间隔，单位为秒。	15
`suspension`	是否在页面不可见时暂停心跳。	`true`

第六幕：一个更复杂的例子 – 实时更新文章字数

假设你想在文章编辑页面实时显示文章的字数。你可以使用 Heartbeat API 来实现这个功能。

客户端代码 (JavaScript):

jQuery(document).ready(function($) {
  // 获取文章编辑器的 ID
  var editor_id = 'content'; // 默认的 WordPress 编辑器 ID

  $(document).on('heartbeat-send', function(event, data) {
    // 获取文章内容
    var content = tinyMCE.get(editor_id).getContent();

    // 将文章内容发送到服务器
    data['post_content'] = content;
  });

  $(document).on('heartbeat-tick', function(event, data) {
    // 如果服务器返回了字数
    if (data.word_count) {
      // 更新页面上的显示
      $('#word-count').text('字数: ' + data.word_count);
    }
  });
});

服务器端代码 (PHP):

<?php
/**
 * 注册 Heartbeat API 接收器
 */
add_filter( 'heartbeat_received', 'my_heartbeat_received', 10, 2 );

/**
 * 处理 Heartbeat API 请求
 *
 * @param array $response 服务器返回的数据
 * @param array $data     客户端发送的数据
 *
 * @return array 服务器返回的数据
 */
function my_heartbeat_received( $response, $data ) {
  // 检查客户端是否发送了文章内容
  if ( isset( $data['post_content'] ) ) {
    $content = wp_kses_post( $data['post_content'] ); // 安全过滤

    // 计算字数
    $word_count = str_word_count( strip_tags( $content ) );

    // 将字数添加到响应数据中
    $response['word_count'] = $word_count;
  }

  return $response;
}

解释：

客户端：
- 在 heartbeat-send 事件中，获取文章编辑器的内容，并将其发送到服务器。
- 在 heartbeat-tick 事件中，接收服务器返回的字数，并更新页面上的显示。
服务器端：
- 在 my_heartbeat_received 函数中，接收客户端发送的文章内容。
- 使用 str_word_count 函数计算字数。
- 将字数添加到响应数据中。

第七幕：注意事项和最佳实践

不要滥用： Heartbeat API 会增加服务器负载，不要频繁发送心跳请求。
安全第一： 对客户端发送的数据进行安全过滤，防止 XSS 攻击。使用wp_kses_post进行过滤。
错误处理： 处理心跳请求失败的情况，例如显示错误消息。
性能优化： 尽量减少服务器端任务的执行时间。
节约资源： 页面不可见时暂停心跳，减少资源消耗。
兼容性： 确保你的代码在不同的浏览器和设备上都能正常工作。

第八幕：Heartbeat API 的替代方案

虽然 Heartbeat API 提供了一种方便的实时通信方式，但它也有一些缺点，例如：

轮询机制： 客户端需要定期发送请求，即使服务器端没有新的数据。
服务器负载： 频繁的请求会增加服务器负载。

因此，在某些情况下，你可以考虑使用其他替代方案，例如：

WebSockets： WebSockets 提供了全双工通信，允许服务器主动向客户端推送数据。
Server-Sent Events (SSE)： SSE 允许服务器单向地向客户端推送数据。
GraphQL Subscriptions: 允许客户端订阅服务器端数据的变化。

技术	优点	缺点	适用场景
Heartbeat API	简单易用，与 WordPress 集成紧密。	轮询机制，增加服务器负载。	简单的实时更新，例如自动保存草稿、检查更新。
WebSockets	全双工通信，实时性高，服务器可以主动推送数据。	实现复杂，需要额外的服务器配置。	需要高实时性的应用，例如在线聊天、实时游戏。
SSE	服务器单向推送数据，实现简单，开销小。	客户端无法向服务器发送数据。	服务器需要主动推送数据的应用，例如实时新闻、股票行情。
GraphQL Subscriptions	实时性高，可以选择订阅感兴趣的数据，减少数据传输量。	实现复杂，需要学习 GraphQL。	复杂的实时更新，例如实时协作编辑、社交媒体。

闭幕词：心跳不止，代码不息

Heartbeat API 是 WordPress 提供的一个强大的工具，可以让你实现各种各样的实时通信功能。但是，在使用 Heartbeat API 时，一定要注意性能和安全问题。希望今天的分享能帮助你更好地理解和使用 Heartbeat API。

今天的讲座就到这里，感谢大家的收听！如果你有任何问题，欢迎在评论区留言。咱们下期再见！

发表回复 取消回复

发表回复取消回复