pushy

构建/测试

Pushy是一个用于发送APNs（iOS、macOS和Safari）推送通知的Java库。

Pushy使用Apple基于HTTP/2的APNs协议发送推送通知，支持TLS和基于令牌的身份验证。它以详尽的文档、异步操作和工业级规模设计为重点，区别于其他推送通知库。使用Pushy，可以轻松高效地维护多个并行连接到APNs网关，向多个不同应用程序（"主题"）发送大量通知。

我们相信Pushy已经是从Java应用程序发送APNs推送通知的最佳工具，我们希望您能通过错误报告和拉取请求帮助我们使它变得更好。

如果您需要一个简单的GUI应用程序用于开发或测试目的发送推送通知，您可能还会对Pushy的姐妹项目Pushy Console感兴趣。

快速链接

API文档
讨论（用于一般支持和问题）
问题（用于错误报告和功能请求）

获取Pushy

如果您使用Maven，可以通过在POM中添加以下依赖声明将Pushy添加到您的项目中：

<dependency>
    <groupId>com.eatthepath</groupId>
    <artifactId>pushy</artifactId>
    <version>0.15.4</version>
</dependency>

如果您不使用Maven（或其他理解Maven依赖的工具，如Gradle），您可以下载Pushy的.jar文件并直接添加到您的项目中。您还需要确保Pushy的运行时依赖项在您的类路径中。它们是：

netty 4.1.111
slf4j 1.7（可能还需要一个SLF4J绑定，如下面日志部分所述）
fast-uuid 0.1

Pushy本身需要Java 8或更新版本来构建和运行。虽然不是必需的，但用户可以选择使用netty-native作为SSL提供程序以提高性能。要使用本地提供程序，请确保netty-tcnative在您的类路径中。Maven用户可以向他们的项目添加以下依赖：

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-tcnative-boringssl-static</artifactId>
    <version>2.0.62.Final</version>
    <scope>runtime</scope>
</dependency>

与APNs服务器进行身份验证

在开始使用Pushy之前，您需要在Apple那里进行一些配置工作，注册您的应用并获取所需的证书或签名密钥（稍后会详细介绍）。有关此过程的详细信息，请参阅Apple的UserNotifications文档中的使用APNs注册您的应用部分。请注意，存在一些注意事项，特别是在macOS 10.13（El Capitan）下。

一般来说，APNs客户端必须以某种方式向APNs服务器进行身份验证，然后才能发送推送通知。目前，APNs（和Pushy）支持两种身份验证方法：基于TLS的身份验证和基于令牌的身份验证。这两种方法是互斥的；您需要为每个客户端选择其中一种。

TLS身份验证

在基于TLS的身份验证中，客户端在连接时向服务器提供TLS证书，并可以向证书中指定的任何"主题"发送通知。通常，这意味着单个客户端只能向单个接收应用程序发送推送通知。

一旦您注册了应用并拥有必要的证书，使用Pushy发送推送通知的第一步就是创建一个ApnsClient。使用TLS身份验证的客户端需要证书和私钥来与APNs服务器进行身份验证。存储证书和密钥最常见的方式是使用密码保护的PKCS#12文件（如果您按照Apple的说明操作，最终会得到一个密码保护的.p12文件）。要创建一个使用基于TLS身份验证的客户端：

final ApnsClient apnsClient = new ApnsClientBuilder()
        .setApnsServer(ApnsClientBuilder.DEVELOPMENT_APNS_HOST)
        .setClientCredentials(new File("/path/to/certificate.p12"), "p12-file-password")
        .build();

令牌身份验证

在基于令牌的身份验证中，客户端仍然使用TLS加密的连接连接到服务器，但在连接时不向服务器提供证书。相反，客户端在发送的每个通知中包含一个经过加密签名的令牌（不用担心——Pushy会自动处理这个过程）。客户端可以向任何拥有有效签名密钥的"主题"发送推送通知。

要开始使用基于令牌的客户端，您需要从Apple获取一个签名密钥（在某些上下文中也称为私钥）。一旦您有了签名密钥，就可以创建一个新的客户端：

final ApnsClient apnsClient = new ApnsClientBuilder()
        .setApnsServer(ApnsClientBuilder.DEVELOPMENT_APNS_HOST)
        .setSigningKey(ApnsSigningKey.loadFromPkcs8File(new File("/path/to/key.p8"),
                "TEAMID1234", "KEYID67890"))
        .build();

发送推送通知

Pushy的APNs客户端维护一个内部的APNs服务器连接池，并按需创建新连接。因此，客户端不需要显式启动。无论您选择哪种身份验证方法，一旦创建了客户端，它就可以开始发送推送通知了。至少，推送通知需要一个设备令牌（用于识别通知的目标设备，这是一个与身份验证令牌不同的概念）、一个主题和一个有效载荷。

final SimpleApnsPushNotification pushNotification;

{
    final ApnsPayloadBuilder payloadBuilder = new SimpleApnsPayloadBuilder();
    payloadBuilder.setAlertBody("示例！");

    final String payload = payloadBuilder.build();
    final String token = TokenUtil.sanitizeTokenString("<efc7492 bdbd8209>");

    pushNotification = new SimpleApnsPushNotification(token, "com.example.myApp", payload);
}

Pushy包含一个SimpleApnsPayloadBuilder，并且基于Gson和Jackson的负载构建器也作为单独的模块提供。APNs负载实际上就是JSON字符串，调用者可以选择自己喜欢的方式生成负载；虽然Pushy的负载构建器可能很方便，但调用者并不一定要使用它们。

发送推送通知的过程是异步的；尽管发送通知并从服务器获得回复可能需要一些时间，但客户端会立即返回一个CompletableFuture。您可以使用这个CompletableFuture来跟踪发送操作的进度和最终结果。请注意，发送通知会返回一个PushNotificationFuture，它是CompletableFuture的子类，始终持有对已发送通知的引用。

final PushNotificationFuture<SimpleApnsPushNotification, PushNotificationResponse<SimpleApnsPushNotification>>
    sendNotificationFuture = apnsClient.sendNotification(pushNotification);

CompletableFuture在以下三种情况下会完成：

网关接受通知并将尝试将其传递给目标设备。
网关拒绝通知；这应被视为永久性失败，不应再次发送该通知。此外，APNs网关可能会指示目标令牌变为无效的时间戳。如果发生这种情况，除非该令牌自该时间戳以来已重新注册，否则您应停止尝试向该令牌发送任何通知。
CompletableFuture因异常而失败。这通常应被视为临时失败，当问题解决后，调用者应尝试再次发送通知。

示例：

try {
    final PushNotificationResponse<SimpleApnsPushNotification> pushNotificationResponse =
            sendNotificationFuture.get();

    if (pushNotificationResponse.isAccepted()) {
        System.out.println("推送通知被APNs网关接受。");
    } else {
        System.out.println("通知被APNs网关拒绝：" +
                pushNotificationResponse.getRejectionReason());

        pushNotificationResponse.getTokenInvalidationTimestamp().ifPresent(timestamp -> {
            System.out.println("\t...且令牌自 " + timestamp + " 起无效");
        });
    }
} catch (final ExecutionException e) {
    System.err.println("发送推送通知失败。");
    e.printStackTrace();
}

需要注意的是，CompletableFuture提供了在操作完成时安排额外任务运行的功能。在实践中，等待每个单独的推送通知是低效的，大多数用户最好是向CompletableFuture添加后续任务，而不是阻塞等待其完成。例如：

sendNotificationFuture.whenComplete((response, cause) -> {
    if (response != null) {
        // 从这里开始处理推送通知响应，如前所示。
    } else {
        // 向APNs服务器发送通知时出现问题。请注意，这与服务器的拒绝不同，
        // 表示在实际发送通知或等待回复时出现了问题。
        cause.printStackTrace();
    }
});

所有APNs客户端——即使是那些从未发送过消息的客户端——都可能分配并占用系统资源，释放这些资源很重要。APNs客户端旨在成为持久的、长期存在的资源；您绝对不需要在发送通知（甚至是一批通知）后关闭客户端，但当应用程序关闭时，您需要关闭客户端：

final CompletableFuture<Void> closeFuture = apnsClient.close();

关闭时，客户端会等待所有已发送但未确认的通知从服务器收到回复。已传递给sendNotification但尚未发送到服务器的通知（即等待在内部队列中的通知）在断开连接时会立即失败。调用者通常应确保所有已发送的通知都已得到服务器的确认，然后再关闭。

性能和最佳实践

为高吞吐量应用程序充分利用系统资源总是需要一些努力。为了引导您完成这个过程，我们整理了一个维基页面，涵盖了一些使用Pushy的最佳实践。所有这些要点在维基上都有更详细的介绍，但总的来说，我们的建议是：

将ApnsClient实例视为长期存在的资源
如果您想跟踪推送通知的状态，请向CompletableFutures添加后续任务
使用流量控制策略，避免以超过服务器响应能力的速度将推送通知加入队列
选择能够平衡CPU时间和网络吞吐量的线程数和并发连接数

指标

Pushy包含一个用于监控指标的接口，这些指标提供了客户端行为和性能的洞察。您可以编写自己的ApnsClientMetricsListener接口实现来记录和报告指标。我们还提供了使用Dropwizard Metrics库和使用Micrometer应用监控外观收集和报告指标的指标监听器，作为单独的模块。要开始接收指标，请在构建新客户端时设置监听器：

final ApnsClient apnsClient = new ApnsClientBuilder()
        .setApnsServer(ApnsClientBuilder.DEVELOPMENT_APNS_HOST)
        .setSigningKey(ApnsSigningKey.loadFromPkcs8File(new File("/path/to/key.p8"),
                "TEAMID1234", "KEYID67890"))
        .setMetricsListener(new MyCustomMetricsListener())
        .build();

请注意，监听器实现中的指标处理方法绝不应调用阻塞代码。直接在处理方法中增加计数器是合适的，但对数据库或远程监控端点的调用应该分派到单独的线程。

使用代理

如果您需要为出站连接使用代理，可以在构建ApnsClient实例时指定一个ProxyHandlerFactory。为HTTP、SOCKS4和SOCKS5代理提供了具体的ProxyHandlerFactory实现。

示例：

final ApnsClient apnsClient = new ApnsClientBuilder()
    .setApnsServer(ApnsClientBuilder.DEVELOPMENT_APNS_HOST)
    .setSigningKey(ApnsSigningKey.loadFromPkcs8File(new File("/path/to/key.p8"),
            "TEAMID1234", "KEYID67890"))
    .setProxyHandlerFactory(new Socks5ProxyHandlerFactory(
        new InetSocketAddress("my.proxy.com", 1080), "username", "password"))
    .build();

如果使用通过JVM系统属性配置的HTTP代理，您也可以使用：

final ApnsClient apnsClient = new ApnsClientBuilder()
    .setApnsServer(ApnsClientBuilder.DEVELOPMENT_APNS_HOST)
    .setSigningKey(ApnsSigningKey.loadFromPkcs8File(new File("/path/to/key.p8"),
            "TEAMID1234", "KEYID67890"))
    .setProxyHandlerFactory(HttpProxyHandlerFactory.fromSystemProxies(
            ApnsClientBuilder.DEVELOPMENT_APNS_HOST))
    .build();

日志记录

Pushy 使用 SLF4J 进行日志记录。如果你还不熟悉它，SLF4J 是一个门面，允许用户通过在类路径中添加特定的"绑定"来选择在部署时使用哪个日志库。为了避免替你做出选择，Pushy 本身不依赖于任何 SLF4J 绑定；你需要自己添加一个（可以通过在你自己的项目中添加它作为依赖项，或者直接安装它）。如果你的类路径上没有 SLF4J 绑定，你可能会看到类似这样的警告：

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

更多信息，请参阅 SLF4J 用户手册。

Pushy 使用日志级别如下：

级别	记录的事件
`error`	严重的、不可恢复的错误；可恢复的错误，可能表明 Pushy 中存在 bug
`warn`	严重但可恢复的错误；可能表明调用者代码中存在 bug 的错误
`info`	重要的生命周期事件
`debug`	次要的生命周期事件；预期的异常
`trace`	单个 IO 操作

使用模拟服务器

Pushy 包含一个模拟 APNs 服务器，调用者可以在集成测试和基准测试中使用。在正常操作中不需要使用模拟服务器（或任何相关类）。

要构建模拟服务器，调用者应使用 MockApnsServerBuilder。所有服务器都需要一个 PushNotificationHandler（由提供给构建器的 PushNotificationHandlerFactory 构建），它决定模拟服务器是接受还是拒绝每个传入的推送通知。Pushy 包括一个对基准测试有帮助的 AcceptAllPushNotificationHandlerFactory 和一个对集成测试可能有帮助的 ValidatingPushNotificationHandlerFactory。

调用者在构建模拟服务器时还可以提供一个 MockApnsServerListener；每当模拟服务器接受或拒绝来自客户端的通知时，监听器都会收到通知。