RESTful API’s mit Spring Boot & Java Persistence API (JPA)
Einleitung
Du wolltest schon immer RESTful API’s erstellen, die ihre Daten in einer Datenbank abspeichern? In diesem Tutorial werde ich dir zeigen wie Du mit Spring Boot, Java Persistence API (JPA) und MySQL einen kleine RESTful API erstellen kannst, die Ihre Daten in einer lokalen MySQL Datenbank speichert.
Voraussetzung
- Docker Installation oder lokale MySQL Installation
- Grundkenntnisse in Apache Maven
- Grundkenntnisse in REST API
- Grundkenntnisse in Spring Boot
Docker Container für MySQL
Wie in der Einleitung schon erwähnt brauchen wir für unsere RESTful API eine Datenbank. Hierfür könnt ihr euch entweder eine lokale MySQL Instanz installieren oder mit Docker Compose euch eine MySQL Datenbank Instanz starten bzw. stoppen.
In diesem Tutorial werden wir eine MySQL Datenbank Instanz verwenden, die wir über Docker Compose starten. Dies hat den Vorteil, dass ihr keine eigene MySQL Datenbank installieren müsst.
Um eine MySQL Datenbank Instanz mit Docker Compose starten zu können, benötigen wir erst einmal eine Konfigurationsdatei mit dem Namen “docker-compose.yml”. Hier tragen wir nun unsere Werte für die MySQL Datenbank Instanz ein.
Folgender Abschnitt zeigt die komplette docker-compose.yml Datei
version: '3.3'
services:
db:
image: mysql:5.7
ports:
- 3306:3306
environment:
MYSQL_ROOT_PASSWORD: rootPassword
MYSQL_DATABASE: jpaTutorial1
MYSQL_USER: jpaUser
MYSQL_PASSWORD: jpaPassword
Die MySQL Datenbank Instanz starten wir auf der Console mit den Befehlen “docker-compose up” oder “docker-compose up -d”. Beide Befehle starten die Datenbank Instanz. Mit dem Parameter “-d” wird die MySQL Datenbank Instanz im Detached Modus gestartet. Also im Hintergrund!
Spring Boot Projekt anlegen
Nachdem wir unsere MySQL Datenbank gestartet haben werden wir uns ein Spring Boot Projekt erstellen. Hierfür bietet Spring auf seiner Seite https://start.spring.io/ einen Konfigurator an, mit dem du ein Spring Boot Projekt erstellen kannst. Das schöne an dieser Seite ist es, dass du die Libraries die du benötigt direkt hier mit angeben kannst.
Als erstes geben wir für unser Projekt den Wert für Group ein. In meinem Fall habe ich “de.ertantoker.tutorials” eingegeben. Anschließend geben wir den Wert für Artifact ein. Hier könnt ihr einen Namen eurer Wahl eingeben. In meinem Fall ist es “spring-boot-jpa”.
Für unser Projekt benötigen wir zwei Libraries. In unserem Fall benötigen wir “JPA” und “Web”. Beide Libraries kannst du Rechts bei Dependencies eingeben und auswählen.
Nachdem wir alles eingegeben und ausgewählt haben, erzeugen wir mit dem Klick auf den Button “Generate Project” unser Projekt.
Direkt nach dem Klick startet ein Download, welches unser Projekt mit den entsprechenden Libraries beinhaltet. Als nächstes müssen wir unser Projekt in unsere IDE importieren. Welche IDE ihr verwendet ist euch überlassen
Konfigurationen
Sobald unser Projekt importiert ist können wir nun die Konfigurationen vornehmen, die wir für unsere RESTful API benötigen
Java Persistence API (JPA) in Spring Boot
Als erstes fügen wir die JPA und Spring Boot spezifischen Properties in die application.yml ein. In dem Projekt, welches wir eben importiert haben.
Folgender Abschnitt zeigt die application.properties Datei.
spring.application.name=Spring Boot RESTController and JPA Tutorial spring.jpa.hibernate.ddl-auto=create spring.datasource.url=jdbc:mysql://localhost:3306/jpaTutorial spring.datasource.username=jpaUser spring.datasource.password=jpaPassword
Weitere Konfigurationen sind für Spring Boot und JPA nicht notwendig. Spring Boot verwendet in diesem Fall Hibernate als JPA Implementation, daher bedarf es auch keiner weiteren Konfiguration.
MySQL Datenbank Treiber
Als nächstes müssen wir den Datenbanktreiber für unsere MySQL Datenbank dem Projekt hinzufügen. Hierfür erweitern wir unsere pom.xml Datei um einen dependency Eintrag mit den MySQL JDBC Treibern.
Folgender Abschnitt zeigt die komplette pom.xml
<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>de.ertantoker.tutorial</groupId> <artifactId>spring-boot-jpa</artifactId> <version>0.0.1-SNAPSHOT</version> <packaging>jar</packaging> <name>spring-boot-jpa</name> <description>Demo project for Spring Boot</description> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.6.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> <java.version>1.8</java.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>mysql</groupId> <artifactId>mysql-connector-java</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
Java Persistence API (JPA) Entity Klassen
Wir werden jetzt weitermachen mit der Erstellung des Repository Interfaces. In Spring Data sind Repository Interfaces Zugriffsklassen, die schon vordefinierte Methoden anbieten um auf JPA Objekte zugreifen zu können. In allen Anwendungen, die ich bis jetzt in meiner Karriere als Softwareentwickler entwickelt habe, gab es die klassischen CRUD Methoden. CRUD steht für Create, Read, Update und Delete. Anstatt diese immer neu zu implementieren bietet Spring Data hier schon fertige Methoden an, die man nutzen kann.
Damit unser CustomerRepository Interface als Spring Data Repository Interface definiert werden kann, muss es vom Interface CrudRepository<T, ID> abgeleitet werden. Diese Interface Vererbung ist das einzige was wir machen müssen. Somit steht uns die Datenbankzugriffsschicht mit Spring Data zur Verfügung.
Folgender Abschnitt zeigt die komplette CustomerRepository.java Klasse.
package de.ertantoker.tutorial.springbootjpa.repository;
import de.ertantoker.tutorial.springbootjpa.model.Customer;
import org.springframework.data.repository.CrudRepository;
public interface CustomerRepository extends CrudRepository<Customer, Long> {
}
Spring Boot RestController
Um die Implementierung abschließen zu können, benötigen wir noch einen RestController der unsere RESTful API zur Verfügung stellt. Hierfür werden wir die Klasse CustomerController.java erstellen, die dann eine POST Methode für das Anlegen von Customer Objekten anbieten wird. Sowie eine GET Methode für das holen eines Customer Objektes.
Die RestController Klasse
Einen RestController erstellen wir, indem wir die Klasse mit der Annotation @RestController deklarieren. Diese Annotation sorgt dafür, dass Spring Boot beim starten die Klasse als RestController erkennt und die Methoden, die z.B mit @GetMapping oder @PostMapping deklariert sind als RESTful HTTP Methoden anbietet.
Zusätzlich zu der @RestController Annotation fügen wir noch auf der Klassenebene die Annotation @RequestMapping(“/customers”) hinzu. Diese gibt an, dass die REST Methoden, die in dieser Klasse deklariert werden alle unter der URL http://<myIP>:8080/customers erreichbar sin
Ein umfangreiches Tutorial wie man RestController erstellt findest du in meinem Tutorial RestController mit Spring Boot.
Anlegen mit der POST Methode
Als erstes werden wir die POST Methode für das Anlegen von neuen Customer Objekten anlegen. Hierfür implementieren wir eine neue Methode die ein Customer Objekt als RequestBody entgegennimmt und diese dann über das Repository Interface speichert.
Um das zu realisieren benötigen wir als erstes die Annotation @PostMapping. Hierdurch erreichen wir das alle HTTP POST Anfragen, die auf http://localhost:8080/customers gestellt werden, von dieser Methode abgearbeitet werden. Die Annotation @RequestBody gibt an, dass das Customer Objekt aus dem Request Body der POST Anfrage erstellt wird. Das Default Verhalten ist, dass die Anfrage in JSON gestellt wird.
Folgender Abschnitt zeigt die REST-Schnittstelle für das Anlegen eines neuen Customer Objektes.
@PostMapping
public ResponseEntity saveCustomer(@RequestBody Customer customer) {
customerRepository.save(customer);
return new ResponseEntity<>(customer, HttpStatus.CREATED);
}
Holen mit der GET Methode
Wie oben erwähnt implementieren wir zu der HTTP POST Methode noche eine HTTP GET Methode. Diese wird uns ein Customer Objekt zurück geben. Als Path Parameter übergeben wir der Methode die Id des Customer Objektes und erhalten dann das Customer Objekt aus der Datenbank zurück. Sollte in der Datenbank kein Customer Objekt mit der ID vorhanden sein, wird der HTTP Status 404 NOT FOUND zurück gegeben.
Folgender Abschnitt zeigt die REST-Schnittstelle für das Holen eines Customer Objektes
@GetMapping("/{id}")
public ResponseEntity getCustomerById(@PathVariable Long id) {
return customerRepository.findById(id)
.map(customer -> new ResponseEntity<>(customer, HttpStatus.OK))
.orElseGet(() -> new ResponseEntity<>(HttpStatus.NOT_FOUND));
}
In der Implementierung sehen wir, dass Optional verwendet wurde. Wie man mit Java Streams und Optional Objekte umgeht könnt ihr in meinem Tutorial Java Streams kennen lernen.
Der komplette RestController
Folgender Abschnitt zeigt den kompletten RestController Code.
package de.ertantoker.tutorial.springbootjpa.controller;
import de.ertantoker.tutorial.springbootjpa.model.Customer;
import de.ertantoker.tutorial.springbootjpa.repository.CustomerRepository;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/customers")
public class CustomerController {
private CustomerRepository customerRepository;
public CustomerController(CustomerRepository customerRepository) {
this.customerRepository = customerRepository;
}
@PostMapping
public ResponseEntity saveCustomer(@RequestBody Customer customer) {
customerRepository.save(customer);
return new ResponseEntity<>(customer, HttpStatus.CREATED);
}
@GetMapping("/{id}")
public ResponseEntity getCustomerById(@PathVariable Long id) {
return customerRepository.findById(id)
.map(customer -> new ResponseEntity<>(customer, HttpStatus.OK))
.orElseGet(() -> new ResponseEntity<>(HttpStatus.NOT_FOUND));
}
}
Spring Boot RESTful API starten
Nachdem wir nun unsere RESTful API mit den beiden HTTP Methoden implementiert haben, werden wir diese nun starten.
Zunächst müssen wir die Spring Boot Applikation mit Maven bauen. Mit dem Befehl “mvn clean install” wird die Spring Boot Applikation erstellt.
Sobald der Maven build Prozess mit einem “BUILD SUCCESS” abgeschlossen ist, finden wir in unserem Projekt Ordner ein Verzeichnis mit dem Namen “target”.
Im “target” Order befindet sich nun unsere fertige JAR Datei. Mit dem Befehl “java -jar spring-boot-jpa-0.0.1-SNAPSHOT.jar” starten wir unsere Spring Boot Anwendung. Beachtet bitte, dass vor dem Starten die MySQL Datenbank über Docker Compose gestartet sein muss.
Eine ausführliche Beschreibung wie man RESTful API erstellt findest du auf meinem Tutorial RestController mit Spring Boot.
Schlusswort
Wir haben in diesem Tutorial gelernt wie man eine RESTful Spring Boot Anwendung mit JPA erstellt. Weitere ausführliche Tutorials findet ihr auf meinem Blog. Ich hoffe euch hat das Tutorial gefallen.