★ FEATURED ARTICLE 消息队列流处理后端微服务消息路由【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pu/pulsar点击查看免费下载导读本文深入解析 Apache Pulsar 的 PIP-457Remove support for V1 topic names and V1 Admin API该提案旨在从代码层面彻底移除 Pulsar 2.0 时代遗留的 V1 主题命名格式persistent://tenant/cluster/namespace/topic以及与之配套的 V1 Admin REST API、Lookup 端点和 WebSocket 路径。读完本文你将理解 V1/V2 两套命名体系的历史由来与并存代价、PIP-457 的完整拆除范围Admin API、Lookup、TopicName 解析、WebSocket、CLI 与测试掌握从 V1 到 V2 的迁移对照表与升级/回滚注意事项并通过当前仓库源码验证该提案的实际落地状态。一、背景知识Pulsar 主题命名的 V1 与 V2 之争Apache Pulsar 历史上长期存在两种主题Topic命名格式V1 格式persistent://tenant/cluster/namespace/topic—— 在主题路径中显式包含集群cluster名称V2 格式persistent://tenant/namespace/topic—— 省略集群名使所有命名空间隐式地视为全局global。V1 是 Pulsar 早期采用的原始命名约定。PIP-10 于 Pulsar 2.02018 年 6 月发布引入 V2 命名去掉了集群组件随后 PIP-11 进一步简化命名支持不带域名前缀的短主题名short topic name默认映射到persistent://public/default/。自 Pulsar 2.0 起 V1 主题名即被标记为废弃deprecated到 PIP-457 提出时已近 8 年。V1 命名格式还牵连出一整套配套端点V1 Admin REST API、Lookup 端点以及 WebSocket 路径的 URL 中均包含{property}/{cluster}/{namespace}三段式路径结构而 V2 对应路径使用{tenant}/{namespace}两段式。这些 V1 API 多年以来已被废弃并从 API 文档中隐藏但仍在线上路由表中处于活跃状态。从当前仓库源码看PIP-457 的拆除工作已落地pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/目录下仅剩AdminResource.java、impl/、v2/、v3/等已无v1包pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/下也仅存v2/目录V1 的TopicLookup类已不存在。二、动机为什么必须移除 V1PIP-457 明确列出了 V1 支持长期存在的六类成本维护负担每项 Admin API 操作都要在 V1 与 V2 两套端点类如v1.PersistentTopics、v1.NonPersistentTopics、v1.Namespaces、v1.TopicLookup与各自的 V2 对应类中重复实现。任何涉及 Admin API 的 bug 修复和新特性都必须同时兼顾两条代码路径。攻击面扩大V1 端点虽然从文档中隐藏却依然可路由、可访问形成了未被文档化的 API 表面仍需投入安全、测试与维护成本。TopicName 解析的代码复杂度TopicName类必须同时处理 3 段V2和 4 段V1两种名称解析且isV2()判断会蔓延到 broker、lookup 与客户端代码各处。WebSocket 处理器复杂度WebSocket 路径必须同时支持/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}V1与/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}V2。对新手贡献者与运维人员的困惑两套命名方案和两套 Admin API 并存带来不必要的认知开销。测试矩阵膨胀V1 路径必须由集成测试与单元测试覆盖而它对现代部署毫无价值。V1 主题自 2018 年 6 月发布的 Pulsar 2.0 起即被废弃在项目已步入 4.x 版本线的当下是时候完成这一废弃流程将 V1 支持彻底移除。三、目标范围In Scope / Out of Scope3.1 In Scope纳入本 PIP删除所有 V1 Admin REST API 端点类及其注册org.apache.pulsar.broker.admin.v1.PersistentTopicsorg.apache.pulsar.broker.admin.v1.NonPersistentTopicsorg.apache.pulsar.broker.admin.v1.Namespacesorg.apache.pulsar.broker.admin.v1.Clusters若存在删除 V1 主题查找端点org.apache.pulsar.broker.lookup.v1.TopicLookup删除 V1 WebSocket 处理器路径从TopicName及相关类中移除 V14 段主题名解析移除isV2()方法及所有基于 V1/V2 主题格式的条件分支移除LOOKUP_PATH_V1常量及相关重定向逻辑移除或更新所有覆盖 V1 代码路径的测试更新仍可能引用 V1 格式的 CLI 工具当客户端尝试使用 V1 风格主题名时记录清晰错误信息以辅助迁移3.2 Out of Scope不纳入本 PIP为 V4 Admin API 移除 V2 Admin API那将是另一个独立的 PIP修改二进制协议wire format对既有 V1 主题元数据执行元数据存储迁移本 PIP 只涉及代码移除数据迁移如需要将另行处理四、高层设计一次协同完成的拆除PIP-457 将拆除工作组织为一次协调统一single coordinated change的变更Admin API删除pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/下的v1包并从 broker Web 服务器初始化中移除 V1 REST 资源的注册。Lookup删除pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java及其注册。TopicName 解析将TopicName简化为只接受 3 段 V2 格式domain://tenant/namespace/localName若传入 4 段名称抛出带有清晰说明的IllegalArgumentException解释 V1 名称不再受支持及如何转换。WebSocket从AbstractWebSocketHandler及相关类中移除 V1 URI 解析路径。测试移除或转换所有 V1 专属测试用例偶然使用 V1 名称的测试应更新为 V2 格式。五、详细设计逐模块的代码级变更5.1 Admin API 移除将被删除的类清单pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.javapulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.javapulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java同时移除这些类在 broker 的 Jersey/JAX-RS 应用配置中的注册。对照当前仓库pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/下已无v1目录仅保留AdminResource基类、impl/、v2/与v3/与 PIP-457 的目标状态一致。5.2 TopicName 解析简化核心代码在pulsar-common模块的TopicName类中解析逻辑将从同时接受 V14 段与 V23 段简化为仅接受 V23 段。PIP 给出的目标实现如下// Before: accepts both V1 (4 parts) and V2 (3 parts) // After: only accepts V2 (3 parts) private TopicName(String completeTopicName) { // ... parse domain:// String[] parts rest.split(/, 3); // tenant/namespace/localName if (parts.length ! 3) { throw new IllegalArgumentException( Invalid topic name completeTopicName . Expected format: persistent://tenant/namespace/topic. V1 topic names (with cluster component) are no longer supported. Please use the V2 format without the cluster name.); } this.tenant parts[0]; this.namespace parts[1]; this.localName parts[2]; // cluster field removed entirely }isV2()方法与cluster字段将从TopicName中移除所有依赖isV2()分支的调用点被一并简化NamespaceName类同样会简化以移除 V1 支持。仓库落地验证在 pulsar-common/src/main/java/org/apache/pulsar/common/naming/TopicName.java 中当前解析已对含://的完整名称执行 3 段切分并在切分出 4 段时直接抛出V1 topic names (with cluster component) are no longer supported. Please use the V2 format: domain://tenant/namespace/topic. Got: completeTopicName即isV2()分支已从主解析路径消失V1 名称会被确定性拒绝。同时 TopicName.java 中保留了旧版 V1 managed ledger 名tenant/cluster/namespace/domain/topic自动丢弃 cluster 组件、转换为 V2 格式的兼容处理说明历史存储名的读取仍受到保护。短主题名解析TopicName.java同样只接受topic或tenant/namespace/topic两种形态与 PIP-11 的短名约定一致。与此呼应NamespaceName.java 的错误信息也明确指向 V2 格式tenant/namespace。5.3 Lookup 简化LOOKUP_PATH_V1常量及任何在 V1/V2 重定向路径间做选择的逻辑将被移除lookup 仅使用 V2 路径。当前仓库pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/下只剩LookupResult.java、NamespaceData.java、RedirectData.java、TopicLookupBase.java、v2/与package-info.java不再包含任何v1相关文件。5.4 WebSocket 简化WebSocket 处理器类中的getTopic()方法将只解析 V2 风格 URI/ws/v2/...。当前仓库中pulsar-websocket/src/main/java/org/apache/pulsar/websocket/AbstractWebSocketHandler.java 的路径注释已全部为/ws/v2/producer/...、/ws/v2/consumer/...、/ws/v2/reader/...且WebSocketProducerServlet、WebSocketConsumerServlet、WebSocketReaderServlet的常量分别定义为/ws/v2/producer、/ws/v2/consumer与/ws/v2/readerV1 的/ws/producer/...路径已不复存在。六、对外可见的变更Public-facing Changes6.1 REST API被移除的路径Persistent Topics (V1)GET /admin/persistent/{property}/{cluster}/{namespace}—— 列出主题GET/PUT/DELETE /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...—— 全部主题操作GET/PUT/DELETE /admin/persistent/{property}/{cluster}/{namespace}/partitioned—— 分区主题操作Non-Persistent Topics (V1)GET /admin/non-persistent/{property}/{cluster}/{namespace}—— 列出主题GET/PUT/DELETE /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...—— 全部主题操作Namespaces (V1)GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}—— 全部命名空间操作Lookup (V1)GET /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}—— 主题查找6.2 二进制协议、配置、CLI 与指标二进制协议无任何变更。配置不新增配置项。PIP 明确指出allowV1Topics之类的过渡性配置键不在本提案范围拆除是干净且彻底的。CLIpulsar-admin与pulsar-clientCLI 工具将只接受 V2 主题名传入 V1 主题名会产生带迁移指引的清晰错误信息。指标Metrics无变更。七、监控与安全考量升级后运维人员应关注客户端错误尝试使用 V1 主题名的客户端将收到明确错误响应V1 admin 路径返回 HTTP 404V1 主题名则在客户端侧抛出IllegalArgumentException。在安全方面本次变更通过移除未被文档化但处于活跃状态的 REST 端点缩小了 API 攻击面不引入任何新的安全考量。八、向后与向前兼容性8.1 升级Breaking Change对任何仍在使用 V1 主题名或 V1 Admin API 路径的部署而言这是一次破坏性变更。升级到包含此变更的版本之前运维人员必须确保所有使用的主题名均为 V2 格式persistent://tenant/namespace/topic确保所有 Admin API 客户端使用 V2 端点/admin/v2/...确保所有 WebSocket 客户端使用 V2 路径/ws/v2/...V1 格式自 2018 年 6 月发布的 Pulsar 2.0 起即被废弃已近 8 年。任何在受支持的 Pulsar 版本上持续维护的部署理应已完全采用 V2 格式。8.2 降级 / 回滚回滚到支持 V1 主题名的旧版本不会产生问题因为本次变更不涉及任何数据格式变化。8.3 地理复制Geo-Replication无影响。地理复制早已使用 V2 主题名V1 主题名中的 cluster 组件最初与复制配置相关但自 V2 引入以来已解耦。九、迁移指南对任何仍在使用 V1 主题名的用户迁移非常直接——从主题名路径中移除 cluster 组件即可V1 格式V2 格式persistent://my-tenant/my-cluster/my-namespace/my-topicpersistent://my-tenant/my-namespace/my-topic/admin/persistent/my-tenant/my-cluster/my-namespace/admin/v2/persistent/my-tenant/my-namespace/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic/ws/v2/producer/persistent/my-tenant/my-ns/my-topic十、相关 PIP 与历史脉络PIP-10从主题名中移除 cluster引入 V2 命名PIP-11短主题名进一步简化主题命名PIP-48提出 V4 Admin APIAdmin API 的未来方向三条 PIP 共同勾勒出 Pulsar 主题命名与 Admin API 的演进主线PIP-10/PIP-11 确立 V2 为事实标准PIP-457 完成历史债务清偿而 PIP-48 则为下一代 Admin API 预留了方向。总结PIP-457 是一次清理八年技术债的收尾性变更它删除 V1 Admin API 端点类与注册、V1 Lookup 端点、V1 WebSocket 路径、TopicName中的 4 段解析与isV2()分支、LOOKUP_PATH_V1常量及其重定向逻辑并同步清理测试与 CLI。从当前仓库源码pulsar-broker的admin/与lookup/目录已无v1包、TopicName已拒绝 4 段名、WebSocket 仅暴露/ws/v2路径可见该提案已完整实施。对使用者而言唯一需要做的动作是确保自己的主题名、Admin API 与 WebSocket 客户端全部切换到 V2 格式——这也正是 Pulsar 自 2.0 以来一直推荐的标准用法。赞分享消息队列流处理后端微服务消息路由【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pu/pulsar点击查看免费下载相关推荐Apache Pulsar PIP-422 深度解析全局 Topic 级 replicated clusters 策略与 Topic 级策略删除 APIApache Pulsar PIP 422 深度解析全局 Topic 级 replicated clusters 策略与 Topic 级策略删除 API 导读消息队列流处理后端微服务消息路由Apache Pulsar 短 Topic 名Short Topic Names机制详解PIP-11 从设计到实现Apache Pulsar 短 Topic 名Short Topic Names机制详解PIP 11 从设计到实现 导读 Pulsar 从设计之初就是一个消息队列流处理后端微服务消息路由Apache Pulsar PIP-10 详解从命名空间中移除 cluster 段的历史性变革Apache Pulsar PIP 10 详解从命名空间中移除 cluster 段的历史性变革 PIP 10Remove cluster for names消息队列流处理后端微服务消息路由上一篇ESP-Skainet开启智能语音助手的新纪元下一篇如何快速构建3D地理信息系统Cesium Map完整实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
 清空 OCR 后端注册表)
