diff --git a/shenyu-examples/README.md b/shenyu-examples/README.md new file mode 100644 index 000000000000..56b8312a92e2 --- /dev/null +++ b/shenyu-examples/README.md @@ -0,0 +1,133 @@ +# ShenYu Examples + +This module contains example applications that demonstrate how to integrate your services with the Apache ShenYu gateway. + +## Client Dependencies + +The example modules now consume **independent [shenyu-client-java](https://github.com/apache/shenyu-client-java) artifacts** from Maven Central, rather than depending on in-tree source modules from the main `apache/shenyu` repository. + +This reflects the recommended approach for real users: add the ShenYu client library as an external Maven dependency. + +### How It Works + +The parent POM (`shenyu-examples/pom.xml`) defines a property: + +```xml +2.7.0.3 +``` + +All `shenyu-client-*` and `shenyu-spring-boot-starter-client-*` dependencies in individual example POMs are managed by this property through the `` section. The version is inherited automatically — individual examples do not specify a `` for these artifacts. + +### Which Artifacts Are Consumed Externally + +| Client Artifact | Used By | +|----------------|---------| +| `shenyu-client-springmvc` | `shenyu-examples-springmvc`, `shenyu-examples-springmvc-tomcat` | +| `shenyu-spring-boot-starter-client-springmvc` | `shenyu-examples-http`, `shenyu-examples-http-swagger3`, `shenyu-examples-https`, `shenyu-examples-springcloud`, `shenyu-examples-websocket` (native), `shenyu-examples-mcp`, `shenyu-examples-sdk-http`, `shenyu-examples-sdk-feign` | +| `shenyu-spring-boot-starter-client-grpc` | `shenyu-examples-grpc` | +| `shenyu-spring-boot-starter-client-apache-dubbo` | `shenyu-examples-apache-dubbo-service`, `shenyu-examples-apache-dubbo-service-annotation` | +| `shenyu-client-apache-dubbo` | `shenyu-examples-apache-dubbo-service-xml`, `shenyu-examples-sdk-apache-dubbo-provider` | +| `shenyu-spring-boot-starter-client-tars` | `shenyu-examples-tars` | +| `shenyu-spring-boot-starter-client-sofa` | `shenyu-examples-sofa-service` | +| `shenyu-spring-boot-starter-client-spring-websocket` | `shenyu-examples-websocket` (annotation, native, reactive) | +| `shenyu-spring-boot-starter-client-mcp` | `shenyu-examples-mcp` | + +### Internal Example Dependencies + +The following dependencies remain internal to this repository (`${project.version}`): + +- `shenyu-examples-common` — shared example utilities +- `shenyu-examples-dubbo-api` — Dubbo API definitions +- `shenyu-examples-sofa-api` — Sofa API definitions +- `shenyu-sdk-*` — ShenYu SDK modules (not extracted to shenyu-client-java) +- `shenyu-spring-boot-starter-sdk-*` — ShenYu SDK starters (not extracted to shenyu-client-java) + +## Testing with Unreleased Client Artifacts + +When developing or testing changes to the `shenyu-client-java` library, you may need to build the client artifacts locally and use them in these examples. + +### Option 1: Override the Version via Command Line + +Build the `shenyu-client-java` project locally, install the artifacts to your local Maven repository: + +```bash +git clone https://github.com/apache/shenyu-client-java.git +cd shenyu-client-java +mvn clean install -DskipTests +``` + +This installs the artifacts with the project's snapshot version (e.g., `2.7.0.1-jdk8-SNAPSHOT`). Then, build the examples using that version: + +```bash +cd shenyu +mvn clean install -pl shenyu-examples -Dshenyu.client.java.version=2.7.0.1-jdk8-SNAPSHOT +``` + +### Option 2: Modify the Property in Parent POM + +For a more permanent change during development, edit the `` property in `shenyu-examples/pom.xml`: + +```xml +2.7.0.1-jdk8-SNAPSHOT +``` + +> **Note**: When using `-SNAPSHOT` versions, you may need to configure the Apache Snapshot Repository in your `settings.xml` or POM: +> ```xml +> +> apache-snapshots +> https://repository.apache.org/content/repositories/snapshots/ +> +> true +> +> +> ``` + +### Option 3: Use Maven `-U` Flag for Latest Snapshots + +If the snapshot has been published to the Apache snapshot repository: + +```bash +mvn clean install -pl shenyu-examples -Dshenyu.client.java.version=2.7.0.1-jdk8-SNAPSHOT -U +``` + +The `-U` flag forces Maven to check for updated snapshots. + +## Verification + +After updating the client version, verify that the examples can register with a local ShenYu Admin and Bootstrap. + +### Prerequisites + +Before running any example, install the shared example utilities to your local Maven repository: + +```bash +cd shenyu-examples +mvn install -pl shenyu-examples-common -DskipTests +``` + +### Run Examples + +Run the example from the `shenyu-examples` reactor root using `-pl` so internal dependencies like `shenyu-examples-common` are resolved automatically: + +```bash +cd shenyu-examples + +# Spring MVC HTTP example +mvn spring-boot:run -pl shenyu-examples-springmvc + +# Or other protocol examples: +# mvn spring-boot:run -pl shenyu-examples-grpc +# mvn spring-boot:run -pl shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service +# mvn spring-boot:run -pl shenyu-examples-websocket/shenyu-example-spring-annotation-websocket +# mvn spring-boot:run -pl shenyu-examples-mcp +``` + +> **Note**: Running `mvn spring-boot:run` directly from within an individual example directory (e.g., `cd shenyu-examples-springmvc && mvn spring-boot:run`) will fail because `shenyu-examples-common` and the parent POM cannot be resolved outside the reactor. Always use the `-pl` approach from the `shenyu-examples/` root. + +### Confirm Registration + +After the application starts: + +1. Open the ShenYu Admin console (default: `http://localhost:9095`) +2. Check that the service appears under **Divide** (for HTTP), **Dubbo**, **gRPC**, or the respective plugin list +3. Verify API calls can be proxied through the ShenYu gateway (default: `http://localhost:9195`) diff --git a/shenyu-examples/pom.xml b/shenyu-examples/pom.xml index 51f44b4dcfbd..8990b04599ee 100644 --- a/shenyu-examples/pom.xml +++ b/shenyu-examples/pom.xml @@ -39,6 +39,7 @@ 0.40.1 3.4.0 2.6.0 + 2.7.0.3 @@ -66,6 +67,52 @@ springdoc-openapi-starter-webmvc-ui ${swagger.version} + + + org.apache.shenyu + shenyu-client-springmvc + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-client-apache-dubbo + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-spring-boot-starter-client-springmvc + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-spring-boot-starter-client-grpc + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-spring-boot-starter-client-apache-dubbo + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-spring-boot-starter-client-tars + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-spring-boot-starter-client-sofa + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-spring-boot-starter-client-spring-websocket + ${shenyu.client.java.version} + + + org.apache.shenyu + shenyu-spring-boot-starter-client-mcp + ${shenyu.client.java.version} + diff --git a/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-annotation/pom.xml b/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-annotation/pom.xml index 355c0f23f3ed..9a399856043e 100644 --- a/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-annotation/pom.xml +++ b/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-annotation/pom.xml @@ -31,7 +31,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-apache-dubbo - ${project.version} diff --git a/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-xml/pom.xml b/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-xml/pom.xml index ae3ca54877ce..9b853fc5277b 100644 --- a/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-xml/pom.xml +++ b/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service-xml/pom.xml @@ -30,7 +30,6 @@ org.apache.shenyu shenyu-client-apache-dubbo - ${project.version} diff --git a/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service/pom.xml b/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service/pom.xml index d1864b1011f8..39e8c8084faa 100644 --- a/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service/pom.xml +++ b/shenyu-examples/shenyu-examples-dubbo/shenyu-examples-apache-dubbo-service/pom.xml @@ -31,7 +31,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-apache-dubbo - ${project.version} diff --git a/shenyu-examples/shenyu-examples-grpc/pom.xml b/shenyu-examples/shenyu-examples-grpc/pom.xml index 9852afee87e1..1efbe47a602a 100644 --- a/shenyu-examples/shenyu-examples-grpc/pom.xml +++ b/shenyu-examples/shenyu-examples-grpc/pom.xml @@ -53,7 +53,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-grpc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-http-swagger3/pom.xml b/shenyu-examples/shenyu-examples-http-swagger3/pom.xml index c7faf46d4edd..8b6eb8c4839b 100644 --- a/shenyu-examples/shenyu-examples-http-swagger3/pom.xml +++ b/shenyu-examples/shenyu-examples-http-swagger3/pom.xml @@ -37,7 +37,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-http/pom.xml b/shenyu-examples/shenyu-examples-http/pom.xml index 2bbbd04fd818..5f4871f30e78 100644 --- a/shenyu-examples/shenyu-examples-http/pom.xml +++ b/shenyu-examples/shenyu-examples-http/pom.xml @@ -37,7 +37,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-https/pom.xml b/shenyu-examples/shenyu-examples-https/pom.xml index 96c6418d90ae..82d742a3468b 100644 --- a/shenyu-examples/shenyu-examples-https/pom.xml +++ b/shenyu-examples/shenyu-examples-https/pom.xml @@ -31,7 +31,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-mcp/pom.xml b/shenyu-examples/shenyu-examples-mcp/pom.xml index 9ec4a4292cd4..c2064a0f0ffd 100644 --- a/shenyu-examples/shenyu-examples-mcp/pom.xml +++ b/shenyu-examples/shenyu-examples-mcp/pom.xml @@ -53,13 +53,11 @@ org.apache.shenyu shenyu-spring-boot-starter-client-mcp - ${project.version} org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-dubbo/shenyu-examples-sdk-apache-dubbo-provider/pom.xml b/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-dubbo/shenyu-examples-sdk-apache-dubbo-provider/pom.xml index 658b013fdd72..c4b7f9cb88d2 100644 --- a/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-dubbo/shenyu-examples-sdk-apache-dubbo-provider/pom.xml +++ b/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-dubbo/shenyu-examples-sdk-apache-dubbo-provider/pom.xml @@ -37,7 +37,6 @@ org.apache.shenyu shenyu-client-apache-dubbo - ${project.version} diff --git a/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-feign/pom.xml b/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-feign/pom.xml index ed1182cb54df..d581451e1552 100644 --- a/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-feign/pom.xml +++ b/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-feign/pom.xml @@ -58,7 +58,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-http/pom.xml b/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-http/pom.xml index 752e96de26f1..91a70f3d9764 100644 --- a/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-http/pom.xml +++ b/shenyu-examples/shenyu-examples-sdk/shenyu-examples-sdk-http/pom.xml @@ -68,7 +68,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-sofa/shenyu-examples-sofa-service/pom.xml b/shenyu-examples/shenyu-examples-sofa/shenyu-examples-sofa-service/pom.xml index 932cb13ad4ad..9e6f6e4bfafe 100644 --- a/shenyu-examples/shenyu-examples-sofa/shenyu-examples-sofa-service/pom.xml +++ b/shenyu-examples/shenyu-examples-sofa/shenyu-examples-sofa-service/pom.xml @@ -217,7 +217,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-sofa - ${project.version} guava diff --git a/shenyu-examples/shenyu-examples-springcloud/pom.xml b/shenyu-examples/shenyu-examples-springcloud/pom.xml index 01bdad2e4eb6..c98605fdad43 100644 --- a/shenyu-examples/shenyu-examples-springcloud/pom.xml +++ b/shenyu-examples/shenyu-examples-springcloud/pom.xml @@ -37,7 +37,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-springmvc-tomcat/pom.xml b/shenyu-examples/shenyu-examples-springmvc-tomcat/pom.xml index 1c48955717da..5725c72a824e 100644 --- a/shenyu-examples/shenyu-examples-springmvc-tomcat/pom.xml +++ b/shenyu-examples/shenyu-examples-springmvc-tomcat/pom.xml @@ -37,7 +37,6 @@ org.apache.shenyu shenyu-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-springmvc/pom.xml b/shenyu-examples/shenyu-examples-springmvc/pom.xml index f4f0d9783c61..55ca95043bc6 100644 --- a/shenyu-examples/shenyu-examples-springmvc/pom.xml +++ b/shenyu-examples/shenyu-examples-springmvc/pom.xml @@ -37,7 +37,6 @@ org.apache.shenyu shenyu-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-tars/pom.xml b/shenyu-examples/shenyu-examples-tars/pom.xml index 53fdc9f0e6e8..bad97977fec3 100644 --- a/shenyu-examples/shenyu-examples-tars/pom.xml +++ b/shenyu-examples/shenyu-examples-tars/pom.xml @@ -47,7 +47,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-tars - ${project.version} diff --git a/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-annotation-websocket/pom.xml b/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-annotation-websocket/pom.xml index 77803f3a9018..4ada6bdef0e3 100644 --- a/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-annotation-websocket/pom.xml +++ b/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-annotation-websocket/pom.xml @@ -30,7 +30,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-spring-websocket - ${project.version} diff --git a/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-native-websocket/pom.xml b/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-native-websocket/pom.xml index 8e2412e1323a..6f73835b7698 100644 --- a/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-native-websocket/pom.xml +++ b/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-native-websocket/pom.xml @@ -31,13 +31,11 @@ org.apache.shenyu shenyu-spring-boot-starter-client-spring-websocket - ${project.version} org.apache.shenyu shenyu-spring-boot-starter-client-springmvc - ${project.version} diff --git a/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-reactive-websocket/pom.xml b/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-reactive-websocket/pom.xml index 98fc43c02825..3522d4d34b0e 100644 --- a/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-reactive-websocket/pom.xml +++ b/shenyu-examples/shenyu-examples-websocket/shenyu-example-spring-reactive-websocket/pom.xml @@ -32,7 +32,6 @@ org.apache.shenyu shenyu-spring-boot-starter-client-spring-websocket - ${project.version}