【Kafka官方文档翻译】5.5.1. API 设计

原文地址：https://kafka.apache.org/0101/documentation.html#apidesign

Producer APIs

Producer API封装了底层两个Producer：

• kafka.producer.SyncProducer
• kafka.producer.async.AsyncProducer

    class Producer {

    /* Sends the data, partitioned by key to the topic using either the */
    /* synchronous or the asynchronous producer */
    public void send(kafka.javaapi.producer.ProducerData producerData);

    /* Sends a list of data, partitioned by key to the topic using either */
    /* the synchronous or the asynchronous producer */
    public void send(java.util.List> producerData);

    /* Closes the producer and cleans up */
    public void close();

    }

这么做的目的是通过一个简答的API暴露把所有Producer的功能暴露给Client。Kafka的Producer可以：

• 排队/缓存多个发送请求并且异步的批量分发出去：
  　　kafka.producer.Producer提供批量化多个发送请求(producer.type=async)，之后进行序列化并发送的分区的能力。批大小可以通过一些配置参数进行设置。将事件加入到queue中，他们会被缓冲在queue中，直到满足queue.time或batch.size达到配置的值。后台线程（kafka.producer.async.ProducerSendThread）从queue中获取数据并使用kafka.producer.EventHandler对数据进行序列化并发送到合适的分区。可以通过event.handler参数以插件的形式添加自定义的event handler程序。在producer queue pipeline处理的各个阶段可以注入回调，用于自定义的日志/跟踪代码或者监控逻辑。这可以通过实现kafka.producer.async.CallbackHandler接口并设置callback.handler参数来实现。
• 使用用户指定的Encoder来序列化数据：

    interface Encoder {
    public Message toMessage(T data);
    }

默认使用kafka.serializer.DefaultEncoder。

• 通过用户可选的Partitioner来实现乱负载均衡：
  　　Partition的路由由kafka.producer.Partitioner决定。

    interface Partitioner {
    int partition(T key, int numPartitions);
    }

分区选择API使用key和分区总数来选择最终的partition（返回选择的partition id）。id用于从排序的partition列表中选择最终的一个分区去发送数据。默认的分区策略是hash(key)%numPartitions。如果key是null，会随机选择一个分区。可以通过partitioner.class参数来配置特定的分区选择策略。

Consumer APIs

我们有两个级别的Consumer API。低级别的“简单的”API和单个Broker之间保持链接并且和发送到服务端的网络请求有紧密的对应关系。这个API是无状态的，每个请求都包含offset信息，允许用户维护这个元数据。
　　高级别的API在Consumer端隐藏了Broker的细节，并且允许从集群消费数据而不关心底层的拓扑结构。同样维持了“哪些数据已经被消费过”的状态。高级别的API还提供了通过表达式订阅的Topic的功能（例如通过白名单或者黑名单的方式订阅）。

Low-level API

    class SimpleConsumer {

    /* Send fetch request to a broker and get back a set of messages. */
    public ByteBufferMessageSet fetch(FetchRequest request);

    /* Send a list of fetch requests to a broker and get back a response set. */
    public MultiFetchResponse multifetch(List fetches);

    /**
    * Get a list of valid offsets (up to maxSize) before the given time.
    * The result is a list of offsets, in descending order.
    * @param time: time in millisecs,
    *              if set to OffsetRequest$.MODULE$.LATEST_TIME(), get from the latest offset available.
    *              if set to OffsetRequest$.MODULE$.EARLIEST_TIME(), get from the earliest offset available.
    */
    public long[] getOffsetsBefore(String topic, int partition, long time, int maxNumOffsets);
    }

低级别的API用于实现高级别的API，也被直接使用在一些在状态上有特殊需求的“离线”Consumer。

High-level API

    /* create a connection to the cluster */
    ConsumerConnector connector = Consumer.create(consumerConfig);

    interface ConsumerConnector {

    /**
    * This method is used to get a list of KafkaStreams, which are iterators over
    * MessageAndMetadata objects from which you can obtain messages and their
    * associated metadata (currently only topic).
    *  Input: a map of 
    *  Output: a map of 
    */
    public Map> createMessageStreams(Map topicCountMap);

    /**
    * You can also obtain a list of KafkaStreams, that iterate over messages
    * from topics that match a TopicFilter. (A TopicFilter encapsulates a
    * whitelist or a blacklist which is a standard Java regex.)
    */
    public List createMessageStreamsByFilter(
        TopicFilter topicFilter, int numStreams);

    /* Commit the offsets of all messages consumed so far. */
    public commitOffsets()

    /* Shut down the connector */
    public shutdown()
    }

这个API围绕迭代器，通过KafkaStream类实现。一个KafkaStream表示了一个或多个分区（可以分布在不同的Broker上）组成的消息流。每个Stream被单个线程处理，客户端可以在创建流时提供需要的个数。这样，一个流背后可以是多个分区，但是一个分区只会属于一个流。
　　createMessageStreams调用会把Consumer注册到Topic，促使Consumer/Broker的重新分配。API鼓励在单次调用中创建多个Stream以减少充分配的次数。createMessageStreamsByFilter方法的调用（另外的）用于注册watcher去发现匹配过滤规则的topic。createMessageStreamsByFilter返回的迭代器可以迭代来此多个Topic的消息（如果多个Topic都符合过滤规则）。