Bu yazıda, Spring Boot uygulamamda golden pair adı verilen, etiketlenmiş örneklerden oluşan küçük ama düzgün kurulmuş bir değerlendirme (evaluation) altyapısının nasıl inşa edildiğini anlatacağım. Bu altyapı, Recall@K ve Mean Reciprocal Rank (MRR) gibi sektörde yaygın metrikleri hesaplıyor ve yetkili kullanıcılara açtığım bir admin endpoint üzerinden, üretim ortamına yeni bir değişiklik geçirilmeden önce her zaman yeniden çalıştırılabiliyor.

1. Sezgilerle Ayar Yapmanın Sorunu

Bir destek portalında, agent'lar gelen yeni bir ticket'a benzer geçmiş ticket'lar önerildiğinde çok daha hızlı çözüme ulaşıyorlar. "Benzerini getir" özelliği temelde üç parçadan oluşuyor:

• ticket'ı düz metne dönüştüren bir content builder,
• bu metni vektöre çeviren bir embedding modeli,
• en yakın komşuları (top-K) döndüren bir vektör veritabanı.

Bu pipeline'daki her parça aslında bir ayar düğmesi. Embedding modelini değiştirin? Vektör boyutu, semantik komşuluk ve benzerlik skorları değişir. Ticket'ın metne dönüştürülme şeklini değiştirin? Modele giren sinyaller değişir. Benzerlik eşiğini değiştirin? Recall/precision dengesi kayar.

Bir değişikliğin gerçekten iyileştirme olup olmadığını anlamanın tek dürüst yolu, "iyi" olanı somut örneklerle tanımlamak ve onunla karşılaştırmaktan geçiyor.

2. Doğruluğun Kaynağı: Golden Pair'ler

Bir golden pair, etiketlenmiş bir sorgudur: "Bu girdiye karşılık, sistem şu ticket'ları döndürmeli." Etiketler, alanı bilen kişiler tarafından üretilir.

Tek bir pair'i Java record ile şu şekilde modelliyorum:

@JsonInclude(JsonInclude.Include.NON_NULL)
public record EvalGoldenPair(
        String id,
        String queryText,
        Long queryTicketId,
        List<Long> expectedSimilarTicketIds,
        String note
) {
    public EvalGoldenPair {
        if ((queryText == null || queryText.isBlank()) && queryTicketId == null) {
            throw new IllegalArgumentException(
                    "EvalGoldenPair " + id + " must define either queryText or queryTicketId");
        }
        if (expectedSimilarTicketIds == null || expectedSimilarTicketIds.isEmpty()) {
            throw new IllegalArgumentException(
                    "EvalGoldenPair " + id + " must define at least one expectedSimilarTicketId");
        }
    }
}

Burada altını çizmek istediğim birkaç tasarım kararı var:

• queryText veya queryTicketId. Bazı pair'lerde sorgu, yeni bir ticket'ı simüle eden, elle yazılmış bir metindir. Bazılarında ise zaten çözülmüş mevcut bir ticket'ı, kalan korpus üzerinde sorgu olarak kullanırız — bu leave-one-out tarzı bir değerlendirmedir. Compact constructor, bu iki yoldan en az birinin kullanılmasını zorunlu kılıyor.
• expectedSimilarTicketIds tek bir id değil, bir listedir. Birden fazla geçmiş ticket aynı anda alakalı olabilir. Listenin ilk elemanı en alakalı olan; sonrakiler de geçerli alakalı sonuçlardır.

note.: Etiketleyenin "bu pair neden burada?" sorusuna yazılı cevap verdiği serbest metin alanı. İlerde bir regression olduğunda, "ileride bu kodu okuyacak olan ben" çok minnettar olacaktır.

Dataset wrapper'ı ise basit bir liste tutucu:

public record EvalDataset(
        String name,
        String description,
        List<EvalGoldenPair> pairs
) {}

Listeyi doğrudan List<EvalGoldenPair> olarak değil de bir record içinde tutmak, ileride mevcut dosyaları kırmadan datasetVersion veya tags gibi alanlar eklenebilmesini sağlıyor.

3. Dataset'i Classpath'ten Yükleme

Dataset'ler classpath'te JSON formatında duruyor. Repo'da golden-pairs.example.json adıyla çalıştırılabilir bir başlangıç dosyası tutuyorum; gerçek dataset (müşteri verisi içerebileceği için hassas olabilir) golden-pairs.json adıyla aynı dizine kopyalanıyor ve .gitignorea ekleniyor.

@Slf4j
@Component
@RequiredArgsConstructor
public class EvalDatasetLoader {

    static final String DEFAULT_DATASET_PATH = "classpath:ai-eval/golden-pairs.json";
    static final String EXAMPLE_DATASET_PATH = "classpath:ai-eval/golden-pairs.example.json";

    private final ResourceLoader resourceLoader;
    private final ObjectMapper objectMapper;

    public EvalDataset load() {
        return load(DEFAULT_DATASET_PATH);
    }

    public EvalDataset load(String path) {
        Resource resource = resourceLoader.getResource(path);
        if (!resource.exists()) {
            log.warn("Eval dataset not found at {} — falling back to example dataset at {}",
                    path, EXAMPLE_DATASET_PATH);
            resource = resourceLoader.getResource(EXAMPLE_DATASET_PATH);
            if (!resource.exists()) {
                throw new IllegalStateException(
                        "No eval dataset found at " + path + " or " + EXAMPLE_DATASET_PATH);
            }
        }
        try (InputStream in = resource.getInputStream()) {
            EvalDataset dataset = objectMapper.readValue(in, EvalDataset.class);
            List<EvalGoldenPair> pairs = dataset.pairs();
            if (pairs == null || pairs.isEmpty()) {
                throw new IllegalStateException("Eval dataset at " + path + " contains no pairs");
            }
            log.info("Loaded eval dataset '{}' with {} pairs from {}",
                    dataset.name(), pairs.size(), path);
            return dataset;
        } catch (IOException ex) {
            throw new IllegalStateException("Failed to read eval dataset from " + path, ex);
        }
    }
}

path parametre olarak alınıyor; bu sayede ekip birden fazla dataset (örneğin ürün başına, müşteri başına ya da kalite seviyesine göre) tutup admin endpoint üzerinden hangisinin çalıştırılacağını seçebiliyor.

4. Metrikler: Recall@K ve MRR

Değerlendirmeyi iki temel metrik yönlendiriyor:

• Recall@K — Her pair için, beklenen id'lerden en az biri top-K sonuçları arasında geldi mi? Tüm pair'ler üzerinden ortalama alınır. Ben Recall@1, Recall@3 ve Recall@5 raporluyorum.
• Mean Reciprocal Rank (MRR) — Her pair için 1 / (ilk alakalı sonucun sırası) hesaplanır; sıra 1'den başlar; eğer beklenen id'lerden hiçbiri top-K'ya girmediyse o pair 0 katkıda bulunur. Tüm pair'ler üzerinden ortalama alınır. MRR, sistemi sadece doğru cevabı listeye sokması için değil, üst sıralara koyması için ödüllendirir.

Bunlara ek olarak bir de sanity-check niteliğinde "ortalama top-1 cosine similarity skoru" tutuyorum; ama bu bir kalite metriği değildir: kendinden emin bir biçimde yanlış dönen bir sonucun skoru, daha temkinli bir doğru sonucun skorundan yüksek olabilir. Bu metrik daha çok, kötü bir konfigürasyon değişikliğinden sonra skorların topluca çökmesi gibi durumları yakalamak için kullanılıyor.

5. Değerlendirmenin Çalıştırılması

EmbeddingEvaluator, her pair için canlı retrieval pipeline'ını bir kez sorguluyor; pair bazlı metrikleri hesaplıyor ve sonuçları rapora topluyor:

@Slf4j
@Service
@RequiredArgsConstructor
public class EmbeddingEvaluator {

    static final int TOP_K = 5;

    private final TicketEmbeddingService embeddingService;
    private final TicketRepository ticketRepository;
    private final TicketContentBuilder contentBuilder;

    public EvalReport evaluate(EvalDataset dataset) {
        long started = System.currentTimeMillis();
        List<EvalReport.PerPairResult> perPair = new ArrayList<>(dataset.pairs().size());
        int hitsAt1 = 0, hitsAt3 = 0, hitsAt5 = 0;
        double mrrSum = 0.0;
        double topScoreSum = 0.0;
        int topScoreCount = 0;

        for (EvalGoldenPair pair : dataset.pairs()) {
            EvalReport.PerPairResult result = evaluatePair(pair);
            perPair.add(result);
            if (result.hitAt1()) hitsAt1++;
            if (result.hitAt3()) hitsAt3++;
            if (result.hitAt5()) hitsAt5++;
            if (result.firstRelevantRank() > 0) {
                mrrSum += 1.0 / result.firstRelevantRank();
            }
            if (!result.retrievedScores().isEmpty()) {
                topScoreSum += result.retrievedScores().getFirst();
                topScoreCount++;
            }
        }

        int total = dataset.pairs().size();
        double averageTopScore = topScoreCount == 0 ? 0.0 : topScoreSum / topScoreCount;
        long duration = System.currentTimeMillis() - started;

        return new EvalReport(
                total,
                (double) hitsAt1 / total,
                (double) hitsAt3 / total,
                (double) hitsAt5 / total,
                mrrSum / total,
                averageTopScore,
                duration,
                perPair
        );
    }

    private EvalReport.PerPairResult evaluatePair(EvalGoldenPair pair) {
        String queryText = resolveQueryText(pair);
        List<TicketSimilarityResult> hits = embeddingService.findSimilar(queryText, TOP_K, 0.0);

        List<Long> retrievedIds = new ArrayList<>(hits.size());
        List<Double> retrievedScores = new ArrayList<>(hits.size());
        for (TicketSimilarityResult hit : hits) {
            // Sorgunun kendi ticket'ını atlıyoruz — leave-one-out tarzı bir
            // değerlendirmede bu ticket her zaman 1. sırada gelirdi ve
            // retrieval kalitesini olduğundan iyi gösterirdi.
            if (pair.queryTicketId() != null && hit.ticketId() == pair.queryTicketId()) {
                continue;
            }
            retrievedIds.add(hit.ticketId());
            retrievedScores.add(hit.score());
        }

        int firstRelevantRank = firstRelevantRank(retrievedIds, pair.expectedSimilarTicketIds());
        return new EvalReport.PerPairResult(
                pair.id(),
                pair.expectedSimilarTicketIds(),
                retrievedIds,
                retrievedScores,
                firstRelevantRank,
                firstRelevantRank == 1,
                firstRelevantRank > 0 && firstRelevantRank <= 3,
                firstRelevantRank > 0 && firstRelevantRank <= 5
        );
    }

    private static int firstRelevantRank(List<Long> retrieved, List<Long> expected) {
        for (int rank = 1; rank <= retrieved.size(); rank++) {
            if (expected.contains(retrieved.get(rank - 1))) {
                return rank;
            }
        }
        return 0;
    }
}

Burada altını çizmek istediğim üç ince karar var:

• TOP_K config'ten okunmuyor, sabit 5. Üretimde top-K her ortam için ayrı yapılandırılabiliyor. Ama eval de aynı ayarı kullansaydı, her config değişikliğiyle birlikte raporlanan sayılar sessizce değişirdi — ve modelin gerçekten iyileştiğini mi, yoksa sadece daha çok aday getirdiğinizi mi göremezdiniz. Sabit bir eval penceresi, çalışmaları karşılaştırılabilir kılıyor.
• findSimilara verilen minimum benzerlik threshold'u 0.0. Recall zaten "sonuç yeterince iyi miydi?" sorusunu kapsıyor. Skor üzerinden ayrıca filtre uygulamak iki ayrı soruyu birbirine karıştırırdı: "Doğru ticket bulunabilir miydi?" ve "Skor bir eşik üzerinde mi?".
• Leave-one-out atlaması. Sorgu zaten mevcut bir ticket'sa, vektör veritabanı bu ticket'ı keyifle 1. sıraya yazardı. Sırayı hesaplamadan önce onu listeden çıkarmak, eval'in olduğundan iyi görünmesini engelliyor.

6. Rapor

EvalReport toplu sonuçları taşıyor; ama her pair'in detayı da hata ayıklayabilelim diye saklanıyor:

public record EvalReport(
        int totalPairs,
        double recallAt1,
        double recallAt3,
        double recallAt5,
        double meanReciprocalRank,
        double averageTopScore,
        long durationMillis,
        List<PerPairResult> perPair
) {
    public record PerPairResult(
            String id,
            List<Long> expectedSimilarTicketIds,
            List<Long> retrievedTicketIds,
            List<Double> retrievedScores,
            int firstRelevantRank,
            boolean hitAt1,
            boolean hitAt3,
            boolean hitAt5
    ) {}
}

Üst seviye sayılar, değişikliğin iyi olup olmadığını söyler. Pair bazlı liste ise hangi sorguların gerilediğini söyler — ki bir sonraki iterasyonu mümkün kılan asıl şey budur. "Recall@5, 0,78'den 0,74'e düştü" bir problem ifadesidir; "Recall@5 0,78'den 0,74'e düştü ve şu üç pair durumu değiştirdi" ise üzerinde çalışılabilecek bir ipucudur.

7. Değerlendirmenin İstendiğinde Çalıştırılması

Son olarak, eval'i istediğimiz zaman tekrar tetikleyebileceğimiz, sadece admin'e açık bir HTTP endpoint:

@RestController
@RequestMapping(API_PREFIX + "/ai/admin/evaluation")
@RequiredArgsConstructor
public class EvaluationAdminController {

    private final EvalDatasetLoader datasetLoader;
    private final EmbeddingEvaluator evaluator;

    @PostMapping("/run")
    @PreAuthorize(Role.HAS_ADMIN)
    public EvalReport run(@RequestParam(required = false) String datasetPath) {
        EvalDataset dataset = datasetPath == null || datasetPath.isBlank()
                ? datasetLoader.load()
                : datasetLoader.load(datasetPath);
        return evaluator.evaluate(dataset);
    }
}

Beklenen kullanım akışı oldukça basit:

1. Bir retrieval parametresini, modeli veya prompt'u değiştirin.
2. POST /api/ai/admin/evaluation/run endpoint'ine istek atın.
3. Raporu önceki referansla karşılaştırın.
4. Sayılar gerçekten iyileştiyse (ya da önemli olan metriklerde sabit kaldıysa) değişikliği üretime alın.

Aynı evaluator'ı bir CI işine bağlayıp, Recall@5 belli bir tabanın altına düştüğünde build'i başarısız hale getirmek de mümkün — bu yapı, kod henüz üretime gitmeden devreye giren bir regression koruması haline gelir.

Sonuç

Değerlendirme altyapısı olmadan bir AI özelliği geliştirmek, test suite'i olmayan bir refactoring sürecine benziyor: her değişiklik ilerleme gibi hissettiriyor, ama kanıtlamak imkânsız. Bu yazıda yürüdüğüm yapı bilinçli olarak küçük tutuldu — üç record, iki servis, bir controller ve bir JSON dosyası — yine de "bu daha iyi mi?" sorusunu, çalışmalar arasında karşılaştırılabilir bir sayıya çeviriyor.

Bu yatırım, birisi "yeni embedding modelinin gerçekten daha iyi olduğundan emin miyiz?" diye sorduğu ilk anda kendini geri ödüyor: cevap artık "Recall@5, 0,71'den 0,83'e çıktı, durumu değiştiren dört pair de şunlar" oluyor. Sezgilerden sayılara.

Bu minimal versiyonu büyütmek istediğinizde doğal sonraki adımlar şunlar olabilir: dataset bazında metrikleri zaman içinde takip etmek, false-positive'in canınızı yaktığı senaryolarda precision tarzı metrikler eklemek, ya da retrieval yerine doğrudan LLM'in cevabını puanlamak (LLM-as-judge). Ama ilk gün bunların hiçbirine ihtiyacınız yok. Küçük bir dataset ve Recall@K, içgüdüyle değil veriyle yön bulmaya başlamak için yeterli.

Sorularınız için ya da kendi retrieval pipeline'ınız için benzer bir altyapı kurmayı tartışmak isterseniz benimle iletişime geçebilirsiniz.

In this article, I will walk through how I built a small but proper evaluation harness in Spring Boot that measures retrieval quality using a curated set of golden pairs. It computes industry-standard metrics like Recall@K and Mean Reciprocal Rank (MRR), and exposes them via an admin-only endpoint so the team can re-run evaluations any time before promoting a change to production.

1. The Problem with Tuning by Vibes

In a support portal, agents resolve incoming tickets faster when the system suggests similar tickets that were already resolved in the past. The "find similar" feature is implemented with three moving parts:

• a content builder that turns a ticket into a piece of text,
• an embedding model that turns that text into a vector,
• a vector store that returns the top-K nearest neighbours.

Every component in that pipeline is a knob. Change the embedding model? The vector dimensions, semantic neighbourhood, and similarity scores change. Tweak how the ticket is rendered into text? Different signals are encoded. Adjust the similarity threshold? The recall/precision trade-off shifts.

The only honest way to know whether a change is an improvement is to define what "good" looks like — with concrete examples — and measure against it.

2. Golden Pairs: The Source of Truth

A golden pair is a labeled query: "for this input, the system should return these tickets". The labels are produced by domain experts (here, support engineers who know which past resolutions actually applied to a given new ticket).

I model a single pair as a Java record:

@JsonInclude(JsonInclude.Include.NON_NULL)
public record EvalGoldenPair(
        String id,
        String queryText,
        Long queryTicketId,
        List<Long> expectedSimilarTicketIds,
        String note
) {
    public EvalGoldenPair {
        if ((queryText == null || queryText.isBlank()) && queryTicketId == null) {
            throw new IllegalArgumentException(
                    "EvalGoldenPair " + id + " must define either queryText or queryTicketId");
        }
        if (expectedSimilarTicketIds == null || expectedSimilarTicketIds.isEmpty()) {
            throw new IllegalArgumentException(
                    "EvalGoldenPair " + id + " must define at least one expectedSimilarTicketId");
        }
    }
}

A few decisions are worth calling out:

• queryText or queryTicketId. Sometimes the labeled query is a hand-written description simulating a new ticket. Other times it is an existing resolved ticket used as a query against the rest of the corpus — a leave-one-out style evaluation. The compact constructor enforces that exactly one route is taken.
• expectedSimilarTicketIds is a list, not a single ID. Multiple past tickets may legitimately be relevant. The first element is the most relevant; the rest are also acceptable hits.

note. A free-text field where the labeller explains why this is a golden pair. Future-you, debugging a regression, will be grateful.

The dataset wrapper is a simple list:

public record EvalDataset(
        String name,
        String description,
        List<EvalGoldenPair> pairs
) {}

Wrapping the list in a record (instead of using a bare List<EvalGoldenPair>) lets future versions add fields like datasetVersion or tags without breaking existing files.

3. Loading the Dataset from the Classpath

Datasets live in JSON on the classpath. I keep a golden-pairs.example.json checked into the repo so anyone cloning the project gets a runnable starter, while the real dataset (which can include sensitive customer data) lives at golden-pairs.json and is .gitignored.

@Slf4j
@Component
@RequiredArgsConstructor
public class EvalDatasetLoader {

    static final String DEFAULT_DATASET_PATH = "classpath:ai-eval/golden-pairs.json";
    static final String EXAMPLE_DATASET_PATH = "classpath:ai-eval/golden-pairs.example.json";

    private final ResourceLoader resourceLoader;
    private final ObjectMapper objectMapper;

    public EvalDataset load() {
        return load(DEFAULT_DATASET_PATH);
    }

    public EvalDataset load(String path) {
        Resource resource = resourceLoader.getResource(path);
        if (!resource.exists()) {
            log.warn("Eval dataset not found at {} — falling back to example dataset at {}",
                    path, EXAMPLE_DATASET_PATH);
            resource = resourceLoader.getResource(EXAMPLE_DATASET_PATH);
            if (!resource.exists()) {
                throw new IllegalStateException(
                        "No eval dataset found at " + path + " or " + EXAMPLE_DATASET_PATH);
            }
        }
        try (InputStream in = resource.getInputStream()) {
            EvalDataset dataset = objectMapper.readValue(in, EvalDataset.class);
            List<EvalGoldenPair> pairs = dataset.pairs();
            if (pairs == null || pairs.isEmpty()) {
                throw new IllegalStateException("Eval dataset at " + path + " contains no pairs");
            }
            log.info("Loaded eval dataset '{}' with {} pairs from {}",
                    dataset.name(), pairs.size(), path);
            return dataset;
        } catch (IOException ex) {
            throw new IllegalStateException("Failed to read eval dataset from " + path, ex);
        }
    }
}

The path is parameterised so the team can ship multiple datasets — one per product, customer, or quality tier — and pick which to run from the admin endpoint.

4. The Metrics: Recall@K and MRR

Two metrics drive the evaluation:

• Recall@K — for each pair, did at least one of the expected IDs show up in the top-K retrieved results? Average over all pairs. I report Recall@1, Recall@3, and Recall@5.
• Mean Reciprocal Rank (MRR) — for each pair, take 1 / rank-of-first-relevant-result, where rank is 1-indexed; if none of the expected IDs appears in the top-K, contribute 0. Average over all pairs. MRR rewards the system for putting the right answer near the top, not just somewhere in the list.

I also keep a sanity-check metric — average top-1 cosine similarity score — but it is not a quality signal: a confidently wrong answer can have a higher score than a less confident correct one. It is useful for spotting score collapse after a bad config change, nothing more.

5. Running the Evaluation

The EmbeddingEvaluator queries the live retrieval pipeline once per pair, computes per-pair metrics, and aggregates them into a report:

@Slf4j
@Service
@RequiredArgsConstructor
public class EmbeddingEvaluator {

    static final int TOP_K = 5;

    private final TicketEmbeddingService embeddingService;
    private final TicketRepository ticketRepository;
    private final TicketContentBuilder contentBuilder;

    public EvalReport evaluate(EvalDataset dataset) {
        long started = System.currentTimeMillis();
        List<EvalReport.PerPairResult> perPair = new ArrayList<>(dataset.pairs().size());
        int hitsAt1 = 0, hitsAt3 = 0, hitsAt5 = 0;
        double mrrSum = 0.0;
        double topScoreSum = 0.0;
        int topScoreCount = 0;

        for (EvalGoldenPair pair : dataset.pairs()) {
            EvalReport.PerPairResult result = evaluatePair(pair);
            perPair.add(result);
            if (result.hitAt1()) hitsAt1++;
            if (result.hitAt3()) hitsAt3++;
            if (result.hitAt5()) hitsAt5++;
            if (result.firstRelevantRank() > 0) {
                mrrSum += 1.0 / result.firstRelevantRank();
            }
            if (!result.retrievedScores().isEmpty()) {
                topScoreSum += result.retrievedScores().getFirst();
                topScoreCount++;
            }
        }

        int total = dataset.pairs().size();
        double averageTopScore = topScoreCount == 0 ? 0.0 : topScoreSum / topScoreCount;
        long duration = System.currentTimeMillis() - started;

        return new EvalReport(
                total,
                (double) hitsAt1 / total,
                (double) hitsAt3 / total,
                (double) hitsAt5 / total,
                mrrSum / total,
                averageTopScore,
                duration,
                perPair
        );
    }

    private EvalReport.PerPairResult evaluatePair(EvalGoldenPair pair) {
        String queryText = resolveQueryText(pair);
        List<TicketSimilarityResult> hits = embeddingService.findSimilar(queryText, TOP_K, 0.0);

        List<Long> retrievedIds = new ArrayList<>(hits.size());
        List<Double> retrievedScores = new ArrayList<>(hits.size());
        for (TicketSimilarityResult hit : hits) {
            // Skip the query ticket itself — it would always rank #1 in a
            // leave-one-out eval and would mask retrieval quality.
            if (pair.queryTicketId() != null && hit.ticketId() == pair.queryTicketId()) {
                continue;
            }
            retrievedIds.add(hit.ticketId());
            retrievedScores.add(hit.score());
        }

        int firstRelevantRank = firstRelevantRank(retrievedIds, pair.expectedSimilarTicketIds());
        return new EvalReport.PerPairResult(
                pair.id(),
                pair.expectedSimilarTicketIds(),
                retrievedIds,
                retrievedScores,
                firstRelevantRank,
                firstRelevantRank == 1,
                firstRelevantRank > 0 && firstRelevantRank <= 3,
                firstRelevantRank > 0 && firstRelevantRank <= 5
        );
    }

    private static int firstRelevantRank(List<Long> retrieved, List<Long> expected) {
        for (int rank = 1; rank <= retrieved.size(); rank++) {
            if (expected.contains(retrieved.get(rank - 1))) {
                return rank;
            }
        }
        return 0;
    }
}

Three subtle decisions are worth pulling out:

• TOP_K is fixed at 5, not read from config. In production, top-K is configurable per deployment. But if the eval used the same setting, every config tweak would silently change the reported numbers — and you would not know whether the model improved or you simply retrieved more candidates. A fixed eval window keeps runs comparable.
• The minimum-similarity threshold passed to findSimilar is 0.0. Recall already encodes whether a result was good enough. Filtering by score would conflate two different questions: "is the right ticket findable?" vs. "is the score above a threshold?".
• Leave-one-out skip. When the query is itself an existing ticket, the vector store will gleefully return that ticket as the perfect top-1 match. Skipping it before computing rank prevents the eval from looking better than it really is.

6. The Report

EvalReport is the aggregated picture, but each per-pair result is preserved so failures are debuggable:

public record EvalReport(
        int totalPairs,
        double recallAt1,
        double recallAt3,
        double recallAt5,
        double meanReciprocalRank,
        double averageTopScore,
        long durationMillis,
        List<PerPairResult> perPair
) {
    public record PerPairResult(
            String id,
            List<Long> expectedSimilarTicketIds,
            List<Long> retrievedTicketIds,
            List<Double> retrievedScores,
            int firstRelevantRank,
            boolean hitAt1,
            boolean hitAt3,
            boolean hitAt5
    ) {}
}

The top-level numbers tell you whether the change is good. The per-pair list tells you which queries regressed — and that is what makes the next iteration possible. "Recall@5 dropped from 0.78 to 0.74" is a problem statement; "Recall@5 dropped from 0.78 to 0.74 and these three specific pairs flipped" is a debuggable lead.

7. Triggering Evaluation On-Demand

Finally, an admin-only HTTP endpoint to re-run the evaluation any time:

@RestController
@RequestMapping(API_PREFIX + "/ai/admin/evaluation")
@RequiredArgsConstructor
public class EvaluationAdminController {

    private final EvalDatasetLoader datasetLoader;
    private final EmbeddingEvaluator evaluator;

    @PostMapping("/run")
    @PreAuthorize(Role.HAS_ADMIN)
    public EvalReport run(@RequestParam(required = false) String datasetPath) {
        EvalDataset dataset = datasetPath == null || datasetPath.isBlank()
                ? datasetLoader.load()
                : datasetLoader.load(datasetPath);
        return evaluator.evaluate(dataset);
    }
}

The intended workflow is simple:

1. Change a retrieval parameter, model, or prompt.
2. Hit POST /api/ai/admin/evaluation/run.
3. Compare the report to the previous baseline.
4. Only promote the change if the numbers improved (or held steady on the metrics that matter).

The same evaluator can also be wired into a CI job that fails the build if Recall@5 drops below a floor — turning the harness into a regression gate before code ever reaches production.

Wrapping Up

Building an AI feature without an evaluation harness is like refactoring without a test suite: every change feels like progress, but you have no way to prove it. The harness I walked through here is intentionally small — three records, two services, one controller, and a JSON file — yet it converts a fuzzy "is this better?" question into a number you can compare across runs.

The investment pays for itself the first time someone asks "are we sure the new embedding model is actually better?" and the answer is "Recall@5 went from 0.71 to 0.83, and here are the four pairs that flipped". From vibes to numbers.

Natural next steps, when you outgrow this minimal version, are: tracking metrics over time per dataset, adding precision-style metrics for cases where false positives hurt, or scoring the LLM's answer instead of the retrieval (using LLM-as-judge). But you do not need any of that on day one. A small dataset and Recall@K are enough to start steering with data instead of intuition.

If you have any questions or want to discuss building one of these for your own retrieval pipeline, feel free to reach out.

1. Adding Required Dependencies

To perform JWT-based authentication and authorization in a Spring Boot application, you need to add some essential dependencies to your project. These dependencies are necessary for security and JWT operations. Below is how to add these dependencies to your Spring Boot project.

If you are using Maven:

You can include the required libraries in your pom.xml file by adding the following dependencies.

<dependencies>
    <!-- Spring Security -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <!-- JJWT (Java JWT) -->
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-api</artifactId>
        <version>0.11.5</version>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-impl</artifactId>
        <version>0.11.5</version>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-jackson</artifactId>
        <version>0.11.5</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

If you are using Gradle:

If you are using Gradle, you can add the following dependencies to your build.gradle file.

dependencies {
  // Spring Security
  implementation 'org.springframework.boot:spring-boot-starter-security'

  // JJWT (Java JWT) API, Implementation, and Jackson support
  implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
  runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
  runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'
}

2. Storing User Information Securely: AuthDto

As the first step, we need to create a DTO (Data Transfer Object) class to store user information. This class will represent the information that will be included in the JWT token. For example, it might include user ID, email address, and roles:

@Builder
@Getter
@Setter
public class AuthDto {
    private UUID id;
    private String email;
    private List<GrantedAuthority> roles;
}

This DTO will carry the user information and will be used securely within the SecurityContext.

3. JWT Creation and Validation: TokenService

We need to write a service class that will handle the creation and validation of the JWT. This class will manage all operations from generating the token to validation and constructing the authentication context.

@RequiredArgsConstructor
@Service
public class TokenService implements ITokenService {
    private final IUserRepository userRepository;
    private final int MILLISECOND_IN_MINUTE = 1000 * 60; // Milliseconds per minute
    private final SignatureAlgorithm SIGNATURE_ALGORITHM = SignatureAlgorithm.HS256; // Signing algorithm

    @Value("${security.token.access.secret}")
    private String accessTokenSecret; // Secret key for Access token

    @Value("${security.token.access.expires}")
    private int accessTokenExpires; // Expiration time for Access token (in minutes)

    // Generating JWT from User object
    @Override
    public String generateAccessToken(User user) {
        Date now = new Date(); // Current time
        int expiresIn = accessTokenExpires * MILLISECOND_IN_MINUTE; // Expiration time in milliseconds

        // Create JWT token
        return Jwts.builder()
                .setSubject(user.getEmail()) // User's email
                .claim("id", user.getId()) // User's ID
                .claim("roles", rolesToString(user.getRoles())) // User's roles as a string
                .setIssuedAt(now) // Token issued at
                .setExpiration(new Date(now.getTime() + expiresIn)) // Token expiration time
                .signWith(jwtKeyGenerator(accessTokenSecret), SIGNATURE_ALGORITHM) // JWT signing
                .compact(); // Generate the token
    }

    // Generating authentication from JWT token
    @Override
    public Authentication getAuthenticationFromAccessToken(String accessToken) {
        Claims claims = Jwts.parserBuilder()
                .setSigningKey(jwtKeyGenerator(accessTokenSecret)) // Verify the JWT signature using the secret key
                .build().parseClaimsJws(accessToken).getBody(); // Parse the JWT token

        // Get roles from token and convert to GrantedAuthority
        List<GrantedAuthority> roles = stringToRoles(claims.get("roles", String.class));

        // Build Authentication object with user information
        AuthDto authDto = AuthDto.builder()
                .id(UUID.fromString(claims.get("id", String.class))) // User's UUID
                .email(claims.getSubject()) // User's email
                .roles(roles) // User's roles
                .build();

        // Return Authentication object
        return new UsernamePasswordAuthenticationToken(authDto, null, roles);
    }

    // Convert roles to a comma-separated string
    private String rolesToString(Collection<Role> roles) {
        return roles.stream()
                .map(Role::name) // Get role names
                .collect(Collectors.joining(",")); // Join with commas
    }

    // Convert string roles to GrantedAuthority list
    private List<GrantedAuthority> stringToRoles(String rolesString) {
        if (rolesString == null || rolesString.isEmpty()) {
            return Collections.emptyList(); // Return empty list if no roles
        }

        // Convert string roles to GrantedAuthority
        return Arrays.stream(rolesString.split(",\\s*"))
                .map(role -> Role.valueOf(role)) // Convert to Role enum
                .filter(Objects::nonNull) // Filter non-null roles
                .map(role -> new SimpleGrantedAuthority(role.name())) // Convert to GrantedAuthority
                .collect(Collectors.toList());
    }

    // Generate secret key for JWT
    private Key jwtKeyGenerator(String secret) {
        return Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret)); // Decode the secret key with BASE64
    }
}

4. JWT Validation with AuthTokenFilter

To check the validity of the JWT on every incoming request, we use a filter. This filter verifies the JWT, and if valid, authenticates the user.

@RequiredArgsConstructor
@Component
public class AuthTokenFilter extends OncePerRequestFilter {
    private final ITokenService tokenService; // TokenService used for JWT verification

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String url = request.getRequestURI(); // Get the URL of the incoming request

        // Skip JWT verification for '/api/auth/*' paths
        if (url.matches("/api/auth/*")) {
            filterChain.doFilter(request, response);
            return;
        }

        // Get access token from cookie
        Cookie accessTokenCookie = WebUtils.getCookie(request, "accessToken");

        // If no token found, attach error and proceed
        if (accessTokenCookie == null) {
            attachError(request, ErrorCode.ACCESS_TOKEN_DOES_NOT_EXIST); // Attach error message
            filterChain.doFilter(request, response);
            return;
        }

        try {
            // Validate the token and get Authentication object
            Authentication authentication = tokenService.getAuthenticationFromAccessToken(accessTokenCookie.getValue());

            // Set the authentication context
            SecurityContextHolder.getContext().setAuthentication(authentication);
        } catch (ExpiredJwtException e) {
            // Handle expired token error
            attachErrorAndClearAuthContext(request, ErrorCode.ACCESS_TOKEN_EXPIRED);
        } catch (MalformedJwtException e) {
            // Handle malformed token error
            attachErrorAndClearAuthContext(request, ErrorCode.ACCESS_TOKEN_MALFORMED);
        } catch (RuntimeException e) {
            // Handle other errors
            attachErrorAndClearAuthContext(request, ErrorCode.INTERNAL_SERVER);
        }

        filterChain.doFilter(request, response); // Continue with the filter chain
    }

    private void attachError(HttpServletRequest request, ErrorCode errorCode) {
        // Attach error information to the request
        request.setAttribute("exceptionStatus", errorCode.getHttpStatusCode());
        request.setAttribute("exceptionCode", errorCode.getCode());
        request.setAttribute("exceptionMessage", errorCode.getMessage());
    }

    private void attachErrorAndClearAuthContext(HttpServletRequest request, ErrorCode errorCode) {
        // Attach error and clear authentication context
        attachError(request, errorCode);
        SecurityContextHolder.clearContext(); // Clear authentication information
    }
}

5. Handling JWT Errors with AuthExceptionHandler

The AuthenticationEntryPoint is used to manage errors during JWT verification, sending the correct error messages to users.

@Slf4j
@Component
public class AuthExceptionHandler implements AuthenticationEntryPoint {
    final ObjectMapper MAPPER = new ObjectMapper(); // ObjectMapper for JSON responses

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException, ServletException {
        log.error("Unauthorized error: {}", authException.getMessage()); // Log error message

        response.setContentType(MediaType.APPLICATION_JSON_VALUE); // Set response type to JSON
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); // Set HTTP 401 (Unauthorized) status code

        final Map<String, Object> body = new HashMap<>(); // Map to store error details

        // If error details are present in the request, return them in the JSON response
        if (request.getAttribute("exceptionCode") != null &&
            request.getAttribute("exceptionMessage") != null &&
            request.getAttribute("exceptionStatus") != null) {
            body.put("code", request.getAttribute("exceptionCode").toString());
            body.put("message", request.getAttribute("exceptionMessage").toString());
            body.put("status", Integer.parseInt(request.getAttribute("exceptionStatus").toString()));
        } else {
            // If no error details are found, send a general authentication required error
            body.put("code", ErrorCode.AUTHENTICATION_REQUIRED.getCode());
            body.put("message", ErrorCode.AUTHENTICATION_REQUIRED.getMessage());
            body.put("status", ErrorCode.AUTHENTICATION_REQUIRED.getHttpStatusCode());
        }

        // Send JSON response
        MAPPER.writeValue(response.getOutputStream(), body);
    }
}

6. Spring Security Configuration: SecurityConfig

Finally, we include the JWT validation filter and error handler in the Spring Security configuration. This configuration will handle security and validation processes across the application.

@RequiredArgsConstructor
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    private final AuthTokenFilter authTokenFilter; // Filter for JWT validation
    private final AuthExceptionHandler authExceptionHandler; // Error handler for JWT errors

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity httpSecurity) throws Exception {
        return httpSecurity
                .exceptionHandling(customizer -> customizer.authenticationEntryPoint(authExceptionHandler)) // Use the error handler
                .addFilterBefore(authTokenFilter, BasicAuthenticationFilter.class) // Add JWT validation filter
                .csrf(AbstractHttpConfigurer::disable) // Disable CSRF protection
                .sessionManagement(customizer -> customizer.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) // Stateless session management
                .authorizeHttpRequests(requests -> requests
                        .requestMatchers("/api/auth/*").permitAll() // Allow unauthenticated access to auth endpoints
                        .anyRequest().authenticated()) // Require authentication for all other requests
                .build(); // Apply configuration
    }
}

Wrapping Up

In this article, we have explored how to implement JWT-based authentication and authorization in Spring Boot applications. We covered key concepts like creating and validating JWT tokens, security filters, and error handling. If you have any questions, feel free to contact me.

1. Gerekli Bağımlılıkların Eklenmesi

Spring Boot ile JWT tabanlı kimlik doğrulama ve yetkilendirme işlemleri gerçekleştirebilmek için bazı temel bağımlılıkları projenize dahil etmeniz gerekmektedir. Bu bağımlılıklar, güvenlik ve JWT işlemleri için gereklidir. Aşağıda, Spring Boot projenize bu bağımlılıkların nasıl ekleneceği açıklanmıştır.

Maven Kullanıyorsanız:

pom.xml dosyanıza aşağıdaki bağımlılıkları ekleyerek gerekli kütüphaneleri projenize dahil edebilirsiniz.

<dependencies>
    <!-- Spring Security -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <!-- JJWT (Java JWT) -->
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-api</artifactId>
        <version>0.11.5</version>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-impl</artifactId>
        <version>0.11.5</version>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-jackson</artifactId>
        <version>0.11.5</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

Gradle Kullanıyorsanız:

Eğer Gradle kullanıyorsanız, aşağıdaki bağımlılıkları build.gradle dosyanıza ekleyebilirsiniz.

dependencies {
  // Spring Security
  implementation 'org.springframework.boot:spring-boot-starter-security'

  // JJWT (Java JWT) API, Implementation ve Jackson desteği
  implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
  runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
  runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'
}

2. Kullanıcı Bilgilerinin Güvenli Bir Şekilde Saklanması: AuthDto

İlk adım olarak, kullanıcı bilgilerini saklayacağımız bir DTO (Data Transfer Object) sınıfı oluşturmalıyız. Bu sınıf, JWT token içinde yer alacak bilgileri temsil edecektir. Örneğin, kullanıcı id'si, email adresi ve rollerini içerecek bir sınıf:

@Builder
@Getter
@Setter
public class AuthDto {
    private UUID id;
    private String email;
    private List<GrantedAuthority> roles;
}

Bu DTO, kullanıcı bilgilerini taşıyacak ve güvenli bir şekilde SecurityContext içinde kullanılacaktır.

3. JWT Oluşturma ve Doğrulama: TokenService

JWT'yi oluşturup doğrulayacak olan servis sınıfını yazmamız gerekiyor. Bu sınıf, token'ın üretilmesinden, doğrulama ve güvenlik bağlamını (authentication) oluşturma sürecine kadar olan tüm işlemleri yönetecek.

@RequiredArgsConstructor
@Service
public class TokenService implements ITokenService {
    private final IUserRepository userRepository;
    private final int MILLISECOND_IN_MINUTE = 1000 * 60; // Zaman hesaplamalarında kullanmak için milisaniye cinsinden dakika çevirisi
    private final SignatureAlgorithm SIGNATURE_ALGORITHM = SignatureAlgorithm.HS256; // Kullanılacak imzalama algoritması

    @Value("${security.token.access.secret}")
    private String accessTokenSecret; // Access token için gizli anahtar

    @Value("${security.token.access.expires}")
    private int accessTokenExpires; // Access token'in geçerlilik süresi (dakika cinsinden)

    // Kullanıcı objesinden JWT'nin oluşturulması
    @Override
    public String generateAccessToken(User user) {
        Date now = new Date(); // Şu anki zaman
        int expiresIn = accessTokenExpires * MILLISECOND_IN_MINUTE; // Token'ın geçerlilik süresi

        // JWT token'ı oluşturuluyor
        return Jwts.builder()
                .setSubject(user.getEmail()) // Kullanıcının email adresi
                .claim("id", user.getId()) // Kullanıcının id'si
                .claim("roles", rolesToString(user.getRoles())) // Kullanıcının rollerini string olarak ekliyoruz
                .setIssuedAt(now) // Token'ın oluşturulma zamanı
                .setExpiration(new Date(now.getTime() + expiresIn)) // Token'ın son kullanma tarihi
                .signWith(jwtKeyGenerator(accessTokenSecret), SIGNATURE_ALGORITHM) // JWT imzalaması
                .compact(); // Token'ı oluştur
    }

    // JWT token'ından kullanıcı kimlik doğrulaması (Authentication) oluşturulması
    @Override
    public Authentication getAuthenticationFromAccessToken(String accessToken) {
        Claims claims = Jwts.parserBuilder()
                .setSigningKey(jwtKeyGenerator(accessTokenSecret)) // JWT'nin imzasını doğrulamak için gizli anahtar
                .build().parseClaimsJws(accessToken).getBody(); // JWT token'ını çöz

        // Token'dan roller bilgisini alıyoruz ve GrantedAuthority objelerine dönüştürüyoruz
        List<GrantedAuthority> roles = stringToRoles(claims.get("roles", String.class));

        // Authentication objesini oluşturuyoruz
        AuthDto authDto = AuthDto.builder()
                .id(UUID.fromString(claims.get("id", String.class))) // Kullanıcının UUID'sini al
                .email(claims.getSubject()) // Kullanıcının e-posta adresini al
                .roles(roles) // Kullanıcının rollerini ekle
                .build();

        // Kullanıcı bilgisiyle birlikte authentication objesini döndür
        return new UsernamePasswordAuthenticationToken(authDto, null, roles);
    }

    // Kullanıcının rollerini string formatına dönüştüren yardımcı metot
    private String rolesToString(Collection<Role> roles) {
        return roles.stream()
                .map(Role::name) // Rollerin isimlerini al
                .collect(Collectors.joining(",")); // Virgülle ayırarak tek bir string'e çevir
    }

    // String formatındaki rollerin GrantedAuthority listesine dönüştürülmesi
    private List<GrantedAuthority> stringToRoles(String rolesString) {
        if (rolesString == null || rolesString.isEmpty()) {
            return Collections.emptyList(); // Eğer roller boşsa, boş bir liste döndür
        }

        // String içindeki rollerden her birini GrantedAuthority'ye dönüştür
        return Arrays.stream(rolesString.split(",\\s*"))
                .map(role -> Role.valueOf(role)) // Her rolü Role enum'ına dönüştür
                .filter(Objects::nonNull) // Null olmayanları filtrele
                .map(role -> new SimpleGrantedAuthority(role.name())) // GrantedAuthority nesnelerine dönüştür
                .collect(Collectors.toList());
    }

    // JWT için gizli anahtarın oluşturulması
    private Key jwtKeyGenerator(String secret) {
        return Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret)); // BASE64 ile decode edilmiş anahtarı kullanıyoruz
    }
}

4. JWT Kontrolü İçin AuthTokenFilter

Her gelen istekte, JWT'nin doğruluğunu kontrol etmek için bir filtre kullanıyoruz. Bu filtre, JWT'nin geçerli olup olmadığını kontrol eder ve geçerli ise kullanıcıyı doğrular.

@RequiredArgsConstructor
@Component
public class AuthTokenFilter extends OncePerRequestFilter {
    private final ITokenService tokenService; // TokenService, JWT doğrulama işlemleri için kullanılır

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String url = request.getRequestURI(); // Gelen isteğin URL'sini al

        // Eğer URL '/api/auth/*' ile başlıyorsa, JWT kontrolü yapma
        if (url.matches("/api/auth/*")) {
            filterChain.doFilter(request, response);
            return;
        }

        // Cookie içinde access token'ı alıyoruz
        Cookie accessTokenCookie = WebUtils.getCookie(request, "accessToken");

        // Eğer token yoksa, hata mesajı ekleyip, filtreyi geçiyoruz
        if (accessTokenCookie == null) {
            attachError(request, ErrorCode.ACCESS_TOKEN_DOES_NOT_EXIST); // Hata mesajı ekle
            filterChain.doFilter(request, response); // Filtreyi geç
            return;
        }

        try {
            // Token'ı doğrulayıp Authentication objesini alıyoruz
            Authentication authentication = tokenService.getAuthenticationFromAccessToken(accessTokenCookie.getValue());

            // SecurityContext'e doğrulama bilgilerini yerleştiriyoruz
            SecurityContextHolder.getContext().setAuthentication(authentication);
        } catch (ExpiredJwtException e) {
            // Token süresi dolmuşsa, hata mesajı ekleyip, SecurityContext'i temizliyoruz
            attachErrorAndClearAuthContext(request, ErrorCode.ACCESS_TOKEN_EXPIRED);
        } catch (MalformedJwtException e) {
            // Token bozulmuşsa, hata mesajı ekleyip, SecurityContext'i temizliyoruz
            attachErrorAndClearAuthContext(request, ErrorCode.ACCESS_TOKEN_MALFORMED);
        } catch (RuntimeException e) {
            // Diğer hata durumlarında, hata mesajı ekleyip, SecurityContext'i temizliyoruz
            attachErrorAndClearAuthContext(request, ErrorCode.INTERNAL_SERVER);
        }

        filterChain.doFilter(request, response); // Filtreyi geç
    }

    private void attachError(HttpServletRequest request, ErrorCode errorCode) {
        // Hata mesajlarını request'e ekliyoruz
        request.setAttribute("exceptionStatus", errorCode.getHttpStatusCode());
        request.setAttribute("exceptionCode", errorCode.getCode());
        request.setAttribute("exceptionMessage", errorCode.getMessage());
    }

    private void attachErrorAndClearAuthContext(HttpServletRequest request, ErrorCode errorCode) {
        // Hata mesajlarını ekleyip, SecurityContext'i temizliyoruz
        attachError(request, errorCode);
        SecurityContextHolder.clearContext(); // Authentication bilgilerini temizle
    }
}

5. JWT Hatalarını Yönetmek İçin AuthExceptionHandler

JWT doğrulama sırasında oluşabilecek hataları yönetmek için kullanılan AuthenticationEntryPoint, kullanıcılara doğru hata mesajları göndermek için yapılandırılır.

@Slf4j
@Component
public class AuthExceptionHandler implements AuthenticationEntryPoint {
    final ObjectMapper MAPPER = new ObjectMapper(); // JSON yanıtları için ObjectMapper

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException, ServletException {
        log.error("Unauthorized error: {}", authException.getMessage()); // Hata mesajını logluyoruz

        response.setContentType(MediaType.APPLICATION_JSON_VALUE); // Yanıt türünü JSON olarak belirliyoruz
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); // HTTP 401 (Unauthorized) durum kodu

        final Map<String, Object> body = new HashMap<>(); // Yanıt için hata bilgilerini içeren bir map

        // Eğer hata bilgileri request içinde varsa, bunları alıp JSON yanıt olarak gönderiyoruz
        if (request.getAttribute("exceptionCode") != null &&
            request.getAttribute("exceptionMessage") != null &&
            request.getAttribute("exceptionStatus") != null) {
            body.put("code", request.getAttribute("exceptionCode").toString());
            body.put("message", request.getAttribute("exceptionMessage").toString());
            body.put("status", Integer.parseInt(request.getAttribute("exceptionStatus").toString()));
        } else {
            // Eğer hata bilgileri yoksa, genel bir yetkilendirme hatası mesajı gönderiyoruz
            body.put("code", ErrorCode.AUTHENTICATION_REQUIRED.getCode());
            body.put("message", ErrorCode.AUTHENTICATION_REQUIRED.getMessage());
            body.put("status", ErrorCode.AUTHENTICATION_REQUIRED.getHttpStatusCode());
        }

        // JSON yanıtı gönder
        MAPPER.writeValue(response.getOutputStream(), body);
    }
}

6. Spring Security Yapılandırması: SecurityConfig

Son olarak, JWT doğrulama filtremizi ve hata yönetimi sınıfımızı Spring Security yapılandırmasına dahil ediyoruz. Bu yapılandırma, tüm uygulama genelinde güvenliği sağlayacak şekilde filtre ve doğrulama işlemleri yapar.

@RequiredArgsConstructor
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    private final AuthTokenFilter authTokenFilter; // AuthTokenFilter, her gelen istekte JWT doğrulamasını yapacak
    private final AuthExceptionHandler authExceptionHandler; // AuthExceptionHandler, hata mesajlarını yönetir

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity httpSecurity) throws Exception {
        return httpSecurity
                .exceptionHandling(customizer -> customizer.authenticationEntryPoint(authExceptionHandler)) // Hata yönetimi sınıfını kullan
                .addFilterBefore(authTokenFilter, BasicAuthenticationFilter.class) // JWT doğrulama filtresini yerleştir
                .csrf(AbstractHttpConfigurer::disable) // CSRF korumasını devre dışı bırak
                .sessionManagement(customizer -> customizer.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) // Stateless oturum yönetimi
                .authorizeHttpRequests(requests -> requests
                        .requestMatchers("/api/auth/*").permitAll() // Kimlik doğrulaması gerektirmeyen yollar
                        .anyRequest().authenticated()) // Diğer tüm isteklerde kimlik doğrulaması gerektir
                .build(); // Yapılandırmayı uygula
    }
}

Sonuç

Bu yazıda, Spring Boot uygulamalarında JWT tabanlı kimlik doğrulama ve yetkilendirme işlemleri nasıl yapılır, bunu inceledik. JWT'nin oluşturulması, doğrulanması, güvenlik filtreleri ve hata yönetimi gibi temel adımları olabildiğince yalın ve detaylı anlatmaya çalıştım. Sorularınız için benimle iletişime geçebilirsiniz.

Are you seeking a cutting-edge solution for your data management needs? Look no further than Couchbase, the heavyweight champion in the realm of NoSQL databases. In this article, we will delve into the reasons why Couchbase stands head and shoulders above the rest, and why it should be your top choice for modern data storage and retrieval.

Lightning-Fast Performance

Couchbase is renowned for its lightning-fast performance, providing unparalleled speed and efficiency in handling large volumes of data. Its innovative memory-first architecture ensures that data access is swift and seamless, making it the go-to choice for applications requiring real-time responsiveness.

Click to see more details on offical document

Scalability at its Finest

One of the standout features of Couchbase is its exceptional scalability. Whether you're a small startup experiencing rapid growth or a large enterprise handling massive amounts of data, Couchbase can effortlessly scale to meet your evolving needs. Say goodbye to bottlenecks and limitations – with Couchbase, the sky's the limit.

Built for High Availability

In today's fast-paced digital landscape, downtime is simply not an option. Couchbase is designed with high availability in mind, ensuring that your data remains accessible and secure around the clock. Its built-in replication and failover capabilities guarantee uninterrupted service, keeping your operations running smoothly without missing a beat.

Flexible Data Model

Gone are the days of rigid, inflexible data structures. Couchbase offers a flexible data model that adapts to your evolving requirements, allowing you to store and retrieve data in a way that makes sense for your applications. Whether you're dealing with structured or unstructured data, Couchbase provides the versatility you need to stay agile and responsive in a dynamic environment.

Robust Querying Capabilities

Searching for specific data within a vast database can be like finding a needle in a haystack. With Couchbase's powerful querying capabilities, locating the information you need is a breeze. Its support for SQL-like queries and indexing features simplifies the process of data retrieval, empowering you to extract insights and drive informed decision-making with ease.

Example query:

SELECT a.callsign FROM default:`travel-sample`.inventory.airline
a LIMIT 5;

Result:

{
    "requestID": "cfc095c5-d23b-4a81-a4b5-990ad445559f",
    "signature": {
        "callsign": "json"
    },
    "results": [
    {
        "callsign": "MILE-AIR"
    },
    {
        "callsign": "TXW"
    },
    {
        "callsign": "atifly"
    },
    {
        "callsign": null
    },
    {
        "callsign": "LOCAIR"
    }
    ],
    "status": "success",
    "metrics": {
        "elapsedTime": "3.197119ms",
        "executionTime": "3.086979ms",
        "resultCount": 5,
        "resultSize": 175,
        "serviceLoad": 3
    }
}

Wrapping Up

In conclusion, Couchbase emerges as the undisputed champion in the world of NoSQL databases, offering unmatched performance, scalability, availability, flexibility, and querying capabilities. By choosing Couchbase as your data management solution, you're not just making a choice – you're making a statement. Elevate your data infrastructure to new heights with Couchbase and experience the power of next-generation database technology.

So why settle for mediocrity when you can have excellence? Make the smart choice. Choose Couchbase.

For more please reach out to Couchbase Türkiye Partner: Plainex Technology

Understanding the Challenge

In a typical Node.js application, database models are defined as classes or objects representing database tables. When changes are made to these models, it's essential to reflect these changes in the database schema. Manually synchronizing each model with the database can be time consuming and error-prone, especially as the number of models grows.

The Solution: Automated Model Synchronization Script

To address this challenge, we can create a script that automatically synchronizes all models with the database. Let's break down the script step by step:

import path from 'path'
import config from 'config'
import fs from 'fs'
import { SyncOptions } from 'sequelize'

export default async function syncModels(options?: SyncOptions): Promise<void> {
    // Fetch current environment
    const currentEnv = config.get<string>('server.env')

    // Determine file extension based on environment
    const fileExtension = currentEnv === 'development' ? '.ts' : '.js'

    // Read all files in the current directory
    fs.readdirSync(__dirname)
        .filter((file) => {
            // Filter out unwanted files and select files with the correct extension
            const returnFile =
                file.indexOf('.') !== 0 &&
                file !== path.basename(__filename) &&
                path.extname(file) === fileExtension

            return returnFile
        })
        .forEach((file) => {
            // Import the model dynamically
            const model = require(path.join(__dirname, file)).default

            // Synchronize the model with the database
            model.sync(options)
        })
}

Handling Model Imports

In the past, developers commonly used sequelize.import() to load model definitions from separate files. However, this method has been deprecated see more. Instead, I recommend using native import statements or require().

// CommonJS
const ProjectModel = require('./path/to/models/project').default;

// ES Modules
import ProjectModel from './path/to/models/project'

Wrapping Up

By automating the synchronization of database models with the database schema, we can streamline the development process and reduce the risk of inconsistencies between models and the database. This script offers a convenient solution for maintaining data integrity in Node.js applications.

Feel free to integrate this script into your Node.js projects and adapt it to suit your specific requirements. Happy coding!

Correct HTML Usage

When building web pages, use semantic HTML tags correctly. Use <h1> through <h6> for headings, <ul>, <ol>, <li> for lists, and <section>, <article>, <aside> for content sections.

<h1>Main Heading</h1>
<p>This is a paragraph.</p>
<ul>
    <li>Item 1</li>
    <li>Item 2</li>
</ul>

Alternative Texts

When adding images with the <img> tag, include appropriate alternative text (alt attribute) for each image. This is important for screen readers as they cannot view images.

<img src="image.jpg" alt="A beautiful landscape image">

Labeling Forms

Add <label> tags to form fields to help users understand what they should input. Additionally, you can group form fields using <fieldset> and <legend>.

<label for="username">Username:</label>
<input type="text" id="username" name="username">

Alternatively, you can use the aria-labelledby attribute.

<label id="username-label">Username:</label>
<input type="text" aria-labelledby="username-label">

Using Aria Labels

Use ARIA (Accessible Rich Internet Applications) labels to enhance accessibility for screen reader users, especially for dynamic content and single-page applications.

<div role="navigation">
    <!-- Navigation menu content -->
</div>

For more information on how to use Aria labels, you can refer to the MDN Aria Guides.

sr-only Class

The sr-only class is used for content that is visually hidden but accessible to screen readers. It's commonly used to hide text accompanying visual elements while keeping it accessible to screen reader users.

.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0,0,0,0);
    border: 0;
}

This CSS code visually hides the content while keeping it accessible to screen readers.

For example, you can use the sr-only class for the alternative text of a button's icon:

<button>
    <span class="sr-only">More information</span>
    <i class="fas fa-info-circle"></i>
</button>

Or, for describing a link:

<a href="page.html">
  <span class="sr-only">Click for more information</span> Click here
</a>

Wrapping Up

Improving the experience of screen reader users on websites is a crucial responsibility for web developers. By following these guidelines including proper HTML usage, alternative texts, clear and concise texts, link labeling, specifying focus states, utilizing ARIA labels, keyboard accessibility, and continuous testing and feedback, we can create more accessible and user-friendly websites.

Click here to read this post in english

Ekran okuyucu kullanan kullanıcılar, interneti gezinirken bazı zorluklarla karşılaşabilirler. Bu nedenle, web geliştiricilerin, bu kullanıcıların deneyimini iyileştirmek için belirli adımlar atmaları önemlidir. İşte ekran okuyucu kullanıcılarının daha iyi bir deneyim yaşamasını sağlamak için web geliştiricilerin yapması gereken bazı önemli adımlar:

Doğru HTML Kullanımı

Web sayfalarınızı oluştururken, semantik HTML etiketlerini doğru bir şekilde kullanın. Başlıklar için <h1> ile <h6>, listeler için <ul>, <ol>, <li>, ve içerik bölmeleri için <section>, <article>, <aside> gibi etiketler kullanın.

<h1>Ana Başlık</h1>
<p>Bu bir paragraf.</p>
<ul>
    <li>Madde 1</li>
    <li>Madde 2</li>
</ul>

Alternatif Metinler

Resimlerinizi <img> etiketi ile eklerken, her resim için uygun bir alternatif metin (alt attribute) ekleyin. Bu, ekran okuyucular için önemlidir, çünkü resimleri görüntüleyemezler.

<img src="image.jpg" alt="Güzel bir manzara resmi">

Formları Etiketlemek

Form alanlarına <label> etiketleri ekleyerek kullanıcıların ne girmeleri gerektiğini anlamalarını sağlayın. Ayrıca, form alanlarını gruplamak için <fieldset> ve <legend> kullanabilirsiniz.

<label for="username">Kullanıcı Adı:</label>
<input type="text" id="username" name="username">

Farklı bir yaklaşım olarak, aria-labelledby özelliğini de kullanabilirsiniz.

<label id="username-label">Kullanıcı Adı:</label>
<input type="text" aria-labelledby="username-label">

Aria Etiketlerini Kullanmak

ARIA (Accessible Rich Internet Applications) etiketlerini kullanarak, ekran okuyucular için daha iyi erişilebilirlik sağlayın. Özellikle dinamik içerikler ve SPA'lar (Single Page Applications) için önemlidir.

<div role="navigation">
    <!-- Navigasyon menüsü içeriği -->
</div>

Aria etiketlerinin nasil kullanildigini ogrenmek icin MDN sayfasina bakabilirsiniz.

sr-only Sınıfı

sr-only sınıfı, içeriği görüntülemeyen, ancak ekran okuyucular tarafından okunabilen içerikler için kullanılır. Bu genellikle görsel öğelerin yanında bulunan metinleri gizlemek için kullanılır, ancak ekran okuyucular tarafından hala erişilebilir olmasını sağlar.

.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0,0,0,0);
    border: 0;
}

Bu CSS, içeriği ekranda görünmez hale getirir, ancak ekran okuyucular için hala erişilebilir kalır.

Örneğin, bir butonun yanında bulunan görsel ikonun alternatif metni için sr-only sınıfını kullanabilirsiniz:

<button>
    <span class="sr-only">Daha fazla bilgi</span>
    <i class="fas fa-info-circle"></i>
</button>

Ya da, linkin açıklama metni için sr-only sınıfını kullanabilirsiniz:

<a href="page.html">
  <span class="sr-only">Daha fazla bilgi almak için</span> tıklayın
</a>

Toparlamak Gerekirse

Karanlığa bürüneceğine, sende bir ışık yak!

Ekran okuyucu kullanıcılarının web sitelerindeki deneyimlerini iyileştirmek, web geliştiricilerin önemli bir sorumluluğudur. Doğru HTML kullanımı, alternatif metinler, net ve açık metinler, bağlantı tanımlama, odak durumunu belirtme, ARIA etiketleri, klavye erişilebilirliği ve sürekli test ve geri bildirimler, bu hedefe ulaşmada temel adımlardır. Bu yönergeleri takip ederek, daha erişilebilir ve kullanıcı dostu web siteleri oluşturabiliriz.

I'm Adem, a full-stack developer and architect. I've been working in software development for over 10 years. During this time, I've been involved in various projects and worked with many different technologies. Currently, I'm developing my own projects and creating content to assist other developers.

Learning new technologies and writing code is a passion of mine. Through this blog, I aim to share content on software development, technology, career, and personal development, helping people who are on the same journey as me.

Apart from coding, I love traveling, cooking, listening to music, and reading books. Additionally, exploring new cultures and meeting new people is very valuable to me. If you share similar interests, please don't hesitate to get in touch with me.

Click here to read this post in english

Herkese merhaba!

Ben Adem full-stack developer ve architect' im. 10 yılı aşkın bir süredir yazılım geliştirme alanında çalışıyorum. Bu süre zarfında birçok farklı projede yer aldım ve birçok farklı teknoloji ile çalıştım. Şu anda ise kendi projelerimi geliştirmek ve diğer geliştiricilere yardımcı olacak içerikler üretiyorum.

Yeni teknolojileri öğrenmek ve kod yazmak benim için bir tutku. Bu blogda, yazılım geliştirme, teknoloji, kariyer ve kişisel gelişim konularında içerikler paylaşıp benimle aynı yolda yürüyen insanlara yardımcı olmak istiyorum.

Kod yazmak dışında, seyahat etmeyi, yemek yapmayı, müzik dinlemeyi ve kitap okumayı çok severim. Ayrıca, yeni kültürler keşfetmek ve yeni insanlarla tanışmak benim için çok değerli. Eğer benimle aynı ilgi alanlarına sahipseniz, lütfen benimle iletişime geçmekten çekinmeyin.