https://dzone.com/articles/building-microservices-spring
In the modern world of microservices it's important to provide strict and polyglot clients for your service. It's better if your API is self-documented. One of the best tools for it is Apache Thrift. I want to explain how to use it with my favorite platform for microservices - Spring Boot.
All project source code is available on GitHub: https://github.com/bsideup/spring-boot-thrift
Project skeleton
I will use Gradle to build our application. First, we need our main build.gradle file:
buildscript {
repositories {
jcenter()
}
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:1.1.8.RELEASE")
}
}
allprojects {
repositories {
jcenter()
}
apply plugin:'base'
apply plugin: 'idea'
}
subprojects {
apply plugin: 'java'
}
Nothing special for a Spring Boot project. Then we need a gradle file for thrift protocol modules (we will reuse it in next part):
import org.gradle.internal.os.OperatingSystem
repositories {
ivy {
artifactPattern "http://dl.bintray.com/bsideup/thirdparty/[artifact]-[revision](-[classifier]).[ext]"
}
}
buildscript {
repositories {
jcenter()
}
dependencies {
classpath "ru.trylogic.gradle.plugins:gradle-thrift-plugin:0.1.1"
}
}
apply plugin: ru.trylogic.gradle.thrift.plugins.ThriftPlugin
task generateThrift(type : ru.trylogic.gradle.thrift.tasks.ThriftCompileTask) {
generator = 'java:beans,hashcode'
destinationDir = file("generated-src/main/java")
}
sourceSets {
main {
java {
srcDir generateThrift.destinationDir
}
}
}
clean {
delete generateThrift.destinationDir
}
idea {
module {
sourceDirs += [file('src/main/thrift'), generateThrift.destinationDir]
}
}
compileJava.dependsOn generateThrift
dependencies {
def thriftVersion = '0.9.1';
Map platformMapping = [
(OperatingSystem.WINDOWS) : 'win',
(OperatingSystem.MAC_OS) : 'osx'
].withDefault { 'nix' }
thrift "org.apache.thrift:thrift:$thriftVersion:${platformMapping.get(OperatingSystem.current())}@bin"
compile "org.apache.thrift:libthrift:$thriftVersion"
compile 'org.slf4j:slf4j-api:1.7.7'
}
We're using my Thrift plugin for Gradle. Thrift will generate source to the "generated-src/main/java" directory. By default, Thrift uses slf4j v1.5.8, while Spring Boot uses v1.7.7. It will cause an error in runtime when you will run your application, that's why we have to force a slf4j api dependency.
Calculator service
Let's start with a simple calculator service. It will have 2 modules: protocol and app.We will start with protocol. Your project should look as follows:
- calculator/
- protocol/
- src/
- main/
- thrift/
- calculator.thrift
- thrift/
- main/
- build.gradle
- src/
- protocol/
- build.gradle
- settings.gradle
- thrift.gradle
Where calculator/protocol/build.gradle contains only one line:
apply from: rootProject.file('thrift.gradle')
Don't forget to put these lines to settings.gradle, otherwise your modules will not be visible to Gradle:
include 'calculator:protocol'
include 'calculator:app'
Calculator protocol
Even if you're not familiar with Thrift, its protocol description file (calculator/protocol/src/main/thrift/calculator.thrift) should be very clear to you:
namespace cpp com.example.calculator
namespace d com.example.calculator
namespace java com.example.calculator
namespace php com.example.calculator
namespace perl com.example.calculator
namespace as3 com.example.calculator
enum TOperation {
ADD = 1,
SUBTRACT = 2,
MULTIPLY = 3,
DIVIDE = 4
}
exception TDivisionByZeroException {
}
service TCalculatorService {
i32 calculate(1:i32 num1, 2:i32 num2, 3:TOperation op) throws (1:TDivisionByZeroException divisionByZero);
}
Here we define TCalculatorService with only one method - calculate. It can throw an exception of type TDivisionByZeroException. Note how many languages we're supporting out of the box (in this example we will use only Java as a target, though)
Now run ./gradlew generateThrift, you will get generated Java protocol source in thecalculator/protocol/generated-src/main/java/ folder.
Calculator application
Next, we need to create the service application itself. Just create calculator/app/ folder with the following structure:
- src/
- main/
- java/
- com/
- example/
- calculator/
- handler/
- CalculatorServiceHandler.java
- service/
- CalculatorService.java
- CalculatorApplication.java
- handler/
- calculator/
- example/
- com/
- java/
- main/
- build.gradle
Our build.gradle file for app module should look like this:
apply plugin: 'spring-boot'
dependencies {
compile project(':calculator:protocol')
compile 'org.springframework.boot:spring-boot-starter-web'
testCompile 'org.springframework.boot:spring-boot-starter-test'
}
Here we have a dependency on protocol and typical starters for Spring Boot web app.
CalculatorApplication is our main class. In this example I will configure Spring in the same file, but in your apps you should use another config class instead.
package com.example.calculator;
import com.example.calculator.handler.CalculatorServiceHandler;
import org.apache.thrift.protocol.*;
import org.apache.thrift.server.TServlet;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.*;
import javax.servlet.Servlet;
@Configuration
@EnableAutoConfiguration
@ComponentScan
public class CalculatorApplication {
public static void main(String[] args) {
SpringApplication.run(CalculatorApplication.class, args);
}
@Bean
public TProtocolFactory tProtocolFactory() {
//We will use binary protocol, but it's possible to use JSON and few others as well
return new TBinaryProtocol.Factory();
}
@Bean
public Servlet calculator(TProtocolFactory protocolFactory, CalculatorServiceHandler handler) {
return new TServlet(new TCalculatorService.Processor<CalculatorServiceHandler>(handler), protocolFactory);
}
}
You may ask why Thrift servlet bean is called "calculator". In Spring Boot, it will register your servlet bean in context of the bean name and our servlet will be available at /calculator/.
After that we need a Thrift handler class:
package com.example.calculator.handler;
import com.example.calculator.*;
import com.example.calculator.service.CalculatorService;
import org.apache.thrift.TException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
@Component
public class CalculatorServiceHandler implements TCalculatorService.Iface {
@Autowired
CalculatorService calculatorService;
@Override
public int calculate(int num1, int num2, TOperation op) throws TException {
switch(op) {
case ADD:
return calculatorService.add(num1, num2);
case SUBTRACT:
return calculatorService.subtract(num1, num2);
case MULTIPLY:
return calculatorService.multiply(num1, num2);
case DIVIDE:
try {
return calculatorService.divide(num1, num2);
} catch(IllegalArgumentException e) {
throw new TDivisionByZeroException();
}
default:
throw new TException("Unknown operation " + op);
}
}
}
In this example I want to show you that Thrift handler can be a normal Spring bean and you can inject dependencies in it.
Now we need to implement CalculatorService itself:
package com.example.calculator.service;
import org.springframework.stereotype.Component;
@Component
public class CalculatorService {
public int add(int num1, int num2) {
return num1 + num2;
}
public int subtract(int num1, int num2) {
return num1 - num2;
}
public int multiply(int num1, int num2) {
return num1 * num2;
}
public int divide(int num1, int num2) {
if(num2 == 0) {
throw new IllegalArgumentException("num2 must not be zero");
}
return num1 / num2;
}
}
That's it. Well... almost. We still need to test our service somehow. And it should be an integration test.
Usually, even if your application is providing JSON REST API, you still have to implement a client for it. Thrift will do it for you. We don't have to care about it. Also, it will support different protocols. Let's use a generated client in our test:
package com.example.calculator;
import org.apache.thrift.protocol.*;
import org.apache.thrift.transport.THttpClient;
import org.apache.thrift.transport.TTransport;
import org.junit.*;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.*;
import org.springframework.boot.test.IntegrationTest;
import org.springframework.boot.test.SpringApplicationConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import static org.junit.Assert.*;
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = CalculatorApplication.class)
@WebAppConfiguration
@IntegrationTest("server.port:0")
public class CalculatorApplicationTest {
@Autowired
protected TProtocolFactory protocolFactory;
@Value("${local.server.port}")
protected int port;
protected TCalculatorService.Client client;
@Before
public void setUp() throws Exception {
TTransport transport = new THttpClient("http://localhost:" + port + "/calculator/");
TProtocol protocol = protocolFactory.getProtocol(transport);
client = new TCalculatorService.Client(protocol);
}
@Test
public void testAdd() throws Exception {
assertEquals(5, client.calculate(2, 3, TOperation.ADD));
}
@Test
public void testSubtract() throws Exception {
assertEquals(3, client.calculate(5, 2, TOperation.SUBTRACT));
}
@Test
public void testMultiply() throws Exception {
assertEquals(10, client.calculate(5, 2, TOperation.MULTIPLY));
}
@Test
public void testDivide() throws Exception {
assertEquals(2, client.calculate(10, 5, TOperation.DIVIDE));
}
@Test(expected = TDivisionByZeroException.class)
public void testDivisionByZero() throws Exception {
client.calculate(10, 0, TOperation.DIVIDE);
}
}
This test will run your Spring Boot application, bind it to a random port and test it. All client-server communications will be performed in the same way real world clients are.
Note how easy to use our service is from the client side. We're just calling methods and catching exceptions.