Pulsar官方文档翻译-概念和架构-Pulsar客户端（Pulsar Clients）

本篇翻译转自Zongyang在crowdin apache pulsar项目中的翻译，由于已经完成翻译，我直接转载，不再翻译。

------------------------------------------

Pulsar 客户端

Pulsar向用户暴露原生的Java和C++的客户端API。

Puslar客户端封装并优化了客户端-服务器的通信协议，并暴露出一套简单直观的API，提供给应用程序使用。

底层实现上，目前官方版的Pulsar客户端支持对用户透明的连接重连、故障切换、未ack消息的缓冲、消息重传。

自定义客户端库

如果您想创建自己的客户端库, 我们建议参考Pulsar的自定义 二进制协议 的文档。

 

客户端使用步骤

当应用程序要创建生产者/消费者时, Pulsar客户端库执行按以下两个步骤的工作:

1. 客户端将尝试通过向服务器（Broker）发送 HTTP 查找请求，来确定主题（Topic）所在的服务器（Broker）。客户端通过查询Zookeeper中（缓存）的元数据，来确定这条消息的topic在哪个broker上，如果该topic不在任何一个broker上，则把这个topic分配在负载最少的broker上。

2. 当客户端获取了broker的地址之后，将会创建一个TCP连接（或复用连接池中的连接）并且进行鉴权。客户端和broker通过该连接交换基于自定义协议的二进制命令。同时，客户端会向broker发送一条命令用以在broker上创建生产者/消费者，该命令将会在验证授权策略后生效。

每当 TCP 连接中断时, 客户端将立即重新启动此安装阶段, 并将继续尝试使用指数退避重新建立生产者或使用者, 直到操作成功为止。

 

Reader 接口

在Pulsar中, "标准" 消费者接口 涉及使用消费者监听 主题, 处理传入消息, 并在处理完这些消息后最终确认它们。 每当使用者连接到某个主题时, 它就会自动开始从最早的没被确认(unacked)的消息处读取, 因为该主题的游标是由Pulsar自动管理的。

使用Pulsar的 读取器接口, 应用程序可以手动管理游标。 当使用读取器连接到一个主题而非消费者时，在读取器连接到主题的时候就需要指定读取器从哪个位置开始读消息。

当连接到某个主题时, 读取器从以下位置开始读消息:

• 主题中的 最早的 可用消息

• 主题中的 最新 可用消息

• 除最早的和最新的之外的可用消息位点。如果你使用该选项，你需要显式的提供一个消息ID。你的应用程序需要自己管理消息ID，例如从持久化的数据存储或缓存中获取

Pulsar的读取器接口在流计算场景下，对提供effective-once的语义很有帮助。 Pulsar能够将主题的消息进行重放，并从重放后的位置开始读取消息，是满足流处理的场景的重要基础。读取器界面为Pulsar客户端在主体内提供了一种底层抽象“手动管理的位点”

未分区主题

Pulsar的读取器目前无法在已分区的主题上使用。

下面是一个Java语言实现的从主题上最早可用消息的位置开始消费的例子：

import org.apache.pulsar.client.api.Message;
import org.apache.pulsar.client.api.MessageId;
import org.apache.pulsar.client.api.Reader;

// Create a reader on a topic and for a specific message (and onward)
Reader<byte[]> reader = pulsarClient.newReader()
    .topic("reader-api-test")
    .startMessageId(MessageId.earliest)
    .create();

while (true) {
    Message message = reader.readNext();

    // Process the message
}

创建一个从最新可用消息处开始读取消息的读取器 

Reader<byte[]> reader = pulsarClient.newReader()
    .topic(topic)
    .startMessageId(MessageId.latest)
    .create();

创建一个从其他位置（非最早可用且非最新可用消息处）读取消息的读取器

byte[] msgIdBytes = // Some byte array
MessageId id = MessageId.fromByteArray(msgIdBytes);
Reader<byte[]> reader = pulsarClient.newReader()
    .topic(topic)
    .startMessageId(id)
    .create();