Pulsarctl 的开发原由

Apache Pulsar 是下一代云原生分布式消息发布订阅系统。在进行云端产品开发时，需要一套基于 Golang 的 admin API 库，方便和 Pulsar Broker 的 Admin API 进行交互。

此前，Apache Pulsar 提供了 pulsar-admin 来管理客户端，提供了对 Brokers、Clusters、Namespaces、Topics 等配置信息的更新和获取。在使用过程中我们发现 pulsar-admin 存在如下问题：

• pulsar-admin 需要更多的依赖，在运行时需要加载 JVM 等环境，因此命令在执行时需要较长的时间；
• pulsar-admin 对命令的描述信息不全面，使用过程中出现错误时，不能快速准确的定位到相应问题，给用户使用带来不便。

Pulsarctl 简介

Pulsarctl 基于 Pulsar REST API 使用 Go 语言进行开发，相比 Java 更加轻量级。一方面为 Go 的开发者提供了 API 接口，方便用户开发。另一方面提供了一个更为方便、快速的命令行客户端。

如何在 Pulsarctl 中使用 AdminAPI

Pulsarctl Admin API 提供了基于 Go 语言开发的 Admin 接口与 Pulsar Broker 进行交互，方便 Go 使用者开发。

如何使用 Pulsarctl Admin API 进行开发呢？Pulsarctl Admin API 提供了以下接口：

     
    // Client provides a client to the Pulsar Restful API
    type Client interface {
        Clusters() Clusters
        Functions() Functions
        Tenants() Tenants
        Topics() Topics
        Subscriptions() Subscriptions
        Sources() Sources
        Sinks() Sinks
        Namespaces() Namespaces
        Schemas() Schema
        Brokers() Brokers
        BrokerStats() BrokerStats
    }
   

如果需要更多接口文档，可以参考: https://godoc.org/github.com/streamnative/pulsarctl。

Pulsarctl Admin API 使用示例:

     
    config := &pulsar.Config{
        WebServiceURL: “http://localhost:8080”,
        HTTPClient:    http.DefaultClient,

        // If the server enable the TLSAuth
        // Auth: auth.NewAuthenticationTLS()

        // If the server enable the TokenAuth
        // TokenAuth: auth.NewAuthenticationToken()
    }
    // the default NewPulsarClient will use v2 APIs. If you need to request other version APIs,
    // you can specified the API version like this:
    // admin := cmdutils.NewPulsarClientWithAPIVersion(pulsar.V2)
    admin, err := pulsar.New(config)
    if err != nil {
        // handle the err
        return
    }

    // more APIs, you can find them in the pkg/pulsar/admin.go
    // You can find all the method in the pkg/pulsar
    clusters, err := admin.Clusters().List()
    if err != nil {
        // handle the error
    }

    // handle the result
    fmt.Println(clusters)
        

Pulsarctl 中的命令行工具

Pulsarctl 命令行提供了更全面的命令描述和使用方式。

以 create topic 为例，输出如下：

如上图所示：pulsarctl 提供了以下四部分信息：

Used for : 对该命令的使用场景进行描述 Required Permission：使用该命令所需要的权限 Output：列出使用该命令所有的输出信息，包括正确的输出和错误的输出 Examples：列出命令的使用示例

Pulsarctl 比 pulsar-admin 提供了更详细的信息，方便用户快速定位问题。

此外，在开发 Pulsarctl 的过程中，我们针对 pulsar-admin 命令不合理的地方做了修改，并对其进一步拆分，使 Pulsarctl 更符合用户的使用行为和习惯。比如：

• 整合原有 topics 命令中的 partitioned-topics 和 topics 命令，输出信息更易懂、易用。

• 在 pulsarctl 中，将 subscription 相关的命令提取为一个新的命令组 —— subscription。而 pulsar-admin 中，subscription 的相关命令是作为 topics 的子命令，用户使用并不方便。

• 在 pulsarctl 中，优化了特殊字符的使用。在 pulsar-admin 中，有时用户需要在 shell 中输入 json-string，这个易用性不是很好。以 functions putstate 为例，二者对比如下：

putstate	pulsar-admin	pulsarctl
stringValue	bin/pulsar-admin functions putstate --tenant test --namespace test-namespace --name word_count --state "{\"key\":\"pulsar-1\", \"stringValue\":\"hello\"}"	./pulsarctl functions putstate --tenant public --namespace default --name word_count_1 pulsar-1 - hello
byteValue	bin/pulsar-admin functions putstate --tenant test --namespace test-namespace --name word_count --state "{\"key\":\"pulsar-1\", \"byteValue\":\"README.md\"}"	./pulsarctl functions putstate --tenant public --namespace default --name word_count_1 pulsar = README.md

下面，我们通过具体示例来展示 pulsarctl 与 pulsar-admin 在使用中的差别。

查询所有命令

创建 non-partitioned topic

创建 partitioned topic

使用 pulsar-admin 查询 Topics 时，需要区分 Partitioned Topic 和 NonPartitioned Topic。

查询 non-partitioned topic

查询 partitioned topics

使用 pulsarctl 查询 Topics

参与 Pulsarctl

在使用 Pulsarctl 过程中发现任何问题，欢迎指出。同时，欢迎参与 Pulsarctl 项目，贡献代码或文档。在参与的过程中，您会进一步了解 Pulsarctl 的使用和开发历程。

• Github: https://github.com/streamnative/pulsarctl
• 贡献指南：https://github.com/streamnative/pulsarctl/blob/master/CONTRIBUTING.md
• 开发指南： https://github.com/streamnative/pulsarctl/blob/master/docs/en/developer-guide.md