Nacos Agent Discovery Java SDK 场景矩阵测试优先契约、集成测试分层与实现轨迹【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos导读本文围绕 Nacos 仓库中的 AGENT_DISCOVERY_SDK_IT_SCENARIOS.md 展开它是第一个AgentDiscoveryService协议无关的 Agent 发现服务实现的测试优先契约test-first contract与执行轨迹execution trace在生产代码落地之前先固定场景清单再由配套的 Java SDK 集成测试IT与单元测试UT逐条守护。读完本文你将掌握Agent 发现的测试分层体系IT / Directed IT / UT / 延后项Search、Discover、本地轮询订阅、完整端点发布、部分/完整注销、心跳重连与重放redo等核心工作流的精确预期18 个稳定单机工作流的覆盖范围以及真实单机进程重启场景下 gRPC 重连与 HTTP50404恢复的验证方式。文章同时结合 AgentDiscoveryService.java、AgentDiscoveryServiceJavaSdkITCase.java 等源码给出实现级证据。一、背景为什么需要一份场景矩阵式测试契约Agent 发现涉及命名空间、版本演进、标签选择、端点发布/注销、多传输gRPC/HTTP以及断线重连等多个正交维度单纯靠参数笛卡尔积式的用例堆砌既不可维护也无法表达真实操作次序带来的语义差异。因此该矩阵采用**操作次序等价类operation-order equivalence classes**作为组织单位例如对单个发布方而言Register 是完整替换语义因此有意义的次序只有端点先于定义、定义先于端点、在已上线版本上做替换三类。矩阵本身的定位是测试优先契约场景在生产代码之前固定并与最终落地的测试一同维护每个场景分配到稳定的单机 Java SDK IT、确定性单元测试或两者兼有明确范围边界首个实现采用主动 Discover 轮询active Discover polling不新增服务端 Watch 请求、Push 载荷、ACK 或 Watch 能力。对应的测试载体为 AgentDiscoveryServiceJavaSdkITCase.java1894 行它仅通过公共AiService契约驱动被测行为AgentMaintainerService只作为外部搭建与清理客户端使用见文件头注释 L96-L105。二、测试分层图例Test-Layer Legend矩阵为每个场景标注了验证层级含义如下测试层级含义IT通过公共 Java SDK 针对单机服务端运行。Directed IT通过公共 SDK 客户端运行同时外部 harness 重启真实单机服务端。由于普通共享服务端 IT 不能停机该层级默认不参与opt-in。UT使用确定性的传输、调度器、重连或故障注入。IT UT公共工作流在 IT 中运行本地不变量由单元测试验证。Deferred不在本阶段范围内记录原因且不新增生产代码。关键约束在文档中有明确表述共享服务端 CI 运行永远不会被测试停机调度器、监听器失败、传输错误、能力ability、心跳/50404、回滚以及重放竞态等都属于确定性 UT 职责。三、已落地的单机实现证据18 个稳定工作流AgentDiscoveryServiceJavaSdkITCase执行了以下稳定的公共工作流每个方法对应一个场景组IT 方法覆盖的场景组shouldInteroperateWithLegacyA2aSdk旧 A2A SDK 定义发布、Console 与 RAD 规范读取、重复发布不覆盖、旧版 exact-Version Endpoint 注册进规范 Runtime RegistryBeta 阶段不向历史 Naming 服务双写、Console Runtime Snapshot 与旧 SERVICE 查询一致、Version 2 预注册、省略选择器多版本聚合与显式 latest 隔离、规范版本发布、旧版 latest 订阅收敛。shouldSearchDiscoverAndIsolateNamespaces默认/自定义命名空间默认、单个、组合、空、分页 Searchlatest/exact/label Discover组合过滤调用方不可变性显式与不匹配的命名空间绑定命名空间隔离的发布。shouldReplaceAndPartiallyDeregisterCompletePublications完整注册、相同内容的幂等、替换收敛、规范自然键的部分注销、未知/重复注销为 no-op、最终注销、协议隔离。shouldAggregateIndependentSdkPublishers两个 SDK 身份贡献同一自然键、最后贡献者移除。shouldDiscoverPreRegistrationAndPollUntilAgentAppears预注册、Discover 缺失、先订阅后创建、完整回调快照、退订、退订后抑制。shouldPollExistingAgentOnlyWhenCompleteFingerprintChanges订阅已有当前值、Runtime source-revision 替换事件、指纹未变时的回调去重。shouldTrackVersionEvolutionAcrossRegistrationOrdersVersion 1 定义优先、Version 2 端点优先、Version 3 定义优先、latest/exact/label 订阅、目录顺序、离线/上线后的 latest 重算。shouldSeparateDefaultRolloutPoolFromExplicitLatest两个独立发布方并发保有 exact Version 1 与 Version 2 端点省略选择器使用 latest 版本元数据但聚合所有在线版本的兼容端点显式labellatest仅含 latest验证 Version 2 端点注册前的空窗期、注册后的合并池、Version 1 下线后的移除、绑定来源、两种选择器的轮询回调去重。shouldApplyPublicationRangeAcrossOnlineVersions含端点的版本区间、替换为不同区间、精确版本匹配、非匹配版本排除。shouldDeregisterActiveHttpPublicationDuringIdempotentShutdown活跃及重复 SDK 关闭期间的 HTTP 发布清理。shouldKeepHttpAndGrpcDiscoverySemanticsEquivalentSearch、Discover、HTTP 发布、gRPC 观察、注销的传输等价性。shouldUseGrpcForAutoWhenInitialConnectionIsAvailableAUTO 同步启动有可用协商 gRPC 连接随后 Search、端点发布、Discover、注销。shouldFallbackAutoToHttpWhenGrpcNeverLeavesStarting故意不可达的 gRPC 端口使连接停留在 STARTINGAUTO 立即通过 HTTP 完成 Search、轮询订阅、发布、注销显式 HTTP 与 gRPC 无关显式 GRPC 无回退且失败。shouldKeepSearchProjectionLifecyclePaginationAndTransportParitygRPC/HTTP Search 在组合类型过滤、大小写敏感名称、稳定的首页/中页/末页/越界页码、Runtime Endpoint 不建索引、两版本 latest/目录收敛、单版本下线收敛、全部版本下线后移除等方面的等价性同一组终态断言可复用于AUTO、INDEX、SCAN服务端运行。shouldEnforceConfiguredLocalSubscriptionCapacityAndReuseSlot工作流配置的轮询订阅容量、幂等重复准入、超限同步拒绝缓存之前、退订后槽位复用。shouldEnforceConfiguredLocalPublicationCapacityAndReuseSlot工作流配置的 SDK 发布软水位、从下方整批跨越、超水位幂等替换与新身份拒绝、注销后槽位复用。shouldSurfaceServerPublicationCapacityAndStopRejectedRedo工作流配置的服务端权威发布软水位、从下方整批跨越、远端超限异常映射、被拒重放清理、注销后容量复用。shouldRejectInvalidBoundariesBeforeRemoteMutationNull、页边界、重复过滤条件/自然键、命名空间不匹配、引用歧义、非法协议/URI/传输/版本/区间、空发布、服务端持有健康状态、非法注销载荷、未知本地 no-op、not-found 映射。补充事实同样的 18 个工作流在默认 JSON adapter 与jackson3下均通过既有AiServiceJavaSdkITCase作为兼容性回归一起运行。可选的shouldRestoreGrpcAndHttpPublicationsAndPollingAfterRealServerRestart工作流见源码 L968-L1118还针对由外部 harness 停止/重启的真实单机进程通过它同时保有独立的 gRPC 与 HTTP 发布方及轮询订阅因此重启后的服务端必须同时恢复 gRPC 重连重放与 HTTPHTTP_CLIENT_NOT_FOUND重新注册。四、工厂、命名空间与生命周期场景预期结果覆盖通过AiFactory创建不带命名空间的AiServiceAgent 操作绑定到public。IT创建绑定public与自定义命名空间的服务Search、Discover、订阅、发布保持命名空间隔离。IT UTRequest/Batch 省略命名空间SDK 复制值并注入绑定命名空间不改动调用方输入。IT UTRequest/Batch 携带相同命名空间请求成功且调用方输入不变。UTRequest/Batch 携带另一个非空命名空间SDK 在传输调用前本地拒绝。IT UT调用后复用调用方的列表、映射、引用、过滤器、端点SDK 状态与线上载荷与后续调用方变更隔离。UT无订阅/发布时关闭轮询、心跳、HTTP 资源、gRPC 资源干净停止。IT UT有活跃订阅/发布时关闭SDK 取消轮询与心跳并尽力注销每个完整发布。IT UT重复关闭无重复回调、未受控异常或泄漏任务。UTgrpcAgent 传输模式初始 gRPC 连接同步尝试连接不可用时持续重试Agent 操作绝不回退 HTTP。IT UThttpAgent 传输模式Agent 操作不依赖初始 gRPC 启动配置的 gRPC 端口不可达时仍可用。IT UTauto 可用协商 gRPCAgent 操作优先 gRPC。IT UTauto gRPC 停留在STARTING公共请求不等待后台探测通过 HTTP 成功仅在重试预算耗尽且一次 HTTP 成功后落定 HTTP。IT UT非法、带空白或未知传输模式工厂创建本地失败抛出受控非法参数异常。UT实现证据传输模式由 AgentTransportMode.java 定义GRPC/HTTP/AUTO对应属性值grpc/http/autofromValue大小写不敏感非法值抛IllegalArgumentExceptionL65-L72。属性键集中在 AiConstants.javaAI_TRANSPORT_MODE nacosAiTransportModeL79、AI_REQUEST_TIMEOUT nacosAiRequestTimeoutL87以及发布/订阅容量键nacosAiAgentEndpointMaxPublications默认 100L105-L114与nacosAiAgentDiscoveryMaxSubscriptions默认 300L111-L116。AiService通过 AiFactory.createAiService(Properties) 反射创建com.alibaba.nacos.client.ai.NacosAiService失败时抛CLIENT_INVALID_PARAM。五、Search目录搜索场景预期结果覆盖仅默认分页输入的 Search返回可见启用且拥有在线 latest 版本的 Agent分页稳定。IT按字面量agentNameContains搜索仅返回大小写敏感的字面包含匹配%、_、\不作为数据存储通配符解释。OpenAPI IT Java SDK IT按多个tagsAll搜索每个返回的 Agent 都包含全部请求标签。IT按多个protocolsAny搜索每个返回的 Agent 至少包含一个请求协议。IT组合名称、标签、协议与分页除protocolsAny外过滤器以 AND 语义组合页码元数据正确。IT空命名空间或不匹配过滤器的 Search返回成功的空Page。ITNull 请求、非法页码、重复过滤值或非法协议抛受控本地非法参数异常且不发请求。UTgRPC ability 为SUPPORTED恰好发送一次 Search RPC返回类型化分页。UTgRPC ability 为NOT_SUPPORTED或UNKNOWN本地抛 unsupported 错误无 legacy 或 HTTP 回退。UTHTTP 传输使用文档化的 GET 查询、auth 资源与稳定的 HTTP Client id。IT UTAUTO 读且 gRPC 当前不可用立即选 HTTP不等待异步重连。IT UTAUTO 读遇到 gRPC 连接类失败读可经 HTTP 重试明确的业务错误不回退。UT从 AgentDiscoveryService.java 看searchAgents(AgentSearchRequest)返回PageAgentCatalogEntryL49-L54是Since(3.3.0)的公共 API。测试侧对分页/目录收敛的断言见 AgentDiscoveryServiceJavaSdkITCase.java 中searchNamesByPageL1792-L1808与waitForCatalogL1775-L1785等辅助方法。六、Discover发现快照场景预期结果覆盖无 Version/label 的 Discover定义元数据从 latest 解析Runtime Endpoints 聚合与每个在线版本兼容的绑定。IT UT显式labellatest的 Discover定义元数据与 Runtime Endpoints 都限制在当前 latest 版本。IT UT精确 Version 与自定义 label 引用每个引用只解析该精确解析版本的元数据与端点。IT无 Filter 的 Discover保留所有允许的调用接口与端点来源。IT按 protocol/protocolVersion 过滤保留匹配接口无匹配返回callInterfaces[]。IT按端点来源过滤保留匹配接口无匹配来源返回endpointSets[]。IT按 transport/metadata 过滤保留匹配端点集无匹配端点返回endpoints[]。IT组合全部过滤维度完整类型化结果在文档化层级被过滤。ITRuntime Endpoint 不健康Discover 保留它并标记healthyfalse不发生隐式选择。IT目标不存在、被禁用或无可见在线版本抛受控 not-found 异常。ITVersion 与 label 同时设置或引用/过滤非法SDK 本地拒绝且不改输入。IT UTgRPC ability 缺失或未知本地抛 unsupported 错误不发远程请求。UTHTTP 与 gRPC 传输等价两种传输对同一服务端状态返回等价类型化快照。ITAUTO 可用或从未连接 gRPC分别经 gRPC 或立即 HTTP 路由返回同一类型化快照。IT UTAPI 层面对应discoverAgent(AgentReference)与discoverAgent(AgentReference, AgentDiscoveryFilter)两个重载AgentDiscoveryService.java。测试中sourceEndpoints(...)帮助方法按协议与EndpointSourceDECLARED/RUNTIME抽取端点集L1690-L1708。七、定义与版本演进Definition And Version Evolution场景预期结果覆盖发布 Version 1 后注册其精确端点 Batch省略、显式 latest、精确版本 Discover 都返回 Version 1 与 Runtime Endpoint。IT在 Version 2 存在前注册精确 Version 2 Batch注册成功latest 仍是 Version 1 可发现但仅 Version 2 的端点被过滤掉。IT注册其端点前发布 Version 2Search 与两种选择模式使用 Version 2 元数据省略 Discover 保留 Version 1 端点显式 latest 返回空 Runtime 集。IT UT从独立于 Version 1 的发布方注册 Version 2省略 Discover 返回带绑定的 Version 1 与 Version 2 端点显式 latest 仅返回 Version 2。IT UTVersion 1 下线而 Version 2 在线省略 Discover 移除仅 Version 1 的端点显式 latest 不变且不发重复回调。IT UTVersion 1 保留自定义 label 而 latest 前进Label Discover 停留在 Version 1不隐式跟随 latest。IT自定义 label 从 Version 1 移到 Version 2Label Discover 与匹配的轮询订阅原子地移到 Version 2。IT注册精确 Batch 前发布 Version 3显式 latest Discover 变为 Version 3 且 Runtime 集为空省略 Discover 保留与较旧在线版本兼容的端点后续 Register 改变相关 Runtime source-revision。ITlatest 在后续版本中前进时保持精确 Version 1 订阅不收版本变更回调仅当 Version 1 内容或匹配 source-revision 变化时才变更。IT UT省略选择器订阅经历 latest 变更立即收到 latest 元数据但保留旧在线版本端点直至其版本下线。IT UT显式 latest 订阅经历端点替换与版本变更严格切到新 latest 池含刻意空窗期并抑制未变化的轮询。IT UT多个在线版本后的 Search单条目录条目按 SemVer 降序列出所有在线版本并报告当前 latest。IT注册/注销 Runtime 端点而不改定义Search 目录字段与版本成员关系不变因为 Runtime Endpoints 不建索引。OpenAPI IT Java SDK IT两个在线版本下线其一再下线最后一个目录先收敛到剩余版本随后 Agent 完全退出 Search。OpenAPI IT Java SDK IT发布区间跨多个版本每个匹配的 exact/latest Discover 看到共享端点不匹配版本看不到。IT UT下线后又将当前 latest 上线另一版本仍在线Search/Discover 遵循服务端重算的 latest不改发布方意图。IT该小节在测试源码中的典型映射是shouldTrackVersionEvolutionAcrossRegistrationOrdersL740-L837它依次验证 Version 1 定义优先、Version 2 端点优先、Version 3 定义优先以及offline/online后的 latest 重算。八、本地轮询订阅Local Polling Subscription场景预期结果覆盖订阅已存在目标方法返回当前快照并保留一条轮询记录。IT UT目标存在前订阅返回null保留轮询目标出现后投递完整快照。IT UT重复 not-found 轮询不投递空快照订阅保持活跃。UT轮询返回相同 Version、digest 与 source-revisions不投递重复监听器事件。IT UT解析版本变化投递一次完整替换事件。IT UTcontentDigest变化投递一次完整替换事件。UT任一sourceRevision变化投递一次完整替换事件。IT UTRuntime 绑定变化而端点载荷与健康不变v2 Runtime revision 变化因为发现可见的绑定来源属于快照的一部分。UTFilter 产生类型化空结果结果被缓存并可替换更早的非空快照。UT相同引用/过滤与两个监听器实例监听器身份隔离两者都收到变化。UT用相同监听器身份重复订阅每个变化只保留一条轮询记录与一次回调。UT达到配置的本地订阅上限最后被接纳的订阅保持活跃由于当前 API 每次调用安装一个订阅下一个不同键在 Discover/缓存插入/调度之前抛CLIENT_OVER_THRESHOLD。未来批量的 Wire Watch 操作必须基于操作前水位整体准入或整体拒绝整批不得部分缓存。IT UT在上限处退订后再订阅另一键释放的槽位立即复用新订阅正常调度。IT UT用相同引用/过滤/监听器退订仅该监听器停止其他监听器继续。IT UT退订不存在的或不同的监听器幂等 no-op。UT监听器抛异常轮询与其他监听器继续。UTHTTP 轮询使用发布 Client id只续订 Client 存活不续订 Publisher 存活。IT轮询期间关闭关闭后不投递回调。UT容量场景的实现佐证shouldEnforceConfiguredLocalSubscriptionCapacityAndReuseSlotL467-L498读取nacos.agent.it.client.subscription.capacity默认 3用AiConstants.AI_AGENT_DISCOVERY_MAX_SUBSCRIPTIONS配置服务断言超限时抛NacosApiExceptionCLIENT_OVER_THRESHOLDAGENT_DISCOVERY_SUBSCRIPTION_OVER_LIMIT。九、完整端点发布Complete Endpoint Publication场景预期结果覆盖Agent 定义存在前注册发布成功但 Discover 保持 not-found 直到 Agent 可发现。IT注册一个或多个端点完整 Batch 在匹配的 Runtime source 中可见。IT重复相同完整 Batch幂等成功且不产生重复端点。IT用变更的端点载荷替换 Batch新完整 Batch 替换旧端点与绑定值。IT UT替换 Batch 时省略先前端点被省略端点被移除。IT发布两个协议每个(namespace, agent, protocol)状态独立Discover 过滤正确。IT UT两个 SDK 实例发布贡献按自然键聚合一个发布方注销不移除另一个。IT用一个完整 Batch 跨越本地发布水位当操作前端点条目数低于水位时整批被接纳并缓存即使结果数超水位不保留部分 Batch。IT UT已处于或高于本地发布水位时增长等大小或缩小的替换仍允许新身份或增长的替换抛CLIENT_OVER_THRESHOLD既不进入发布也不进入 gRPC 重放缓存。IT UT服务端在其每 Client 水位拒绝发布增长SDK 暴露OVER_THRESHOLD从所有重放/心跳状态移除被拒身份在注销足够端点条目后重新接受。OpenAPI IT Java SDK IT UT缺失 range服务端收到有效 Batch其 range 默认为精确 runtime 版本语义。IT UT重复自然键、非法 URI/传输/版本/区间、空 Batch 或healthy输入SDK 本地拒绝 Batch 且不保留非法重放意图。IT UT注册后调用方修改 Batch 或端点对象存储的期望状态与重放载荷保持原始规范副本。UTgRPC 端点 ability 不支持或未知SDK 本地失败无 HTTP 或 legacy 回退。UTHTTP 注册发送稳定 Client id 与所需模块头返回的存活区间调度心跳。IT UT容量场景佐证shouldEnforceConfiguredLocalPublicationCapacityAndReuseSlotL500-L540配置nacosAiAgentEndpointMaxPublications后断言超限拒绝码为CLIENT_OVER_THRESHOLDAGENT_ENDPOINT_PUBLICATION_OVER_LIMITshouldSurfaceServerPublicationCapacityAndStopRejectedRedoL542-L605把本地水位设得高于服务端水位nacos.agent.it.server.publication.capacity默认 100验证服务端拒绝后本地缓存与重放状态被清理。十、部分与完整注销Partial And Complete Deregistration场景预期结果覆盖从多端点 Batch 移除一个自然键SDK 发送一次仅含剩余部分的完整替换注册。IT UT移除最后一个自然键SDK 发送一次整发布注销并移除本地期望状态。IT UT注销未知本地发布或自然键作为 no-op 成功不发远程变更。IT UT重复注销同一键之后每次调用仍是 no-op。IT注销 URI 仅在路径、查询或主机拼写不同匹配遵循规范主机、有效端口与传输的自然身份。UT注销试图包含 priority、weight、metadata 或 healthSDK 本地拒绝请求。UT注销一个协议而另一协议存在另一协议保持注册并可发现。IT本地移除后替换注册失败缩减后的期望 Batch 仍可用于后续重连重放。UT最后本地移除后整体注销失败注销意图保留至完成或关闭。UT测试中的典型实现是shouldReplaceAndPartiallyDeregisterCompletePublicationsL401-L465它验证路径不同但 authority 相同的注销键仍能命中replacePath辅助方法 L1673-L1676以及 a2a/mcp 两协议的独立注册与独立移除。十一、心跳、重试、重连与重放Heartbeat, Retry, Reconnect, And Redo场景预期结果覆盖HTTP 心跳成功使用同一 Client id下次心跳遵循返回的有效区间。UT心跳之间的 HTTP 查询不延长 Publisher 存活。ITHTTP 操作返回HTTP_CLIENT_NOT_FOUND (50404)该 HTTP SDK 实例的全部发布被标记未注册并以完整 Batch 重放。Directed IT UT50404 以外的瞬时 HTTP 心跳失败保留期望发布状态后续心跳可恢复且不创建新 Client id。UTgRPC 断开后重连每个期望发布被标记未注册并在新连接上重放一次。UT重连后 gRPC ability 变化重新检查 ability不支持或未知时阻止该连接上的重放。UT未知结果的写超时SDK 保留意图但不盲目切换传输。UT保留写之后收到参数或授权错误重放停止、先前已确认发布被恢复、或首个非法意图被丢弃。UTHTTP 与 gRPC 服务发布同一逻辑 Agent传输持有的重放记录与注销保持隔离。UT关闭时多个协议发布每个完整发布在传输关闭前被尽力注销。UT十二、Directed 真实服务端生命周期重启恢复该可选重连用例与普通 IT 使用同一生产发行版与公共AiService/AgentMaintainerServiceAPI。JUnit 进程从不启动或停止 Nacos它写入 ready 标记外部 harness 用同一数据目录停止并重启单机进程测试仅在 harness 写入 restarted 标记后继续。阶段操作与断言覆盖初始服务端创建并发布 legacy 兼容的 Version 1为 Version 1、2 预注册 legacy exact-Version 端点进规范 Runtime Service在同一 SDK 连接上注册协议无关的 gRPC 与 HTTP 端点 BatchSearch、legacy SERVICE 查询、latest/exact Discover、Runtime 绑定、轮询订阅一致且无发布覆盖。Directed IT服务端不可用保持同一 gRPC/HTTP SDK 实例及其本地订阅/发布意图两种传输都观察到连接不可用但客户端进程存活且本地意图不删除。Directed IT UT同一服务端重启gRPC SDK 重连并重放协议无关完整 Batch 及两个 legacy exact-Version 发布HTTP 心跳收到HTTP_CLIENT_NOT_FOUND保留同一外部 HTTP client id创建全新服务端状态并重新注册完整 Batchlegacy 子发布者在新连接上重建Runtime 绑定独立恢复两传输轮询收敛。Directed IT UT重连后的端点优先升级在 legacy 端点已注册并恢复后创建并发布 Version 2legacy SERVICE 查询、RAD Discover 与两个订阅立即解析该规范 Runtime Endpoint后续协议无关的 gRPC/HTTP 发布者增加独立贡献而不替换它。Directed IT重连后的精确与 label 检查精确 Version 1 仍可解析exact/latest Version 2 经两传输一致移动的自定义 label 解析到 Version 2。Directed IT清理退订两个监听器注销两个协议无关最终发布与 legacy Version 2 发布验证精确 Runtime 池变空删除 Agent关闭客户端重启后的服务端仍可供后续 IT 使用。Directed IT该场景有界等待两个标记及每个服务端/客户端收敛断言若 harness 协调缺失产生的是跳过或失败的目标运行而不是沉睡的常规 CI 测试。对应测试方法为shouldRestoreGrpcAndHttpPublicationsAndPollingAfterRealServerRestart通过系统属性nacos.agent.reconnect.enabledtrue开启、nacos.agent.reconnect.control.dir指定标记目录源码 L969-L982。十三、复合单机工作流Compound Standalone Workflows工作流交叉校验覆盖Maintainer 创建并发布 Agent随后 SDK Search 与 Discover管理端写入经两种客户端读操作可见。ITlegacy A2A SDK 发布 AgentCard 与 Version 1、2 的旧 exact-Version 端点随后 Console Runtime Snapshot、RAD、legacy SERVICE、直接 Naming 读检查Maintainer 发布 Version 2随后省略/默认与显式 latest 发现比较池legacy 与协议无关表面共享规范 Agent 定义与 Runtime Service重复发布不覆盖在线版本预注册不创建定义精确绑定独立存活历史 Version 特定 Naming 服务在 Beta 阶段保持为空省略选择聚合两个在线版本显式 latest 仅含 Version 2。ITSDK 预注册端点Maintainer 创建/发布 AgentSDK Discover预注册在无隐式定义创建下可见。ITMaintainer 发布 AgentSDK 注册/替换/部分注销/最终注销Discover 依序观察完整替换、剩余部分与空 Runtime source。IT两个 SDK 发布者注册同一端点一个注销再另一个注销聚合可见性保持到最后贡献被移除。IT两个协议独立发布并过滤Search 协议目录与 Discover 协议过滤一致。ITAgent 创建前启动订阅随后定义与 Runtime Endpoint 出现监听器仅在公共指纹变化时收到完整快照。IT移除订阅后定义或 Runtime Endpoint 变化退订后无回调。IT同一工作流经 gRPC 与显式 HTTP 客户端查询形态与发布语义传输等价。ITMaintainer 发布三个 Agent随后 gRPC 与 HTTP SDK 立即查询当前快照并分页/过滤收敛目录期间一个 Agent 获得版本、接收 Runtime Endpoint、逐版本下线两传输在无 readiness 错误下保持可用收敛后返回相同稳定顺序与完整目录类型化过滤组合一致端点发布不改变 Search生命周期投影收敛无陈旧版本。ITpublic 与自定义命名空间工作流并行Search、Discover、订阅、发布从不跨命名空间。ITVersion 1 在线 Version 2 端点预注册 Version 2 发布Search、latest/exact/label Discover 与订阅在每个过渡点一致。ITVersion 1 在线 端点注册前 Version 2 发布 独立 Version 2 发布者省略选择跨过渡保留 rollout 池显式 latest 只观察 Version 2两个轮询订阅收敛且无重复回调。IT活跃 gRPC/HTTP 发布与轮询订阅下真实单机重启同一存活 SDK 进程恢复两个传输持有的完整 Batch恢复两个轮询循环随后观察到后续版本与两个端点。Directed IT十四、本阶段延后项Deferred In This Phase项目原因服务端 Watch/Push、watchKey、Push ACK、gap recovery 与 Watch ability已批准的首版使用主动 Discover 轮询。公共getAll/selectOneHealthy辅助 API 形态设计已声明本地选择语义但尚未规定稳定的 Java 类型与方法签名不阻塞 Search、Discover、轮询或发布作为记录而非本阶段发明。Agent 管理元数据变更通知AgentDiscoveryResult有意排除显示名、描述、标签、provider 等管理元数据。其轮询指纹仅包含解析版本、版本contentDigest与端点sourceRevision。未来订阅已发布 Agent 元数据强制更新的需求需要 Search/目录订阅或显式 RAD 契约扩展不能由当前 Discover 订阅推断。单帧级丢包与未知 gRPC 写结果歧义由确定性单元故障注入覆盖真实单节点进程重启单独覆盖帧级故障注入不是稳定的单机 IT。十五、如何运行与继续深入场景矩阵文档test/java-sdk-test/AGENT_DISCOVERY_SDK_IT_SCENARIOS.md主测试类18 个稳定工作流 1 个可选 Directed 重启工作流AgentDiscoveryServiceJavaSdkITCase.java公共 API 契约AgentDiscoveryService.java、AiService.java后者还扩展了A2aService提供releaseAgentCard、getAgentCard、subscribeAgentCard等 legacy 兼容面工厂与传输模式AiFactory.java、AgentTransportMode.java容量与超时属性常量AiConstants.javaRAD 数据模型api/src/main/java/com/alibaba/nacos/api/ai/model/radAgentSearchRequest、AgentReference、AgentDiscoveryFilter、AgentDiscoveryResult、AgentEndpointRegistrationBatch、AgentEndpointDeregistrationBatch、AgentCatalogEntry、EndpointSet等相关设计与协议规格specs/en/ai/rad-protocol-spec.md、specs/en/ai/agent-api-spec.md、specs/en/ai/a2a-agent-spec.md运行集成测试需先按 JAVA_SDK_IT_SCENARIOS.md 与 JAVA_SDK_IT_COVERAGE.md 的准备说明启动单机 Nacos共享服务端 IT 不得停机Directed 重启用例额外要求外部 harness 通过nacos.agent.reconnect.enabled与nacos.agent.reconnect.control.dir协调进程启停与标记文件。SDK 侧发布/订阅容量等行为化配置见nacosAiAgentEndpointMaxPublications默认 100与nacosAiAgentDiscoveryMaxSubscriptions默认 300。结语这份场景矩阵的价值在于把协议无关 Agent 发现这一复杂域拆解为可逐条验证的契约从命名空间隔离、版本/标签语义、端点发布与注销、本地轮询订阅的去重与容量控制到 gRPC/HTTP 传输等价与真实进程重启后的重连重放每一行都对应明确的预期与验证层级。对二次开发者而言它既是行为规格书也是回归测试的活文档对维护者而言它界定了首版不做 Watch/Push、不做管理元数据订阅、不做部分缓存的清晰边界为后续迭代如批量 Wire Watch 的整批准入预留了可扩展的契约位置。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 1:31:49 · 阅读 1.2k Nacos Agent Discovery Java SDK 场景矩阵：测试优先契约、集成测试分层与实现轨迹
Nacos Agent Discovery Java SDK 场景矩阵测试优先契约、集成测试分层与实现轨迹【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos导读本文围绕 Nacos 仓库中的 AGENT_DISCOVERY_SDK_IT_SCENARIOS.md 展开它是第一个AgentDiscoveryService协议无关的 Agent 发现服务实现的测试优先契约test-first contract与执行轨迹execution trace在生产代码落地之前先固定场景清单再由配套的 Java SDK 集成测试IT与单元测试UT逐条守护。读完本文你将掌握Agent 发现的测试分层体系IT / Directed IT / UT / 延后项Search、Discover、本地轮询订阅、完整端点发布、部分/完整注销、心跳重连与重放redo等核心工作流的精确预期18 个稳定单机工作流的覆盖范围以及真实单机进程重启场景下 gRPC 重连与 HTTP50404恢复的验证方式。文章同时结合 AgentDiscoveryService.java、AgentDiscoveryServiceJavaSdkITCase.java 等源码给出实现级证据。一、背景为什么需要一份场景矩阵式测试契约Agent 发现涉及命名空间、版本演进、标签选择、端点发布/注销、多传输gRPC/HTTP以及断线重连等多个正交维度单纯靠参数笛卡尔积式的用例堆砌既不可维护也无法表达真实操作次序带来的语义差异。因此该矩阵采用**操作次序等价类operation-order equivalence classes**作为组织单位例如对单个发布方而言Register 是完整替换语义因此有意义的次序只有端点先于定义、定义先于端点、在已上线版本上做替换三类。矩阵本身的定位是测试优先契约场景在生产代码之前固定并与最终落地的测试一同维护每个场景分配到稳定的单机 Java SDK IT、确定性单元测试或两者兼有明确范围边界首个实现采用主动 Discover 轮询active Discover polling不新增服务端 Watch 请求、Push 载荷、ACK 或 Watch 能力。对应的测试载体为 AgentDiscoveryServiceJavaSdkITCase.java1894 行它仅通过公共AiService契约驱动被测行为AgentMaintainerService只作为外部搭建与清理客户端使用见文件头注释 L96-L105。二、测试分层图例Test-Layer Legend矩阵为每个场景标注了验证层级含义如下测试层级含义IT通过公共 Java SDK 针对单机服务端运行。Directed IT通过公共 SDK 客户端运行同时外部 harness 重启真实单机服务端。由于普通共享服务端 IT 不能停机该层级默认不参与opt-in。UT使用确定性的传输、调度器、重连或故障注入。IT UT公共工作流在 IT 中运行本地不变量由单元测试验证。Deferred不在本阶段范围内记录原因且不新增生产代码。关键约束在文档中有明确表述共享服务端 CI 运行永远不会被测试停机调度器、监听器失败、传输错误、能力ability、心跳/50404、回滚以及重放竞态等都属于确定性 UT 职责。三、已落地的单机实现证据18 个稳定工作流AgentDiscoveryServiceJavaSdkITCase执行了以下稳定的公共工作流每个方法对应一个场景组IT 方法覆盖的场景组shouldInteroperateWithLegacyA2aSdk旧 A2A SDK 定义发布、Console 与 RAD 规范读取、重复发布不覆盖、旧版 exact-Version Endpoint 注册进规范 Runtime RegistryBeta 阶段不向历史 Naming 服务双写、Console Runtime Snapshot 与旧 SERVICE 查询一致、Version 2 预注册、省略选择器多版本聚合与显式 latest 隔离、规范版本发布、旧版 latest 订阅收敛。shouldSearchDiscoverAndIsolateNamespaces默认/自定义命名空间默认、单个、组合、空、分页 Searchlatest/exact/label Discover组合过滤调用方不可变性显式与不匹配的命名空间绑定命名空间隔离的发布。shouldReplaceAndPartiallyDeregisterCompletePublications完整注册、相同内容的幂等、替换收敛、规范自然键的部分注销、未知/重复注销为 no-op、最终注销、协议隔离。shouldAggregateIndependentSdkPublishers两个 SDK 身份贡献同一自然键、最后贡献者移除。shouldDiscoverPreRegistrationAndPollUntilAgentAppears预注册、Discover 缺失、先订阅后创建、完整回调快照、退订、退订后抑制。shouldPollExistingAgentOnlyWhenCompleteFingerprintChanges订阅已有当前值、Runtime source-revision 替换事件、指纹未变时的回调去重。shouldTrackVersionEvolutionAcrossRegistrationOrdersVersion 1 定义优先、Version 2 端点优先、Version 3 定义优先、latest/exact/label 订阅、目录顺序、离线/上线后的 latest 重算。shouldSeparateDefaultRolloutPoolFromExplicitLatest两个独立发布方并发保有 exact Version 1 与 Version 2 端点省略选择器使用 latest 版本元数据但聚合所有在线版本的兼容端点显式labellatest仅含 latest验证 Version 2 端点注册前的空窗期、注册后的合并池、Version 1 下线后的移除、绑定来源、两种选择器的轮询回调去重。shouldApplyPublicationRangeAcrossOnlineVersions含端点的版本区间、替换为不同区间、精确版本匹配、非匹配版本排除。shouldDeregisterActiveHttpPublicationDuringIdempotentShutdown活跃及重复 SDK 关闭期间的 HTTP 发布清理。shouldKeepHttpAndGrpcDiscoverySemanticsEquivalentSearch、Discover、HTTP 发布、gRPC 观察、注销的传输等价性。shouldUseGrpcForAutoWhenInitialConnectionIsAvailableAUTO 同步启动有可用协商 gRPC 连接随后 Search、端点发布、Discover、注销。shouldFallbackAutoToHttpWhenGrpcNeverLeavesStarting故意不可达的 gRPC 端口使连接停留在 STARTINGAUTO 立即通过 HTTP 完成 Search、轮询订阅、发布、注销显式 HTTP 与 gRPC 无关显式 GRPC 无回退且失败。shouldKeepSearchProjectionLifecyclePaginationAndTransportParitygRPC/HTTP Search 在组合类型过滤、大小写敏感名称、稳定的首页/中页/末页/越界页码、Runtime Endpoint 不建索引、两版本 latest/目录收敛、单版本下线收敛、全部版本下线后移除等方面的等价性同一组终态断言可复用于AUTO、INDEX、SCAN服务端运行。shouldEnforceConfiguredLocalSubscriptionCapacityAndReuseSlot工作流配置的轮询订阅容量、幂等重复准入、超限同步拒绝缓存之前、退订后槽位复用。shouldEnforceConfiguredLocalPublicationCapacityAndReuseSlot工作流配置的 SDK 发布软水位、从下方整批跨越、超水位幂等替换与新身份拒绝、注销后槽位复用。shouldSurfaceServerPublicationCapacityAndStopRejectedRedo工作流配置的服务端权威发布软水位、从下方整批跨越、远端超限异常映射、被拒重放清理、注销后容量复用。shouldRejectInvalidBoundariesBeforeRemoteMutationNull、页边界、重复过滤条件/自然键、命名空间不匹配、引用歧义、非法协议/URI/传输/版本/区间、空发布、服务端持有健康状态、非法注销载荷、未知本地 no-op、not-found 映射。补充事实同样的 18 个工作流在默认 JSON adapter 与jackson3下均通过既有AiServiceJavaSdkITCase作为兼容性回归一起运行。可选的shouldRestoreGrpcAndHttpPublicationsAndPollingAfterRealServerRestart工作流见源码 L968-L1118还针对由外部 harness 停止/重启的真实单机进程通过它同时保有独立的 gRPC 与 HTTP 发布方及轮询订阅因此重启后的服务端必须同时恢复 gRPC 重连重放与 HTTPHTTP_CLIENT_NOT_FOUND重新注册。四、工厂、命名空间与生命周期场景预期结果覆盖通过AiFactory创建不带命名空间的AiServiceAgent 操作绑定到public。IT创建绑定public与自定义命名空间的服务Search、Discover、订阅、发布保持命名空间隔离。IT UTRequest/Batch 省略命名空间SDK 复制值并注入绑定命名空间不改动调用方输入。IT UTRequest/Batch 携带相同命名空间请求成功且调用方输入不变。UTRequest/Batch 携带另一个非空命名空间SDK 在传输调用前本地拒绝。IT UT调用后复用调用方的列表、映射、引用、过滤器、端点SDK 状态与线上载荷与后续调用方变更隔离。UT无订阅/发布时关闭轮询、心跳、HTTP 资源、gRPC 资源干净停止。IT UT有活跃订阅/发布时关闭SDK 取消轮询与心跳并尽力注销每个完整发布。IT UT重复关闭无重复回调、未受控异常或泄漏任务。UTgrpcAgent 传输模式初始 gRPC 连接同步尝试连接不可用时持续重试Agent 操作绝不回退 HTTP。IT UThttpAgent 传输模式Agent 操作不依赖初始 gRPC 启动配置的 gRPC 端口不可达时仍可用。IT UTauto 可用协商 gRPCAgent 操作优先 gRPC。IT UTauto gRPC 停留在STARTING公共请求不等待后台探测通过 HTTP 成功仅在重试预算耗尽且一次 HTTP 成功后落定 HTTP。IT UT非法、带空白或未知传输模式工厂创建本地失败抛出受控非法参数异常。UT实现证据传输模式由 AgentTransportMode.java 定义GRPC/HTTP/AUTO对应属性值grpc/http/autofromValue大小写不敏感非法值抛IllegalArgumentExceptionL65-L72。属性键集中在 AiConstants.javaAI_TRANSPORT_MODE nacosAiTransportModeL79、AI_REQUEST_TIMEOUT nacosAiRequestTimeoutL87以及发布/订阅容量键nacosAiAgentEndpointMaxPublications默认 100L105-L114与nacosAiAgentDiscoveryMaxSubscriptions默认 300L111-L116。AiService通过 AiFactory.createAiService(Properties) 反射创建com.alibaba.nacos.client.ai.NacosAiService失败时抛CLIENT_INVALID_PARAM。五、Search目录搜索场景预期结果覆盖仅默认分页输入的 Search返回可见启用且拥有在线 latest 版本的 Agent分页稳定。IT按字面量agentNameContains搜索仅返回大小写敏感的字面包含匹配%、_、\不作为数据存储通配符解释。OpenAPI IT Java SDK IT按多个tagsAll搜索每个返回的 Agent 都包含全部请求标签。IT按多个protocolsAny搜索每个返回的 Agent 至少包含一个请求协议。IT组合名称、标签、协议与分页除protocolsAny外过滤器以 AND 语义组合页码元数据正确。IT空命名空间或不匹配过滤器的 Search返回成功的空Page。ITNull 请求、非法页码、重复过滤值或非法协议抛受控本地非法参数异常且不发请求。UTgRPC ability 为SUPPORTED恰好发送一次 Search RPC返回类型化分页。UTgRPC ability 为NOT_SUPPORTED或UNKNOWN本地抛 unsupported 错误无 legacy 或 HTTP 回退。UTHTTP 传输使用文档化的 GET 查询、auth 资源与稳定的 HTTP Client id。IT UTAUTO 读且 gRPC 当前不可用立即选 HTTP不等待异步重连。IT UTAUTO 读遇到 gRPC 连接类失败读可经 HTTP 重试明确的业务错误不回退。UT从 AgentDiscoveryService.java 看searchAgents(AgentSearchRequest)返回PageAgentCatalogEntryL49-L54是Since(3.3.0)的公共 API。测试侧对分页/目录收敛的断言见 AgentDiscoveryServiceJavaSdkITCase.java 中searchNamesByPageL1792-L1808与waitForCatalogL1775-L1785等辅助方法。六、Discover发现快照场景预期结果覆盖无 Version/label 的 Discover定义元数据从 latest 解析Runtime Endpoints 聚合与每个在线版本兼容的绑定。IT UT显式labellatest的 Discover定义元数据与 Runtime Endpoints 都限制在当前 latest 版本。IT UT精确 Version 与自定义 label 引用每个引用只解析该精确解析版本的元数据与端点。IT无 Filter 的 Discover保留所有允许的调用接口与端点来源。IT按 protocol/protocolVersion 过滤保留匹配接口无匹配返回callInterfaces[]。IT按端点来源过滤保留匹配接口无匹配来源返回endpointSets[]。IT按 transport/metadata 过滤保留匹配端点集无匹配端点返回endpoints[]。IT组合全部过滤维度完整类型化结果在文档化层级被过滤。ITRuntime Endpoint 不健康Discover 保留它并标记healthyfalse不发生隐式选择。IT目标不存在、被禁用或无可见在线版本抛受控 not-found 异常。ITVersion 与 label 同时设置或引用/过滤非法SDK 本地拒绝且不改输入。IT UTgRPC ability 缺失或未知本地抛 unsupported 错误不发远程请求。UTHTTP 与 gRPC 传输等价两种传输对同一服务端状态返回等价类型化快照。ITAUTO 可用或从未连接 gRPC分别经 gRPC 或立即 HTTP 路由返回同一类型化快照。IT UTAPI 层面对应discoverAgent(AgentReference)与discoverAgent(AgentReference, AgentDiscoveryFilter)两个重载AgentDiscoveryService.java。测试中sourceEndpoints(...)帮助方法按协议与EndpointSourceDECLARED/RUNTIME抽取端点集L1690-L1708。七、定义与版本演进Definition And Version Evolution场景预期结果覆盖发布 Version 1 后注册其精确端点 Batch省略、显式 latest、精确版本 Discover 都返回 Version 1 与 Runtime Endpoint。IT在 Version 2 存在前注册精确 Version 2 Batch注册成功latest 仍是 Version 1 可发现但仅 Version 2 的端点被过滤掉。IT注册其端点前发布 Version 2Search 与两种选择模式使用 Version 2 元数据省略 Discover 保留 Version 1 端点显式 latest 返回空 Runtime 集。IT UT从独立于 Version 1 的发布方注册 Version 2省略 Discover 返回带绑定的 Version 1 与 Version 2 端点显式 latest 仅返回 Version 2。IT UTVersion 1 下线而 Version 2 在线省略 Discover 移除仅 Version 1 的端点显式 latest 不变且不发重复回调。IT UTVersion 1 保留自定义 label 而 latest 前进Label Discover 停留在 Version 1不隐式跟随 latest。IT自定义 label 从 Version 1 移到 Version 2Label Discover 与匹配的轮询订阅原子地移到 Version 2。IT注册精确 Batch 前发布 Version 3显式 latest Discover 变为 Version 3 且 Runtime 集为空省略 Discover 保留与较旧在线版本兼容的端点后续 Register 改变相关 Runtime source-revision。ITlatest 在后续版本中前进时保持精确 Version 1 订阅不收版本变更回调仅当 Version 1 内容或匹配 source-revision 变化时才变更。IT UT省略选择器订阅经历 latest 变更立即收到 latest 元数据但保留旧在线版本端点直至其版本下线。IT UT显式 latest 订阅经历端点替换与版本变更严格切到新 latest 池含刻意空窗期并抑制未变化的轮询。IT UT多个在线版本后的 Search单条目录条目按 SemVer 降序列出所有在线版本并报告当前 latest。IT注册/注销 Runtime 端点而不改定义Search 目录字段与版本成员关系不变因为 Runtime Endpoints 不建索引。OpenAPI IT Java SDK IT两个在线版本下线其一再下线最后一个目录先收敛到剩余版本随后 Agent 完全退出 Search。OpenAPI IT Java SDK IT发布区间跨多个版本每个匹配的 exact/latest Discover 看到共享端点不匹配版本看不到。IT UT下线后又将当前 latest 上线另一版本仍在线Search/Discover 遵循服务端重算的 latest不改发布方意图。IT该小节在测试源码中的典型映射是shouldTrackVersionEvolutionAcrossRegistrationOrdersL740-L837它依次验证 Version 1 定义优先、Version 2 端点优先、Version 3 定义优先以及offline/online后的 latest 重算。八、本地轮询订阅Local Polling Subscription场景预期结果覆盖订阅已存在目标方法返回当前快照并保留一条轮询记录。IT UT目标存在前订阅返回null保留轮询目标出现后投递完整快照。IT UT重复 not-found 轮询不投递空快照订阅保持活跃。UT轮询返回相同 Version、digest 与 source-revisions不投递重复监听器事件。IT UT解析版本变化投递一次完整替换事件。IT UTcontentDigest变化投递一次完整替换事件。UT任一sourceRevision变化投递一次完整替换事件。IT UTRuntime 绑定变化而端点载荷与健康不变v2 Runtime revision 变化因为发现可见的绑定来源属于快照的一部分。UTFilter 产生类型化空结果结果被缓存并可替换更早的非空快照。UT相同引用/过滤与两个监听器实例监听器身份隔离两者都收到变化。UT用相同监听器身份重复订阅每个变化只保留一条轮询记录与一次回调。UT达到配置的本地订阅上限最后被接纳的订阅保持活跃由于当前 API 每次调用安装一个订阅下一个不同键在 Discover/缓存插入/调度之前抛CLIENT_OVER_THRESHOLD。未来批量的 Wire Watch 操作必须基于操作前水位整体准入或整体拒绝整批不得部分缓存。IT UT在上限处退订后再订阅另一键释放的槽位立即复用新订阅正常调度。IT UT用相同引用/过滤/监听器退订仅该监听器停止其他监听器继续。IT UT退订不存在的或不同的监听器幂等 no-op。UT监听器抛异常轮询与其他监听器继续。UTHTTP 轮询使用发布 Client id只续订 Client 存活不续订 Publisher 存活。IT轮询期间关闭关闭后不投递回调。UT容量场景的实现佐证shouldEnforceConfiguredLocalSubscriptionCapacityAndReuseSlotL467-L498读取nacos.agent.it.client.subscription.capacity默认 3用AiConstants.AI_AGENT_DISCOVERY_MAX_SUBSCRIPTIONS配置服务断言超限时抛NacosApiExceptionCLIENT_OVER_THRESHOLDAGENT_DISCOVERY_SUBSCRIPTION_OVER_LIMIT。九、完整端点发布Complete Endpoint Publication场景预期结果覆盖Agent 定义存在前注册发布成功但 Discover 保持 not-found 直到 Agent 可发现。IT注册一个或多个端点完整 Batch 在匹配的 Runtime source 中可见。IT重复相同完整 Batch幂等成功且不产生重复端点。IT用变更的端点载荷替换 Batch新完整 Batch 替换旧端点与绑定值。IT UT替换 Batch 时省略先前端点被省略端点被移除。IT发布两个协议每个(namespace, agent, protocol)状态独立Discover 过滤正确。IT UT两个 SDK 实例发布贡献按自然键聚合一个发布方注销不移除另一个。IT用一个完整 Batch 跨越本地发布水位当操作前端点条目数低于水位时整批被接纳并缓存即使结果数超水位不保留部分 Batch。IT UT已处于或高于本地发布水位时增长等大小或缩小的替换仍允许新身份或增长的替换抛CLIENT_OVER_THRESHOLD既不进入发布也不进入 gRPC 重放缓存。IT UT服务端在其每 Client 水位拒绝发布增长SDK 暴露OVER_THRESHOLD从所有重放/心跳状态移除被拒身份在注销足够端点条目后重新接受。OpenAPI IT Java SDK IT UT缺失 range服务端收到有效 Batch其 range 默认为精确 runtime 版本语义。IT UT重复自然键、非法 URI/传输/版本/区间、空 Batch 或healthy输入SDK 本地拒绝 Batch 且不保留非法重放意图。IT UT注册后调用方修改 Batch 或端点对象存储的期望状态与重放载荷保持原始规范副本。UTgRPC 端点 ability 不支持或未知SDK 本地失败无 HTTP 或 legacy 回退。UTHTTP 注册发送稳定 Client id 与所需模块头返回的存活区间调度心跳。IT UT容量场景佐证shouldEnforceConfiguredLocalPublicationCapacityAndReuseSlotL500-L540配置nacosAiAgentEndpointMaxPublications后断言超限拒绝码为CLIENT_OVER_THRESHOLDAGENT_ENDPOINT_PUBLICATION_OVER_LIMITshouldSurfaceServerPublicationCapacityAndStopRejectedRedoL542-L605把本地水位设得高于服务端水位nacos.agent.it.server.publication.capacity默认 100验证服务端拒绝后本地缓存与重放状态被清理。十、部分与完整注销Partial And Complete Deregistration场景预期结果覆盖从多端点 Batch 移除一个自然键SDK 发送一次仅含剩余部分的完整替换注册。IT UT移除最后一个自然键SDK 发送一次整发布注销并移除本地期望状态。IT UT注销未知本地发布或自然键作为 no-op 成功不发远程变更。IT UT重复注销同一键之后每次调用仍是 no-op。IT注销 URI 仅在路径、查询或主机拼写不同匹配遵循规范主机、有效端口与传输的自然身份。UT注销试图包含 priority、weight、metadata 或 healthSDK 本地拒绝请求。UT注销一个协议而另一协议存在另一协议保持注册并可发现。IT本地移除后替换注册失败缩减后的期望 Batch 仍可用于后续重连重放。UT最后本地移除后整体注销失败注销意图保留至完成或关闭。UT测试中的典型实现是shouldReplaceAndPartiallyDeregisterCompletePublicationsL401-L465它验证路径不同但 authority 相同的注销键仍能命中replacePath辅助方法 L1673-L1676以及 a2a/mcp 两协议的独立注册与独立移除。十一、心跳、重试、重连与重放Heartbeat, Retry, Reconnect, And Redo场景预期结果覆盖HTTP 心跳成功使用同一 Client id下次心跳遵循返回的有效区间。UT心跳之间的 HTTP 查询不延长 Publisher 存活。ITHTTP 操作返回HTTP_CLIENT_NOT_FOUND (50404)该 HTTP SDK 实例的全部发布被标记未注册并以完整 Batch 重放。Directed IT UT50404 以外的瞬时 HTTP 心跳失败保留期望发布状态后续心跳可恢复且不创建新 Client id。UTgRPC 断开后重连每个期望发布被标记未注册并在新连接上重放一次。UT重连后 gRPC ability 变化重新检查 ability不支持或未知时阻止该连接上的重放。UT未知结果的写超时SDK 保留意图但不盲目切换传输。UT保留写之后收到参数或授权错误重放停止、先前已确认发布被恢复、或首个非法意图被丢弃。UTHTTP 与 gRPC 服务发布同一逻辑 Agent传输持有的重放记录与注销保持隔离。UT关闭时多个协议发布每个完整发布在传输关闭前被尽力注销。UT十二、Directed 真实服务端生命周期重启恢复该可选重连用例与普通 IT 使用同一生产发行版与公共AiService/AgentMaintainerServiceAPI。JUnit 进程从不启动或停止 Nacos它写入 ready 标记外部 harness 用同一数据目录停止并重启单机进程测试仅在 harness 写入 restarted 标记后继续。阶段操作与断言覆盖初始服务端创建并发布 legacy 兼容的 Version 1为 Version 1、2 预注册 legacy exact-Version 端点进规范 Runtime Service在同一 SDK 连接上注册协议无关的 gRPC 与 HTTP 端点 BatchSearch、legacy SERVICE 查询、latest/exact Discover、Runtime 绑定、轮询订阅一致且无发布覆盖。Directed IT服务端不可用保持同一 gRPC/HTTP SDK 实例及其本地订阅/发布意图两种传输都观察到连接不可用但客户端进程存活且本地意图不删除。Directed IT UT同一服务端重启gRPC SDK 重连并重放协议无关完整 Batch 及两个 legacy exact-Version 发布HTTP 心跳收到HTTP_CLIENT_NOT_FOUND保留同一外部 HTTP client id创建全新服务端状态并重新注册完整 Batchlegacy 子发布者在新连接上重建Runtime 绑定独立恢复两传输轮询收敛。Directed IT UT重连后的端点优先升级在 legacy 端点已注册并恢复后创建并发布 Version 2legacy SERVICE 查询、RAD Discover 与两个订阅立即解析该规范 Runtime Endpoint后续协议无关的 gRPC/HTTP 发布者增加独立贡献而不替换它。Directed IT重连后的精确与 label 检查精确 Version 1 仍可解析exact/latest Version 2 经两传输一致移动的自定义 label 解析到 Version 2。Directed IT清理退订两个监听器注销两个协议无关最终发布与 legacy Version 2 发布验证精确 Runtime 池变空删除 Agent关闭客户端重启后的服务端仍可供后续 IT 使用。Directed IT该场景有界等待两个标记及每个服务端/客户端收敛断言若 harness 协调缺失产生的是跳过或失败的目标运行而不是沉睡的常规 CI 测试。对应测试方法为shouldRestoreGrpcAndHttpPublicationsAndPollingAfterRealServerRestart通过系统属性nacos.agent.reconnect.enabledtrue开启、nacos.agent.reconnect.control.dir指定标记目录源码 L969-L982。十三、复合单机工作流Compound Standalone Workflows工作流交叉校验覆盖Maintainer 创建并发布 Agent随后 SDK Search 与 Discover管理端写入经两种客户端读操作可见。ITlegacy A2A SDK 发布 AgentCard 与 Version 1、2 的旧 exact-Version 端点随后 Console Runtime Snapshot、RAD、legacy SERVICE、直接 Naming 读检查Maintainer 发布 Version 2随后省略/默认与显式 latest 发现比较池legacy 与协议无关表面共享规范 Agent 定义与 Runtime Service重复发布不覆盖在线版本预注册不创建定义精确绑定独立存活历史 Version 特定 Naming 服务在 Beta 阶段保持为空省略选择聚合两个在线版本显式 latest 仅含 Version 2。ITSDK 预注册端点Maintainer 创建/发布 AgentSDK Discover预注册在无隐式定义创建下可见。ITMaintainer 发布 AgentSDK 注册/替换/部分注销/最终注销Discover 依序观察完整替换、剩余部分与空 Runtime source。IT两个 SDK 发布者注册同一端点一个注销再另一个注销聚合可见性保持到最后贡献被移除。IT两个协议独立发布并过滤Search 协议目录与 Discover 协议过滤一致。ITAgent 创建前启动订阅随后定义与 Runtime Endpoint 出现监听器仅在公共指纹变化时收到完整快照。IT移除订阅后定义或 Runtime Endpoint 变化退订后无回调。IT同一工作流经 gRPC 与显式 HTTP 客户端查询形态与发布语义传输等价。ITMaintainer 发布三个 Agent随后 gRPC 与 HTTP SDK 立即查询当前快照并分页/过滤收敛目录期间一个 Agent 获得版本、接收 Runtime Endpoint、逐版本下线两传输在无 readiness 错误下保持可用收敛后返回相同稳定顺序与完整目录类型化过滤组合一致端点发布不改变 Search生命周期投影收敛无陈旧版本。ITpublic 与自定义命名空间工作流并行Search、Discover、订阅、发布从不跨命名空间。ITVersion 1 在线 Version 2 端点预注册 Version 2 发布Search、latest/exact/label Discover 与订阅在每个过渡点一致。ITVersion 1 在线 端点注册前 Version 2 发布 独立 Version 2 发布者省略选择跨过渡保留 rollout 池显式 latest 只观察 Version 2两个轮询订阅收敛且无重复回调。IT活跃 gRPC/HTTP 发布与轮询订阅下真实单机重启同一存活 SDK 进程恢复两个传输持有的完整 Batch恢复两个轮询循环随后观察到后续版本与两个端点。Directed IT十四、本阶段延后项Deferred In This Phase项目原因服务端 Watch/Push、watchKey、Push ACK、gap recovery 与 Watch ability已批准的首版使用主动 Discover 轮询。公共getAll/selectOneHealthy辅助 API 形态设计已声明本地选择语义但尚未规定稳定的 Java 类型与方法签名不阻塞 Search、Discover、轮询或发布作为记录而非本阶段发明。Agent 管理元数据变更通知AgentDiscoveryResult有意排除显示名、描述、标签、provider 等管理元数据。其轮询指纹仅包含解析版本、版本contentDigest与端点sourceRevision。未来订阅已发布 Agent 元数据强制更新的需求需要 Search/目录订阅或显式 RAD 契约扩展不能由当前 Discover 订阅推断。单帧级丢包与未知 gRPC 写结果歧义由确定性单元故障注入覆盖真实单节点进程重启单独覆盖帧级故障注入不是稳定的单机 IT。十五、如何运行与继续深入场景矩阵文档test/java-sdk-test/AGENT_DISCOVERY_SDK_IT_SCENARIOS.md主测试类18 个稳定工作流 1 个可选 Directed 重启工作流AgentDiscoveryServiceJavaSdkITCase.java公共 API 契约AgentDiscoveryService.java、AiService.java后者还扩展了A2aService提供releaseAgentCard、getAgentCard、subscribeAgentCard等 legacy 兼容面工厂与传输模式AiFactory.java、AgentTransportMode.java容量与超时属性常量AiConstants.javaRAD 数据模型api/src/main/java/com/alibaba/nacos/api/ai/model/radAgentSearchRequest、AgentReference、AgentDiscoveryFilter、AgentDiscoveryResult、AgentEndpointRegistrationBatch、AgentEndpointDeregistrationBatch、AgentCatalogEntry、EndpointSet等相关设计与协议规格specs/en/ai/rad-protocol-spec.md、specs/en/ai/agent-api-spec.md、specs/en/ai/a2a-agent-spec.md运行集成测试需先按 JAVA_SDK_IT_SCENARIOS.md 与 JAVA_SDK_IT_COVERAGE.md 的准备说明启动单机 Nacos共享服务端 IT 不得停机Directed 重启用例额外要求外部 harness 通过nacos.agent.reconnect.enabled与nacos.agent.reconnect.control.dir协调进程启停与标记文件。SDK 侧发布/订阅容量等行为化配置见nacosAiAgentEndpointMaxPublications默认 100与nacosAiAgentDiscoveryMaxSubscriptions默认 300。结语这份场景矩阵的价值在于把协议无关 Agent 发现这一复杂域拆解为可逐条验证的契约从命名空间隔离、版本/标签语义、端点发布与注销、本地轮询订阅的去重与容量控制到 gRPC/HTTP 传输等价与真实进程重启后的重连重放每一行都对应明确的预期与验证层级。对二次开发者而言它既是行为规格书也是回归测试的活文档对维护者而言它界定了首版不做 Watch/Push、不做管理元数据订阅、不做部分缓存的清晰边界为后续迭代如批量 Wire Watch 的整批准入预留了可扩展的契约位置。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考