Number To Words

number2words is a demo project showcasing Spring Cloud Consul and Spring Boot with a microservices architecture.

This app is made of two components:

• number2words-backend: a microservice exposing a REST endpoint, converting a number to words (12 -> twelve);
• number2words-frontend: a microservice exposing an API endpoint, connected to backend instances.

Each microservice connects to a Consul server, which is used as a service registry. You may start several instances of number2words-backend: all these instances will be visible to number2words-frontend.

This app is also powered by Spring Cloud Netflix to build reliable service clients, using:

• Netflix Ribbon: a client-side load balancer to distribute load among microservices;
• Netflix Hystrix: a latency and fault tolerance library;
• Open Feign: a REST client library that allows you to consume HTTP APIs with minimal overhead.

Run manually

Compile this project using Maven and JDK 8:

$ ./mvnw clean package

Start a local Consul server, using the Consul Docker image:

$ docker run --rm --name consul -e CONSUL_BIND_INTERFACE=eth0 -p "8500:8500/tcp" consul:1.3.0

Finally, start microservices:

$ java -jar number2words-backend/target/number2words-backend.jar
$ java -jar number2words-frontend/target/number2words-frontend.jar

Feel free to start many number2words-backend instances: a random port is used, so that you can even start many processes on your host.

You are now ready to use the conversion endpoint:

$ curl -s http://localhost:8080/api/convert?n=1234 | jq
{
  "number": 1234,
  "words": "one thousand two hundred thirty-four"
}

On the Consul dashboard, you should be able to see registered services:

In case a service disappears, the Consul server takes care of removing the faulty process in the registry. On the client side, API calls are automatically sent to healthy services.

Consul periodically checks service availability by executing service healthchecks:

Service registration & healthcheck setup are automatically done by Spring Cloud Consul.

Run with docker-compose

You may want to test this app using docker-compose: this enables you to easily scale backend instances, using a single command:

$ docker-compose up -d --scale backend=2
Creating network "number2words_default" with the default driver
Creating number2words_backend_1  ... done
Creating number2words_backend_2  ... done
Creating number2words_consul_1   ... done
Creating number2words_frontend_1 ... done

Stop docker-compose with this command:

$ docker-compose down
Stopping number2words_backend_2  ... done
Stopping number2words_consul_1   ... done
Stopping number2words_frontend_1 ... done
Stopping number2words_backend_1  ... done
Removing number2words_backend_2  ... done
Removing number2words_consul_1   ... done
Removing number2words_frontend_1 ... done
Removing number2words_backend_1  ... done
Removing network number2words_default

The consul dashboard and the number2words API are available as shown previously.

When invoking the API, you can easily follow logs generated in backend instances:

$ docker-compose logs --follow backend

This docker-compose configuration will pull two images from Docker Hub:

• alexandreroman/number2words-backend
• alexandreroman/number2words-frontend

In case you want to use your own Docker images, please update the file docker-compose.yml. Docker images for this app are built using jib-maven-plugin from Google:

$ ./mvnw clean package jib:build

Contribute

Contributions are always welcome!

Feel free to open issues & send PR.

License

Copyright © 2018 Pivotal Software, Inc.

This project is licensed under the Apache Software License version 2.0.