Nacos v3 Client OpenAPI 集成测试场景全解析：从配置查询到 AI 资源发现

本文以 Nacos 仓库中的 Client API IT Scenario Index 为核心骨架，系统梳理 Nacos v3 面向客户端（Client）的 HTTP OpenAPI 接口族：配置查询、服务实例注册与发现，以及 AI Registry 下的 Prompt、Skill、AgentSpec、Agent 等资源发现能力。文章将结合 test/openapi-test 下的集成测试实现与服务端控制器源码，讲解每个接口的覆盖场景、参数校验边界、错误码契约及背后的实现原理，帮助读者理解 Nacos v3 客户端 API 的"能力契约、边界校验、受控异常"三维测试模型，并掌握如何用这些测试用例反推接口的完整行为。

一、背景：为什么 Nacos 需要一套 Client OpenAPI

Nacos 客户端与服务端的标准通信协议是 gRPC（支持长连接、配置监听与服务订阅），但并非所有语言、所有场景都能承载 gRPC 依赖。Nacos v3 提供了一套纯 HTTP 的 Client OpenAPI，为不支持 gRPC 的编程语言提供一条轻量接入路径。

这一点在服务端控制器源码中有明确注释：以 InstanceOpenApiController 为例，其类注释说明这套 OpenAPI 面向"不支持 gRPC 请求、但希望用客户端从 Nacos 获取远程配置/注册实例"的场景，且明确不提供 HTTP 长轮询监听与订阅能力——需要监听配置或订阅服务时，仍需走 gRPC 通道。同理，ConfigOpenApiController 的注释也强调"仅提供获取指定配置的功能 API，不支持 HTTP 监听配置"。

因此，Client OpenAPI 的定位可以概括为：

• 服务端面向客户端程序（区别于面向管理员/控制台的 Admin、Console API）；
• 覆盖配置读取、实例注册/注销/列表查询，以及 AI 资源（Prompt、Skill、AgentSpec、Agent 等）的发现与发布；
• 接口统一挂载在 /v3/client/** 路径之下；
• 不提供长连接订阅能力，订阅类能力由 gRPC 承担。

二、测试矩阵总览：文档的核心骨架

CLIENT_API_TEST_SCENARIOS.md 是一份 Client OpenAPI 集成测试（IT）场景索引，记录了独立服务器（standalone-server）模式下，src/test/java/com/alibaba/nacos/test/openapi/client 下各 IT 类对每个公开 API 操作（API operation）的覆盖情况。分支级覆盖率目标聚焦于"API 场景覆盖率"：期望能力、边界/校验行为、受控异常/错误处理三类。

状态图例

状态	含义
Covered	当前 IT 已验证期望行为及其重要结果形态
Partial	当前 IT 验证了代表性行为，但仍存在重要的公开 API 场景未覆盖
Pending	当前没有任何 IT 验证该公开 API 场景

全量覆盖矩阵

API surface / IT 类	覆盖的 API 操作	当前状态	当前 / 缺失覆盖
ConfigOpenApiITCase	GET /v3/client/cs/config	Covered	查询 Admin API 发布的配置（含 content、md5、lastModified、contentType 及灰度 beta 字段）；验证公共命名空间默认、错误命名空间 not-found、必填 dataId/groupName、拒绝旧 group 参数、非法命名空间、包装式 not-found/error 响应体
InstanceRegisterOpenApiITCase	POST /v3/client/ns/instance	Covered	注册实例并通过 list 验证可见性；覆盖 namespace/group/cluster/healthy/weight/enabled 默认值、显式 group/cluster 行为、必填 service/ip/port 校验、非法 weight/cluster、重复或服务状态错误
InstanceListOpenApiITCase	GET /v3/client/ns/instance/list	Covered	列出已启用的注册实例（含 metadata 与 health 字段）；覆盖 namespace/group/cluster 默认值、healthy-only 与 enabled 过滤、空结果行为、必填 serviceName、畸形或未知参数、not-found 风格结果
InstanceDeregisterOpenApiITCase	DELETE /v3/client/ns/instance	Covered	注销已存在实例并验证从列表消失；覆盖默认/显式 group/cluster 值、缺失实例的幂等行为、必填 service/ip/port 校验、畸形 port 处理
PromptClientOpenApiITCase	GET /v3/client/ai/prompt	Partial	按 latest、显式 version、label 查询在线 Prompt；验证命名空间默认、version 优先于 label、md5 条件 HTTP 304、缺失 promptKey/version 解析、Prompt 不存在、未知 version、offline/未上线错误
SkillClientOpenApiITCase	GET /v3/client/ai/skills	Covered	按 latest、version、label 以 ZIP 形式下载在线 Skill（含资源条目）；覆盖命名空间默认、version 优先于 label、缺失 skillName、Skill 不存在、未知 version/label、下载失败的受控 not-found JSON
AgentSpecClientOpenApiITCase	GET /v3/client/ai/agentspecs	Covered	按 latest、version、label 查询在线 AgentSpec（含 manifest/resource 内容）；覆盖命名空间默认、label/version 解析、缺失 name、AgentSpec 不存在、未知 version、受控 not-found 错误
AgentSpecSearchClientOpenApiITCase	GET /v3/client/ai/agentspecs/search	Covered	基于共享索引搜索 AgentSpec 投影（在线版本、字面关键字过滤、tagsAll）；覆盖最终索引收敛、可选 keyword、命名空间默认、分页默认值与校验、空页成功、非法分页错误
AiResourceSearchClientOpenApiITCase	GET /v3/client/ai/resources/search、GET /v3/client/ai/skills/search、GET /v3/client/ai/prompt/search、GET /v3/client/ai/mcp/search	Covered	通过 Admin 生命周期 API 发布 Agent/AgentSpec/Skill/Prompt/MCP 资源，验证异步投影期间 Search 始终基于当前快照成功，等待持久化收敛后验证跨类型关键字召回；覆盖默认命名空间、确定性空查询列表、tagsAll、capabilitiesAny、MCP protocolsAny、不透明多页游标遍历无重复、无匹配成功、不支持资源类型、畸形游标、有界 limit、超大查询、非法数字分页
AgentDiscoveryClientOpenApiITCase	GET /v3/client/ai/agents/search、GET /v3/client/ai/agents	Covered	通过 Admin 辅助路径发布 Agent，验证 RAD Search 与 Discover 投影；覆盖 AUTO/INDEX/SCAN 兼容的最终一致契约、大小写敏感字面名过滤（含 %、_、\）、tagsAll/protocolsAny 组合、稳定 ASCII 数字分页、多版本完整目录、latest/offline 收敛、Runtime Endpoint 写入不改变 Search、双版本灰度发布工作流、可选 selector 语义、默认命名空间、类型化空协议结果、分页校验、version/label 互斥、缺失标识、Agent 不存在错误
AgentPublishClientOpenApiITCase	POST /v3/client/ai/agents	Covered	验证草稿与自动提交发布、恢复、等价重试、冲突内容或初始元数据、高级/offline 版本错误、直接与 basedOnVersion 内容、默认/自定义命名空间隔离、畸形 Form JSON 与布尔字段、无 Endpoint 副作用、Admin/Console/RAD/legacy A2A 交叉校验
AgentEndpointClientOpenApiITCase	POST, DELETE /v3/client/ai/agents/endpoints、PUT /v3/client/ai/agents/endpoints/heartbeat	Covered	验证基于 Form 的完整 HTTP Publisher 替换、通过 Discover 可见、幂等注册/注销、注销后空 Runtime Endpoint 投影、存活间隔、心跳、注册前后 HTTP_CLIENT_NOT_FOUND (50404)；跨校验 Admin 创建与 Overview、Console Overview 两侧管理面快照；确认同 Client id 查询不会创建 Publisher；覆盖必填头、Client-id 语法、整批校验、畸形 endpoints JSON Form 字段、服务端软水位（it-new.yml 中降为 3）、从低于到高于水位的整批准入、高于水位的等量替换、AGENT_ENDPOINT_PUBLICATION_OVER_LIMIT 原子拒绝继续增长、注销后容量复用

授权元数据覆盖说明

文档同时明确：独立 OpenAPI IT 配置未启用 Client API 授权，因此针对仅授权修复的功能场景保持不变。聚焦的 Auth 与 AI 模块测试验证了 AgentSpec 详情端点保留 OPEN_API/AI 元数据，并从客户端 name 参数解析授权资源。

三、Config：GET /v3/client/cs/config 配置查询契约

3.1 控制器实现

服务端入口为 ConfigOpenApiController，位于 config 模块的 controller.v3 包下，类级映射 Constants.CONFIG_V3_CLIENT_API_PATH，方法标注 @Since("3.0.0")、@GetMapping 与 @TpsControl(pointName = "ConfigQuery")，意味着该接口自 3.0.0 起提供，并受 TPS 流控保护。其底层查询由 ConfigQueryChainService 承担（配置查询责任链服务），响应模型使用 ConfigQueryResponse，包含 content、md5、lastModified、contentType 等字段。

3.2 IT 覆盖的能力场景

ConfigOpenApiITCase 直接对应文档中的 ConfigOpenApiITCase 行，测试路径常量为 nacosPath(Constants.CONFIG_V3_CLIENT_API_PATH)，即实际请求 URL 为 /nacos/v3/client/cs/config（nacosPath 统一在 OpenApiBaseITCase 中为 /nacos 前缀 + API 路径）。

核心验证链路（testGetConfigSuccessAfterPublish）：

1. 通过 Admin API（publishConfig）发布一条配置；
2. 循环重试 GET 客户端接口直至成功——注释说明"发布成功后 Nacos 会异步将配置从存储落盘到缓存"（After publish success, nacos will async cache into disk from storage），这解释了查询接口的最终一致性窗口；
3. 断言响应包含：
   • content 与发布内容一致；
   • md5 等于 MD5Utils.md5Hex(content, UTF-8)；
   • lastModified > 0；
   • contentType 非空；
   • beta 为 false（非灰度状态）。

3.3 边界与错误契约

• 空结果不报错：testGetConfigWhenNotExists 验证不存在的配置返回 HTTP 2xx，响应体为包装的 Result，code 为 ErrorCode.RESOURCE_NOT_FOUND（ErrorCode.java 中定义为 20004, "resource not found"）；
• 必填校验：dataId 与 groupName 必填，缺失时返回受控的 HTTP 400 文本（控制器路径下的参数校验，而非 HTTP 500）；
• 旧参数拒绝：v3 不接受 legacy 的 group 参数替代 groupName；
• 命名空间默认：省略 namespaceId 使用公共命名空间（public）；
• 错误命名空间：错误命名空间返回包装的 not-found 结果；
• 非法命名空间：参数校验直接拒绝（HTTP 400 + 包装 Result 字段）。

IT 类注释还说明：pre-3.0 的 namespace 或 beta/tag 存储迁移不在 3.3 客户端 API 契约范围内（"Removed pre-3.0 namespace or beta/tag storage migration is outside the 3.3 client API contract"）。

四、Naming：实例注册、列表与注销

4.1 控制器实现

服务端入口为 InstanceOpenApiController，类级映射 UtilsAndCommons.INSTANCE_V3_CLIENT_API_PATH，即 /v3/client/ns/instance。它组合了 InstanceOperator（实例操作门面）与 SwitchDomain，并持有三个端点：

方法	路径	职责
POST	/v3/client/ns/instance	注册实例
DELETE	/v3/client/ns/instance	注销实例
GET	/v3/client/ns/instance/list	查询实例列表

控制器标注 @NacosApi 与 @ExtractorManager.Extractor(httpExtractor = NamingDefaultHttpParamExtractor.class)，注册/注销使用 NamingDefaultHttpParamExtractor 做参数提取与校验，列表查询使用 NamingInstanceListHttpParamExtractor。

4.2 注册：InstanceRegisterOpenApiITCase

InstanceRegisterOpenApiITCase 验证：

• 默认值语义（testRegisterWithDefaultValuesMakesInstanceDiscoverable）：仅传 serviceName、ip、port、metadata 注册后，通过 list 接口可见，并断言默认派生：serviceName 为 DEFAULT_GROUP + "@@" + serviceName（即 DEFAULT_GROUP@serviceName）、clusterName 为 UtilsAndCommons.DEFAULT_CLUSTER_NAME、healthy=true、enabled=true、ephemeral=true、weight=1.0、metadata 原样保留；
• 显式字段持久化（testRegisterWithExplicitFieldsPersistsClientVisibleState）：显式传 groupName、clusterName、healthy=false、enabled=true 等字段可覆盖默认值并持久化到客户端可见状态；
• 边界校验：serviceName、ip、port 必填；非法 weight 与 clusterName 返回受控 HTTP 400 + 包装 Result 字段（而非 500）；heartBeat=true 对已存在实例可接受，对不存在实例返回 INSTANCE_NOT_FOUND；重复注册或服务状态异常返回对应错误。

4.3 列表与注销

• InstanceListOpenApiITCase 对应 GET /v3/client/ns/instance/list：默认只返回 enabled 实例，支持 healthy-only 与 enabled 过滤、空结果行为、serviceName 必填校验、畸形/未知参数处理，以及 not-found 风格结果（注意文档与源码均区分"HTTP 2xx + 业务 not-found code"与"受控错误体"两种风格）；
• InstanceDeregisterOpenApiITCase 对应 DELETE /v3/client/ns/instance：注销后实例从列表消失；对不存在的实例注销是幂等的（不报错）；serviceName/ip/port 必填；畸形 port 受控处理。

4.4 统一测试基础设施

所有 OpenAPI IT 都继承 OpenApiBaseITCase，它提供了：

• 基于 nacos.host/nacos.port 系统属性（默认 127.0.0.1:8848）构建 BASE_URL；
• 统一的 GET/POST/PUT/DELETE/Form/JSON/Multipart 原始请求封装（getRaw/postFormOk/postJsonOk/putFormOk/deleteJsonOk/postMultipartRaw 等）；
• assertSuccess（断言 code 为 ErrorCode.SUCCESS）、assertError（断言 HTTP 状态码 + 业务 code + message + data 包含关键字）；
• addCleanup 后置清理队列，保证每个测试用例结束后注销/删除测试资源，避免污染后续用例。

五、AI Registry：AI 资源的客户端发现契约

/v3/client/ai/** 是 Nacos v3 面向 AI 资源的客户端查询通道，对应仓库中的 AI 模块（ai）与 ai-registry-adaptor（ai-registry-adaptor）。文档按资源类型逐一记录了 IT 覆盖：

5.1 Prompt：GET /v3/client/ai/prompt（Partial）

PromptClientOpenApiITCase 验证在线 Prompt 的三种查询维度与优先级：

• latest：不传 version/label 返回最新在线版本；
• 显式 version：返回指定版本；
• label：返回 label 指向的版本；
• version 优先于 label：同时传 version 与 label 时以 version 为准（测试 versionWins 断言返回 2.0.0 而非 stable 指向的 1.0.0）；
• 未知 label 回退 latest：label 不存在时回退到最新版本；
• md5 条件请求：携带与最新内容一致的 md5 参数时返回 HTTP 304 Not Modified（实现类似配置的条件拉取，节省带宽）；
• 错误契约：缺失 promptKey 返回 HTTP 400 + PARAMETER_MISSING（ErrorCode 中 10000, "parameter missing"）；Prompt 不存在或版本未上线返回 404 + RESOURCE_NOT_FOUND（20004）且 message 含 "Prompt not found" 之类关键字；
• Partial 原因：独立 IT 配置未启用授权，无法切换身份，因此"不可读 Prompt 返回 not found"（权限导致的隐藏）由聚焦的 Prompt 服务测试覆盖，而非端到端 IT。

响应数据模型包含 promptKey、version、template（如 Hello {{name}} from v1）、md5、variables（含 name/defaultValue，测试断言变量 name 与默认值 Nacos）。

5.2 Skill：GET /v3/client/ai/skills（Covered）

SkillClientOpenApiITCase 验证以 ZIP 形式下载在线 Skill：按 latest/version/label 解析，ZIP 内包含资源条目；覆盖命名空间默认、version 优先于 label、缺失 skillName、Skill 不存在、未知 version/label，以及下载失败时返回受控的 not-found JSON（而不是裸 500）。

5.3 AgentSpec：GET /v3/client/ai/agentspecs 与搜索（Covered）

• AgentSpecClientOpenApiITCase：按 latest/version/label 查询在线 AgentSpec，响应含 manifest/resource 内容；覆盖命名空间默认、缺失 name、AgentSpec 不存在、未知 version、受控 not-found；
• AgentSpecSearchClientOpenApiITCase（GET /v3/client/ai/agentspecs/search）：基于共享索引搜索 AgentSpec 投影，限制为在线版本，支持字面关键字过滤与 tagsAll；覆盖索引最终收敛（异步投影）、可选 keyword、命名空间默认、分页默认值/校验、空页成功、非法分页错误。

5.4 通用 AI 资源搜索：AiResourceSearchClientOpenApiITCase（Covered）

该 IT 覆盖四个搜索端点：/v3/client/ai/resources/search、/v3/client/ai/skills/search、/v3/client/ai/prompt/search、/v3/client/ai/mcp/search。核心验证策略：

1. 通过各资源的 Admin 生命周期 API 发布 Agent、AgentSpec、Skill、Prompt、MCP；
2. 验证异步投影期间 Search 始终基于当前快照返回成功（不因未收敛而失败）；
3. 等待持久化收敛后验证跨类型关键字召回；
4. 对每个可搜索类型，用通用单类型查询与资源专属 Search 门面交叉核对（Agent 与 AgentSpec 已有专属门面）；MCP 的通用标识是其 canonical name，而兼容 DTO 保留 mcpId 字段。

覆盖的边界：默认命名空间、确定性空查询列表、tagsAll、capabilitiesAny、MCP protocolsAny、不透明多页游标遍历无重复、无匹配成功、不支持资源类型、畸形游标、有界 limit、超大查询、非法数字分页。

5.5 Agent 发现：AgentDiscoveryClientOpenApiITCase（Covered）

覆盖 GET /v3/client/ai/agents/search 与 GET /v3/client/ai/agents（Discover），核心契约：

• RAD 搜索的最终一致契约：AUTO/INDEX 模式返回当前快照成功（不因未就绪返回 503），随后通过收敛轮询建立完整目录；SCAN 兼容；
• 字面名过滤：大小写敏感，且 %、_、\ 作为字面字符参与匹配（不做通配解释）；
• 组合过滤：tagsAll/protocolsAny 组合；
• 分页：稳定 ASCII 数字分页，含越界页；
• 多版本目录：完整多版本目录、latest/offline 收敛；
• 不变量：Runtime Endpoint 写入不改变 Search 结果；
• 双版本灰度工作流：两个独立 HTTP Publisher 并发维护 Version 1 与 Version 2 Endpoint——省略 selector 时返回最新元数据 + 所有在线版本兼容 Endpoint 及绑定来源；显式 label=latest 只返回 Version 2 Endpoint；精确 Version 1 保持隔离；Version 1 下线后其 Endpoint 只从默认池移除；
• 错误契约：默认命名空间、类型化空协议结果、空搜索、分页校验、version/label 互斥（二者不可同时传）、缺失标识、Agent 不存在。

5.6 Agent 发布：AgentPublishClientOpenApiITCase（Covered）

POST /v3/client/ai/agents 的发布契约：草稿-only 与自动提交发布、发布中断后恢复（resume）、等价重试（相同内容重试幂等）、冲突内容或初始元数据、高级/offline 版本错误、直接内容与 basedOnVersion 内容、默认/自定义命名空间隔离、畸形 Form JSON 与布尔字段处理、发布无 Endpoint 副作用，并通过 Admin/Console/RAD/legacy A2A 交叉校验结果一致性。

5.7 Agent Endpoint：AgentEndpointClientOpenApiITCase（Covered）

覆盖 POST, DELETE /v3/client/ai/agents/endpoints 与 PUT /v3/client/ai/agents/endpoints/heartbeat：

• 完整替换语义：基于 Form 的完整 HTTP Publisher 替换（整批提交而非增量）；
• 可见性：注册后通过 Discover 可见，注销后 Runtime Endpoint 投影为空；
• 幂等：注册/注销幂等；心跳维护存活；
• 错误码：注册前与注销后访问返回 HTTP_CLIENT_NOT_FOUND (50404)（ErrorCode.java 定义 50404, "HTTP client not found"）；
• 管理面交叉验证：同一工作流从 Admin 创建与 Overview、Console Overview 两侧核对快照，覆盖 HTTP+JSON 无损传输、Endpoint 载荷、版本绑定、启用、健康、状态与 Console Naming 引用；
• 身份语义：同 Client id 的查询不会创建 Publisher；
• 校验：必填请求头、Client-id 语法、整批校验、畸形 endpoints JSON Form 字段；
• 容量水位：服务端软水位在 it-new.yml 中降为 3；验证从低于到高于水位的整批准入、高于水位的等量替换（替换不触发超限）、继续增长时以 AGENT_ENDPOINT_PUBLICATION_OVER_LIMIT 原子拒绝（50103, "Agent Endpoint publication capacity reached"）、注销后容量复用。

六、从错误码反推 API 契约

Client OpenAPI 的业务错误统一走 ErrorCode 枚举 + Result 包装体。文中频繁出现的核心错误码：

错误码	名称	含义	典型触发
0	SUCCESS	成功	所有正常响应
10000	PARAMETER_MISSING	参数缺失	缺失 promptKey/dataId/serviceName 等必填参数
10001	ACCESS_DENIED	访问被拒绝	授权失败（IT 未启用授权，由聚焦测试覆盖）
20002	PARAMETER_VALIDATE_ERROR	参数校验失败	非法命名空间、非法 weight/cluster
20004	RESOURCE_NOT_FOUND	资源不存在	配置/Prompt/AgentSpec/Agent 不存在或版本未上线
50100	AGENT_NOT_FOUND	Agent 不存在	Discover 中缺失 Agent
50103	AGENT_ENDPOINT_PUBLICATION_OVER_LIMIT	Endpoint 发布容量超限	超过服务端软水位的整批增长被原子拒绝
50404	HTTP_CLIENT_NOT_FOUND	HTTP 连接型客户端不存在	Endpoint 注册前/注销后访问

错误响应同时遵循"HTTP 2xx + 业务 code"与"受控 HTTP 4xx + 包装 Result"两种形态：不存在的资源通常返回 HTTP 2xx 且 code=RESOURCE_NOT_FOUND（如配置查询），而参数缺失/非法通常返回 HTTP 400/404 + 包装字段（如 Prompt 查询缺失 promptKey 返回 400 + PARAMETER_MISSING）。assertError 基类方法正是对这一契约的固化：同时断言 HTTP 状态、业务 code、message 与 data 关键字。

七、如何运行与扩展这套 IT

运行入口在 test/openapi-test 模块（pom.xml），依赖一个独立运行的 Nacos 服务器。公共基类 OpenApiBaseITCase 支持通过 JVM 系统属性覆盖目标地址：

# 默认 127.0.0.1:8848，可覆盖
mvn -pl test/openapi-test test -Dnacos.host=127.0.0.1 -Dnacos.port=8848

若要单独执行 Client 相关用例，可限定测试类：

mvn -pl test/openapi-test test -Dtest=ConfigOpenApiITCase,InstanceRegisterOpenApiITCase

AI 相关用例继承 AiOpenApiBaseITCase/AgentClientOpenApiBaseITCase 等中间基类，这些基类封装了通过 Admin API 发布 Prompt/Skill/AgentSpec/Agent 等前置辅助调用（例如 publishPrompt、updateLabels），使测试聚焦于客户端侧契约本身。运行前需保证目标 Nacos 已启动且相关模块（config、naming、ai）已构建。

八、总结

从 CLIENT_API_TEST_SCENARIOS.md 可以清晰看到 Nacos v3 Client OpenAPI 的三大设计原则，这也是其 IT 场景编排的逻辑主线：

1. 能力契约（Expected capability）：每个接口必须有一个"happy path"——配置查询返回 content/md5/lastModified、实例注册后可见、AI 资源按 latest/version/label 可发现；
2. 边界/校验（Boundary/validation）：默认值派生（公共命名空间、DEFAULT_GROUP、weight=1.0、healthy/enabled/ephemeral 默认）、必填参数、参数互斥（version/label）、旧参数拒绝（legacy group）、容量水位；
3. 受控异常（Exception/error handling）：统一 ErrorCode + Result 包装，区分"资源不存在"（2xx + RESOURCE_NOT_FOUND）与"参数错误"（4xx + PARAMETER_MISSING/PARAMETER_VALIDATE_ERROR），杜绝裸 500。

这套场景索引同时是 API 消费者与维护者的"行为规格说明书"：消费者可以据此快速确认接口的边界语义（如 AI 搜索的字面匹配、Agent Endpoint 的整批替换与水位拒绝），维护者在修改客户端 API 时也可以直接对照该矩阵补齐回归用例。需要深入了解某一接口时，推荐按"索引文档 → 对应 IT 类 → 服务端 v3 控制器 → ErrorCode 枚举"的链路继续阅读仓库源码。