Aias00 opened a new issue, #7602: URL: https://github.com/apache/shenyu/issues/7602
## Background Apache ShenYu currently keeps Java client implementation, client starters, client registration repositories, and client-facing examples in the main repository while also maintaining the independent [`apache/shenyu-client-java`](https://github.com/apache/shenyu-client-java) repository. The long-term goal is to make `shenyu-client-java` the owner and release source of business-service client artifacts without introducing a reverse dependency from the main ShenYu repository to the client repository. The dependency direction must remain strictly one-way: ```text shenyu-client-java ↓ released protocol and foundation artifacts from apache/shenyu ``` The main repository, including production code, tests, bootstrap, and retained examples, must not depend on artifacts published by `shenyu-client-java`. The client repository should use the same Java baseline as the main repository. Java 8 / Spring Boot 2 compatibility is out of scope for this migration. The current baseline is Java 17 and Spring Boot 3, with Java 21 compatibility verification aligned with the main repository CI. ## Scope and ownership ### Move to `apache/shenyu-client-java` - `shenyu-client/**` - Business-service client starters under `shenyu-spring-boot-starter-client/**` - `shenyu-register-client-api` - `shenyu-register-client-http` - Client-owned unit and starter tests - Examples that depend on `shenyu-client-*` or `shenyu-spring-boot-starter-client-*` - Client-side compatibility and end-to-end verification against released ShenYu Admin versions ### Keep in the main repository - `shenyu-common` - `shenyu-disruptor` - `shenyu-spi` - `shenyu-register-common` - `shenyu-registry-api` and registry implementations - `shenyu-protocol-*` - Admin registration controllers, publishers, subscribers, and services - `shenyu-register-client-beat` - `shenyu-spring-boot-starter-client-beat` - Bootstrap heartbeat behavior and tests Although the beat modules currently contain `client` in their artifact names, they are used by `shenyu-bootstrap` and belong to the gateway/data-plane runtime rather than the business-service client SDK. ## Main design constraints 1. **No main-to-client dependency** - Remove the Admin production dependency on `shenyu-client-mcp-common`. - Remove the Admin test dependency on `shenyu-client-core`. - Move client-dependent examples out of the main repository. - Do not add a `shenyu.client.java.version` property to the main reactor as a replacement dependency. 2. **Main repository owns the wire protocol** - Extract or define a dependency-light registration protocol artifact in the main repository, tentatively `shenyu-register-protocol`. - The protocol artifact should contain registration DTOs, endpoint constants, protocol version information, capabilities, response contracts, and compatibility fixtures. - It must not depend on Admin, Spring, Disruptor, or client implementation code. - Existing DTO package names may be retained during extraction to avoid unnecessary source and binary incompatibility. 3. **Client releases may lag behind main releases** - Compatibility must not depend on coordinated releases. - Existing clients without an explicit protocol header must be treated as protocol v1. - Add registration protocol and client version headers, for example: ```http X-Shenyu-Register-Protocol-Version: 1 X-Shenyu-Client-Version: 2.7.x ``` - Additive changes within a protocol version must remain optional and defaultable. - Breaking field, endpoint, type, enum, or semantic changes require a new protocol version and a transition period where Admin accepts both versions. 4. **Compatibility tests must not import client classes in main** - Main-repo tests should replay versioned raw JSON fixtures through Admin controllers and services. - Client-repo tests should verify generated requests against the published protocol artifact and released Admin images. - Cross-repository E2E workflows belong to the client repository or an external compatibility workflow, not the main reactor. ## Priority and implementation plan ### P0 — Freeze dependency direction and module ownership - [ ] Approve the one-way dependency rule: `shenyu-client-java -> apache/shenyu` only. - [ ] Confirm the move/keep module inventory above. - [ ] Confirm that Java 8 compatibility is out of scope. - [ ] Confirm that beat and beat starter remain in the main repository. - [ ] Inventory all client-facing examples that must move. ### P1 — Establish the versioned registration protocol in main - [ ] Complete the compatibility contract tracked by #6365. - [ ] Create or extract the registration protocol artifact in the main repository. - [ ] Move endpoint constants and wire DTO ownership into the protocol boundary. - [ ] Add `X-Shenyu-Register-Protocol-Version` handling with absent header defaulting to v1. - [ ] Add optional client version and capability reporting. - [ ] Define required, optional, deprecated, and defaulted fields. - [ ] Define the supported protocol/client version window. - [ ] Add v1 JSON fixtures for metadata, URI, API docs, discovery config, MCP tools, offline, and heartbeat flows. ### P2 — Remove reverse client dependencies from main - [ ] Refactor `SwaggerImportServiceImpl` so it no longer imports MCP DTOs or generators from `shenyu-client-mcp-common`. - [ ] Move annotation-independent MCP models/generation logic to a main-owned protocol or register module. - [ ] Remove the production dependency on `shenyu-client-mcp-common` from `shenyu-admin`. - [ ] Rewrite `ZookeeperClientDiscoveryIntegrationTest` to register an `InstanceEntity` through main-owned registry APIs instead of client listeners. - [ ] Remove the test dependency on `shenyu-client-core` from `shenyu-admin`. - [ ] Verify that no main production or test source imports `org.apache.shenyu.client.*`. ### P3 — Rebaseline and migrate client implementation - [ ] Rebaseline `apache/shenyu-client-java` on Java 17 and Spring Boot 3. - [ ] Replace the old JDK8-adapted implementation with the current main-repo client implementation. - [ ] Remove duplicated `shenyu-registry-api` ownership from the client repository. - [ ] Remove JDK8-only copied common/register/timer/DTO implementations. - [ ] Do not restore Motan support that has already been removed from the main repository. - [ ] Move client API/HTTP registration repositories and their tests. - [ ] Move business-service client starters, excluding beat starter. - [ ] Preserve all client unit, lifecycle, retry, shutdown, annotation, protocol, and starter tests. ### P4 — Move client-facing examples - [ ] Move examples that depend on `shenyu-client-*` or client starters to `apache/shenyu-client-java`. - [ ] Keep gateway/plugin/server-side examples in the main repository. - [ ] Allow moved examples to depend on released SDK/protocol artifacts from the main repository. - [ ] Ensure the main examples reactor no longer resolves client-repository artifacts. ### P5 — Compatibility CI and release sequencing - [ ] Implement the cross-repo compatibility strategy tracked by #6367. - [ ] Execute the independent verification tracked by #6366. - [ ] Run client tests on Java 17 and the same Java 21 compatibility lane used by the main repository. - [ ] Test the current client against supported released Admin versions. - [ ] Test the current Admin against committed fixtures from supported older protocol/client versions. - [ ] Define the release order: main protocol/foundation release first, client release second, main source removal last. - [ ] Provide a rollback procedure that does not require the main repository to depend on client artifacts. ### P6 — Remove migrated source and finalize documentation - [ ] Remove migrated client modules from the main reactor only after the external artifacts and compatibility CI are ready. - [ ] Remove migrated client starter modules from the main starter reactor. - [ ] Remove migrated client-facing examples from the main examples reactor. - [ ] Keep beat modules and bootstrap heartbeat dependencies in main. - [ ] Update contribution and release documentation under #6373. - [ ] Document which repository owns each client, protocol, registry, beat, and example change. ## Compatibility rules Within one protocol version: - New fields must be optional. - Missing fields must have backward-compatible defaults. - Unknown fields must be ignored. - Existing field types and semantics must not change. - Existing enum values must not be removed or renamed. - Existing endpoint paths, methods, authentication behavior, and success responses must remain compatible. Breaking changes require a new protocol version and an explicit dual-support window. ## Acceptance criteria - [ ] The main repository has no production, test, bootstrap, or retained-example dependency on `shenyu-client-java` artifacts. - [ ] No main source or test imports `org.apache.shenyu.client.*`. - [ ] `shenyu-client-java` depends only on released main-repo protocol/foundation artifacts. - [ ] Registration protocol v1 is documented and covered by versioned JSON fixtures. - [ ] Current Admin accepts all client versions within the declared support window. - [ ] Client modules and client-facing examples build independently on Java 17. - [ ] Java 21 compatibility verification matches the main repository policy. - [ ] Beat and bootstrap heartbeat behavior remain buildable and tested in main. - [ ] No artifact coordinate is published by both repositories. - [ ] Source removal occurs only after client artifacts, compatibility tests, and rollback documentation are available. ## Related issues - #6365 — Define the client-admin registration protocol compatibility contract - #6366 — Verify independent Java client against main repo admin/bootstrap - #6367 — Add cross-repo compatibility test strategy - #6373 — Document the split-client migration and contribution workflow ## Estimated effort The current estimate is approximately 24–34 person-days, including protocol extraction/versioning, reverse-dependency removal, client and example migration, compatibility fixtures, CI, and release documentation. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
