Spring Boot'ta Yapılandırma Bindingi: Doğrulama, Gizli Veri ve Test

Spring Boot eğitimi için immutable ConfigurationProperties tasarımı

Bir spring boot eğitimi içinde yapılandırmayı doğrudan @Value ile alan sınıflar genellikle görünmez hata üretir: anahtar adı değiştiğinde derleme kırılmaz, varsayılan değer yanlışlıkla devreye girer ve aynı ayar birden fazla bean'e dağılır. Bunun yerine ayarları Java record ile tek bir sözleşmede toplayın. Record constructor binding kullandığı için uygulama başladıktan sonra değer değiştirilemez; bu, özellikle connection timeout gibi bir isteğin ortasında değişmemesi gereken parametrelerde önemlidir.

package com.acme.payment;

import java.net.URI;
import java.time.Duration;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@Validated
@ConfigurationProperties(prefix = "payment")
public record PaymentProperties(
    @NotNull URI baseUrl,
    @NotBlank String merchantId,
    @NotNull @Positive Duration connectTimeout,
    @Valid Retry retry
) {
    public record Retry(
        @Positive int maxAttempts,
        @NotNull Duration initialBackoff
    ) {}
}

Bu bean'i uygulama girişinde @ConfigurationPropertiesScan ile etkinleştirin. Duration için 500 gibi bir sayı yerine 500ms yazmak zorunlu birim belirtir; çıplak sayıların varsayılan milisaniye kabul edilmesi, YAML'dan environment variable'a geçişlerde sık rastlanan süre hatalarını azaltır.

Spring Framework ve Spring MVC uygulamalarında ayar katmanlarını izlemek

Spring Framework eğitimi materyallerinde sıklıkla atlanan nokta, property source sırasının iş kuralı kadar kritik olduğudur. Örneğin bir spring mvc uygulamasında server.forward-headers-strategy değerinin platform environment'ı tarafından ezilmesi, reverse proxy arkasındaki yönlendirme URL'lerini hatalı üretebilir. Etkin değerleri tahmin etmek yerine Actuator'un env ve configprops uçlarını yalnızca yönetim ağına açıp kaynak adını inceleyin:

# application.yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,env,configprops
  endpoint:
    env:
      show-values: when-authorized

# Çalışan pod içinde, yetkili yönetim token'ı ile
curl -s -H 'Authorization: Bearer $OPS_TOKEN'   http://localhost:8081/actuator/env/payment.base-url | jq .

/actuator/env yanıtı değerin hangi property source'dan geldiğini gösterir; ancak şifre, token ve JDBC URL gibi verileri loglara sızdırmamak için show-values: never varsayılanını koruyun ve yalnızca yetkili operasyon rolüne koşullu görünürlük tanımlayın. Endpoint'i internete açmak, maskelenmemiş olmayan anahtar adlarının bile altyapı topolojisini ifşa etmesine yol açabilir.

Microservices mimarisi ve Spring Cloud'da Config Tree ile sır yönetimi

microservices mimarisi içinde aynı container imajının staging ve production'da çalışması için parolayı application-prod.yaml dosyasına koymak yerine Kubernetes Secret'ını volume olarak bağlayın. Spring Boot'un Config Tree desteği, dizindeki her dosyayı property anahtarı olarak okur; dosya sonundaki newline'ı da kırptığı için echo ile üretilen secret'larda elle trim() çağırmaya gerek bırakmaz. spring cloud kullanılıyor olsa bile kimlik bilgisi gibi kısa ömürlü olmayan verileri merkezi config deposuna düz metin olarak koymamak daha doğru bir ayrımdır.

# Kubernetes Secret volume mount
volumeMounts:
  - name: payment-secrets
    mountPath: /run/secrets/payment
    readOnly: true
volumes:
  - name: payment-secrets
    secret:
      secretName: payment-provider

# application.yaml
spring:
  config:
    import: "optional:configtree:/run/secrets/payment/"

# Secret içindeki dosya adı: payment.api-key
# Java tarafında: @ConfigurationProperties(prefix = "payment")

Önemli edge case: Secret volume güncellense bile singleton olarak bind edilmiş PaymentProperties nesnesi kendiliğinden değişmez. Anahtar rotasyonu için uygulamayı kontrollü biçimde yeniden başlatın ya da gerçekten dinamik değer gerekiyorsa sağlayıcının SDK'sı üzerinden her çağrıda token alın; @RefreshScope eklemek bean referanslarını ve bağlantı havuzlarını çalışma anında değiştirebildiği için etkisi ölçülmeden varsayılan çözüm yapılmamalıdır.

Spring Security ve Spring REST API ayarlarını fail-fast doğrulamak

Bir spring rest api kaynak sunucusunda issuer URI'nin boş kalması, uygulamanın ilk korumalı isteğinde değil başlangıçta durdurulmalıdır. spring security için nested binding ve çapraz alan doğrulaması ekleyerek yanlış tenant/issuer eşleşmesini deploy aşamasında yakalayabilirsiniz. Aşağıdaki @AssertTrue kontrolü, yalnızca JWT modu seçildiğinde issuer zorunluluğunu uygular; salt @NotNull burada yetersizdir çünkü API key modu için issuer geçerli olarak boş olabilir.

import jakarta.validation.constraints.NotBlank;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
import jakarta.validation.constraints.AssertTrue;

@Validated
@ConfigurationProperties(prefix = "api-auth")
public record ApiAuthProperties(AuthMode mode, String issuerUri, String apiKeyHeader) {
    enum AuthMode { JWT, API_KEY }

    @AssertTrue(message = "JWT modunda issuer-uri https:// ile başlamalıdır")
    boolean isValidAuthenticationConfiguration() {
        return mode != AuthMode.JWT ||
            (issuerUri != null && issuerUri.startsWith("https://"));
    }
}

Bu doğrulama yalnızca properties bean'i gerçekten oluşturulursa çalışır; sınıfı taramaya dahil etmeyi unutmak yaygın hatadır. Bu nedenle giriş sınıfında @ConfigurationPropertiesScan(basePackageClasses = ApiAuthProperties.class) kullanın ve CI'da aşağıdaki bölümdeki context testini çalıştırın.

Java Spring eğitimi: yapılandırma sözleşmesini ApplicationContextRunner ile test etmek

İyi bir java spring eğitimi veya ileri seviye spring boot kursu, YAML'ın parse edilmesini test etmekten öteye geçmelidir: kritik ayarlar eksikken context'in ayağa kalkmadığını kanıtlayan küçük testler yazın. ApplicationContextRunner tam web sunucusunu başlatmaz; bu nedenle onlarca saniyelik @SpringBootTest yerine yalnızca ilgili auto-configuration ve binder'ı milisaniyeler içinde doğrular.

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import static org.assertj.core.api.Assertions.assertThat;

class PaymentPropertiesTest {
  private final ApplicationContextRunner context = new ApplicationContextRunner()
      .withUserConfiguration(PaymentPropertiesConfiguration.class);

  @Test
  void rejects_missing_merchant_id() {
    context.withPropertyValues(
        "payment.base-url=https://gateway.example",
        "payment.connect-timeout=750ms",
        "payment.retry.max-attempts=3",
        "payment.retry.initial-backoff=100ms"
    ).run(ctx -> {
      assertThat(ctx).hasFailed();
      assertThat(ctx.getStartupFailure())
          .hasMessageContaining("merchantId");
    });
  }
}

PaymentPropertiesConfiguration içinde @EnableConfigurationProperties(PaymentProperties.class) tanımlayın. Ayrıca CI'da her dağıtım manifestinin gerekli anahtarları içerdiğini helm template çıktısı üzerinde denetleyin; yalnızca local application.yaml ile test etmek, platformun en sık ezdiği environment değişkenlerini kapsamaz.

Sık Sorulan Sorular

Spring Boot eğitimi kapsamında @Value yerine ConfigurationProperties ne zaman kullanılmalı?

Birden fazla ilişkili alan, nested yapı, Duration/DataSize dönüşümü veya Bean Validation gerekiyorsa ConfigurationProperties kullanın. Tek bir sabit bayrak için @Value kabul edilebilir; ancak aynı prefix altındaki 5 alanı @Value ile dağıtmak, yeniden adlandırma ve eksik alan kontrollerini derleme zamanının dışına iter.

Spring Cloud kullanırken Kubernetes Secret değerleri nasıl Spring Boot'a aktarılır?

Secret'ı dosya olarak /run/secrets altına mount edin ve spring.config.import=configtree:/run/secrets/ ekleyin. Dosya adı property anahtarına dönüşür; örneğin payment.api-key dosyası payment.api-key değerini üretir. Secret güncellemesinin mevcut singleton bean'i otomatik yenilemeyeceğini operasyon planına dahil edin.

Spring Security kullanan Spring REST API için issuer URI doğrulaması nasıl test edilir?

Issuer ayarını @ConfigurationProperties record'unda modelleyin, JWT modu için @AssertTrue veya class-level custom Constraint yazın ve ApplicationContextRunner ile issuer-uri olmadan context'in failed olduğunu doğrulayın. Böylece hatayı ilk istek sırasında JwtDecoder oluşturulurken değil CI aşamasında görürsünüz.