Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Spring Cloud in Practice

This project can be used as a starter for spring cloud microservice application developing. It uses Spring Cloud Consul for service discovery and config management, Spring Cloud Gateway to implement api gateway, and Keycloak for running an optional OAuth2 service. There is also an article Spring Cloud 微服务开发指南 for learning this project.

Dependent frameworks and packages

  1. Spring Boot Web framework and server
  2. Spring Data JPA Access database
  3. Querydsl JPA Type safe dynamic sql builder
  4. Spring Security Authenticate and authrorize
  5. Spring Cloud Gateway Api gateway
  6. Spring Cloud Consul Service discovery
  7. Spring Cloud OpenFeign Declarative rest client



  1. Authentication checked and implemented in gateway, it will request user info from user service to verify username and password, and write logged user info into session storage.
  2. Gateway will pass logged user id through header X-User-Id, and it will be passed between microservices.
  3. Gateway also support login with thirdparty OAuth2 service, after successfully completed the OAuth2 authentication flow, it will request user service to bind thirdparty user to an inner user. Other microservices only knows about the inner user, this makes user related logic keeps the same for all microservices.


Name Description
Gateway Request routing, authentication and authorization checking
User User related business, including users management, roles management and following relationship
Post Post related business
File File related business
Stat Stat related business


Path Method Description
/auth/login POST Login user
/auth/logout GET Logout user
/auth/logged GET Logged user
/user/user/register POST Register user
/user/user/modify POST Modify logged user
/user/user/info GET Get user info
/user/user/sendMobileVerifyCode POST Send mobile verify code
/user/user/sendEmailVerifyCode POST Send email verify code
/user/follow/follow POST Follow user
/user/follow/unfollow POST Unfollow user
/user/follow/following GET Following users of someone
/user/follow/follower GET Fans of some user
/post/post/publish POST Publish post
/post/post/delete POST Delete post
/post/post/info GET Get post info
/post/post/published GET Get published posts of some user
/post/post/like POST Like post
/post/post/unlike POST Unlike post
/post/post/liked GET Liked posts of some user
/post/post/following GET Posts published by following users of someone
/file/file/upload POST Upload file
/file/file/info GET Get file meta info
/stat/stat/ofUser GET Get user stat info
/stat/stat/ofPost GET Get post stat info

The path is following the format /<service>/<module>/<operation>, and the /<service> prefix will be stripped away when gateway forwarding request to microservices.

How to run

This project need java 11+.

By local environment

Run a mysql service

If you use macOS, you can use brew install mysql to install mysql, and use brew services start mysql to start service at port 3306. Then you should create databases and tables for each microservice using sql files under db/migration/mysql.

  1. Use V1__Initial_create_dbs.sql to create databases and accounts to access these databases;
  2. Use V2__Initial_create_tables.sql to create tables;
  3. [Optional] Use V3__Initial_insert_data.sql to insert some data for testing;

Run a redis service

If you use macOS, you can use brew install redis to install redis, and use brew services start redis to start service at port 6379.

Run a consul service

If you use macOS, you can use brew install consul to install consul, and use brew services start consul to start service at port 8500.

Package all microservices

./mvnw package

Start all microservices

java -jar gateway/target/spring-cloud-in-practice-gateway-1.0.0-SNAPSHOT.jar
java -jar user/target/spring-cloud-in-practice-user-1.0.0-SNAPSHOT.jar
java -jar post/target/spring-cloud-in-practice-post-1.0.0-SNAPSHOT.jar
java -jar file/target/spring-cloud-in-practice-file-1.0.0-SNAPSHOT.jar
java -jar stat/target/spring-cloud-in-practice-stat-1.0.0-SNAPSHOT.jar

Then you can access all apis through gateway at http://localhost:8080.

By docker compose

Package all services

./mvnw package

Start all services

docker-compose up

If you repackaged services, you should add --build option to rebuild images.

Then you can access all apis at http://localhost:8080.

Login with OAuth2 service

Choose an OAuth2 service and register a client

You can choose any OAuth2 service like GitHub or Google, or you can start your own OAuth2 service using open source software like Keycloak, you can even Embed Keycloak in a Spring Boot Application. Here we choose to using Keycloak, and register a client in consistent with configuration at in gateway/src/main/resources/application.yml, under realm JW.

Some import attributes of the registered client are as follows:

  • Client ID: scip
  • Client Protocol: openid-connect
  • Access Type: confidential
  • Client Roles: user post file stat

Create a user named jaggerwang with password 123456 for testing, and given all roles of client scip.

Initiate an OAuth2 authentication flow

You can now open http://localhost:8080/login to initiate an OAuth2 authorization code flow and logout at endpoint /logout.


A starter project for spring cloud microservice application.






No releases published


No packages published