apache/dubbo-samples: the runnable reference set for Apache Dubbo

What apache/dubbo-samples is for

Apache Dubbo is an RPC framework, and its surface area is large: registries, protocols, serialization, governance rules, Spring and Spring Boot integration. The documentation describes features in prose, but prose does not show a working provider and consumer pair. This repository fills that gap. It contains a number of projects that illustrate various usages of Dubbo from basic to advanced, and the README states that all samples are standard Java, Spring, or Spring Boot applications that can be built and run in the same way as normal applications.

The audience is narrow and specific. If you are evaluating Dubbo and want to see what a service export looks like before you commit, a sample answers that faster than reading the user manual. If you maintain Dubbo itself, the repository doubles as the integration test suite, and the README says as much: it is used for integration tests for dubbo, and readers who are just learning Dubbo do not have to care about that part.

It is not a starter kit and not a library. Nothing here is published as a dependency, and the top-level layout (1-basic, 2-advanced, 3-extensions, 4-governance, 10-task, 11-quickstart) is a curriculum, not an API.

How a sample is structured and how the integration harness drives it

Every sample is a self-contained Maven project with its own provider and consumer classes, its own configuration, and its own README. The repository root pom.xml exists, but the README explicitly warns against using it as the entry point: it is highly NOT recommended to build the entire project from the root directory, as building all samples can take a long time. That warning is the single most useful sentence in the file.

The integration test layer is the more interesting mechanism. It runs on Docker, and the README describes the purpose precisely: to start a dubbo provider instance, and any other supporting systems like registry center if necessary, in docker. Each testable sample carries a case-configuration.yml that declares services. A service of type app runs a main class; a service of type test runs test classes matching a glob. Because containers address each other by service name, the configuration passes registry and provider coordinates as system properties, and waitPortsBeforeRun blocks until the registry and provider ports accept connections. A second file, case-versions.conf, declares which Dubbo, Spring or Spring Boot versions a sample supports, which is how the repository tests the same sample against multiple dependency lines.

Common shapes are factored into templates such as app-builtin-zookeeper.yml and app-external-zookeeper.yml, stored under test/dubbo-scenario-builder/src/main/resources/configs. A sample references a template with a from key and overrides values under props, so a new case is mostly a main class name and two port numbers.

Building and running one sample

Prerequisites are JDK 8 or later, Maven 3.6+, and an external ZooKeeper. The README is explicit that samples do not rely on an embedded ZooKeeper by default, so download and start a standard distribution before running most samples. The command the README gives is the ZooKeeper start script:

bin/zkServer.sh start

Then choose a sample and build it in place. The README uses the Spring Boot basic sample as its example, and this is the sequence it gives:

cd 1-basic/dubbo-samples-spring-boot
mvn clean package

What you should expect is an ordinary Maven build producing a runnable application in that directory's target folder; the README notes that you may need to read each individual README under the sub directories to understand how to build and run a given sample. That is not boilerplate. Samples differ in whether they need ZooKeeper, Nacos, or nothing at all, and the per-sample README is the only place that states which.

If you are working on Dubbo itself rather than learning it, the integration path starts by building the test image:

cd dubbo-samples
./test/build-test-image.sh

A single case then runs by passing its directory:

./test/run-tests.sh 2-advanced/dubbo-samples-annotation

If a container fails to start, the README points at ${project.basedir}/target/logs for the reason.

The external ZooKeeper requirement is the main friction point

The default assumption of an external registry is the biggest practical obstacle. Most samples will not start until ZooKeeper is running somewhere reachable, and the README offers no embedded fallback for local use, only the download-and-start instruction. That is a deliberate choice, and a defensible one, because it keeps samples close to how Dubbo is deployed. It also means the first ten minutes of using this repository are spent on infrastructure rather than on Dubbo.

The integration harness softens this for its own cases: case-configuration.yml files can declare an embedded ZooKeeper inside the provider container, which is why the annotation example passes zookeeper.address as the provider's hostname and zookeeper.port as 2181. But that convenience belongs to the Docker test path, not to someone running a sample from a shell.

A second limitation is version drift. The repository tracks Dubbo 3.2 and 3.3 in its CI badges, and case-versions.conf files record ranges such as dubbo.version=2.7.*, 3.*. Samples are updated alongside the framework, so a sample you copy into your own project can carry configuration that matches a Dubbo line you are not on. The README does not document any migration or compatibility guarantee for the samples themselves, and there are no retrieved releases, so there is nothing to pin against.

Finally, this is the wrong tool if you want a production skeleton. Samples favor the shortest path to a running provider, which means minimal error handling, minimal observability, and configuration chosen for readability. A service that needs retries, timeouts and circuit-breaking configured deliberately will not find that here.

apache/dubbo-samples compared with the Dubbo user manual and dubbo-go-samples

The obvious alternative is the Dubbo User Manual that the README itself suggests cross-referencing. The difference is the direction of the work. The manual explains what a feature does and when to use it; the samples show the minimum viable configuration that makes it run. If you already know which feature you need, the manual is faster. If you know the outcome you want but not the configuration, a sample is faster, because you can read the provider bootstrap class and the properties file side by side.

A second alternative is dubbo-go-samples. The README states that dubbo-go samples are moved to dubbo-go-samples, which means this repository is Java-only in practice. If your provider or consumer is written in Go, this repository will not help you, and the move is worth knowing about because search results still point here for Go material.

A third comparison is against writing a throwaway provider yourself. That is often the right call for a single protocol question, since a minimal Dubbo provider is not much code. The samples win when the question involves a registry, a governance rule, or a Spring Boot integration, because those are the parts where a wrong configuration produces a confusing failure rather than a clear one.

Maintenance, licence and what upgrading costs you

The last push to the default branch was on 2026-05-15, and the repository is not archived. The CI badges in the README track Dubbo 3.2 and 3.3, which tells you the samples are kept in step with current framework lines rather than frozen.

There are no retrieved releases, and that is consistent with what this repository is: a collection of buildable projects rather than a versioned artifact. You cannot depend on it, so there is no upgrade path in the dependency sense. The cost you carry instead is re-reading a sample when Dubbo changes, and checking case-versions.conf to see which framework versions a given sample is expected to work with.

Licensing is Apache-2.0 for the repository, and the README shows the licence badge. Copying a sample into your own codebase is therefore straightforward from a licence standpoint, but the usual obligations apply: keep the licence and notice files, and be aware that a copied sample is your code once you modify it. This is not legal advice; if you are redistributing, read the LICENSE file at the repository root and the .licenserc.yaml that governs headers.

Editorial conclusion

Adopt apache/dubbo-samples if you are learning Dubbo or wiring a Dubbo integration test, and pick a single sub-project rather than the root build. Do not treat it as a dependency or a production template; there is no released artifact and no versioning promise. Before relying on a sample, open its own README, confirm the JDK and Maven versions it expects, and check whether the case configuration points at an embedded or an external ZooKeeper.

Frequently asked questions

Official sources

1. apache/dubbo-samples on GitHub
2. Issues
3. License: Apache-2.0
4. README