With this blog post, you'll get an overview of how to get started with Kotlin and Maven for building Spring Boot applications. I've already covered the usage of Kotlin for Java EE applications and want to provide the same guide for Spring Boot. The demo application communicates with an external system, exposes data via a REST API, and stores data in an embedded H2. We're going to use Spring Boot 2.5.0 and Kotlin 1.5.0.
TL;DR:
- Spring provides first-class support for Kotlin
- Write concise applications with Kotlin and be more productive
- When working with JPA, don't use Kotlin
dataclasses
Maven Project Setup for Spring Boot and Kotlin
After bootstrapping a new Spring Boot and Maven project using Kotlin at start.spring.io, the pom.xml for this application setup looks like the following:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 |
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.0</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>de.rieckpil.blog</groupId> <artifactId>spring-boot-with-kotlin</artifactId> <version>0.0.1-SNAPSHOT</version> <name>spring-boot-with-kotlin</name> <description>Template for Spring Boot applications with Kotlin</description> <properties> <java.version>11</java.version> <kotlin.version>1.5.0</kotlin.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> <dependency> <groupId>com.fasterxml.jackson.module</groupId> <artifactId>jackson-module-kotlin</artifactId> </dependency> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-stdlib-jdk8</artifactId> </dependency> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-reflect</artifactId> </dependency> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>io.projectreactor</groupId> <artifactId>reactor-test</artifactId> <scope>test</scope> </dependency> </dependencies> <!-- build section is described later --> </project> |
Apart from the well-known Spring Boot dependencies, we use three Kotlin-specific dependencies.
First, kotlin-stdlib-jdk8 is the basic standard library from Kotlin, and it provides living essentials for working with Kotlin. Second, jackson-module-kotlin adds support for our Jackson ObjectMapper to serialize and deserialize Kotlin classes properly. Last but not least, kotlin-reflect is mandatory as of Spring 5 to enable reflection features for Kotlin.
Moreover, we have to add the kotlin-maven-plugin to our project and instruct Maven to find the Kotlin source files. We configure this within the build section of the pom.xml:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
<build> <sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory> <testSourceDirectory>${project.basedir}/src/test/kotlin</testSourceDirectory> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> <plugin> <artifactId>kotlin-maven-plugin</artifactId> <groupId>org.jetbrains.kotlin</groupId> <configuration> <args> <arg>-Xjsr305=strict</arg> </args> <compilerPlugins> <plugin>spring</plugin> <plugin>jpa</plugin> <plugin>all-open</plugin> </compilerPlugins> <pluginOptions> <option>all-open:annotation=javax.persistence.Entity</option> <option>all-open:annotation=javax.persistence.Embeddable</option> <option>all-open:annotation=javax.persistence.MappedSuperclass</option> </pluginOptions> </configuration> <dependencies> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-allopen</artifactId> <version>${kotlin.version}</version> </dependency> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-noarg</artifactId> <version>${kotlin.version}</version> </dependency> </dependencies> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-antrun-plugin</artifactId> <version>1.8</version> <executions> <execution> <id>ktlint</id> <phase>validate</phase> <configuration> <target name="ktlint"> <java taskname="ktlint" dir="${basedir}" fork="true" failonerror="true" classname="com.pinterest.ktlint.Main" classpathref="maven.plugin.classpath"> <arg value="src/**/*.kt" /> </java> </target> </configuration> <goals> <goal>run</goal> </goals> </execution> </executions> <dependencies> <dependency> <groupId>com.pinterest</groupId> <artifactId>ktlint</artifactId> <version>0.41.0</version> </dependency> </dependencies> </plugin> </plugins> </build> |
To make use of Kotlin's null-safety feature for the Java-based Spring Framework, we add the compiler argument -Xjsr305=strict. The reason for this is described here:
Although Java does not allow one to express null-safety in its type-system, Spring Framework provides null-safety of the whole Spring Framework API via tooling-friendly annotations declared in the
org.springframework.langpackage. By default, types from Java APIs used in Kotlin are recognized as platform types for which null-checks are relaxed. Kotlin support for JSR 305 annotations + Spring nullability annotations provide null-safety for the whole Spring Framework API to Kotlin developers, with the advantage of dealing withnullrelated issues at compile time.This feature can be enabled by adding the
-Xjsr305compiler flag with thestrictoptions.
Furthermore, to have a no-args constructor for our JPA entities, we have to add the jpa plugin. Similar to this, the all-open plugin is required to make use of lazy fetching with JPA.
As a general best practice, we can include ktlint to be aligned with the Kotlin formatting conventions. As part of the Maven validate phase the maven-ant-run plugin will check the formatting of our sources and fail the build if there's malformatted code.
Kotlin Spring Boot Application Walkthrough
Next, let's have a look at the demo application.
As already mentioned, the application exposes data using a REST API. There are two endpoints, one for returning data fetched from a remote API and the other for returning data from the embedded H2 database:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
@RestController @RequestMapping("/api") class ApiController( val jsonPlaceHolderWebClient: WebClient, val personRepository: PersonRepository ) { @GetMapping(value = ["/todos"], produces = [MediaType.APPLICATION_JSON_VALUE]) fun getAllTodos() = jsonPlaceHolderWebClient .get() .uri("/todos") .retrieve() .bodyToMono(ArrayNode::class.java) .block() @GetMapping(value = ["/persons"], produces = [MediaType.APPLICATION_JSON_VALUE]) fun getAllPersons(): List<Person> = personRepository.findAll() } |
Compared to Java, this endpoint looks quite similar. The main difference is the way we define the primary constructor. With Kotlin, we do this right after the class name as part of the class header.
Furthermore, we can write the controller methods as one-liner as they contain one expression.
The injected WebClient within the constructor of the ApiController class is configured as the following:
|
1 2 3 4 5 6 7 8 9 10 11 |
@Configuration class WebClientConfig { @Bean fun jsonPlaceHolderWebClient(builder: WebClient.Builder) = builder .clone() .baseUrl("https://jsonplaceholder.typicode.com") .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE) .defaultHeader(HttpHeaders.USER_AGENT, "SpringBootKotlinApplication") .build() } |
It points to a remote API that returns fake data for different domains (e.g., todos, user, comments).
Important Notes When Using JPA with Kotlin
As already described in the Maven project setup section, we need the jpa and all-open plugin for Kotlin to properly use JPA.
|
1 2 3 4 5 6 7 8 |
@Entity class Person( @Id @GeneratedValue var id: Long? = null, @Column(nullable = false) var firstname: String, @Column(nullable = false) var lastname: String, @Column(unique = true, nullable = false) var username: String, @Column(nullable = false) var dayOfBirth: LocalDate ) |
You might wonder why I don't use Kotlin's data classes for the JPA entity. As JPA is not designed to work with immutable classes, which we get while using data classes with val properties, we have to use mutable classes.
Creating a JpaRepository from Spring Data is similar to Java:
|
1 |
interface PersonRepository : JpaRepository<Person, Long> |
Given this repository, we can initialize the embedded H2 database with some persons on application startup:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
@Component class PersonInitializer( private val personRepository: PersonRepository ) : CommandLineRunner { override fun run(vararg args: String?) { val personOne = Person(null, "Mike", "Kotlin", "mk90", LocalDate.of(1990, 1, 1)) val personTwo = Person(null, "Java", "Duke", "jduke", LocalDate.of(1995, 1, 1)) val personThree = Person(null, "Andy", "Fresh", "afresh", LocalDate.of(2000, 1, 1)) personRepository.saveAll(listOf(personOne, personTwo, personThree)) } } |
Writing Test for Spring Boot Applications With Kotlin
As mentioned in the Kotlin Coding Conventions, we can use method names with spaces enclosed in backticks. This is a rather small feature but improves the quality of our tests. With Java, we either use camel case or underscores within our test method name to express what it tests.
In contrast, if we are using JUnit 5, something similar is now available for Java applications. We can use the @DisplayName above our test method to describe the tested behavior.
Nevertheless, writing unit and integration tests with Kotlin for our Spring Boot application is similar to Java. To demonstrate this, let's have a look at these short and concise integration tests:
|
1 2 3 4 5 6 7 |
@SpringBootTest class SpringBootWithKotlinApplicationTest { @Test fun `Spring context should load`() { } } |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT) class ApiControllerIntegrationTest( @Autowired val webTestClient: WebTestClient) { @Test fun `should get todos with status code 200`() { this.webTestClient .get() .uri("/api/todos") .accept(MediaType.APPLICATION_JSON) .exchange() .expectStatus().is2xxSuccessful .expectBody() .jsonPath("$[0].userId").isEqualTo(1) .jsonPath("$[0].id").isEqualTo(1) .jsonPath("$[0].title").isEqualTo("delectus aut autem") .jsonPath("$[0].completed").isEqualTo(false) } @Test fun `should get three persons right after startup`() { this.webTestClient .get() .uri("/api/persons") .accept(MediaType.APPLICATION_JSON) .exchange() .expectStatus().is2xxSuccessful .expectBody() .jsonPath("$.length()").isEqualTo(3) } } |
PS: For the second test, we might want to mock the remote call using WireMock.
Final Thoughts on Using Kotlin With Spring Boot
After using Kotlin for almost two years now for several applications in production, these are my final thoughts:
- Kotlin is a first-class citizen for Spring
- Once you use JPA, make sure to understand the difference between Java and Kotlin
- Maven plugins are available for using Spring Boot with Kotlin (also for Gradle)
- Kotlin is a great language to be even more productive
- More support and dedicated Kotlin modules are coming
- Kotlin is simple to adopt as a Java developer
If you are looking for an excellent introduction to Kotlin dedicated to former Java Developers, have a look at this Udemy course.
For those of you who are using Java EE, I've also published a guide on using Kotlin alongside Java EE. As always, the source code is available on GitHub.
Have fun building your next Spring Boot application with Kotlin and Maven,
Philip
