Webhook Java 工具类 API

概述

Webhook Java 快速入门 介绍了如何快速使用神策智能运营工具类快速启动一个用于接收和处理神策智能运营 Webhook 请求的方法。本文将结合使用场景对工具类进行更多介绍。

简单接收和处理

Webhook Java 快速入门 的示例实现了 com.sensorsdata.webhook.processor.SfWebhookProcessor 接口。接口定义如下：

public interface SfWebhookProcessor {
  void handleWebhookEntries(List<SfWebhookEntry> entries);
}

• 参数 entries 包含一组来自神策智能运营服务器的请求，其中 SfWebhookEntry 包含了每个请求的 request  和 response 。
• 若一个 entry 处理失败，可以通过调用 entry.getResponse().failed("some reason"); 返回错误原因给神策智能运营服务器，以供排查。
• 若没有显式对 response 设置是否成功，默认按处理成功返回。
• 该接口可以满足大部分使用场景，并可以通过增加服务线程数（Jetty 线程池大小）来增加并发度，具体方法请见本文关于 Bootstrap 类的介绍。
• 该实现函数可能被多个线程同时调用。
• 一个简单的示例代码 。

异步中间人请求转发

一种 Webhook 处理场景：当我们接到一个来自神策智能运营服务器的 Webhook 请求后，会对请求内容进行一定变换，拼装成一个新的请求，再发送到其他服务器的 HTTP API。一个例子是某短信发送平台对外提供 HTTP API 接口，并提供了请求规范，包括请求内容如何封装，这时就需要有一个“中间人”中转神策智能运营 Webhook 的请求。

这种场景可以用上面第二节的“简单接收和处理”实现，但如需要实现更高性能的异步转发，可以实现我们封装的抽象类 com.sensorsdata.webhook.middleman.SfWebhookMiddleManProcessor  ，类定义如下：

public abstract class SfWebhookMiddleManProcessor {

  /**
   * 将 webhook 请求转换成向下游请求的内容
   *
   * @param requestEntries 原 webhook 请求
   * @param httpClient
   * @return 向下游请求的 request body
   */
  public abstract Request handleWebhookRequest(List<SfWebhookRequestEntry> requestEntries,
      HttpClient httpClient) throws Exception;

  /**
   * 如果目标服务有 response body，将调用该请求将 response 转化为对神策智能运营请求结果
   *
   * @param responseStatusCode 目标服务的返回码
   * @param responseBody       目标服务的 response body，可能为 null
   * @param requestEntries     本次请求对应的神策智能运营 request
   * @return 返回空集合表示全部成功
   */
  public List<SfWebhookResponseEntry> handleNewEndpointResponse(
      int responseStatusCode,
      String responseBody,
      List<SfWebhookRequestEntry> requestEntries) throws Exception {
    return Collections.emptyList();
  }
}

• 实现该抽象类可以将转发的请求异步执行。
• handleWebhookRequest 实现只需要根据 requestEntries 构造并返回 Request 对象 ，不需要实际执行这个请求。
• Request 对象 描述了对模板的请求，包括使用哪种 HTTP Method，Cookie、Header、Request Body 等。
• 向目标 API 请求结束后，工具框架将调用 handleNewEndpointResponse 方法，以解析目标 API 的请求结果，返回空数组或 null 表示本次所有请求都是成功的。
• 该实现类的方法可能会被多个线程同时访问。
  示例使用代码可以参考 代码实现样例 。

用 Bootstrap 类启动服务

您可以在您的 Java 程序中合适的位置启动 Webhook 服务，Bootstrap 封装了用于启动的参数：