Package top.wcpe.beacon.agent.kit

Class BeaconAccess

java.lang.Object
top.wcpe.beacon.agent.kit.BeaconAccess
public final class BeaconAccess extends Object
Beacon 下游接入便捷门面。

把业务插件接入 Beacon 的样板收口成几个「正确」的便捷方法，杜绝常见踩坑——尤其是 回退判据只看 BeaconAgentProvider.isAvailable()、绝不看 BeaconAgent.connected()。 控制面短暂不可用时 agent 仍用本地快照 fail-static、配置仍可读，若误用 connected() 当回退判据 会把这种「在场但暂未连上」误判为「不可用」而回退到本地文件，造成 split-brain。

本类不是有状态静态单例：可自由 new，内部不缓存 agent 引用（每次调用现取门面， 避免持有已注销的旧实例）。订阅返回 BeaconSubscription 句柄，由调用方保管并 close()。

边界（守 ADR-0005，实现不进 kit）：

  • kit 不碰线程调度（不引 okhttp/kotlinx/TabooLib）。发现查询走同步 HTTP，请在异步线程调用； 变更回调在 agent 异步线程触发，重活下游自行切线程。
  • 本地文件回退不在 kit：agent 不在场时读配置便捷方法返回空，要不要回退本地文件、怎么读， 由下游自行决定（kit 只用 isBeaconPresent() 告知是否在场）。
  • 身份/zone/ORM 仍归 CoreLib；identity() 仅薄转发，不重复实现。

  • Constructor Summary

    Constructors
    Constructor
    Description
    BeaconAccess()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<top.wcpe.beacon.agent.api.AgentIdentity>
    awaitIdentity(long timeoutMillis)
    有界等待 agent 首次注册完成后取身份；agent 不在场、或等待超时仍未就绪时为空。
    Optional<String>
    configFormat(String dataId)
    取某 dataId 的格式（yaml / properties / json）；agent 不在场或无此项时为空。
    Optional<String>
    configMd5(String dataId)
    取某 dataId 的单项 md5；agent 不在场或无此项时为空。
    List<String>
    dataIds()
    列出当前所有有效配置项的 dataId；agent 不在场时为空列表。
    Optional<String>
    effectiveMd5()
    当前有效配置整体 md5；agent 不在场或尚未收敛时为空。
    Optional<top.wcpe.beacon.agent.api.AgentIdentity>
    identity()
    当前 agent 身份（薄转发）；agent 不在场时为空。
    List<top.wcpe.beacon.agent.api.ServiceInstance>
    instancesInGroup(String group)
    列出某大区(group)下全部在线实例（同步 HTTP，请在异步线程调用）；agent 不在场时为空列表。
    List<top.wcpe.beacon.agent.api.ServiceInstance>
    instancesInZone(String group, String zone)
    列出某 zone 下在线实例（同步 HTTP，请在异步线程调用）；agent 不在场时为空列表。
    boolean
    isBeaconPresent()
    Beacon agent 是否在场（下游回退判据）。
    List<top.wcpe.beacon.agent.api.ServiceInstance>
    query(top.wcpe.beacon.agent.api.DiscoveryQuery query)
    按条件过滤在线实例（同步 HTTP，请在异步线程调用）；agent 不在场时为空列表。
    Optional<String>
    rawConfig(String dataId)
    取某 dataId 的合并后原始文本；agent 不在场或无此项时为空。
    BeaconSubscription
    subscribeConfig(top.wcpe.beacon.agent.api.ConfigChangeListener listener)
    订阅有效配置变更。

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • BeaconAccess

      public BeaconAccess()

  • Method Details

    • isBeaconPresent

      public boolean isBeaconPresent()
      Beacon agent 是否在场（下游回退判据）。

      只看 BeaconAgentProvider.isAvailable()。为 false 时下游可回退到本地文件； 为 true 时即便控制面暂未连上（fail-static）也应继续走 Beacon，不要回退（防 split-brain）。

    • identity

      public Optional<top.wcpe.beacon.agent.api.AgentIdentity> identity()
      当前 agent 身份（薄转发）；agent 不在场时为空。

    • awaitIdentity

      public Optional<top.wcpe.beacon.agent.api.AgentIdentity> awaitIdentity(long timeoutMillis)
      有界等待 agent 首次注册完成后取身份；agent 不在场、或等待超时仍未就绪时为空。

      供下游（如 CoreLib）在自身启动阶段「优先取 Beacon 身份、超时降级本地」用： 在场且就绪→返回含权威 zone 的身份；不在场或超时→返回空，由下游回退本地配置 + 告警。 调用线程会被阻塞至多 timeoutMillis 毫秒，请勿在对延迟敏感的线程滥用。

    • rawConfig

      public Optional<String> rawConfig(String dataId)
      取某 dataId 的合并后原始文本；agent 不在场或无此项时为空。

    • configFormat

      public Optional<String> configFormat(String dataId)
      取某 dataId 的格式（yaml / properties / json）；agent 不在场或无此项时为空。

    • configMd5

      public Optional<String> configMd5(String dataId)
      取某 dataId 的单项 md5；agent 不在场或无此项时为空。

    • dataIds

      public List<String> dataIds()
      列出当前所有有效配置项的 dataId；agent 不在场时为空列表。

    • effectiveMd5

      public Optional<String> effectiveMd5()
      当前有效配置整体 md5；agent 不在场或尚未收敛时为空。

    • subscribeConfig

      public BeaconSubscription subscribeConfig(top.wcpe.beacon.agent.api.ConfigChangeListener listener)
      订阅有效配置变更。

      注册即重放当前值；subscribe 时 agent 未就绪不会丢订阅，由下游周期调用 BeaconSubscription.pump() 在 agent 转可用后补注册并重放（见其文档）。

      Returns:
      订阅句柄，由调用方保管并 close()

    • query

      public List<top.wcpe.beacon.agent.api.ServiceInstance> query(top.wcpe.beacon.agent.api.DiscoveryQuery query)
      按条件过滤在线实例（同步 HTTP，请在异步线程调用）；agent 不在场时为空列表。

    • instancesInZone

      public List<top.wcpe.beacon.agent.api.ServiceInstance> instancesInZone(String group, String zone)
      列出某 zone 下在线实例（同步 HTTP，请在异步线程调用）；agent 不在场时为空列表。

    • instancesInGroup

      public List<top.wcpe.beacon.agent.api.ServiceInstance> instancesInGroup(String group)
      列出某大区(group)下全部在线实例（同步 HTTP，请在异步线程调用）；agent 不在场时为空列表。