apache/incubator-seata-samples: four transaction protocols, four runnable services

Four directories, and they are the four transaction modes

The whole content of this repository can be described in one listing. The second layer of the directory structure is four directories, and they are named after Seata's transaction modes:

at-sample
tcc-sample
saga-sample
xa-sample

Everything below that layer is a variation on the same demo, one directory per framework and configuration combination, and the third layer is described as the specific sample. So this is not a library repository that happens to contain examples. It is a taxonomy. A distributed transaction library gives you four ways to coordinate a commit across services, and those choices differ in what they demand of your code: some need a proxy in the path, some need you to write confirm and cancel logic, some need a compensation handler, and some need a resource that speaks the two-phase protocol. That difference is invisible in documentation and obvious in code, and running the same business scenario four ways is the way to see it. There is a fifth directory, saga-annotation-sample, which sits alongside the others and suggests an annotation-driven variant of one of the modes. So if you are evaluating which protocol to adopt, the honest reading of this repository is that it is a comparison harness: four implementations of one scenario, differing only in the coordination strategy.

The dependency rule inverts what a parent pom exists for

There is one engineering decision in this README, and it is stated as a single sentence in the dependency section. The dependencies of each sample should be independent and should not depend on the dependencies of the parent pom of the samples. That is the opposite of the usual reason a parent pom exists, which is to centralise versions and inherit dependencies so a project has one place to change. Here the parent pom is deliberately kept out of the dependency graph. The reason the choice makes sense is that a sample is meant to be copied. If a sample's pom inherits from a parent, then lifting that sample into your own project drags in a parent pom you would have to vendor, or you have to unpick the inheritance and resolve the versions yourself, which defeats the point of a self-contained example. Independence means the directory can be moved into an application, its pom dropped in, and the versions it names are the versions you get. The cost is exactly the benefit's mirror image. With no shared dependency management, a version that needs updating is updated in every sample rather than once, and the samples will drift apart over time. Nothing in the repository prevents that, because the rule removes the mechanism that would have caught it. For a samples repository that is a reasonable trade, since the examples are meant to be individually instructive rather than collectively consistent. The rule is worth knowing before you spend an afternoon wondering why your copy of a sample does not build.

Sample names encode the stack, and the README misspells its own example

The naming convention is the only navigation aid in a tree that will eventually hold dozens of directories. Names are built with the framework in them, and the two examples given are a Spring variant with Nacos and a Spring Boot variant with a second configuration component, written as spring-nacos-seata and springboot-naocs-zk-seata. So a name tells you three things before you open anything: the web framework, the service discovery or configuration component, and the fact that it is a Seata sample. That is a good convention, because in a samples repository the directory name is the documentation. There is a small catch. The second example in the README misspells the configuration component, with the letters transposed, so a reader who searches the tree using the example from the README will not find a match. That is a trivial defect with a real cost, because the convention is documented in exactly one place, in one line, and that line is the entry point. Read the tree itself for the real spellings rather than trusting the example. The convention also tells you what the sample population looks like. Samples are organised by integration stack rather than by use case, which is the right axis for this project, since the question a reader has is usually how do I use Seata with the framework I already have, not what is an interesting scenario.

Four services, a fixed start order, and a domain you have to learn first

The only instructions for running anything are four words, given as a numbered start sequence. The services are account, then storage, then order, then business. Read that as a domain model for the canonical distributed transaction problem rather than as a list of modules. Account is one service holding a balance, storage is another holding inventory, order is the one that wants both, and business is the orchestrating service that calls into them. The order is a dependency order, not an alphabetical one, and it matters: you start the leaves before the service that depends on them, and business goes last because it is the coordinator. Four JVMs, one fixed sequence, and no instructions in the repository for configuration, ports or the middleware the samples expect, so the model documentation link is where those details live. That link is the samples transaction model reference on the Seata site, and it is the entire conceptual documentation in this repository. Which is the honest shape of a samples project: the scenarios are here, the explanation is on the website, and the connection between them is a URL. The practical consequence for an evaluator is that the first run of any sample is a debugging session, not a demonstration.

An e2e-test directory is why the examples can be trusted

Most samples repositories are documentation that happens to be executable, and the usual failure mode is an example that no longer compiles against the library it illustrates. This one has an e2e-test directory at the top level, next to the four sample directories and a style directory, which means there is somewhere for automated tests that run the scenarios end to end. For a repository whose entire value is that its examples work, that directory is the most important entry in the listing, because it converts the samples from a claim into a checked property. It also implies a cost: a samples repository with end-to-end tests needs the services, the middleware and the build wired into continuous integration, which is why there is a .github directory and a .travis.yml, the older continuous integration service, sitting together. Having both is normal in a project that migrated rather than switched, and it is a small signal about how the automation is actually maintained. The style directory alongside it is a formatting convention, and there is a .licenserc.yaml, which is a licence header checker, so contributions are checked for the required header before they land. For an incubator project, that is a reasonable amount of process around what is otherwise a directory of demos.

Two contribution guides and no releases

Two other details frame what this repository is. There are two contribution guides, CONTRIBUTING.md and CONTRIBUTING_CN.md, so the process is documented in English and Chinese, which for a project originating in China and hosted by a foundation is the arrangement you would expect and worth crediting. And there are no GitHub releases at all, with the last push on 2026-07-27, so the repository is not archived and the work continues, but there is no tagged version of the sample set. For a samples repository that is a much smaller problem than it would be for a library, because you are expected to read master rather than depend on a pinned artefact. The repository name also carries a piece of history: it is under the incubator-seata-samples path, and the README title names the project as incubating. The incubator prefix in the path is the older naming convention for the incubation phase, and it will change when the project graduates. Nothing in the tree depends on the name, but if you script anything against these paths, expect them to move. The governance files around it are the standard set, with a NOTICE, a LICENSE, a DISCLAIMER and an .asf.yaml for the foundation metadata.

What the samples are for, and the decision they exist to inform

The useful way to read this repository is as a decision tool. Seata offers several coordination strategies for a distributed transaction and they differ in what they require from your application. One is largely automatic from the caller's point of view, one asks you to write and expose confirm and cancel operations, one expects you to define compensating actions for a business process that spans services and time, and one requires the participants to speak a two-phase protocol. That taxonomy is not explained in this README, and the repository should not be blamed for it, because the model documentation is one link away. What the samples do is show the same four-service business case, account buying from storage and order and business coordinating, in each strategy. So the evaluation question is not which one is best, because the answer depends on whether you can accept an extra round trip, whether you can write compensation logic, and whether your databases participate in a distributed transaction. The samples answer the second-order question that documentation never does: how much code do I have to write, and where does it go. Copy the two or three candidates into a scratch project, run the same scenario, and read the diffs between the four. That is a day of work, and it is what the repository is for.

Editorial conclusion

Use this repository to choose, not to depend on it. It contains no library, and its value is that the same business case appears once per transaction mode, which is the fastest way to see what each protocol asks of your application code. Do not add it as a dependency or expect it to explain anything, because the README is a naming specification and points to the quickstart page for what the modes actually are. Two things to check when you arrive. The four services in the demo have to be started in the documented order, account then storage then order then business, which means four processes and a fixed sequence before you can see anything happen. And the independence rule cuts both ways: each sample's pom deliberately avoids inheriting from the parent, so a sample copies cleanly into another project but no version is managed centrally, and drift between samples is a maintenance cost you accept rather than a bug. The e2e-test directory is the reason to trust the examples, since it implies these samples run in CI rather than being aspirational snippets.

Frequently asked questions

Official sources

1. apache/incubator-seata-samples on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README