smart-cloud: a Spring Cloud scaffold built out of opinionated starters

Merge first, split later, and switch with a build change

The design decision that distinguishes smart-cloud from a generic Spring Cloud starter collection is the split-and-merge story.

The stated problem is that splitting microservices early is expensive, while splitting them late means the running system cannot carry the load. The project's answer is to let a team start with services merged by business domain, deployed as one unit, which saves machines. When a domain grows enough to need its own deployment, the same code is split out. While merged, the calls are in-process; once split, they become Feign RPC. The documentation says the switch is one line of the pom file.

That framing is aimed at teams with uneven traffic across domains, where a single large service is a reasonable starting point. It also pushes back on the usual criticism of microservice scaffolding, which is that the assembly is locked in from the first commit.

The stack underneath is the mainstream Chinese Spring Cloud line: Spring Boot, Spring Cloud Gateway as the service gateway, Nacos for service registration and configuration, OpenFeign for declarative RPC, Sentinel for rate limiting and circuit breaking, MyBatis with MyBatis-Plus, Dynamic-DataSource for multiple data sources, ShardingSphere for sharding, RabbitMQ, Redis, Elasticsearch and XXL-Job for scheduled work. The project is Java, licensed Apache-2.0, and develops on the `dev` branch.

The starter library is the actual product

The repository is mostly a module tree, and the module tree tells you what the project considers worth standardising. The top level holds `smart-api-core`, `smart-code-generate`, `smart-common-pojo`, `smart-common-web`, `smart-constants`, `smart-exception`, `smart-design-pattern-utility`, `smart-utility`, `smart-test` and `smart-cloud-starter`.

`smart-api-core` is where the security annotations live: interface permissions, request and response encryption and decryption, and signature annotations, along with a `smart-user-context` module for the user context. `smart-common-pojo` holds the shared object types, namely VO, DTO, BO and DO.

The `smart-cloud-starter` directory is the part teams actually import, and the documentation describes it as a library of more than 20 starters that you add on demand. The names cover the ground: `smart-cloud-starter-web` for logging aspects, exception handling and parameter validation, `smart-cloud-starter-feign` for the Feign wrapper that supports the merge and split switch, `smart-cloud-starter-mock` for mock tooling, strategies and interceptors, `smart-cloud-starter-log-mask` plus separate Log4j2 and Logback variants for masking, `smart-cloud-starter-rate-limit` for Sentinel, `smart-cloud-starter-redis` for caching and distributed locks, `smart-cloud-starter-global-id` for distributed ID generation, `smart-cloud-starter-api-version` for API version coexistence, `smart-cloud-starter-locale` for internationalisation, `smart-cloud-starter-job` for XXL-Job, `smart-cloud-starter-trace-debug` for request and response logging with timing, and `smart-cloud-starter-static-discovery` for static service discovery.

The trade-off is obvious once you see the list. Convenience arrives as a large surface of opinionated code, and each starter you adopt is a dependency you will own.

Masking, signing and encryption as compile-time concerns

The security section of the project is the most distinctive part of the offer, and it is built around the idea that sensitive data handling should not be a matter of individual developer discipline.

Request and response encryption is handled by automatic add-and-decrypt behaviour with tamper detection through signature verification. Configuration file encryption is built on Jasypt, so secrets in properties files are not stored in the clear. Table column encryption covers privacy fields automatically and supports multiple keys, which is what makes key rotation possible without a data migration.

Log masking is the piece with the most distinctive mechanism, because it is annotation driven. A developer marks a field with a custom annotation and the log output masks it automatically, across both the Log4j2 and Logback starters. That is a materially different approach from a regex filter in the log appender, because the field is identified where it is declared rather than inferred from the rendered text afterwards.

The same section of the documentation lists request idempotency validation and aspect-based printing of interface and SQL logs, and the topics on the repository confirm the stack in use: mybatis, mybatis-plus, openfeign, rabbitmq, redis, sharding-jdbc, dynamic-datasource, gateway, mock, yapi and spring-boot.

None of this is presented as a way to skip a security review. It is a way to make the default output of a service safe, which is a different and more modest claim.

Mock data and a test path that needs no Nacos

The testing story is one of the more convincing parts of the design, because it attacks a real cost of Spring Cloud development: the dependency on infrastructure before you can run a test.

The documentation describes a dependency-free monolith test mode. You turn off Nacos and Sentinel, mock the RPC interfaces, and then develop and test the service on its own. That is the difference between a unit test suite that needs a running registry and one that does not.

The integration suite uses an H2 database, an embedded Redis and a RabbitMQ mock, and the unit test wrappers use Mockito with Podam for data generation. A separate mock data engine generates responses by return type at random and supports custom mock rules, and there is code generation for the business-independent parts of a service such as VO, DTO and Mapper classes.

The mock engine has two audiences. In development it removes the need for the backend to exist when the frontend is being built, and in tests it removes the need for a live collaborator. The documentation makes the same point twice from different directions, which is a fair sign that it is the feature the project most wants to advertise.

Monitoring through Spring Boot Admin and WeCom alerts

Observability in this project is split between service health and interface behaviour.

On the service side, Spring Boot Admin reports status along with GC, threads, memory, CPU and Tomcat metrics. On the interface side, the monitor starters track slow interfaces and failing interfaces, with alerting on repeated failures and the ability to trip a circuit breaker. The `smart-cloud-starter-monitor` module contains `smart-cloud-monitor-common` for shared code, `smart-cloud-starter-monitor-api` for the slow and failing interface monitoring, and `smart-cloud-starter-monitor-admin` for Spring Boot Admin together with the WeCom alerting.

The alert channel is WeCom, meaning a message to a corporate chat group when a service goes offline or a health check fails, with support for mentioning a specific person. That is a deliberate choice of audience: the notifications land where a Chinese operations team already works.

The logging story is separate and broader. There are starters for Log4j2 and Logback with masking, a method-log starter for aspect-based method logging, and a trace-debug starter that prints the inputs and outputs of an HTTP request along with elapsed time. The documentation describes logging across web, Feign, method, MyBatis and MQ layers with configurable levels. On the API documentation side, an IDEA plugin pushes generated documentation to a YAPI server, and the repository topics include yapi, which confirms that this is the intended workflow rather than an optional extra.

Adding the parent and the starters you actually need

Consumption is ordinary Maven. The parent POM carries the group id and artifact id, and the version placeholder in the documentation is filled with the version you want:

<parent>
    <groupId>io.github.smart-cloud</groupId>
    <artifactId>smart-cloud</artifactId>
    <version>${latest-version}</version>
</parent>

After that you import the starters you need, and the documentation shows three of them side by side: the web starter, the MyBatis-Plus starter and the Redis starter.

<dependency>
    <groupId>io.github.smart-cloud</groupId>
    <artifactId>smart-cloud-starter-web</artifactId>
</dependency>

<dependency>
    <groupId>io.github.smart-cloud</groupId>
    <artifactId>smart-cloud-starter-mybatis-plus</artifactId>
</dependency>

<dependency>
    <groupId>io.github.smart-cloud</groupId>
    <artifactId>smart-cloud-starter-redis</artifactId>
</dependency>

The three starters in that snippet are the web starter, the MyBatis-Plus ORM layer, and the Redis starter for caching with distributed locks. A complete runnable example lives in a separate repository, `smart-cloud-examples`, which the documentation points to as the fastest route to a working setup, with a claim of five minutes to get started.

The project also keeps an English document alongside the Chinese one, `README_EN.md`, and the repository publishes to Maven Central under the `io.github.smart-cloud` group id.

A dev branch that moves faster than its releases

The maintenance picture is the main thing to check before adopting. The repository is not archived and the last push was on 2026-10-04, so work is still landing. The release tags tell a different story. The most recent published release is 1.0.6 from 2024-12-11, before that a 1.0.6-SNAPSHOT from 2024-02-18, and before that 1.0.5 from 2023-03-22.

In other words, the default branch is several months ahead of the newest artifact on Maven Central, and the gap between the last release and the last commit is close to two years. For a scaffold whose value is compatibility with a moving stack of Spring Boot, Spring Cloud, Nacos, Sentinel and ShardingSphere versions, that gap matters. Starters get updated against new upstream releases in the source tree long before a tag carries them.

There is also a default branch to be aware of, which is `dev` rather than `master`, and the build badge in the documentation points at that branch. Anyone building from source or tracking upstream changes has to know which branch is the working one.

The licence is Apache-2.0, which is a permissive grant for a company framework and does not oblige you to publish changes to the framework itself. The dependency risk is more ordinary: you are pulling in a wide set of Spring ecosystem libraries, and the versions they resolve to are the ones your team will have to keep current.

Editorial conclusion

Adopt smart-cloud if your team runs Spring Cloud with Nacos and Sentinel and keeps rewriting the same cross-cutting plumbing, especially masking, signing, mock responses and monitoring, and if you are willing to work on the dev branch until the next release catches up. Do not adopt it if you want a small dependency set, if you are on a Spring Cloud version line the project does not target, or if you need a supported artifact rather than a snapshot. First check the parent version published under io.github.smart-cloud, confirm that the starters you need exist in the module tree, and verify that the example project builds against the same Spring Boot and Spring Cloud releases you run in production.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. smart-cloud/smart-cloud on GitHub