EasyWeChat企业微信服务端消息处理指南

企业微信服务端消息推送概述

在企业微信开发中，服务端消息推送是一个重要功能，它允许企业微信服务器主动向开发者服务器推送各种事件通知。EasyWeChat提供了简洁高效的方式来处理这些推送消息，开发者可以轻松实现通讯录变更、任务完成等事件的监听和处理。

消息推送类型

企业微信主要推送以下两类事件消息：

1. 通讯录变更事件（change_contact）

通讯录变更事件包含三个维度的变更通知：

• 成员变更：

  • 新增成员（create_user）
  • 更新成员（update_user）
  • 删除成员（delete_user）

• 部门变更：

  • 新增部门（create_party）
  • 更新部门（update_party）
  • 删除部门（delete_party）

• 标签变更：

  • 成员标签变更（update_tag）

2. 批量任务执行完成事件（batch_job_result）

当异步任务执行完成时，企业微信会推送此事件通知开发者任务执行结果。

消息处理方式

EasyWeChat提供了多种处理消息的方式，开发者可以根据需求选择最适合的方法。

内置消息处理器

1. 通讯录变更事件处理

$server->handleContactChanged(function($message, \Closure $next) {
    // 处理通讯录变更逻辑
    return $next($message);
});

2. 任务执行完成事件处理

$server->handleBatchJobsFinished(function($message, \Closure $next) {
    // 处理任务完成逻辑
    return $next($message);
});

3. 成员变更事件处理

// 新增成员
$server->handleUserCreated(function($message, \Closure $next) {
    // 处理新增成员逻辑
    return $next($message);
});

// 更新成员
$server->handleUserUpdated(function($message, \Closure $next) {
    // 处理更新成员逻辑
    return $next($message);
});

// 删除成员
$server->handleUserDeleted(function($message, \Closure $next) {
    // 处理删除成员逻辑
    return $next($message);
});

4. 部门变更事件处理

// 新增部门
$server->handlePartyCreated(function($message, \Closure $next) {
    // 处理新增部门逻辑
    return $next($message);
});

// 更新部门
$server->handlePartyUpdated(function($message, \Closure $next) {
    // 处理更新部门逻辑
    return $next($message);
});

// 删除部门
$server->handlePartyDeleted(function($message, \Closure $next) {
    // 处理删除部门逻辑
    return $next($message);
});

5. 成员标签变更事件处理

$server->handleUserTagUpdated(function($message, \Closure $next) {
    // 处理标签变更逻辑
    return $next($message);
});

自定义事件处理

对于上述便捷方法未覆盖的事件类型，可以使用中间件形式自定义处理：

$server->with(function($message, \Closure $next) {
    // 通过$message->event_type判断事件类型
    // 自定义处理逻辑
    return $next($message);
});

消息获取方式

EasyWeChat提供了两种获取推送消息的方式：

1. 获取原始消息：

$message = $server->getRequestMessage();

2. 获取解密后的消息（需要6.5.0+版本）：

$message = $server->getDecryptedMessage();

获取到的$message是一个EasyWeChat\Work\Message实例，开发者可以根据需要提取其中的信息进行处理。

最佳实践建议

1. 消息处理幂等性：由于网络原因可能导致消息重复推送，建议处理逻辑设计为幂等的。

2. 异常处理：在回调函数中加入适当的异常处理机制，确保单条消息处理失败不会影响其他消息处理。

3. 日志记录：建议在处理前后记录相关日志，便于排查问题。

4. 性能优化：对于耗时操作，建议异步处理，避免阻塞消息接收。

5. 安全验证：确保验证消息来源，防止伪造请求。

通过EasyWeChat提供的这些功能，开发者可以轻松构建稳定可靠的企业微信应用服务端，高效处理各类企业微信推送事件。