Spring Boot & MiniBank'a Giriş

Mini sözlük: Aynı dili konuşalım

Eğitim boyunca sık geçecek birkaç kelimeyi en baştan netleştirelim. Bu modülde derinleşmiyoruz; sadece kelimelerin ne anlama geldiğini oturtuyoruz.

Bu eğitimde ne yapacağız?

Üç gün ve 11 modül boyunca tek bir ürün inşa edeceğiz: MiniBank. Sıfırdan başlayıp birikimli olarak production'a yakın bir olgunluğa ulaşacağız.

Bu eğitim bağımsız örneklerden oluşmaz. Her modül bir öncekinin bıraktığı yerin üstüne yeni bir yetenek ekler: önce çekirdek servis katmanı, sonra web katmanı, en sonunda güvenlik, veri ve gözlemlenebilirlik. Modül sonunda elinde ezberlenmiş parçalar değil, çalışan ve anlamlı bir banka API'si olur.

Spring Boot neden var?

Spring Boot'un temel vaadi sade: "Sen iş mantığına odaklan; uygulamayı ayağa kaldırmak için gereken standart parçaları ben hazırlayayım."

Bir web uygulaması yazmak sadece controller yazmak değildir. HTTP isteğini karşılayacak bir sunucu, isteği doğru metoda yönlendiren bir mekanizma, JSON dönüşümü, hata yönetimi, konfigürasyon okuma ve daha fazlası gerekir. Spring Boot bu tekrar eden parçaları yaygın ve güvenli varsayılanlarla hazırlar. Bu modülde sadece bu çerçeveyi tanıyoruz; nasıl çalıştığını Modül 01'de açacağız.

Nasıl çalışacağız?

Her modülde aynı akışı izleyeceğiz: önce portalda öğren, sonra dashboard'da case'i aç, eğitmenin erişime açtığı private lab repository'sini klonla, kendin yaz ve test ile doğrula.

Geliştirme ortamı

Tek ihtiyacın JDK 17 ve projeyi klonlamak. Maven'ı ayrı kurmana gerek yok, çünkü proje kendi wrapper'ı (./mvnw) ile gelir.

Adım 1: JDK 17'yi doğrula

Terminali aç ve aşağıdaki komutu çalıştır. Çıktının ilk satırında 17 görmen gerekiyor. 11 veya 8 görüyorsan proje derlenmez; 21 gibi daha yeni bir sürüm de çalışır ama eğitimde herkesin aynı sürümde olması sorun ayıklamayı kolaylaştırır.

$ java -version
openjdk version "17.0.11" 2024-04-16        # ilk satırda 17 olmalı
OpenJDK Runtime Environment Temurin-17...

"command not found" alıyorsan JDK kurulu değil demektir; aşağıdaki indirme linklerinden Temurin 17'yi kur ve terminali kapatıp yeniden aç.

Adım 2: Açılan ilk lab repository'sini klonla

git clone https://github.com/definex-training/MiniBank-Lab-00.git
cd MiniBank-Lab-00
git branch   # * main görmelisin

Adım 3: Çalıştır ve doğrula

./mvnw spring-boot:run     # Windows'ta: mvnw.cmd spring-boot:run

İlk çalıştırma birkaç dakika sürebilir çünkü Maven önce bağımlılıkları indirir. Konsolda neler olacağını İlk Çalıştırma bölümünde satır satır göreceğiz. Uygulama kalktığında tarayıcıdan http://localhost:8080 adresini aç: Lab Dashboard seni karşılar. http://localhost:8080/api/status ise uygulamanın UP olduğunu söyleyen bir JSON döner. Port varsayılan olarak 8080'dir; base projede henüz özel bir application.yml yoktur, her şey Spring Boot'un varsayılanlarıyla çalışır.

# Çalışırken eksik scaffold build'i kesmez
./mvnw test -Dminibank.lab.mode=learning -Dtest=MiniBankLabCheckpointTests

# Case sonunda eksik veya yanlış davranış fail olur
./mvnw test -Dminibank.lab.mode=checkpoint -Dtest=MiniBankLabCheckpointTests

Araçlar & indirme linkleri

Eğitim için gereken ve işini kolaylaştıran araçlar. JDK 17, IntelliJ IDEA ve Git zorunlu; gerisi opsiyonel.

Projeyi IntelliJ'de aç

Eğitim boyunca kodu IntelliJ IDEA içinde yazacağız. Projeyi ilk kez açarken şu adımları izle; toplamda 2-3 dakika sürer.

Her şey yolundaysa sol taraftaki proje ağacında src/main/java klasörü mavi (source root) görünür ve MiniBankApplication sınıfının yanında yeşil çalıştırma oku belirir. Bu oka tıklayarak uygulamayı IDE içinden de başlatabilirsin; terminaldeki ./mvnw spring-boot:run ile aynı işi yapar.

pom.xml: Projenin kimlik kartı

pom.xml, Maven'a "bu proje nedir, neye ihtiyaç duyar, nasıl derlenir" sorularının cevabını veren dosyadır. MiniBank'in gerçek pom.xml'inden en önemli kısımlara bakalım.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.0</version>                <!-- Spring Boot sürümü -->
</parent>

<properties>
    <java.version>17</java.version>          <!-- JDK 17 şartı -->
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>       <!-- REST + Tomcat -->
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId> <!-- @NotBlank vb. -->
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>   <!-- /actuator/health -->
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>                                      <!-- JUnit + MockMvc -->
    </dependency>
</dependencies>

İlk çalıştırma: konsolda ne göreceksin?

./mvnw spring-boot:run dediğinde arka arkaya dört şey olur. Konsol çıktısını okuyabilmek, ileride sorun ayıklarken en çok işine yarayacak beceridir.

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 ...
 :: Spring Boot ::                (v3.5.0)

INFO ... : Starting MiniBankApplication using Java 17
INFO ... : Tomcat initialized with port 8080 (http)
INFO ... : Root WebApplicationContext: initialization completed
INFO ... : Tomcat started on port 8080 (http) with context path '/'
INFO ... : Started MiniBankApplication in 1.8 seconds

Son iki satır kritik: "Tomcat started on port 8080" web sunucusunun dinlemede olduğunu, "Started MiniBankApplication" ise Spring context'inin sorunsuz kurulduğunu söyler. Bu iki satırı görmeden tarayıcıda adres açmaya çalışma; göremiyorsan Sorun Giderme bölümüne bak.

• http://localhost:8080 açılıyor ve Lab Dashboard görünüyor.
• http://localhost:8080/api/status şu JSON'u dönüyor: {"application":"MiniBank","status":"UP",...}
• http://localhost:8080/actuator/health da {"status":"UP"} dönüyor (actuator starter'ın hediyesi).
• Durdurmak için terminalde Ctrl+C.

Base project turu

lab-00-base bilinçli olarak neredeyse boş bir iskelettir: sadece uygulamanın ayağa kalkması ve dashboard'un servis edilmesi için gereken minimum vardır. Domain (hesap, müşteri, transfer…) henüz yoktur. Onları modül modül biz ekleyeceğiz.

minibank
├── pom.xml                          # Spring Boot 3.5.0 · Java 17
├── mvnw / mvnw.cmd                  # Maven Wrapper
└── src
    ├── main
    │   ├── java/com/definex/minibank
    │   │   ├── MiniBankApplication.java   # @SpringBootApplication (giriş noktası)
    │   │   └── web
    │   │       └── HomeController.java     # GET /api/status
    │   └── resources
    │       └── static
    │           └── index.html             # Lab Dashboard
    └── test/java/com/definex/minibank
        ├── MiniBankApplicationTests.java      # context ayağa kalkıyor mu
        └── MiniBankHomeControllerTests.java   # status + dashboard

Giriş noktası: MiniBankApplication

Projedeki en küçük ama en önemli sınıf budur. Base projedeki gerçek hali şu:

package com.definex.minibank;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MiniBankApplication {

    public static void main(String[] args) {
        SpringApplication.run(MiniBankApplication.class, args);
    }
}

@SpringBootApplication tek bir annotation gibi görünür ama aslında üç annotation'ın kısaltmasıdır. Şimdilik isimlerini tanıman yeterli; her birinin mekanizmasını Modül 01'de tek tek açacağız:

İlk controller: HomeController

/api/status cevabını üreten sınıf da base projede hazır. İki annotation'a dikkat: @RestController sınıfı "HTTP isteklerine JSON cevap veren bileşen" yapar, @GetMapping ise metodu belirli bir URL'e bağlar. Dönen record tipini Spring otomatik olarak JSON'a çevirir; bu dönüşümün perde arkasını Modül 04'te göreceğiz.

@RestController
public class HomeController {

    @GetMapping("/api/status")
    public MiniBankStatus status() {
        return new MiniBankStatus(
                "MiniBank",
                "UP",
                "MiniBank API calisiyor.",
                List.of(
                        "GET / (Lab Dashboard)",
                        "GET /api/status",
                        "GET /actuator/health"));
    }

    public record MiniBankStatus(
            String application,
            String status,
            String message,
            List<String> links) {
    }
}

Paket kök kuralı

Tüm kod com.definex.minibank kök paketinin altında durur. MiniBankApplication bu kökte olduğu için, eklediğimiz her alt paket (account, customer …) otomatik olarak görülebilir konumda olur. Bunun neden böyle olduğunu Modül 01'de (component scanning) açacağız.

Takıldıysan: en sık görülen 5 sorun

İlk kurulumda bir şeyler ters gittiyse büyük ihtimalle aşağıdakilerden biridir. Belirtiyi bul, çözümü uygula; hiçbiri tutmazsa eğitmene konsol çıktısının son 20 satırını göster.