Spring Cloud Tencent: one starter per concern, and a version number with two parts

One starter per concern, and an all-in-one starter too

The module list at the repository root is the API surface, and it is organised by the problem rather than by layer.

There is a starter for service discovery, one for authentication, one for rate limiting, one for routing, one for circuit breaking, one for configuration, and one for contracts. Alongside them are a starter that transfers metadata between components, a starter that bundles several of them together, and a starter set meant for building plugins rather than applications.

Underneath sit the pieces those starters share: a commons module, a module holding the Polaris context, a module enhancing remote calls, a coverage module, the dependencies module that acts as the managed version list, and an examples module.

Two naming details are worth internalising. Every user-facing module is named as a starter, which is Spring's word for a module that brings its own transitive dependencies so you do not have to assemble them, and the aggregation module is named with an all suffix, so taking everything is one decision rather than eight.

So the adoption question is not whether to use the framework but which starters you want, and the all starter exists for the teams who would rather not decide.

The version number encodes two things

Look at the release tags and you will see four numbers where most projects have three.

A recent tag reads as a project version, then a dash, then a Spring Cloud release train. The repository's default branch is named after that release train rather than for a master or main, which tells you that this is a train rather than a single line of development.

The consequence is that compatibility is negotiated, not inherited. If you are on one Spring Cloud train and the framework has a version for it, you use that one. A second release in the same snapshot goes to a much older train, which tells you that older trains still receive maintenance and that the project is not simply following the newest one.

And here is the part that costs people an afternoon: the readme does not contain the version list. It points at a wiki page on version management and tells you to take the value from there, and the example dependency uses a placeholder where the version goes. So the repository you are reading cannot tell you what to write in your build file.

That is a real friction point in an otherwise conventional setup, and it is deliberate, because the mapping from Spring Cloud trains to framework versions changes more often than a Maven coordinate does.

Polaris is the surface, and it maps to four problems

The integration story is one system. Spring Cloud Tencent plugs into Polaris, an open source service discovery and governance project, and the documentation lists the four problem groups it claims to solve.

Service management covers discovery, the registry itself, and health checks. Traffic control covers customizable routing, load balancing, rate limiting and access control. Fault tolerance is circuit breaking, and the granularity is stated: a breaker per service, per interface, and per instance. Configuration management covers version control of configuration, grayscale release, and dynamic update.

Two things follow from the granularity and from the configuration group. Per instance breakers are more precise than a single breaker per service, which matters when one backend node is unhealthy. And dynamic configuration update with grayscale release is a different operational model from restarting clients to pick up a change, which is the part teams tend to care about most in a running system.

The framework's claim is that it implements the standard Spring Cloud extension interface rather than asking applications to wire to its own types, which is what makes the starters replaceable.

The dependency snippet imports a list, not artifacts

The usage section is one snippet, and its shape is the important part.

It begins with a dependency management block containing a single import of the framework's dependencies module, declared as a pom with import scope. That is the standard way to publish a managed version list: you import it once and every starter you then declare comes with a version you did not write.

The snippet then shows the second half, a normal dependency declaration for one starter, in this case discovery, using a group identifier under the project's own namespace. The readme notes that every component is on the Maven central repository, so nothing else is required: no repository configuration, no local build.

And the version in the import is a placeholder, with the readme telling you to substitute the value from the wiki page. So the snippet is a template rather than something you can paste unchanged, which is a slightly awkward first experience for something whose whole premise is ease of dependency management.

The build is one wrapper command, and the wrapper is committed

The build instructions are two commands, one per platform family.

On Linux and a Mac you run the wrapper directly with a clean and package goal. On Windows you run the command script version. Both are the Maven wrapper, and both the Unix script and the Windows script are committed to the repository along with the wrapper's own configuration directory.

Committing the wrapper is the right call for a project with this many contributors, because it pins the build tool rather than trusting whatever Maven is installed.

On Linux and a Mac:

./mvnw clean package

and on Windows the command script equivalent. It also means a contributor needs no Java build tool on the machine, only a JDK.

The quality signals sit next to the licence badge in the readme: a workflow badge for a unit test job, and a coverage badge pinned to the branch matching the current release train rather than to a default branch. That last detail is the one that tells you the coverage number on the readme is about the code you are actually looking at.

The example environment is one shared public server

The examples section publishes a working environment, and the first thing to notice about it is that it is shared and public.

Two addresses are given: a console on a plain web port, and a registry server on a gRPC port, both on a bare IP address rather than a hostname. The examples themselves default to that same registry address, so a clone-and-run does not require any setup at all.

That is generous for evaluation and wrong for anything else. There is no per-user namespace, no mention of authentication, and nothing in the documentation suggesting the instance is isolated. Anything you push into it is visible to anyone else using the same environment, and it can be reset by the maintainers at any time.

So the practical reading is: use it to click through the starters, then point the same configuration at your own Polaris deployment before you build anything. The address in the readme is a convenience, not a dependency, and the documentation does not ask you to treat it as anything more.

changes/ holds the fragments, and the licence badge disagrees with the metadata

A few repository details that tell you how the project is run.

There is a directory for changes, beside a changelog file at the root. The convention is the fragment one: each change adds a file describing itself, and the assembled changelog is generated. That keeps the changelog from becoming the file two contributors always conflict on.

There is a licence header configuration file, which means source files are expected to carry a licence header and something checks it. The readme carries a badge for the three clause BSD licence.

And here is the small inconsistency: the repository metadata does not resolve a recognised licence identifier, while the badge points at a specific licence and the tree contains both a licence file and a header checker. So the licensing is stated in three places and machine-readable in none of them. If you need a licence identifier for a compliance scanner, read the file rather than the badge.

There are two readmes, English and Chinese, and a contributor guide, a code of conduct, and a change log alongside. Support is a chat group you join by scanning a QR code and sending a message, which is the one part of the process that assumes you have a phone.

Editorial conclusion

Use Spring Cloud Tencent if you run Spring Cloud, need service discovery and governance, and want those capabilities wired to Polaris rather than to a cloud vendor registry. The module layout means you adopt one starter per concern instead of the whole set, and the dependency import gives you a managed version across all of them. Do not adopt it because it is a Tencent product if you have no reason to be in that ecosystem, since the only hard dependency named in the documentation is the registry. Before you start, note two things: the version you use is not discoverable from the readme but from a wiki page, and the published example environment is a shared public server, so use it for evaluation and never for anything you would mind losing.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. Tencent/spring-cloud-tencent on GitHub