AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when working with the Nacos repository. For human contributors, see [CONTRIBUTING.md](./CONTRIBUTING.md).
4 
5## AI Contribution Guidelines
6 
7- **Do NOT post AI-generated comments** on issues or PRs. Discussions are for humans only.
8- **Discuss before implementing**: Ensure the implementation direction is agreed upon with maintainers in the issue comments before starting work.
9- **Spec-first coding is mandatory**: Before changing behavior, APIs, SDKs,
10  plugins, storage, runtime flow, or domain semantics, AI agents MUST read the
11  relevant specs under [`specs/`](./specs/README.md) and treat them as the rule
12  source for the implementation.
13- **Discuss spec-impacting changes before coding**: If a change touches behavior
14  covered by an existing spec, or exposes a gap between the code and the spec,
15  AI agents MUST discuss the implementation direction and the required spec
16  update with maintainers before starting the code change.
17- **Update specs with the design**: Any design proposal that changes or
18  clarifies spec-covered behavior MUST include the corresponding spec updates
19  in the same change set. When the design is large or controversial, prefer a
20  spec/design-only PR first, then follow with implementation PRs.
21- **API IT impact comes first**: Before adding, changing, deleting, or
22  deprecating any HTTP API, AI agents MUST analyze the affected
23  `test/openapi-test` coverage and update the API IT scenario matrix, test
24  cases, and coverage registry in the same change set. If the functional path
25  cannot be exercised in standalone IT, cover boundary/error scenarios and
26  document the reason.
27- **Java SDK IT impact comes first**: Before adding, changing, deleting, or
28  deprecating any public Java SDK interface, factory, model, listener behavior,
29  lifecycle behavior, or exception mapping, AI agents MUST analyze and update
30  `test/java-sdk-test` coverage, including scenario documentation. If the
31  end-to-end success path is impractical, cover SDK parameter validation,
32  boundary behavior, and controlled exceptions.
33- **Disclose AI usage**: When a significant part of a commit is AI-generated, add a trailer to your commit message:
34```
35  Assisted-by: Claude Code
36```
37- **Follow [CONTRIBUTING.md](./CONTRIBUTING.md)** for all contribution processes.
38 
39## Repository Overview
40 
41Nacos (Dynamic Naming and Configuration Service) is an easy-to-use platform designed for dynamic service discovery, configuration management, and AI agent management. It helps you build cloud-native applications and AI Agent applications easily. Key capabilities: service discovery, dynamic configuration, dynamic DNS service, service/metadata management, and AI registry (Prompt, MCP, A2A).
42 
43**Current Version**: 3.2.1-SNAPSHOT | **Main Branch**: `develop` | **Java**: JDK 17+ (client modules: JDK 8+) | **Build**: Maven 3.2.5+
44 
45## Core Architecture
46 
47Key modules and their roles:
48 
49- **api / client / client-basic**: Client-facing APIs, gRPC definitions, SDK (Java 8 compatible)
50- **common**: Shared utilities, HTTP client, notify center, executor
51- **config**: Configuration management server
52- **naming**: Service discovery and registration server
53- **core**: Core server infrastructure (cluster, distributed consensus)
54- **consistency**: JRaft-based CP protocol + custom Distro AP protocol
55- **auth**: Authentication and authorization
56- **plugin / plugin-default-impl**: Extensible plugin system (Java SPI). Types: auth, visibility, datasource dialect, config change, encryption, trace, environment, control, AI pipeline, AI storage
57- **console / console-ui**: Web UI backend (Spring Boot) and frontend (React)
58- **ai / copilot / ai-registry-adaptor**: AI Agent support, Copilot integration, and AI registry adaptor
59- **sys**: System environment utilities and JVM parameter management
60- **bootstrap / server**: Server startup and aggregation
61- **persistence**: Data persistence with multi-database support (Derby, MySQL, PostgreSQL)
62- **maintainer-client**: Internal maintenance client
63- **lock**: Distributed lock support
64 
65Communication: **gRPC** (primary) + **HTTP/REST** (legacy compatibility). Protobuf definitions in `api/src/main/proto/`.
66 
67## Build & Test Commands
68 
69```bash
70# Full build (skip tests)
71mvn '-Prelease-nacos,!dev' -Dmaven.test.skip=true clean install -U
72 
73# Run all unit tests
74mvn test
75 
76# Run standalone-server integration tests
77mvn -pl test/openapi-test -Pintegration-test -DskipTests=false verify
78mvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTests=false verify
79mvn -pl test/maintainer-sdk-test -Pmaintainer-sdk-integration-test -DskipTests=false verify
80 
81# Format code (run before commit)
82mvn spotless:apply
83 
84# Pre-submission checks (MUST pass before PR)
85mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests
86```
87 
88### Mandatory Formatting Before Commit
89 
90Before committing Java code or tests, AI agents MUST run Spotless for the
91affected module or nearest aggregator:
92 
931. Run `mvn spotless:apply` first.
942. Run `mvn spotless:check` for the same scope.
953. Then run the relevant compile/check/test command.
964. Commit only after Spotless and the relevant validation pass.
97 
98Do not rely on `checkstyle:check`, `spotbugs:check`, or `git diff --check` as a
99substitute for Spotless. Spotless uses the project formatter and may accept
100formatting that generic whitespace checks report differently.
101 
102## Code Style
103 
104Follows **Alibaba Java Coding Guidelines**.
105 
106- Checkstyle config: [`style/NacosCheckStyle.xml`](style/NacosCheckStyle.xml)
107- IDEA code style: [`style/nacos-code-style-for-idea.xml`](style/nacos-code-style-for-idea.xml)
108 
109### Key Rules for AI Agents
110 
111| Rule | Value |
112|------|-------|
113| Indentation | **4 spaces** (basic offset), 4 spaces (case indent) |
114| Line length | **100 characters** max (enforced by Spotless + Checkstyle) |
115| Star imports | **Forbidden** — always use explicit imports |
116| Unused imports | **Forbidden** |
117| Javadoc | Required for API methods (exemptions: `@Override`, `@Test`, `@Before`, `@After`, `@BeforeClass`, `@AfterClass`, `@Parameterized`, `@Parameters`, `@Bean`) |
118| Braces | Required for all `if/else/for/while/do-while` blocks, even single-line |
119| Switch | Must have `default` case; fall-through must be commented |
120| Naming | `camelCase` for methods/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants |
121| Abbreviations | Max 1 consecutive capital letter in names (exception: `VO`) |
122 
123### License Header
124 
125Every new source file **must** include the Apache License 2.0 header. CI enforces this via `apache-rat:check`.
126 
127```java
128/*
129 * Copyright 1999-${year} Alibaba Group Holding Ltd.
130 *
131 * Licensed under the Apache License, Version 2.0 (the "License");
132 * you may not use this file except in compliance with the License.
133 * You may obtain a copy of the License at
134 *
135 *      http://www.apache.org/licenses/LICENSE-2.0
136 *
137 * Unless required by applicable law or agreed to in writing, software
138 * distributed under the License is distributed on an "AS IS" BASIS,
139 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
140 * See the License for the specific language governing permissions and
141 * limitations under the License.
142 */
143```
144 
145## API Standards
146 
147Nacos v3 APIs follow strict conventions. AI agents **must** comply with these
148standards when generating controller code.
149 
150Authoritative API and SDK specs live under [`specs/`](./specs/README.md).
151Before coding any API, SDK, plugin, storage, runtime, or domain change, AI
152agents **MUST** consult the relevant specs below. If the intended behavior
153differs from the existing spec, do not silently implement the code first:
154discuss the change with maintainers and update the affected specs as part of
155the design. For broad or uncertain changes, submit a spec/design PR first so
156the contract is reviewed before implementation.
157 
158English:
159 
160- Design foundation:
161  [Nacos Design Spec](./specs/en/design/nacos-design-spec.md),
162  [Resource Model Spec](./specs/en/design/resource-model-spec.md),
163  [Compatibility And Deprecation Spec](./specs/en/design/compatibility-deprecation-spec.md),
164  [Foundation Capabilities Spec](./specs/en/design/foundation-capabilities-spec.md),
165  [Server Lifecycle And Environment Configuration Spec](./specs/en/design/foundation-server-lifecycle-env-spec.md),
166  [Cluster Membership Spec](./specs/en/design/foundation-cluster-membership-spec.md),
167  [Remote Connection Lifecycle Spec](./specs/en/design/foundation-remote-connection-spec.md),
168  [Request Filtering And Runtime Context Spec](./specs/en/design/foundation-request-context-spec.md),
169  [Internal RPC And Cluster Request Spec](./specs/en/design/foundation-internal-rpc-spec.md),
170  [AP Consistency Spec](./specs/en/design/foundation-ap-consistency-spec.md),
171  [CP Consistency Spec](./specs/en/design/foundation-cp-consistency-spec.md),
172  [Persistence And Dump Spec](./specs/en/design/foundation-persistence-dump-spec.md),
173  [Task Execution Spec](./specs/en/design/foundation-task-execution-spec.md),
174  [Event Dispatch And NotifyCenter Spec](./specs/en/design/foundation-event-dispatch-spec.md),
175  [Observability Hooks Spec](./specs/en/design/foundation-observability-hooks-spec.md),
176  [Core Capabilities Spec](./specs/en/design/core-capabilities-spec.md)
177- Interface model:
178  [HTTP API Spec](./specs/en/http-api/api-spec.md),
179  [Authorization Spec](./specs/en/http-api/authorization-spec.md),
180  [Response And Error Spec](./specs/en/http-api/response-error-spec.md),
181  [V3 API Surface](./specs/en/http-api/v3-api-surface.md),
182  [gRPC API Spec](./specs/en/grpc-api/api-spec.md),
183  [SDK Spec](./specs/en/sdk/sdk-spec.md),
184  [Java SDK Implementation Spec](./specs/en/sdk/sdk-java-impl-spec.md),
185  [Client Runtime Spec](./specs/en/client/client-runtime-spec.md),
186  [Client Connection And Failover Spec](./specs/en/client/client-connection-failover-spec.md),
187  [Client Ability Negotiation Spec](./specs/en/client/client-ability-negotiation-spec.md),
188  [Client Local Cache And Redo Spec](./specs/en/client/client-local-cache-redo-spec.md),
189  [Runtime Push And Reconnect Spec](./specs/en/client/runtime-push-reconnect-spec.md)
190- Domain model:
191  [Config Spec](./specs/en/config/config-spec.md),
192  [Config Resource Spec](./specs/en/config/config-resource-spec.md),
193  [Config Publish And Query Spec](./specs/en/config/config-publish-query-spec.md),
194  [Config Listener And Watch Spec](./specs/en/config/config-listener-watch-spec.md),
195  [Config Gray Release Spec](./specs/en/config/config-gray-release-spec.md),
196  [Config Persistence And History Spec](./specs/en/config/config-persistence-history-spec.md),
197  [Config Consistency, Dump, And Visibility Spec](./specs/en/config/config-consistency-dump-visibility-spec.md),
198  [Config Capacity And Ops Spec](./specs/en/config/config-capacity-ops-spec.md),
199  [Naming Spec](./specs/en/naming/naming-spec.md),
200  [Naming Resource Spec](./specs/en/naming/naming-resource-spec.md),
201  [Naming Instance Lifecycle Spec](./specs/en/naming/naming-instance-lifecycle-spec.md),
202  [Naming Discovery And Subscription Spec](./specs/en/naming/naming-discovery-subscription-spec.md),
203  [Naming Health And Protection Spec](./specs/en/naming/naming-health-protection-spec.md),
204  [Naming Metadata And Selector Spec](./specs/en/naming/naming-metadata-selector-spec.md),
205  [Naming Consistency And Client State Spec](./specs/en/naming/naming-consistency-client-spec.md),
206  [Naming Ephemeral Distro Consistency Spec](./specs/en/naming/naming-ephemeral-distro-consistency-spec.md),
207  [Naming Persistent CP Consistency Spec](./specs/en/naming/naming-persistent-cp-consistency-spec.md),
208  [Naming Ops Spec](./specs/en/naming/naming-ops-spec.md),
209  [AI Registry Spec](./specs/en/ai/ai-registry-spec.md),
210  [AI Resource Model Spec](./specs/en/ai/ai-resource-model-spec.md),
211  [AI Resource Lifecycle Spec](./specs/en/ai/ai-resource-lifecycle-spec.md),
212  [AI Registry Adaptor Spec](./specs/en/ai/ai-registry-adaptor-spec.md),
213  [Agent Management Spec](./specs/en/ai/agent-management-spec.md),
214  [Remote Agent Discovery Protocol Spec](./specs/en/ai/rad-protocol-spec.md),
215  [Agent API Spec](./specs/en/ai/agent-api-spec.md),
216  [Agent Storage Spec](./specs/en/ai/agent-storage-spec.md),
217  [MCP Server Spec](./specs/en/ai/mcp-server-spec.md),
218  [A2A Agent Spec](./specs/en/ai/a2a-agent-spec.md),
219  [Prompt Spec](./specs/en/ai/prompt-spec.md),
220  [Skill Spec](./specs/en/ai/skill-spec.md),
221  [AgentSpec Spec](./specs/en/ai/agentspec-spec.md),
222  [Core Operations Spec](./specs/en/core/core-operations-spec.md),
223  [Console Spec](./specs/en/console/console-spec.md),
224  [Distributed Lock Spec](./specs/en/lock/lock-spec.md)
225- Extension model:
226  [Integration And Adapter Spec](./specs/en/integration/integration-adapter-spec.md),
227  [Plugin Specs](./specs/en/plugin/README.md)
228- Security model:
229  [Auth And Permission Spec](./specs/en/auth/auth-permission-spec.md),
230  [Auth Plugin Spec](./specs/en/auth/auth-plugin-spec.md),
231  [RAM Auth Plugin Spec](./specs/en/auth/ram-auth-plugin-spec.md),
232  [OIDC Auth Plugin Spec](./specs/en/auth/oidc-auth-plugin-spec.md),
233  [Visibility Plugin Spec](./specs/en/auth/visibility-plugin-spec.md),
234  [Default Auth Plugin Implementation Spec](./specs/en/auth/default-auth-plugin-spec.md)
235- Testing model:
236  [API Integration Test Spec](./specs/en/testing/api-integration-test-spec.md),
237  [Java SDK Integration Test Spec](./specs/en/testing/java-sdk-integration-test-spec.md)
238- Shared schemas:
239  [JSON Schema Index](./specs/schemas/README.md)
240 
241Simplified Chinese:
242 
243- 设计基础：
244  [Nacos 设计规范](./specs/zh-cn/design/nacos-design-spec.md)，
245  [资源模型规范](./specs/zh-cn/design/resource-model-spec.md)，
246  [兼容与废弃策略规范](./specs/zh-cn/design/compatibility-deprecation-spec.md)，
247  [基础能力规范](./specs/zh-cn/design/foundation-capabilities-spec.md)，
248  [服务端生命周期与环境配置规范](./specs/zh-cn/design/foundation-server-lifecycle-env-spec.md)，
249  [集群成员规范](./specs/zh-cn/design/foundation-cluster-membership-spec.md)，
250  [远程连接生命周期规范](./specs/zh-cn/design/foundation-remote-connection-spec.md)，
251  [请求过滤与运行时上下文规范](./specs/zh-cn/design/foundation-request-context-spec.md)，
252  [内部 RPC 与集群请求规范](./specs/zh-cn/design/foundation-internal-rpc-spec.md)，
253  [AP 一致性规范](./specs/zh-cn/design/foundation-ap-consistency-spec.md)，
254  [CP 一致性规范](./specs/zh-cn/design/foundation-cp-consistency-spec.md)，
255  [持久化与 Dump 规范](./specs/zh-cn/design/foundation-persistence-dump-spec.md)，
256  [任务执行规范](./specs/zh-cn/design/foundation-task-execution-spec.md)，
257  [事件分发与 NotifyCenter 规范](./specs/zh-cn/design/foundation-event-dispatch-spec.md)，
258  [可观测钩子规范](./specs/zh-cn/design/foundation-observability-hooks-spec.md)，
259  [核心功能规范](./specs/zh-cn/design/core-capabilities-spec.md)
260- 接口模型：
261  [HTTP API 规范](./specs/zh-cn/http-api/api-spec.md)，
262  [鉴权规范](./specs/zh-cn/http-api/authorization-spec.md)，
263  [响应与错误规范](./specs/zh-cn/http-api/response-error-spec.md)，
264  [V3 API 范围](./specs/zh-cn/http-api/v3-api-surface.md)，
265  [gRPC API 规范](./specs/zh-cn/grpc-api/api-spec.md)，
266  [SDK 规范](./specs/zh-cn/sdk/sdk-spec.md)，
267  [Java SDK 实现规范](./specs/zh-cn/sdk/sdk-java-impl-spec.md)，
268  [客户端运行时规范](./specs/zh-cn/client/client-runtime-spec.md)，
269  [客户端连接与故障切换规范](./specs/zh-cn/client/client-connection-failover-spec.md)，
270  [客户端能力协商规范](./specs/zh-cn/client/client-ability-negotiation-spec.md)，
271  [客户端本地缓存与 Redo 规范](./specs/zh-cn/client/client-local-cache-redo-spec.md)，
272  [运行时推送与重连规范](./specs/zh-cn/client/runtime-push-reconnect-spec.md)
273- 领域模型：
274  [Config 规范](./specs/zh-cn/config/config-spec.md)，
275  [Config 资源规范](./specs/zh-cn/config/config-resource-spec.md)，
276  [Config 发布与查询规范](./specs/zh-cn/config/config-publish-query-spec.md)，
277  [Config 监听与 Watch 规范](./specs/zh-cn/config/config-listener-watch-spec.md)，
278  [Config 灰度发布规范](./specs/zh-cn/config/config-gray-release-spec.md)，
279  [Config 持久化与历史规范](./specs/zh-cn/config/config-persistence-history-spec.md)，
280  [Config 一致性、Dump 与可见性规范](./specs/zh-cn/config/config-consistency-dump-visibility-spec.md)，
281  [Config 容量与运维规范](./specs/zh-cn/config/config-capacity-ops-spec.md)，
282  [Naming 规范](./specs/zh-cn/naming/naming-spec.md)，
283  [Naming 资源规范](./specs/zh-cn/naming/naming-resource-spec.md)，
284  [Naming 实例生命周期规范](./specs/zh-cn/naming/naming-instance-lifecycle-spec.md)，
285  [Naming 发现与订阅规范](./specs/zh-cn/naming/naming-discovery-subscription-spec.md)，
286  [Naming 健康检查与保护规范](./specs/zh-cn/naming/naming-health-protection-spec.md)，
287  [Naming 元数据与 Selector 规范](./specs/zh-cn/naming/naming-metadata-selector-spec.md)，
288  [Naming 一致性与客户端状态规范](./specs/zh-cn/naming/naming-consistency-client-spec.md)，
289  [Naming 临时服务 Distro 一致性规范](./specs/zh-cn/naming/naming-ephemeral-distro-consistency-spec.md)，
290  [Naming 持久服务 CP 一致性规范](./specs/zh-cn/naming/naming-persistent-cp-consistency-spec.md)，
291  [Naming 运维规范](./specs/zh-cn/naming/naming-ops-spec.md)，
292  [AI Registry 规范](./specs/zh-cn/ai/ai-registry-spec.md)，
293  [AI 资源模型规范](./specs/zh-cn/ai/ai-resource-model-spec.md)，
294  [AI 资源生命周期规范](./specs/zh-cn/ai/ai-resource-lifecycle-spec.md)，
295  [AI Registry 适配器规范](./specs/zh-cn/ai/ai-registry-adaptor-spec.md)，
296  [Agent 管理规范](./specs/zh-cn/ai/agent-management-spec.md)，
297  [Remote Agent Discovery 协议规范](./specs/zh-cn/ai/rad-protocol-spec.md)，
298  [Agent API 规范](./specs/zh-cn/ai/agent-api-spec.md)，
299  [Agent 存储规范](./specs/zh-cn/ai/agent-storage-spec.md)，
300  [MCP Server 规范](./specs/zh-cn/ai/mcp-server-spec.md)，
301  [A2A Agent 规范](./specs/zh-cn/ai/a2a-agent-spec.md)，
302  [Prompt 规范](./specs/zh-cn/ai/prompt-spec.md)，
303  [Skill 规范](./specs/zh-cn/ai/skill-spec.md)，
304  [AgentSpec 规范](./specs/zh-cn/ai/agentspec-spec.md)，
305  [Core 运维规范](./specs/zh-cn/core/core-operations-spec.md)，
306  [Console 规范](./specs/zh-cn/console/console-spec.md)，
307  [分布式锁规范](./specs/zh-cn/lock/lock-spec.md)
308- 扩展模型：
309  [集成与适配器规范](./specs/zh-cn/integration/integration-adapter-spec.md)，
310  [插件规范](./specs/zh-cn/plugin/README.md)
311- 安全模型：
312  [鉴权与权限规范](./specs/zh-cn/auth/auth-permission-spec.md)，
313  [鉴权插件规范](./specs/zh-cn/auth/auth-plugin-spec.md)，
314  [RAM 鉴权插件规范](./specs/zh-cn/auth/ram-auth-plugin-spec.md)，
315  [OIDC 鉴权插件规范](./specs/zh-cn/auth/oidc-auth-plugin-spec.md)，
316  [可见性插件规范](./specs/zh-cn/auth/visibility-plugin-spec.md)，
317  [默认鉴权插件实现规范](./specs/zh-cn/auth/default-auth-plugin-spec.md)
318- 测试模型：
319  [API 集成测试规范](./specs/zh-cn/testing/api-integration-test-spec.md)，
320  [Java SDK 集成测试规范](./specs/zh-cn/testing/java-sdk-integration-test-spec.md)
321- 共享 Schema：
322  [JSON Schema 索引](./specs/schemas/README.md)
323 
324This section is a quick implementation checklist for agents. If it conflicts
325with the specs, follow the specs and update this checklist.
326 
327### URL Path Patterns
328 
329| API Type | Base Path | Purpose | Example |
330|----------|-----------|---------|---------|
331| **Open API** | `/v3/client/{module}/...` | Client-facing operations | `/v3/client/ns/instance` |
332| **Admin API** | `/v3/admin/{module}/...` | Administrative operations | `/v3/admin/ns/service` |
333| **Console API** | `/v3/console/{module}/...` | Web console operations | `/v3/console/cs/config` |
334| **Auth API** | `/v3/auth/{resource}/...` | Plugin-provided auth operations | `/v3/auth/user` |
335 
336### Module Names
337 
338| Module | Abbreviation | Scope |
339|--------|-------------|-------|
340| Config Service | `cs` | Configuration management |
341| Naming Service | `ns` | Service discovery |
342| Core | `core` | Cluster, namespace management |
343| AI | `ai` | AI resource management |
344| Plugin | `plugin` | Plugin management |
345 
346> **Note**: Auth APIs (`/v3/auth/user`, `/v3/auth/role`, `/v3/auth/permission`) are defined in `plugin-default-impl` module, not in core.
347 
348### HTTP Method Semantics
349 
350| Method | Usage | Idempotent |
351|--------|-------|:----------:|
352| `GET` | Query / Retrieve | Yes |
353| `POST` | Create / Register | No |
354| `PUT` | Update / Modify | Yes |
355| `DELETE` | Remove / Deregister | Yes |
356 
357### Response Format
358 
359**Always** wrap responses in `com.alibaba.nacos.api.model.v2.Result<T>`:
360 
361```json
362{
363  "code": 0,
364  "message": "success",
365  "data": { }
366}
367```
368 
369### Authentication
370 
371**Always** add `@Secured` annotation (`com.alibaba.nacos.auth.annotation.Secured`):
372 
373```java
374@Secured(action = ActionTypes.READ,       // READ or WRITE
375         signType = SignType.CONFIG,       // CONFIG, NAMING, or CONSOLE
376         apiType = ApiType.ADMIN_API)      // OPEN_API, ADMIN_API, or CONSOLE_API
377```
378 
379### API Integration Tests
380 
381For every HTTP API addition, modification, deletion, or deprecation, handle
382`test/openapi-test` before the API change is considered complete:
383 
3841. Read the affected controller, form/request model, validators, service path,
385   response model, exception handling, and matching specs.
3862. Build or update the scenario matrix for expected capability,
387   boundary/validation behavior, and exception/error handling.
3883. Add, update, or remove API IT cases for the changed contract. The goal is API
389   scenario coverage, not line or branch coverage.
3904. Update `test/openapi-test/API_TEST_COVERAGE.md` and the matching
391   `*_API_TEST_SCENARIOS.md` document.
3925. If the functional success path is hard to exercise in standalone IT, at
393   least cover boundary and error scenarios and document the uncovered path.
394 
395### Java SDK Integration Tests
396 
397For every Java SDK public contract change, handle `test/java-sdk-test` before
398the SDK change is considered complete:
399 
4001. Read the public interface, implementation, request/response model, listener
401   path, lifecycle code, exception mapping, and matching SDK/client specs.
4022. Build or update the scenario matrix for factory/lifecycle behavior,
403   expected capability, boundary/validation behavior, listener/subscription
404   behavior, and exception handling.
4053. Add, update, or remove Java SDK IT cases for the changed SDK contract. Assert
406   SDK return values, callbacks, remote side effects, and typed exceptions.
4074. Update `test/java-sdk-test/JAVA_SDK_IT_COVERAGE.md`.
4085. Keep SDK ITs as external-client tests against a standalone Nacos server; do
409   not start Spring or Nacos inside the test class.
410 
411### Controller Example
412 
413```java
414import com.alibaba.nacos.api.model.v2.Result;
415import com.alibaba.nacos.auth.annotation.Secured;
416import com.alibaba.nacos.plugin.auth.constant.ActionTypes;
417import com.alibaba.nacos.plugin.auth.constant.SignType;
418import com.alibaba.nacos.api.common.ApiType;
419 
420@RestController
421@RequestMapping("/v3/admin/ns/service")
422public class ServiceControllerV3 {
423 
424    @PostMapping
425    @Secured(action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)
426    public Result<String> create(ServiceForm serviceForm) throws Exception {
427        serviceForm.validate();
428        // business logic ...
429        return Result.success("ok");
430    }
431 
432    @GetMapping("/list")
433    @Secured(action = ActionTypes.READ, apiType = ApiType.ADMIN_API)
434    public Result<Page<ServiceDetailInfo>> list(ServiceListForm serviceListForm) throws NacosException {
435        serviceListForm.validate();
436        // business logic ...
437        return Result.success(result);
438    }
439}
440```
441 
442## Java Version Targeting
443 
444- **Server modules** (config, naming, core, console, etc.): Java 17+
445- **Client/API/Plugin modules** (api, client, plugin): Java 8+ — ensure backwards compatibility when modifying
446 
447## PR Convention
448 
449All PRs must target the `develop` branch. Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
450 
451**Title format**: `[ISSUE #14122] Add JVM --add-opens options for JDK 17+ compatibility`
452 
453**Pre-submission checklist**:
454```bash
455mvn -B clean package apache-rat:check spotbugs:check -DskipTests
456mvn clean install
457mvn clean test-compile failsafe:integration-test
458```
459 
460## Security Vulnerabilities
461 
462Do NOT report security vulnerabilities via GitHub Issues. Use [ASRC (Alibaba Security Response Center)](https://security.alibaba.com) instead.
463