This module contains example applications that demonstrate how to integrate your services with the Apache ShenYu gateway.

The example modules consume independent 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.

The parent POM (shenyu-examples/pom.xml) defines a property:

<shenyu.client.java.version>2.7.0.3</shenyu.client.java.version>

All shenyu-client-* and shenyu-spring-boot-starter-client-* dependencies in individual example POMs are managed by this property through the <dependencyManagement> section. The version is inherited automatically — individual examples do not specify a <version> for these artifacts.

The released version remains the default so a clean standalone checkout can resolve the client artifacts from Maven Central. To test unreleased MCP fixes, explicitly override this property as described below.

The following dependencies remain internal to this repository (${project.version}):

• shenyu-examples-common — shared example utilities
• shenyu-examples-dubbo-api — Dubbo 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)

Use JDK 17 and run the following commands from the root of this apache/shenyu checkout. Use a checkout containing the MCP fixes: installing an unrelated snapshot from shenyu-client-java does not provide the changes in this repository.

The MCP example uses both the MCP and Spring MVC client starters. Build both starters and their required reactor modules into the local Maven repository:

./mvnw install -pl shenyu-spring-boot-starter/shenyu-spring-boot-starter-client/shenyu-spring-boot-starter-client-mcp,shenyu-spring-boot-starter/shenyu-spring-boot-starter-client/shenyu-spring-boot-starter-client-springmvc -am -DskipTests

Build the MCP example and its shared example utilities using the separate examples reactor:

./mvnw -f shenyu-examples/pom.xml install -pl shenyu-examples-mcp -am \
  -Dshenyu.client.java.version=2.7.2-SNAPSHOT -DskipTests

Before starting the example, configure shenyu-examples/shenyu-examples-mcp/src/main/resources/application.yml for your ShenYu Admin address, credentials, namespace, and reachable service address. Run ShenYu Admin and Bootstrap from a checkout containing the corresponding MCP gateway fixes.

./mvnw -f shenyu-examples/pom.xml spring-boot:run -pl shenyu-examples-mcp \
  -Dshenyu.client.java.version=2.7.2-SNAPSHOT

Keep the same version override for build and run commands. This selects 2.7.2-SNAPSHOT for both starters through the parent dependency management. Check the resolved ShenYu dependencies with:

./mvnw -f shenyu-examples/pom.xml dependency:tree -pl shenyu-examples-mcp \
  -Dshenyu.client.java.version=2.7.2-SNAPSHOT '-Dincludes=org.apache.shenyu:*'

Confirm that the selected MCP and Spring MVC starters and their shared client dependencies use 2.7.2-SNAPSHOT. Then verify that the example registers its upstream and MCP tools in ShenYu Admin and that a tool invocation through the gateway succeeds.

Other examples continue to use the released 2.7.0.3 default and do not require this override.

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.

Build the shenyu-client-java project locally, install the artifacts to your local Maven repository:

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:

# Run from the apache/shenyu repository root; select the example to test.
mvn -f shenyu-examples/pom.xml clean install -pl shenyu-examples-springmvc -am \
  -Dshenyu.client.java.version=2.7.0.1-jdk8-SNAPSHOT

For a more permanent change during development, edit the <shenyu.client.java.version> property in shenyu-examples/pom.xml:

<shenyu.client.java.version>2.7.0.1-jdk8-SNAPSHOT</shenyu.client.java.version>

Note: Locally installed snapshots do not require a remote snapshot repository. If the required snapshot has been published, you can configure the Apache Snapshot Repository in your POM or an active profile in settings.xml (inside <repositories>):

<repository>
    <id>apache-snapshots</id>
    <url>https://repository.apache.org/content/repositories/snapshots/</url>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

If the snapshot has been published to the Apache snapshot repository:

mvn -f shenyu-examples/pom.xml clean install -pl shenyu-examples-springmvc -am \
  -Dshenyu.client.java.version=2.7.0.1-jdk8-SNAPSHOT -U

The -U flag forces Maven to check for updated snapshots. It does not publish missing artifacts or replace the local build required for unpublished fixes.

After updating the client version, verify that the examples can register with a local ShenYu Admin and Bootstrap.

After preparing the client dependencies as described above, install the shared example utilities and their parent POM to your local Maven repository:

cd shenyu-examples
mvn install -pl shenyu-examples-common -am -DskipTests

Run the example from the shenyu-examples reactor root using -pl. The run command uses the internal dependencies installed in the previous step:

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: -pl selects an example but does not build its dependencies. Install the required internal modules before running it. If you used a client version override when building, pass the same override to spring-boot:run.

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)