10 Common Pitfalls When Adopting Spring Cloud Alibaba Microservices (And How to Avoid Them)

Recently the author and teammates took over a microservice project built by an outsourcing team using the popular Spring Cloud Alibaba architecture and a well‑known open‑source scaffolding. While working on it, they encountered numerous issues that are common in poorly designed microservice systems.

1. Unreasonable Service Module Splitting

Most open‑source microservice frameworks split modules by backend management, but in practice services should be divided based on domain modeling. The current split follows teams or functions, causing chaotic service calls and increasing distributed transaction risk.

2. Database Not Split After Service Decomposition

All services share a single database, making data isolation impossible and leading some teams to read other services' tables directly. Without database separation, the purpose of microservice splitting is questionable.

3. Function Duplication Instead of Reuse

A common infrastructure module provides file upload, data dictionary, logging, etc., yet the file‑upload feature is re‑implemented in another module, resulting in duplicated code.

4. Useless Component Overload

The base module defines many public starters that are imported by every microservice, such as third‑party login, WeChat payment, an obscure workflow engine, and captcha components, even though the project already has its own SSO, payment, and workflow solutions.

5. Obvious Errors Left Unresolved

An unnecessary message middleware was introduced, causing repeated connection exceptions during runtime. No one addressed the issue, leading to prolonged instability.

6. Chaotic Configuration Files

Each service contains a tangled set of configuration files, many of which duplicate environment‑specific settings that should be managed centrally via a configuration center.

7. Misuse of Configuration Center

Although the project intended to use Apollo as a configuration center with one appId per service, multiple services share the same appId and some services ignore the center altogether.

8. Nacos Registry Chaos

Developers frequently modify the spring.cloud.nacos.discovery.group property and start all related services to coordinate testing, causing users to overwrite each other's configurations and proliferating many unrelated groups in Nacos, making service discovery difficult.

Resolving this only requires customizing the gateway’s load‑balancing strategy to route traffic to the intended service, a feature supported by the underlying framework.

9. Inconsistent Interface Protocols

The scaffolding supports both Dubbo and OpenFeign, but the project only uses OpenFeign internally while still exposing Dubbo‑based endpoints to external callers, creating unnecessary protocol complexity.

10. Deployment Method Chaos

In a Kubernetes environment, proper practice is to expose only the gateway (via NodePort or Ingress) and keep internal services as ClusterIP. The team instead gave every service a NodePort and added an extra Nginx reverse proxy on the host, bypassing the gateway and increasing security risk.

Conclusion

Many open‑source microservice scaffolds bundle excessive features without explaining why they are needed. While such projects can accelerate learning, real‑world adoption requires careful pruning and selective extension based on actual project requirements to avoid unnecessary complexity and ensure successful microservice implementation.