wehub-resource-sync
137 lines
5.6 KiB
Markdown
137 lines
5.6 KiB
Markdown
<!--
|
||
Copyright 1999-2026 Alibaba Group Holding Ltd.
|
||
|
||
Licensed under the Apache License, Version 2.0 (the "License");
|
||
you may not use this file except in compliance with the License.
|
||
You may obtain a copy of the License at
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
Unless required by applicable law or agreed to in writing, software
|
||
distributed under the License is distributed on an "AS IS" BASIS,
|
||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
See the License for the specific language governing permissions and
|
||
limitations under the License.
|
||
-->
|
||
|
||
# Java SDK 集成测试规范
|
||
|
||
本规范定义 Nacos Java SDK 公开契约的集成测试模型。它与
|
||
[API 集成测试规范](api-integration-test-spec.md)互补：HTTP API IT 验证部署后
|
||
的 HTTP 契约，Java SDK IT 验证应用侧看到的类型化 Java SDK 行为。
|
||
|
||
Java SDK IT 的目标是 SDK 场景覆盖，不是行覆盖率或分支覆盖率。
|
||
|
||
## 1. 范围
|
||
|
||
Java SDK IT 的主要位置是 `test/java-sdk-test`。该模块假设单机 Nacos 服务已经
|
||
启动，并以外部应用身份创建真实 Java SDK 客户端。
|
||
|
||
本规范适用于以下变更：
|
||
|
||
- `ConfigService`、`NamingService`、`AiService`、`A2aService`、
|
||
`LockService` 以及 maintainer-client 对应公开 interface；
|
||
- `NacosFactory`、`ConfigFactory`、`NamingFactory`、`AiFactory`、
|
||
`NacosLockFactory` 等公开 factory；
|
||
- SDK 方法返回的公开 request、response 或领域模型；
|
||
- listener、subscription、本地缓存、redo、factory 初始化、shutdown 或异常映射；
|
||
- SDK 配置项和默认值行为。
|
||
|
||
单元测试仍然需要覆盖隔离实现分支，但不能替代对外可见 SDK 行为的 Java SDK IT。
|
||
|
||
## 2. SDK 变更规则
|
||
|
||
在实现 Java SDK 契约新增、修改、删除或废弃前，变更负责人必须完成 SDK IT
|
||
影响分析：
|
||
|
||
1. 识别受影响的 SDK interface、factory、模型或 listener 路径。
|
||
2. 阅读公开 API、实现、校验器、传输映射、响应组装、异常映射、生命周期代码
|
||
和对应 SDK/client 规范。
|
||
3. 形成场景矩阵，覆盖 factory/生命周期行为、预期功能、边界/校验行为、
|
||
listener 或 subscription 行为，以及异常/错误处理。
|
||
4. 在同一个变更集中新增、更新或移除 `test/java-sdk-test` 用例。
|
||
5. 更新 `test/java-sdk-test/JAVA_SDK_IT_COVERAGE.md`。
|
||
|
||
如果完整成功路径在单机 IT 中难以实际执行，测试仍必须覆盖 SDK 参数校验、
|
||
本地边界行为、受控异常，以及低风险可观测的服务端交互。未覆盖路径和原因
|
||
必须记录在文档中。
|
||
|
||
## 3. 必须覆盖的场景组
|
||
|
||
每个 Java SDK IT 都应覆盖以下可观测场景组。
|
||
|
||
### 3.1 Factory 和生命周期
|
||
|
||
验证 SDK 可以通过公开 factory 使用真实 properties 创建，能正确处理 server
|
||
address 和 namespace 默认值，并能通过公开 shutdown 方法释放资源。
|
||
|
||
### 3.2 预期功能
|
||
|
||
验证 SDK 方法完成承诺的远程或本地行为。优先使用发布后查询、注册后查询、
|
||
订阅后回调、加锁后解锁、发布后加载、删除后确认不存在等流程。
|
||
|
||
断言必须检查类型化 SDK 返回值、模型字段、回调和远程副作用，不能只判断没有
|
||
抛出异常。
|
||
|
||
### 3.3 边界和校验
|
||
|
||
覆盖必填参数、可选默认值、非法枚举或类型、namespace/group 默认值、超时行为、
|
||
异常模型对象、listener 身份要求、重复或幂等调用，以及资源不存在行为。
|
||
|
||
### 3.4 异常和错误处理
|
||
|
||
验证 SDK 可见失败会产生受控 `NacosException` 或文档化返回值。测试应捕捉非法
|
||
输入、资源不存在、远端失败或非法生命周期使用变成非预期运行时异常的回归。
|
||
|
||
### 3.5 Listener 和订阅行为
|
||
|
||
对于 listener API，应验证适用场景下的初始查询行为、可观测变更触发回调、
|
||
unsubscribe/remove 行为和清理逻辑。等待必须有边界，并提供清晰断言信息。
|
||
|
||
## 4. 测试组织
|
||
|
||
Java SDK IT 应放在：
|
||
|
||
- `com.alibaba.nacos.test.sdk.config`
|
||
- `com.alibaba.nacos.test.sdk.naming`
|
||
- `com.alibaba.nacos.test.sdk.ai`
|
||
- `com.alibaba.nacos.test.sdk.lock`
|
||
- 新增 maintainer SDK IT 时使用 `com.alibaba.nacos.test.sdk.maintainer.<domain>`
|
||
|
||
建议一个公开 SDK interface 或一组强关联 API family 对应一个测试类。共享的客户端
|
||
构造、清理、有界等待、随机资源名和 shutdown 逻辑应抽象到基础类。
|
||
|
||
## 5. 运行规则
|
||
|
||
Java SDK IT 必须：
|
||
|
||
- 使用 JUnit 5 和 Failsafe；
|
||
- 避免 `@SpringBootTest`、`SpringExtension`，也不要在测试类中启动 Nacos；
|
||
- 读取 `nacos.host` 和 `nacos.port`，默认 `127.0.0.1:8848`；
|
||
- 通过公开 factory 创建真实 SDK 客户端；
|
||
- 生成隔离的资源名称；
|
||
- 清理创建的 config、naming、AI 或 lock 资源；
|
||
- 即使断言失败，也要关闭每个 SDK 实例；
|
||
- 对异步服务端效果使用有界重试。
|
||
|
||
## 6. 场景文档
|
||
|
||
每个 SDK IT 类都必须包含简洁的 `Scenario coverage` Javadoc；当矩阵较大时，
|
||
应更新 `test/java-sdk-test/JAVA_SDK_IT_COVERAGE.md`。文档必须说明验证了什么，
|
||
以及为什么有分支被有意跳过。
|
||
|
||
## 7. 验证
|
||
|
||
Java SDK IT 变更需要运行：
|
||
|
||
- `mvn -pl test/java-sdk-test spotless:check`
|
||
- `mvn -pl test/java-sdk-test -DskipTests test-compile`
|
||
|
||
当单机 Nacos 服务可用时，应运行相关 Failsafe 选择，或执行
|
||
`mvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTests=false
|
||
verify`。
|
||
|
||
Java SDK IT 必须使用独立的 `java-sdk-integration-test` Maven profile。通用
|
||
`integration-test` profile 保留给 HTTP API IT 工作流，不能意外运行依赖 SDK
|
||
gRPC 连接就绪状态或可选服务端能力的 SDK 测试。
|