DEV Community: nikosst

Sieve στο .NET: από το πρώτο φίλτρο σε ένα σωστά σχεδιασμένο API

nikosst — Tue, 10 Nov 2026 11:58:03 +0000

Υπάρχει μια απαίτηση που εμφανίζεται σχεδόν σε κάθε εφαρμογή:

«Θέλω να βλέπω μια λίστα με τα δεδομένα μου».

Μπορεί να είναι προϊόντα σε ένα ηλεκτρονικό κατάστημα, παραγγελίες σε ένα διαχειριστικό περιβάλλον, πελάτες σε ένα CRM ή εργασίες σε ένα σύστημα διαχείρισης έργων.

Στην αρχή, η υλοποίηση φαίνεται απλή. Δημιουργούμε ένα endpoint, διαβάζουμε μερικές εγγραφές από τη βάση και τις επιστρέφουμε.

Στη συνέχεια αρχίζουν οι πραγματικές ανάγκες:

«Να μπορώ να ψάχνω με βάση το όνομα».

«Να εμφανίζω μόνο συγκεκριμένες κατηγορίες».

«Να ταξινομώ με βάση την τιμή».

«Να βλέπω είκοσι αποτελέσματα κάθε φορά».

«Να μπορώ να τα συνδυάζω όλα αυτά».

Κάπως έτσι, ένα μικρό endpoint αποκτά πολλές συνθήκες, διαφορετικές διαδρομές εκτέλεσης και επαναλαμβανόμενο κώδικα. Όταν η ίδια απαίτηση εμφανιστεί σε πέντε ή δέκα διαφορετικές λίστες, το πρόβλημα γίνεται και θέμα συντήρησης.

Το Sieve προσφέρει έναν κοινό τρόπο να περιγράφουμε και να εφαρμόζουμε filtering, sorting και pagination σε ένα .NET API.

Για να το αξιοποιήσουμε σωστά, όμως, χρειάζεται να καταλάβουμε περισσότερα από το πώς εγκαθίσταται ένα NuGet package. Χρειάζεται να δούμε πώς συνδέεται με το LINQ, πότε εκτελείται το query στη βάση, ποια πεδία επιτρέπουμε στον client να χρησιμοποιήσει και ποιο είναι το κόστος αυτής της ευελιξίας.

Σε αυτό το άρθρο θα ξεκινήσουμε από τις βασικές έννοιες και θα προχωρήσουμε σταδιακά σε ένα ολοκληρωμένο παράδειγμα με ASP.NET Core, EF Core και SQLite.

Ο στόχος είναι διπλός: ένας αρχάριος να μπορεί να παρακολουθήσει τη λογική και ένας πιο έμπειρος developer να μπορεί να αξιολογήσει τις σχεδιαστικές αποφάσεις.

1. Τι είναι το Sieve

Το Sieve είναι μια βιβλιοθήκη για .NET που μας επιτρέπει να εφαρμόζουμε:

Filtering: ποια δεδομένα θέλουμε.
Sorting: με ποια σειρά τα θέλουμε.
Pagination: ποιο τμήμα των αποτελεσμάτων θέλουμε.

Η περιγραφή αυτών των επιλογών μπορεί να έρχεται μέσα από τις παραμέτρους ενός HTTP request.

Για παράδειγμα:

GET /api/products?filters=category==Accessories&sorts=priceCents&page=1&pageSize=20

Το request διαβάζεται ως:

«Επέστρεψε την πρώτη σελίδα, με έως είκοσι προϊόντα της κατηγορίας Accessories, ταξινομημένα κατά αύξουσα τιμή».

Το Sieve μετατρέπει αυτή την περιγραφή σε LINQ εκφράσεις πάνω σε ένα IQueryable.

Όταν το IQueryable προέρχεται από EF Core, ο database provider μεταφράζει τις υποστηριζόμενες εκφράσεις σε SQL.

Μπορούμε να σκεφτούμε το Sieve ως έναν μηχανισμό σύνθεσης queries με μια μικρή, συγκεκριμένη γλώσσα.

Ο τεχνικός όρος για μια τέτοια γλώσσα είναι DSL — Domain-Specific Language: μια γλώσσα σχεδιασμένη για έναν συγκεκριμένο σκοπό.

Στην περίπτωσή μας, ο σκοπός είναι η περιγραφή φίλτρων, ταξινομήσεων και σελίδων.

2. Οι βασικές έννοιες χωρίς προϋποθέσεις

Πριν περάσουμε στον κώδικα, αξίζει να ξεκαθαρίσουμε τους όρους που θα χρησιμοποιήσουμε.

API και endpoint

Ένα API είναι ένας τρόπος επικοινωνίας μεταξύ εφαρμογών.

Ένα endpoint είναι ένα συγκεκριμένο σημείο αυτού του API:

GET /api/products

Ένα frontend μπορεί να καλέσει αυτό το endpoint για να ζητήσει τα προϊόντα που θα εμφανίσει στην οθόνη.

Query parameters

Είναι οι παράμετροι που εμφανίζονται μετά το ? σε ένα URL:

?page=2&pageSize=20

Το & χωρίζει τις διαφορετικές παραμέτρους.

Στο συγκεκριμένο παράδειγμα:

Το page έχει τιμή 2.
Το pageSize έχει τιμή 20.

Filtering

Το φιλτράρισμα καθορίζει ποια δεδομένα θα συμπεριληφθούν.

Παράδειγμα:

«Θέλω προϊόντα με τιμή μεγαλύτερη ή ίση από 50 ευρώ».

Sorting

Η ταξινόμηση καθορίζει τη σειρά των αποτελεσμάτων.

Παράδειγμα:

«Θέλω πρώτα τα φθηνότερα προϊόντα».

Pagination

Η σελιδοποίηση χωρίζει τα αποτελέσματα σε μικρότερα τμήματα.

Αν υπάρχουν 1.000 προϊόντα και ζητάμε 20 ανά σελίδα:

Η πρώτη σελίδα αντιστοιχεί στις πρώτες 20 θέσεις.
Η δεύτερη στις επόμενες 20.
Η τρίτη στις επόμενες 20.

Έτσι περιορίζουμε τον όγκο δεδομένων που επιστρέφει κάθε request και διευκολύνουμε την παρουσίασή τους.

Entity

Ένα entity είναι ένα αντικείμενο που αναπαριστά δεδομένα του συστήματος.

Σε μια εφαρμογή με σχεσιακή βάση, συχνά αντιστοιχεί σε εγγραφές ενός πίνακα.

Για παράδειγμα:

public class Product
{
    public int Id { get; set; }

    public string Name { get; set; } = "";
}

DTO

Ένα DTO — Data Transfer Object είναι το αντικείμενο που επιλέγουμε να μεταφέρουμε προς τον client.

Μπορεί να περιέχει λιγότερα ή διαφορετικά πεδία από το entity.

Η βάση μπορεί να γνωρίζει εσωτερικές πληροφορίες που δεν χρειάζεται να εκτίθενται στο response.

LINQ

Το LINQ μάς επιτρέπει να περιγράφουμε queries σε C#:

products.Where(p => p.PriceCents >= 5000);

Το συγκεκριμένο query εκφράζει:

«Κράτησε μόνο τα προϊόντα με τιμή τουλάχιστον 5.000 λεπτά».

Entity Framework Core

Το EF Core είναι ένα ORM.

Συνδέει τα αντικείμενα της εφαρμογής με τα δεδομένα της βάσης και μπορεί να μεταφράζει LINQ queries σε SQL.

Το Sieve συνεργάζεται με αυτή τη διαδικασία. Η σύνδεση με τη βάση και η εκτέλεση του SQL παραμένουν ευθύνη του EF Core και του provider.

3. Ποιο πρόβλημα λύνει

Ας υποθέσουμε ότι κατασκευάζουμε ένα endpoint προϊόντων χωρίς Sieve:

var query = db.Products.AsQueryable();

if (!string.IsNullOrWhiteSpace(category))
{
    query = query.Where(p => p.Category == category);
}

if (minPriceCents.HasValue)
{
    query = query.Where(
        p => p.PriceCents >= minPriceCents.Value);
}

if (maxPriceCents.HasValue)
{
    query = query.Where(
        p => p.PriceCents <= maxPriceCents.Value);
}

if (!string.IsNullOrWhiteSpace(name))
{
    query = query.Where(
        p => p.Name.Contains(name));
}

Για ένα μικρό endpoint, αυτή είναι μια λογική και συχνά επαρκής λύση.

Η πολυπλοκότητα αυξάνεται όταν προσθέτουμε:

Περισσότερα πεδία.
Διαφορετικούς operators ανά πεδίο.
Πολλαπλά κριτήρια ταξινόμησης.
Συνδυασμούς AND και OR.
Παρόμοια συμπεριφορά σε πολλά endpoints.

Με το Sieve, η απαίτηση μπορεί να περιγραφεί ως:

filters=category==Accessories,priceCents>=5000,priceCents<=15000

Και να εφαρμοστεί με έναν κοινό μηχανισμό:

var result = sieve.Apply(model, query);

Η αξία του βρίσκεται στην τυποποίηση μιας επαναλαμβανόμενης κατηγορίας queries.

Αυτό μπορεί να προσφέρει:

Λιγότερο επαναλαμβανόμενο κώδικα.
Κοινές συμβάσεις μεταξύ endpoints.
Ευκολότερη προσθήκη επιτρεπόμενων πεδίων.
Πιο προβλέψιμη συνεργασία backend και frontend.

Υπάρχει όμως και κόστος: το API αποκτά μια γλώσσα queries που πρέπει να τεκμηριώνεται, να περιορίζεται και να συντηρείται.

4. Πώς λειτουργεί κάτω από την επιφάνεια

Η βασική ροή είναι:

HTTP request
    ↓
Παραλαβή και έλεγχος παραμέτρων
    ↓
Δημιουργία βασικού IQueryable
    ↓
Εφαρμογή filtering
    ↓
Εφαρμογή sorting
    ↓
Εφαρμογή pagination
    ↓
Επιλογή πεδίων για το response
    ↓
Μετάφραση από τον EF Core provider
    ↓
Εκτέλεση SQL
    ↓
JSON response

Το Sieve συνθέτει εκφράσεις πάνω στο query.

Η βάση εκτελεί το query όταν φτάσουμε σε μια λειτουργία που απαιτεί πραγματικά αποτελέσματα, όπως:

ToListAsync()

ή:

CountAsync()

Αυτό μας οδηγεί στην πιο σημαντική τεχνική έννοια του άρθρου.

Η διαφορά ανάμεσα σε IQueryable και φορτωμένα δεδομένα

Εξετάζουμε τον παρακάτω κώδικα:

var query = db.Products
    .Where(p => p.IsActive);

Σε αυτό το σημείο συνήθως δεν έχουμε φορτώσει προϊόντα από τη βάση.

Έχουμε δημιουργήσει την περιγραφή ενός query.

Μπορούμε να συνεχίσουμε:

query = query.Where(
    p => p.PriceCents >= 5000);

Και αργότερα να εκτελέσουμε:

var products = await query.ToListAsync();

Αυτή η αναβολή της εκτέλεσης ονομάζεται deferred execution.

Το Sieve αξιοποιεί αυτή τη δυνατότητα για να προσθέσει τις εκφράσεις του πριν εκτελεστεί το query.

Το λάθος που πρέπει να αποφεύγουμε

var products = await db.Products.ToListAsync();

var result = sieve.Apply(
    model,
    products.AsQueryable());

Εδώ τα προϊόντα έχουν ήδη φορτωθεί στη μνήμη.

Το AsQueryable() πάνω σε μια List<Product> δεν επαναφέρει το query στη βάση.

Το Sieve εφαρμόζεται πλέον στα αντικείμενα που έχουν ήδη φορτωθεί.

Για ένα endpoint που διαβάζει από βάση, η επιθυμητή σειρά είναι:

var query = db.Products.AsNoTracking();

query = sieve.Apply(model, query);

var products = await query.ToListAsync();

Αυτό προϋποθέτει ότι οι εκφράσεις που προστίθενται μπορούν να μεταφραστούν από τον συγκεκριμένο database provider.

5. Οι εκδόσεις του παραδείγματος

Το άρθρο χρησιμοποιεί:

Στοιχείο	Έκδοση
Target framework	.NET 10
Sieve	2.5.5
EF Core SQLite provider	10.0.14

Η Sieve 2.5.5 είναι έκδοση του 2022 και το package στοχεύει το .NET Standard 2.1.

Η ηλικία ενός release είναι στοιχείο που πρέπει να λαμβάνουμε υπόψη όταν αξιολογούμε μια εξάρτηση.

Πριν από υιοθέτηση σε πραγματικό project, εξετάζουμε:

Τις λειτουργίες που χρειαζόμαστε.
Την κατάσταση των releases και των σχετικών issues.
Τη συμπεριφορά με τον δικό μας database provider.
Την ευκολία μελλοντικής αντικατάστασης.
Το κόστος συντήρησης του query contract.

Η συμβατότητα του target framework δεν αποδεικνύει από μόνη της ότι κάθε συνδυασμός runtime, EF Core και provider λειτουργεί όπως περιμένουμε.

Ο κώδικας που ακολουθεί είναι εκπαιδευτικό παράδειγμα και δεν έχει εκτελεστεί ή δοκιμαστεί στο πλαίσιο αυτού του άρθρου.

6. Η σύνταξη του Sieve

Οι βασικές παράμετροι είναι:

filters
sorts
page
pageSize

Filtering

Η βασική μορφή είναι:

πεδίο operator τιμή

Στο πραγματικό query:

priceCents>=5000

Στο παράδειγμά μας, οι τιμές αποθηκεύονται ως ακέραια λεπτά του ευρώ:

5000 λεπτά = 50 ευρώ

Οι βασικοί operators

Operator	Σημασία	Παράδειγμα
`==`	Ίσο	`category==Accessories`
`!=`	Διαφορετικό	`category!=Displays`
`>`	Μεγαλύτερο	`priceCents>5000`
`>=`	Μεγαλύτερο ή ίσο	`priceCents>=5000`
`<`	Μικρότερο	`priceCents<15000`
`<=`	Μικρότερο ή ίσο	`priceCents<=15000`
`@=`	Περιέχει	`name@=Keyboard`
`_=`	Αρχίζει με	`name_=Laptop`
`_-=`	Τελειώνει σε	`name_-=Mouse`
`!@=`	Δεν περιέχει	`name!@=Cover`
`!_=`	Δεν αρχίζει με	`name!_=Laptop`
`!_-=`	Δεν τελειώνει σε	`name!_-=Mouse`

Για αρκετές λειτουργίες κειμένου υπάρχει και μορφή χωρίς διάκριση πεζών και κεφαλαίων:

name@=*keyboard

Το @=* εκφράζει contains χωρίς διάκριση πεζών και κεφαλαίων.

Υπάρχουν αντίστοιχα μορφές όπως:

==*
!=*
_=*
_-=*

AND μεταξύ φίλτρων

Το κόμμα συνδέει διαφορετικά φίλτρα:

category==Accessories,priceCents>=5000

Διαβάζεται ως:

Category == Accessories
AND
PriceCents >= 5000

OR μεταξύ τιμών

Το | περιγράφει εναλλακτικές τιμές:

category==Accessories|Displays

Διαβάζεται ως:

Category == Accessories
OR
Category == Displays

OR μεταξύ πεδίων

Μπορούμε να εφαρμόσουμε την ίδια συνθήκη σε περισσότερα πεδία:

(name|category)@=*keyboard

Η σημασία είναι:

Το Name περιέχει keyboard
OR
το Category περιέχει keyboard

Η σύνταξη καλύπτει συγκεκριμένες μορφές συνδυασμών.

Για αυθαίρετα επίπεδα ομαδοποίησης και σύνθετους Boolean κανόνες χρειάζεται ξεχωριστή αξιολόγηση ή ειδικό query contract.

Μια παγίδα με το «διαφορετικό»

Το παρακάτω μπορεί να οδηγήσει σε λάθος προσδοκίες:

category!=Accessories|Displays

Οι εναλλακτικές τιμές συνδέονται με OR.

Αν θέλουμε να αποκλείσουμε και τις δύο κατηγορίες, η σαφής μορφή είναι:

category!=Accessories,category!=Displays

Δηλαδή:

Category != Accessories
AND
Category != Displays

Sorting

Αύξουσα ταξινόμηση:

sorts=priceCents

Φθίνουσα ταξινόμηση:

sorts=-priceCents

Πολλαπλά κριτήρια:

sorts=priceCents,name

Η σειρά των κριτηρίων έχει σημασία:

Πρώτα ταξινόμηση κατά τιμή.
Σε ισοβαθμία, ταξινόμηση κατά όνομα.

Pagination

page=2&pageSize=20

Ζητάμε τη δεύτερη σελίδα, με είκοσι αποτελέσματα ανά σελίδα.

Η offset σελιδοποίηση χρησιμοποιεί τον υπολογισμό:

skip = (page - 1) × pageSize

Για τη δεύτερη σελίδα:

skip = (2 - 1) × 20 = 20

Παραλείπουμε τις πρώτες είκοσι θέσεις και παίρνουμε τις επόμενες είκοσι.

Escaping και URL encoding

Αν μια τιμή περιέχει χαρακτήρες με ειδική σημασία για το Sieve, χρειάζεται escaping:

name@=ACME\, Inc

Το \, δηλώνει ότι το κόμμα ανήκει στην τιμή.

Αυτό είναι διαφορετικό από το URL encoding, που αφορά τη μεταφορά της παραμέτρου μέσα στο URL.

Στην πράξη χρειαζόμαστε:

Σωστή σύνταξη για το Sieve.
Σωστό encoding για το HTTP request.

Στα παραδείγματα θα χρησιμοποιήσουμε το --data-urlencode του curl.

7. Τι θα κατασκευάσουμε

Θα δημιουργήσουμε ένα API καταλόγου προϊόντων:

GET /api/products

Θα υποστηρίζει:

Filtering με βάση όνομα, κατηγορία και τιμή.
Sorting με βάση αναγνωριστικό, όνομα, τιμή και ημερομηνία δημιουργίας.
Pagination.
Συνολικό πλήθος αποτελεσμάτων.
Σταθερή ταξινόμηση στις ισοβαθμίες.
Όρια στα εισερχόμενα queries.
Επιστροφή μόνο ενεργών προϊόντων.

Θα χρησιμοποιήσουμε SQLite ώστε η τοπική βάση να βρίσκεται σε ένα αρχείο.

Οι τιμές θα αποθηκεύονται ως ακέραια λεπτά του ευρώ.

Αυτή είναι μια συγκεκριμένη επιλογή για έναν κατάλογο ενός νομίσματος με δύο δεκαδικά ψηφία. Ένα σύστημα πολλών νομισμάτων ή σύνθετων οικονομικών υπολογισμών χρειάζεται ευρύτερο μοντέλο χρημάτων και κανόνες στρογγυλοποίησης.

Η δομή του project θα είναι:

SieveCatalog.Api/
├── Contracts/
│   └── ProductContracts.cs
├── Controllers/
│   └── ProductsController.cs
├── Data/
│   └── CatalogDbContext.cs
├── Models/
│   └── Product.cs
├── Properties/
│   └── launchSettings.json
├── Querying/
│   ├── CatalogSieveProcessor.cs
│   └── ProductQueryPolicy.cs
├── Program.cs
└── appsettings.json

8. Βήμα 1 — Δημιουργία του project

Χρειαζόμαστε εγκατεστημένο .NET 10 SDK.

Δημιουργούμε ένα κενό ASP.NET Core project:

dotnet new web --name SieveCatalog.Api --framework net10.0

Μπαίνουμε στον φάκελο:

cd SieveCatalog.Api

Προσθέτουμε το Sieve:

dotnet add package Sieve --version 2.5.5

Προσθέτουμε τον SQLite provider του EF Core:

dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 10.0.14

Στη συνέχεια δημιουργούμε τους φακέλους και τα αρχεία της προηγούμενης δομής.

9. Βήμα 2 — Το μοντέλο Product

Στο αρχείο Models/Product.cs:

namespace SieveCatalog.Api.Models;

public sealed class Product
{
    public int Id { get; set; }

    public string Name { get; set; } = "";

    public string Category { get; set; } = "";

    public int PriceCents { get; set; }

    public DateTime CreatedAtUtc { get; set; }

    public bool IsActive { get; set; }
}

Το IsActive θα χρησιμοποιείται από τον server για να αποφασίζει ποια προϊόντα εμφανίζονται.

Η ημερομηνία CreatedAtUtc θα χρησιμοποιείται για ταξινόμηση και στο παράδειγμα περιέχει τιμές UTC.

10. Βήμα 3 — Το DbContext και τα αρχικά δεδομένα

Στο αρχείο Data/CatalogDbContext.cs:

using Microsoft.EntityFrameworkCore;
using SieveCatalog.Api.Models;

namespace SieveCatalog.Api.Data;

public sealed class CatalogDbContext(
    DbContextOptions<CatalogDbContext> options)
    : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();

    protected override void OnModelCreating(
        ModelBuilder modelBuilder)
    {
        var product = modelBuilder.Entity<Product>();

        product.Property(p => p.Name)
            .HasMaxLength(200)
            .IsRequired();

        product.Property(p => p.Category)
            .HasMaxLength(80)
            .IsRequired();

        product.HasIndex(p => new
        {
            p.IsActive,
            p.PriceCents,
            p.Id
        });

        product.HasIndex(p => new
        {
            p.IsActive,
            p.CreatedAtUtc,
            p.Id
        });

        product.HasData(
            Seed(1, "Mechanical Keyboard", "Accessories", 8500, true),
            Seed(2, "Wireless Mouse", "Accessories", 3500, true),
            Seed(3, "USB-C Dock", "Accessories", 12000, true),
            Seed(4, "27-inch Monitor", "Displays", 26000, true),
            Seed(5, "Laptop Pro", "Computers", 140000, true),
            Seed(6, "Laptop Air", "Computers", 95000, true),
            Seed(7, "Keyboard Cover", "Accessories", 1500, true),
            Seed(8, "Retired Keyboard", "Accessories", 6500, false),
            Seed(9, "Travel Mouse", "Accessories", 3500, true)
        );
    }

    private static Product Seed(
        int id,
        string name,
        string category,
        int priceCents,
        bool isActive)
    {
        return new Product
        {
            Id = id,
            Name = name,
            Category = category,
            PriceCents = priceCents,
            IsActive = isActive,
            CreatedAtUtc = new DateTime(
                2026,
                1,
                id,
                12,
                0,
                0,
                DateTimeKind.Utc)
        };
    }
}

Το DbContext είναι το σημείο μέσω του οποίου συνθέτουμε και εκτελούμε queries για τα δεδομένα μας.

Το HasData ορίζει τα αρχικά δεδομένα του παραδείγματος.

Τα indexes είναι ενδεικτικοί υποψήφιοι για τα queries που μας ενδιαφέρουν. Η αποτελεσματικότητά τους εξαρτάται από τα πραγματικά φίλτρα, την ταξινόμηση και το execution plan.

Η ύπαρξη ενός index πρέπει να συνδέεται με συγκεκριμένο workload.

11. Βήμα 4 — Ορίζουμε τα πεδία που εκθέτει το Sieve

Το API χρειάζεται σαφή λίστα επιτρεπόμενων πεδίων.

Για το παράδειγμά μας:

Όνομα στο API	Ιδιότητα C#	Filtering	Sorting
`id`	`Id`	Όχι	Ναι
`name`	`Name`	Ναι	Ναι
`category`	`Category`	Ναι	Όχι
`priceCents`	`PriceCents`	Ναι	Ναι
`created`	`CreatedAtUtc`	Όχι	Ναι

Θα χρησιμοποιήσουμε το Fluent API του Sieve.

Στο αρχείο Querying/CatalogSieveProcessor.cs:

using Microsoft.Extensions.Options;
using Sieve.Models;
using Sieve.Services;
using SieveCatalog.Api.Models;

namespace SieveCatalog.Api.Querying;

public sealed class CatalogSieveProcessor(
    IOptions<SieveOptions> options)
    : SieveProcessor(options)
{
    protected override SievePropertyMapper MapProperties(
        SievePropertyMapper mapper)
    {
        mapper.Property<Product>(p => p.Id)
            .CanSort()
            .HasName("id");

        mapper.Property<Product>(p => p.Name)
            .CanFilter()
            .CanSort()
            .HasName("name");

        mapper.Property<Product>(p => p.Category)
            .CanFilter()
            .HasName("category");

        mapper.Property<Product>(p => p.PriceCents)
            .CanFilter()
            .CanSort()
            .HasName("priceCents");

        mapper.Property<Product>(p => p.CreatedAtUtc)
            .CanSort()
            .HasName("created");

        return mapper;
    }
}

Οι βασικές λειτουργίες είναι:

CanFilter(): επιτρέπει filtering.
CanSort(): επιτρέπει sorting.
HasName(): καθορίζει το εξωτερικό όνομα του πεδίου.

Γιατί χρησιμοποιούμε aliases

Ο client γνωρίζει το όνομα:

created

Η εφαρμογή γνωρίζει την ιδιότητα:

CreatedAtUtc

Αν αλλάξει η ονομασία της ιδιότητας C#, μπορούμε να διατηρήσουμε το εξωτερικό όνομα και να προσαρμόσουμε το mapping.

Έτσι τα query fields αντιμετωπίζονται ως μέρος του API contract.

Η εναλλακτική με attributes

Το Sieve υποστηρίζει και attributes:

using Sieve.Attributes;

public sealed class Product
{
    public int Id { get; set; }

    [Sieve(
        CanFilter = true,
        CanSort = true,
        Name = "name")]
    public string Name { get; set; } = "";
}

Για μικρά projects, αυτή είναι μια απλή επιλογή.

Το Fluent API είναι χρήσιμο όταν θέλουμε οι αποφάσεις για τα queries να συγκεντρώνονται σε ξεχωριστό σημείο.

Στο project του άρθρου συνεχίζουμε με το Fluent API.

12. Βήμα 5 — Σχεδιάζουμε request και response

Στο αρχείο Contracts/ProductContracts.cs:

using System.ComponentModel.DataAnnotations;

namespace SieveCatalog.Api.Contracts;

public sealed class ProductsQuery
{
    [StringLength(500)]
    public string? Filters { get; set; }

    [StringLength(100)]
    public string? Sorts { get; set; }

    [Range(1, 10000)]
    public int Page { get; set; } = 1;

    [Range(1, 100)]
    public int PageSize { get; set; } = 20;
}

public sealed record ProductDto(
    int Id,
    string Name,
    string Category,
    int PriceCents);

public sealed record PagedResult<T>(
    IReadOnlyList<T> Items,
    int Page,
    int PageSize,
    int TotalCount)
{
    public int TotalPages =>
        (int)Math.Ceiling(
            TotalCount / (double)PageSize);

    public bool HasNextPage =>
        Page < TotalPages;
}

Γιατί δικό μας request model

Το Sieve παρέχει ήδη το SieveModel.

Χρησιμοποιούμε δικό μας request model για να ορίσουμε:

Προεπιλεγμένη σελίδα.
Προεπιλεγμένο μέγεθος σελίδας.
Μέγιστο μέγεθος σελίδας.
Μέγιστο μήκος φίλτρων και ταξινομήσεων.

Αργότερα θα το μετατρέψουμε σε SieveModel.

Το όριο Page <= 10000 είναι επιλογή πολιτικής του συγκεκριμένου παραδείγματος.

Το κατάλληλο όριο για μια πραγματική εφαρμογή εξαρτάται από τον όγκο των δεδομένων και τον τρόπο πλοήγησης.

Γιατί DTO

Το response περιέχει μόνο τα πεδία που επιλέξαμε.

Το IsActive, για παράδειγμα, χρησιμοποιείται εσωτερικά χωρίς να εμφανίζεται στο response.

Το ποια πεδία επιστρέφονται και το ποια πεδία χρησιμοποιούνται σε φίλτρα είναι διαφορετικές αποφάσεις.

13. Βήμα 6 — Προσθέτουμε πολιτική για τα queries

Μια δυναμική γλώσσα queries χρειάζεται όρια.

Στο παράδειγμά μας θα επιτρέπουμε:

Έως τρία κριτήρια ταξινόμησης από τον client.
Έως οκτώ filter terms.
Έως τρία εναλλακτικά πεδία ανά term.
Έως δέκα εναλλακτικές τιμές ανά term.
Operators συμβατούς με τον τύπο του πεδίου.
Ακέραιες τιμές για το priceCents.

Θα προσθέτουμε επίσης το id ως κριτήριο ταξινόμησης, όταν δεν υπάρχει ήδη.

Στο αρχείο Querying/ProductQueryPolicy.cs:

using System.Globalization;
using Sieve.Models;
using SieveCatalog.Api.Contracts;

namespace SieveCatalog.Api.Querying;

public sealed class InvalidProductQueryException(
    string message) : Exception(message);

public static class ProductQueryPolicy
{
    private static readonly HashSet<string> SortFields =
        new(StringComparer.Ordinal)
        {
            "id",
            "name",
            "priceCents",
            "created"
        };

    private static readonly HashSet<string> TextOperators =
        new(StringComparer.Ordinal)
        {
            "==", "!=", "@=", "_=", "_-=",
            "!@=", "!_=", "!_-=",
            "==*", "!=*", "@=*", "_=*", "_-=*",
            "!@=*", "!_=*", "!_-=*"
        };

    private static readonly HashSet<string> NumberOperators =
        new(StringComparer.Ordinal)
        {
            "==", "!=", ">", ">=", "<", "<="
        };

    public static SieveModel Create(
        ProductsQuery request)
    {
        var sorts = string.IsNullOrWhiteSpace(request.Sorts)
            ? new List<string> { "-created" }
            : request.Sorts
                .Split(',')
                .Select(s => s.Trim())
                .ToList();

        if (sorts.Count > 3)
        {
            throw new InvalidProductQueryException(
                "Use at most 3 sort fields.");
        }

        foreach (var sort in sorts)
        {
            var name = sort.StartsWith('-')
                ? sort[1..]
                : sort;

            if (!SortFields.Contains(name))
            {
                throw new InvalidProductQueryException(
                    "Unsupported sort field.");
            }
        }

        if (!sorts.Any(s => s is "id" or "-id"))
        {
            sorts.Add("id");
        }

        var model = new SieveModel
        {
            Filters = request.Filters,
            Sorts = string.Join(',', sorts),
            Page = request.Page,
            PageSize = request.PageSize
        };

        var filters = model.GetFiltersParsed();

        if (filters is null)
        {
            return model;
        }

        if (filters.Count > 8)
        {
            throw new InvalidProductQueryException(
                "Use at most 8 filter terms.");
        }

        foreach (var term in filters)
        {
            if (string.IsNullOrEmpty(term.Operator)
                || term.Values is null
                || term.Names.Length > 3
                || term.Values.Length > 10)
            {
                throw new InvalidProductQueryException(
                    "Invalid filter or too many alternatives.");
            }

            foreach (var name in term.Names)
            {
                if (name is "name" or "category")
                {
                    if (!TextOperators.Contains(term.Operator)
                        || term.Values.Any(v => v.Length > 100))
                    {
                        throw new InvalidProductQueryException(
                            "Unsupported text filter.");
                    }
                }
                else if (name == "priceCents")
                {
                    var hasInvalidValue = term.Values.Any(
                        value => !int.TryParse(
                            value,
                            NumberStyles.Integer,
                            CultureInfo.InvariantCulture,
                            out _));

                    if (!NumberOperators.Contains(term.Operator)
                        || hasInvalidValue)
                    {
                        throw new InvalidProductQueryException(
                            "priceCents requires integers "
                            + "and a numeric operator.");
                    }
                }
                else
                {
                    throw new InvalidProductQueryException(
                        "Unsupported filter field.");
                }
            }
        }

        return model;
    }
}

Τι προσφέρει αυτό το επίπεδο

Επιτρέπουμε:

priceCents>=5000

Απορρίπτουμε:

priceCents@=cheap

Το δεύτερο request προσπαθεί να εφαρμόσει λειτουργία κειμένου πάνω σε αριθμητικό πεδίο.

Επιπλέον, το εξωτερικό όνομα είναι συγκεκριμένο:

priceCents

Η πολιτική χρησιμοποιεί ακριβή αντιστοίχιση ονομάτων. Θα ευθυγραμμίσουμε αυτή την επιλογή με το CaseSensitive: true του Sieve.

Γιατί υπάρχει πληροφορία πεδίων και στο mapping και στην policy

Το mapping απαντά:

«Ποια ιδιότητα αντιστοιχεί σε αυτό το όνομα και επιτρέπεται να χρησιμοποιηθεί;»

Η policy απαντά:

«Ποιους operators και ποια όρια επιτρέπει αυτό το endpoint;»

Στο μικρό παράδειγμα κρατάμε εμφανείς τις δύο ευθύνες.

Σε μεγαλύτερο σύστημα μπορούμε να οργανώσουμε αυτές τις πληροφορίες σε κοινά metadata, ώστε να αποφεύγονται αποκλίσεις.

Το όριο αυτού του validator

Η policy ελέγχει τα terms που επιστρέφει ο parser του Sieve.

Δεν αποτελεί ανεξάρτητο, πλήρη parser που αποδεικνύει την εγκυρότητα κάθε χαρακτήρα του αρχικού input.

Για δημόσιο API με αυστηρές απαιτήσεις γραμματικής χρειάζεται επιπλέον σχεδιασμός: αυστηρότερος έλεγχος της αρχικής σύνταξης ή περισσότερο περιορισμένο request model.

Το ThrowExceptions επίσης δεν αντικαθιστά ένα πλήρες validation contract.

14. Βήμα 7 — Ο controller

Στο αρχείο Controllers/ProductsController.cs:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using Sieve.Models;
using Sieve.Services;
using SieveCatalog.Api.Contracts;
using SieveCatalog.Api.Data;
using SieveCatalog.Api.Querying;

namespace SieveCatalog.Api.Controllers;

[ApiController]
[Route("api/products")]
public sealed class ProductsController(
    CatalogDbContext db,
    ISieveProcessor sieve) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<PagedResult<ProductDto>>> Get(
        [FromQuery] ProductsQuery request,
        CancellationToken cancellationToken)
    {
        SieveModel model;

        try
        {
            model = ProductQueryPolicy.Create(request);
        }
        catch (InvalidProductQueryException ex)
        {
            return Problem(
                statusCode: StatusCodes.Status400BadRequest,
                title: "Invalid product query",
                detail: ex.Message);
        }

        var visible = db.Products
            .AsNoTracking()
            .Where(p => p.IsActive);

        var filtered = sieve.Apply(
            model,
            visible,
            applySorting: false,
            applyPagination: false);

        var totalCount = await filtered.CountAsync(
            cancellationToken);

        var page = sieve.Apply(
            model,
            filtered,
            applyFiltering: false);

        var items = await page
            .Select(p => new ProductDto(
                p.Id,
                p.Name,
                p.Category,
                p.PriceCents))
            .ToListAsync(cancellationToken);

        return Ok(new PagedResult<ProductDto>(
            items,
            request.Page,
            request.PageSize,
            totalCount));
    }
}

Αυτό είναι το κεντρικό σημείο του παραδείγματος.

Πρώτα οι υποχρεωτικοί περιορισμοί

.Where(p => p.IsActive);

Η απόφαση ότι το endpoint εμφανίζει ενεργά προϊόντα ανήκει στον server.

Ο client μπορεί να περιορίσει περαιτέρω αυτό το σύνολο μέσω φίλτρων.

Πρώτο Apply για filtering

var filtered = sieve.Apply(
    model,
    visible,
    applySorting: false,
    applyPagination: false);

Σε αυτό το στάδιο εφαρμόζουμε μόνο τα φίλτρα.

Χρειαζόμαστε το σύνολο όλων των αποτελεσμάτων που ικανοποιούν τις συνθήκες.

Μετράμε πριν από το pagination

var totalCount = await filtered.CountAsync(
    cancellationToken);

Αν υπάρχουν 237 προϊόντα που ταιριάζουν και ζητάμε 20 ανά σελίδα:

TotalCount = 237
Items.Count <= 20

Αν μετρούσαμε μετά τη σελιδοποίηση, θα παίρναμε το πλήθος της συγκεκριμένης σελίδας.

Δεύτερο Apply για sorting και pagination

var page = sieve.Apply(
    model,
    filtered,
    applyFiltering: false);

Τα φίλτρα έχουν ήδη εφαρμοστεί.

Τώρα προσθέτουμε την ταξινόμηση και τη σελιδοποίηση.

Projection πριν από τη φόρτωση

.Select(p => new ProductDto(
    p.Id,
    p.Name,
    p.Category,
    p.PriceCents))

Αυτή η επιλογή πεδίων ονομάζεται projection.

Περιγράφουμε ποια δεδομένα χρειαζόμαστε πριν εκτελέσουμε το query.

Γιατί AsNoTracking

Το endpoint διαβάζει δεδομένα.

Το AsNoTracking() δηλώνει ότι δεν χρειαζόμαστε παρακολούθηση των entities για μεταγενέστερο update.

Στο συγκεκριμένο projection επιστρέφουμε μόνο scalar δεδομένα μέσα σε DTO, επομένως δεν επιστρέφονται entities για tracking.

Η παρουσία του AsNoTracking() κάνει επίσης σαφή την πρόθεση του query.

15. Βήμα 8 — Το Program.cs

Αντικαθιστούμε το περιεχόμενο του Program.cs:

using Microsoft.EntityFrameworkCore;
using Sieve.Models;
using Sieve.Services;
using SieveCatalog.Api.Data;
using SieveCatalog.Api.Querying;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails();

builder.Services.AddDbContext<CatalogDbContext>(options =>
{
    options.UseSqlite(
        builder.Configuration.GetConnectionString("Catalog"));
});

builder.Services.Configure<SieveOptions>(
    builder.Configuration.GetSection("Sieve"));

builder.Services.AddScoped<
    ISieveProcessor,
    CatalogSieveProcessor>();

var app = builder.Build();

app.UseExceptionHandler();

// Τοπικό εκπαιδευτικό παράδειγμα.
// Για κανονική διαχείριση schema χρησιμοποιούμε migrations.
if (app.Environment.IsDevelopment())
{
    await using var scope = app.Services.CreateAsyncScope();

    var db = scope.ServiceProvider
        .GetRequiredService<CatalogDbContext>();

    await db.Database.EnsureCreatedAsync();
}

app.MapControllers();

app.Run();

Dependency injection

Ο controller χρειάζεται:

CatalogDbContext
ISieveProcessor

Η εφαρμογή δημιουργεί και παρέχει αυτές τις υπηρεσίες μέσω του dependency injection container.

Με:

builder.Services.AddScoped<
    ISieveProcessor,
    CatalogSieveProcessor>();

δηλώνουμε ότι όπου ζητείται ISieveProcessor, θα χρησιμοποιείται ο δικός μας processor.

Γιατί Scoped

Το scoped lifetime δημιουργεί μια instance μέσα στο scope του request.

Είναι φυσική επιλογή για υπηρεσίες που συμμετέχουν στη διαχείριση ενός request και μπορούν να συνεργάζονται με άλλες scoped υπηρεσίες.

ProblemDetails

Τα ProblemDetails παρέχουν κοινή δομή για error responses.

Στον controller επιστρέφουμε τα αναγνωρισμένα validation errors ως 400 Bad Request.

Τα μη αναμενόμενα exceptions ακολουθούν τον κεντρικό χειρισμό σφαλμάτων.

EnsureCreated και migrations

Το EnsureCreatedAsync() διευκολύνει το τοπικό παράδειγμα με καινούρια βάση.

Για εφαρμογή που θα εξελίσσει το schema της χρειάζεται στρατηγική migrations.

Τα EnsureCreated και migrations δεν πρέπει να αντιμετωπίζονται ως εναλλάξιμοι μηχανισμοί αρχικοποίησης της ίδιας βάσης.

Επίσης, το EnsureCreatedAsync() δεν αποτελεί μηχανισμό εφαρμογής μεταγενέστερων αλλαγών στο schema.

16. Βήμα 9 — Το appsettings.json

Στο αρχείο appsettings.json:

{
  "ConnectionStrings": {
    "Catalog": "Data Source=catalog.db"
  },
  "Sieve": {
    "CaseSensitive": true,
    "DefaultPageSize": 20,
    "MaxPageSize": 100,
    "ThrowExceptions": true,
    "IgnoreNullsOnNotEqual": true
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Information"
    }
  }
}

Οι βασικές επιλογές:

Ρύθμιση	Ευθύνη
`CaseSensitive`	Αν τα ονόματα των πεδίων διακρίνουν πεζά και κεφαλαία
`DefaultPageSize`	Προεπιλεγμένο μέγεθος σελίδας
`MaxPageSize`	Ανώτατο πλήθος αποτελεσμάτων που επιστρέφει η σελιδοποίηση
`ThrowExceptions`	Αν τα exceptions προωθούνται αντί να καταστέλλονται
`IgnoreNullsOnNotEqual`	Επηρεάζει τη συμμετοχή των `null` στις συγκρίσεις διαφορετικότητας

Στη συγκεκριμένη έκδοση, οι προεπιλογές των DefaultPageSize και MaxPageSize είναι 0.

Χρειάζεται επομένως να ορίζουμε συνειδητά τη δική μας πολιτική.

Στο παράδειγμα τα βασικά όρια υπάρχουν και στο request model. Η ρύθμιση του processor προσθέτει ένα ακόμη επίπεδο προστασίας.

CaseSensitive και σύγκριση τιμών

Με:

"CaseSensitive": true

το:

priceCents

είναι ένα συγκεκριμένο όνομα πεδίου.

Αυτό είναι διαφορετικό από το αν:

keyboard

ταιριάζει με:

Keyboard

Η σύγκριση των τιμών επηρεάζεται από τον operator, τη μετάφραση του provider και τους κανόνες σύγκρισης της βάσης.

Για παράδειγμα:

name@=*keyboard

εκφράζει contains χωρίς διάκριση πεζών και κεφαλαίων.

Η συμπεριφορά σε γλώσσες, τόνους και ειδικούς χαρακτήρες χρειάζεται αξιολόγηση με τη συγκεκριμένη βάση.

17. Βήμα 10 — Τοπική εκκίνηση

Στο αρχείο Properties/launchSettings.json:

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5080",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Η τοπική εκκίνηση γίνεται με:

dotnet run --launch-profile http

Το development profile ενεργοποιεί την τοπική αρχικοποίηση της βάσης.

Τα παρακάτω είναι παραδείγματα κλήσεων για τον αναγνώστη.

Όλα τα ορατά προϊόντα

curl "http://localhost:5080/api/products"

Η προεπιλεγμένη ταξινόμηση γίνεται:

-created,id

Δηλαδή:

Νεότερα προϊόντα πρώτα.
Σε ίδια ημερομηνία, αύξουσα σειρά αναγνωριστικού.

Μια συγκεκριμένη κατηγορία

curl --get "http://localhost:5080/api/products" \
  --data-urlencode "filters=category==Accessories"

Τιμή μεταξύ 50 και 150 ευρώ

curl --get "http://localhost:5080/api/products" \
  --data-urlencode "filters=priceCents>=5000,priceCents<=15000" \
  --data-urlencode "sorts=priceCents"

Αναζήτηση στο όνομα

curl --get "http://localhost:5080/api/products" \
  --data-urlencode "filters=name@=*keyboard"

Συνδυασμός φίλτρου, sorting και pagination

curl --get "http://localhost:5080/api/products" \
  --data-urlencode "filters=category==Accessories" \
  --data-urlencode "sorts=priceCents" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=2"

Τα multiline παραδείγματα χρησιμοποιούν σύνταξη Bash.

Σε PowerShell μπορούμε να χρησιμοποιήσουμε μία γραμμή:

curl.exe --get "http://localhost:5080/api/products" --data-urlencode "filters=category==Accessories" --data-urlencode "sorts=priceCents" --data-urlencode "page=1" --data-urlencode "pageSize=2"

Με βάση τα αρχικά δεδομένα και τους κανόνες του παραδείγματος, το αναμενόμενο response έχει τη μορφή:

{
  "items": [
    {
      "id": 7,
      "name": "Keyboard Cover",
      "category": "Accessories",
      "priceCents": 1500
    },
    {
      "id": 2,
      "name": "Wireless Mouse",
      "category": "Accessories",
      "priceCents": 3500
    }
  ],
  "page": 1,
  "pageSize": 2,
  "totalCount": 5,
  "totalPages": 3,
  "hasNextPage": true
}

Το ανενεργό Retired Keyboard δεν συμμετέχει ούτε στα items ούτε στο συνολικό πλήθος.

18. Γιατί χρειάζεται σταθερή ταξινόμηση

Στα δεδομένα μας υπάρχουν δύο προϊόντα με ίδια τιμή:

Wireless Mouse → 3500
Travel Mouse   → 3500

Η ταξινόμηση:

sorts=priceCents

δεν καθορίζει πλήρως τη μεταξύ τους σειρά.

Η policy προσθέτει:

sorts=priceCents,id

Έτσι η ισοβαθμία λύνεται με ένα μοναδικό αναγνωριστικό.

Αυτό έχει σημασία στη σελιδοποίηση.

Χωρίς πλήρως καθορισμένη σειρά, ισότιμα αποτελέσματα μπορούν να εμφανιστούν με διαφορετική σειρά μεταξύ queries.

Η μοναδική ταξινόμηση αντιμετωπίζει την ασάφεια των ισοβαθμιών.

Οι ταυτόχρονες εισαγωγές και διαγραφές εξακολουθούν να μπορούν να μετακινήσουν τις θέσεις των δεδομένων όταν χρησιμοποιούμε offset pagination.

19. Οι αποφάσεις που χρειάζονται προσοχή σε production

19.1 Οι περιορισμοί πρόσβασης προηγούνται

Σε μια εφαρμογή πολλών οργανισμών μπορεί να υπάρχει:

TenantId

Ο οργανισμός στον οποίο έχει πρόσβαση ο χρήστης πρέπει να προκύπτει από έμπιστο server-side context.

Ένα ενδεικτικό βασικό query:

var visible = db.Products
    .AsNoTracking()
    .Where(p =>
        p.TenantId == currentTenantId
        && p.IsActive);

Στη συνέχεια εφαρμόζονται τα φίλτρα του client πάνω στο visible.

Το TenantId αυτού του παραδείγματος είναι επιπλέον πεδίο ενός διαφορετικού, multi-tenant μοντέλου.

Η ουσιαστική αρχή είναι ότι οι περιορισμοί πρόσβασης ανήκουν στον server.

Τα global query filters του EF Core μπορούν να βοηθήσουν στην εφαρμογή κοινών περιορισμών, όπως tenant isolation και soft deletion.

19.2 Ένα πεδίο μπορεί να αποκαλύπτει πληροφορία μέσω φίλτρων

Ένα ευαίσθητο πεδίο μπορεί να απουσιάζει από το DTO αλλά να παραμένει προσβάσιμο μέσω φίλτρων.

Αν ο client μπορεί να φιλτράρει πάνω σε αυτό και να βλέπει TotalCount, ίσως μπορεί να συναγάγει πληροφορίες.

Γι’ αυτό αποφασίζουμε ξεχωριστά:

Ποια πεδία επιστρέφονται.
Ποια πεδία φιλτράρονται.
Ποια πεδία ταξινομούνται.
Αν παρέχεται συνολικό πλήθος.

19.3 Το μικρό pageSize δεν εγγυάται φθηνό query

Ένα request που επιστρέφει δέκα προϊόντα μπορεί να χρειάζεται αναζήτηση σε εκατομμύρια εγγραφές.

Παράδειγμα:

filters=name@=*a

Το κόστος εξαρτάται από το φίλτρο, τα indexes, τη βάση και το πλήθος των υποψήφιων εγγραφών.

Τα όρια στο input είναι χρήσιμα. Η πραγματική απόδοση απαιτεί αξιολόγηση στα πραγματικά δεδομένα.

19.4 Το MaxPageSize χρειάζεται σαφή πολιτική

Όταν ο client ζητά υπερβολικά μεγάλο page size, μπορούμε:

Να απορρίψουμε το request.
Να το προσαρμόσουμε σε επιτρεπόμενη τιμή.

Στο παράδειγμα επιλέξαμε απόρριψη:

[Range(1, 100)]
public int PageSize { get; set; } = 20;

Έτσι το request και τα metadata έχουν την ίδια σημασία.

Αν επιλέξουμε προσαρμογή, η αποτελεσματική τιμή πρέπει να χρησιμοποιείται με συνέπεια στον υπολογισμό του offset και στο response.

Στη Sieve 2.5.5, ο υπολογισμός του Skip χρησιμοποιεί το ζητούμενο page size, ενώ το Take περιορίζεται από το μέγιστο όριο.

Η κανονικοποίηση του input πριν από το Apply αποφεύγει ασυμφωνίες αυτής της μορφής.

19.5 Το Count και τα items προκύπτουν από δύο queries

Ο controller εκτελεί:

await filtered.CountAsync(cancellationToken);

και έπειτα:

await page
    .Select(...)
    .ToListAsync(cancellationToken);

Ανάμεσα στα δύο queries μπορεί να αλλάξουν τα δεδομένα.

Σε έναν συνηθισμένο κατάλογο αυτή η χρονική απόκλιση μπορεί να είναι αποδεκτή.

Σε σύστημα που χρειάζεται αυστηρά συνεπή εικόνα εξετάζουμε transaction, isolation level και τις δυνατότητες της βάσης.

Το ακριβές συνολικό πλήθος έχει επίσης κόστος.

Ορισμένα interfaces χρειάζονται μόνο να γνωρίζουν αν υπάρχει επόμενη σελίδα. Εκεί μπορεί να ταιριάζει σχεδιασμός που ζητά ένα επιπλέον αποτέλεσμα αντί για ξεχωριστό Count.

19.6 Δεν εκτελούμε παράλληλα operations στο ίδιο DbContext

Η παρακάτω προσέγγιση πρέπει να αποφεύγεται στην ίδια instance:

var countTask = filtered.CountAsync();
var itemsTask = page.ToListAsync();

await Task.WhenAll(countTask, itemsTask);

Το EF Core δεν υποστηρίζει πολλαπλές παράλληλες λειτουργίες στο ίδιο DbContext.

Στο παράδειγμά μας οι λειτουργίες εκτελούνται διαδοχικά.

19.7 Διαχωρίζουμε τα λάθη του client από τα λάθη του server

Το:

priceCents>=abc

είναι λάθος input.

Ένα query που αποτυγχάνει επειδή ο provider δεν μεταφράζει μια έκφραση είναι διαφορετική κατηγορία προβλήματος.

Μετατρέπουμε σε 400 τα σφάλματα που αναγνωρίζει η query policy.

Τα υπόλοιπα ακολουθούν τον κεντρικό χειρισμό σφαλμάτων.

Η γενική μετατροπή κάθε exception σε 400 Bad Request δυσκολεύει τη διάγνωση προβλημάτων της εφαρμογής.

20. Απόδοση και database provider

Το Sieve οργανώνει τη σύνθεση του query.

Η απόδοση προκύπτει από το query που τελικά εκτελείται και από το περιβάλλον της βάσης.

Contains και indexes

Η αναζήτηση:

name@=Keyboard

έχει διαφορετικά χαρακτηριστικά από μια αναζήτηση με ισότητα.

Ένα συνηθισμένο index δεν επιταχύνει αυτόματα κάθε αναζήτηση υποσυμβολοσειράς.

Για πραγματικό search feature μπορεί να χρειάζονται:

Full-text search.
Ειδικά indexes του database engine.
Κανονικοποίηση κειμένου.
Ξεχωριστός σχεδιασμός αναζήτησης.

Case-insensitive αναζητήσεις

Λειτουργίες που μετατρέπουν κείμενο με ToUpper() ή ToLower() μπορούν να επηρεάσουν τη χρήση indexes.

Για ελληνικά δεδομένα πρέπει επίσης να ορίσουμε τι σημαίνει «ίδιο κείμενο»:

Αγνοούνται τα πεζά και κεφαλαία;
Αγνοούνται οι τόνοι;
Πώς αντιμετωπίζονται διαφορετικές Unicode αναπαραστάσεις;

Το @=* εκφράζει μια πρόθεση σύγκρισης.

Οι κανόνες του συνολικού search feature χρειάζονται συγκεκριμένο σχεδιασμό.

Βαθιά σελιδοποίηση

Το request:

page=5000&pageSize=100

έχει διαφορετικό κόστος από την πρώτη σελίδα.

Η offset σελιδοποίηση χρειάζεται να προσπεράσει πολλές προηγούμενες θέσεις.

Για interfaces που κινούνται κυρίως σε επόμενη και προηγούμενη σελίδα, μπορεί να είναι καταλληλότερο το keyset pagination.

Αντί να ζητάμε:

«Παράλειψε 499.900 εγγραφές».

Ζητάμε:

«Δώσε μου τις επόμενες εγγραφές μετά από αυτή τη συγκεκριμένη θέση ταξινόμησης».

Το ενσωματωμένο pagination του Sieve χρησιμοποιεί Skip και Take.

Η μετάβαση σε cursor ή keyset pagination χρειάζεται επιπλέον σχεδιασμό.

Διαφορές μεταξύ providers

Το ίδιο LINQ query μπορεί να έχει διαφορετική μετάφραση και διαφορετικούς περιορισμούς σε SQLite, SQL Server ή PostgreSQL.

Η επιλογή provider επηρεάζει:

Τους τύπους που μπορούμε να συγκρίνουμε και να ταξινομούμε.
Τη συμπεριφορά των strings.
Τον χειρισμό των null.
Τις διαθέσιμες συναρτήσεις.
Τη χρήση indexes.

Η συμπεριφορά με τη βάση που χρησιμοποιεί η εφαρμογή αποτελεί μέρος της αξιολόγησης της λύσης.

21. Custom filters για κανόνες του domain

Μερικές φορές ένα φίλτρο δεν αντιστοιχεί σε μία απλή ιδιότητα.

Η εφαρμογή μπορεί, για παράδειγμα, να ορίζει ζώνες τιμών:

Ζώνη	Κανόνας
`budget`	Κάτω από 50 ευρώ
`standard`	Από 50 έως κάτω από 200 ευρώ
`premium`	Από 200 ευρώ και πάνω

Ο client θα μπορούσε να ζητά:

PriceBand==budget|standard

Το Sieve υποστηρίζει custom filter methods μέσω του ISieveCustomFilterMethods.

Το παρακάτω είναι προαιρετική επέκταση του βασικού project.

Η custom μέθοδος

Δημιουργούμε το Querying/ProductCustomFilters.cs:

using Sieve.Services;
using SieveCatalog.Api.Models;

namespace SieveCatalog.Api.Querying;

public sealed class ProductCustomFilters
    : ISieveCustomFilterMethods
{
    public IQueryable<Product> PriceBand(
        IQueryable<Product> source,
        string op,
        string[] values)
    {
        if (op != "=="
            || values.Length == 0
            || values.Any(v =>
                v is not (
                    "budget"
                    or "standard"
                    or "premium")))
        {
            throw new ArgumentException(
                "Unsupported PriceBand filter.");
        }

        var includeBudget =
            values.Contains("budget");

        var includeStandard =
            values.Contains("standard");

        var includePremium =
            values.Contains("premium");

        return source.Where(p =>
            (includeBudget
                && p.PriceCents < 5000)
            ||
            (includeStandard
                && p.PriceCents >= 5000
                && p.PriceCents < 20000)
            ||
            (includePremium
                && p.PriceCents >= 20000));
    }
}

Τα values.Contains(...) ελέγχουν τις λίγες τιμές που έστειλε ο client.

Το query των προϊόντων παραμένει IQueryable<Product>.

Η custom μέθοδος συνθέτει τις επιλεγμένες ζώνες με OR. Αυτή η σημασιολογία είναι δική μας ευθύνη μέσα στο custom filter.

Registration

Προσθέτουμε στο Program.cs:

builder.Services.AddScoped<
    ISieveCustomFilterMethods,
    ProductCustomFilters>();

Προσαρμόζουμε επίσης τον constructor του processor:

public sealed class CatalogSieveProcessor(
    IOptions<SieveOptions> options,
    ISieveCustomFilterMethods customFilters)
    : SieveProcessor(options, customFilters)
{
    // Διατηρούμε το MapProperties
    // του βασικού παραδείγματος.
}

Επέκταση της query policy

Η υπάρχουσα policy απορρίπτει άγνωστα filter fields.

Μέσα στον έλεγχο των term.Names, πριν από το τελικό else, προσθέτουμε:

else if (name == "PriceBand")
{
    if (term.Operator != "=="
        || term.Values.Any(v =>
            v is not (
                "budget"
                or "standard"
                or "premium")))
    {
        throw new InvalidProductQueryException(
            "Unsupported PriceBand filter.");
    }
}

Η αλλαγή στην policy είναι απαραίτητη για να λειτουργήσει η επέκταση στο συγκεκριμένο project.

22. Nested properties και aliases

Σε ένα διαφορετικό μοντέλο, μια παραγγελία μπορεί να έχει πελάτη:

Order
  └── Customer
        └── Name

Το Fluent API μπορεί να χαρτογραφήσει μια nested property:

mapper.Property<Order>(o => o.Customer.Name)
    .CanFilter()
    .CanSort()
    .HasName("customer");

Ο client χρησιμοποιεί:

filters=customer@=*anna

Το Order αυτού του παραδείγματος είναι ενδεικτικό μοντέλο και δεν ανήκει στο project του καταλόγου προϊόντων.

Για relationships εξετάζουμε επίσης:

Τη συμπεριφορά των null.
Τη SQL μετάφραση.
Το κόστος των joins.
Τους κανόνες ορατότητας των σχετικών δεδομένων.

23. Πού ανήκει το Sieve στην αρχιτεκτονική

Στο εκπαιδευτικό project ο controller συντονίζει:

Τον έλεγχο του request.
Τη σύνθεση του query.
Την εκτέλεση.
Τη δημιουργία του response.

Σε μεγαλύτερη εφαρμογή, το ίδιο έργο μπορεί να μεταφερθεί σε query handler ή υπηρεσία ανάγνωσης.

Μια ενδεικτική κατανομή:

API
  └── Παραλαμβάνει το HTTP request

Application
  └── Συντονίζει την περίπτωση χρήσης

Infrastructure ή query implementation
  └── Συνεργάζεται με EF Core και Sieve

Domain
  └── Περιγράφει επιχειρησιακές έννοιες και κανόνες

Η ακριβής κατανομή εξαρτάται από την αρχιτεκτονική του project.

Ένα χρήσιμο κριτήριο είναι να περιορίζεται η γνώση του Sieve στα σημεία που συνθέτουν read queries.

Όσο περισσότερα άσχετα σημεία εξαρτώνται από μια βιβλιοθήκη, τόσο αυξάνεται το κόστος αντικατάστασής της.

Το επίπεδο απομόνωσης πρέπει να είναι ανάλογο με την πραγματική ανάγκη.

Μια μικρή εφαρμογή δεν χρειάζεται απαραίτητα περισσότερα layers.

24. Γιατί να επιλέξω το Sieve

Το Sieve αξίζει να εξεταστεί όταν:

Υπάρχουν πολλές λίστες ή διαχειριστικοί πίνακες.
Χρειάζεται κοινή σύνταξη filtering και sorting.
Οι clients χρειάζονται ελεγχόμενη ευελιξία.
Τα read queries βασίζονται σε IQueryable.
Η διαθέσιμη γλώσσα καλύπτει τις απαιτήσεις.
Η ομάδα αποδέχεται τη συντήρηση αυτού του contract.

Ένα back office με προϊόντα, πελάτες και παραγγελίες μπορεί να ωφεληθεί από κοινές συμβάσεις:

filters=...
sorts=...
page=...
pageSize=...

Αυτό διευκολύνει και τη δημιουργία κοινών frontend components.

Πότε αρκεί χειροκίνητο LINQ

Αν ένα endpoint έχει λίγα, σταθερά φίλτρα:

GET /api/products?category=Accessories&minPriceCents=5000

ένα συγκεκριμένο request model και λίγες LINQ συνθήκες μπορεί να είναι ευκολότερα στην κατανόηση και στη συντήρηση.

Η δυναμική σύνταξη έχει αξία όταν λύνει επαναλαμβανόμενη ανάγκη ευελιξίας.

Σύγκριση επιλογών

Επιλογή	Πότε αξίζει να εξεταστεί
Χειροκίνητο LINQ και συγκεκριμένα request DTOs	Λίγα, σταθερά φίλτρα και σαφείς περιπτώσεις χρήσης
Sieve	Κοινό filtering, sorting και pagination σε πολλά endpoints
OData	Ανάγκη για ευρύτερο query protocol, όπως επιλογή πεδίων και expansion συσχετίσεων
Gridify	Αξιολόγηση διαφορετικής γλώσσας δυναμικών LINQ queries
Ειδική υποδομή αναζήτησης	Relevance ranking, γλωσσική ανάλυση ή εξειδικευμένες απαιτήσεις search

Η χρήσιμη σύγκριση εξετάζει το συμβόλαιο που θέλουμε να παρέχουμε και το κόστος που μπορούμε να συντηρούμε.

25. Οι συνηθέστερες παγίδες

«Έκανα ToListAsync και μετά έβαλα Sieve»

Τα δεδομένα έχουν ήδη φορτωθεί.

Κρατάμε το query ως IQueryable μέχρι να ολοκληρωθούν οι περιορισμοί και η επιλογή πεδίων.

«Έβαλα MaxPageSize, άρα το query είναι ελαφρύ»

Το πλήθος των επιστρεφόμενων εγγραφών είναι μόνο ένα μέρος του κόστους.

Εξετάζουμε φίλτρα, count, sorting, offset και indexes.

«Το πεδίο υπάρχει στο entity, άρα μπορεί να χρησιμοποιηθεί»

Η έκθεση πεδίων είναι συνειδητή απόφαση.

Στο παράδειγμα το IsActive υπάρχει στο entity αλλά δεν εκτίθεται ως δυναμικό φίλτρο.

«Το ThrowExceptions κάνει όλο το validation»

Χρειαζόμαστε πολιτική για πεδία, operators, τιμές και όρια.

«Αφού δεν επιστρέφω το πεδίο, είναι ασφαλές να φιλτράρω πάνω του»

Τα φίλτρα και τα counts μπορούν να αποκαλύπτουν πληροφορίες έμμεσα.

«Η ταξινόμηση κατά ημερομηνία αρκεί»

Όταν υπάρχουν ίδιες ημερομηνίες, χρειάζεται επιπλέον κριτήριο που κάνει τη σειρά μοναδική.

«Ένα valid query πρέπει να βρίσκει αποτελέσματα»

Ένα έγκυρο query μπορεί να επιστρέφει κενή λίστα.

Αυτό διαφέρει από request με μη αποδεκτή τιμή ή σύνταξη.

Στο δικό μας contract, μια σελίδα πέρα από τα διαθέσιμα αποτελέσματα μπορεί να επιστρέφει:

{
  "items": [],
  "page": 10,
  "pageSize": 20,
  "totalCount": 5,
  "totalPages": 1,
  "hasNextPage": false
}

Η συμπεριφορά χρειάζεται να είναι τεκμηριωμένη και συνεπής.

26. Τι πρέπει να τεκμηριώνει το API

Η φράση «το endpoint υποστηρίζει Sieve» αφήνει πολλές σημαντικές λεπτομέρειες ανοιχτές.

Ο client χρειάζεται να γνωρίζει:

Θέμα	Παράδειγμα του άρθρου
Filterable fields	`name`, `category`, `priceCents`
Sortable fields	`id`, `name`, `priceCents`, `created`
Μονάδα τιμής	Ακέραια λεπτά του ευρώ
Default sorting	`-created,id`
Default page	`1`
Default page size	`20`
Μέγιστο page size	`100`
Validation errors	`400 Bad Request` για τα αναγνωρισμένα σφάλματα
Μηδενικά αποτελέσματα	Επιτυχές response με κενό `items`
Ορατά δεδομένα	Ενεργά προϊόντα
Συνολικό πλήθος	Μετά τα φίλτρα και πριν από το pagination

Μια αλλαγή σε αυτά τα στοιχεία μπορεί να αλλάξει τη συμπεριφορά των clients.

Το query contract αξίζει την ίδια προσοχή με τα πεδία του JSON response.

Να Θυμάσαι..

Ένα endpoint που επιστρέφει λίστες είναι ένα μικρό σύστημα αποφάσεων.

Ποια δεδομένα επιτρέπεται να δει ο χρήστης; Ποια ερωτήματα μπορεί να υποβάλει; Πώς ορίζεται η σειρά των αποτελεσμάτων; Πόση πληροφορία θα επιστρέψουμε; Ποιο κόστος είναι αποδεκτό για τη βάση;

Το Sieve μάς προσφέρει έναν κοινό μηχανισμό για ένα σημαντικό μέρος αυτής της δουλειάς. Μπορεί να μειώσει την επανάληψη, να οργανώσει τα read endpoints και να δώσει στους clients χρήσιμη ευελιξία.

Η ποιότητα της λύσης εξαρτάται από τις επιλογές γύρω από τη βιβλιοθήκη: το σωστό IQueryable, τα επιτρεπόμενα πεδία, τα όρια των requests, τη σταθερή ταξινόμηση, τη διαχείριση σφαλμάτων και τη γνώση της βάσης δεδομένων.

Για έναν junior developer, η μελέτη του Sieve είναι μια καλή αφορμή να κατανοήσει πώς ένα request μετατρέπεται σταδιακά σε query και τελικά σε δεδομένα.

Για έναν senior developer, το ενδιαφέρον βρίσκεται στο πώς αυτή η ευελιξία μετατρέπεται σε ένα σταθερό και συντηρήσιμο συμβόλαιο, με σαφείς κανόνες και προβλέψιμη συμπεριφορά.

Η απόφαση να χρησιμοποιήσουμε το Sieve είναι καλή όταν μπορούμε να εξηγήσουμε ποια επανάληψη αφαιρεί, ποια δυνατότητα προσθέτει και ποιες ευθύνες παραμένουν στην εφαρμογή μας.

Αυτή η κατανόηση μάς επιτρέπει να αξιοποιούμε ένα εργαλείο με έλεγχο — και να γνωρίζουμε πότε μια απλούστερη ή διαφορετική λύση ταιριάζει καλύτερα στο πρόβλημα που έχουμε μπροστά μας.

Deadlocks με ένα συγκεκριμένο παράδειγμα

nikosst — Wed, 04 Nov 2026 14:20:55 +0000

Η Μαρία αγοράζει από το ηλεκτρονικό κατάστημα. Ταυτόχρονα, ο Νίκος αγοράζει από το φυσικό κατάστημα.

Οι δύο εφαρμογές ενημερώνουν την ίδια βάση SQL Server.

Για κάθε αγορά πρέπει να αυξηθούν δύο στατιστικά:

Id	Στατιστικό	Τρέχουσα τιμή
`1`	Συνολικές παραγγελίες	`100`
`2`	Σημερινές παραγγελίες	`20`

Κάθε σημερινή αγορά αυξάνει και τις δύο τιμές κατά ένα.

Τα IDs προσδιορίζουν τα στατιστικά, όχι τους πελάτες. Και οι δύο αγορές ενημερώνουν τις ίδιες δύο γραμμές.

Οι αλλαγές γίνονται μέσα σε συναλλαγή

Κάθε αγορά έχει τη δική της συναλλαγή, δηλαδή ομαδοποιεί τις δύο αλλαγές ώστε να οριστικοποιηθούν μαζί.

Όταν μια συναλλαγή ενημερώσει μια γραμμή, μια δεύτερη που θέλει να ενημερώσει την ίδια γραμμή πρέπει να περιμένει την ολοκλήρωση της πρώτης.

Αυτή η προσωρινή προστασία ονομάζεται κλείδωμα lock.

Πώς εμφανίζεται το deadlock

Στο παράδειγμά μας, οι δύο εφαρμογές έχουν διαφορετική σειρά εντολών:

Ηλεκτρονικό κατάστημα: πρώτα Id=1, μετά Id=2.
Εφαρμογή ταμείου:     πρώτα Id=2, μετά Id=1.

Οι εντολές μπορούν να εκτελεστούν ως εξής

1. Το ηλεκτρονικό κατάστημα ενημερώνει το `Id=1`, χωρίς ακόμη να ολοκληρώσει τη συναλλαγή του.
2. Το ταμείο ενημερώνει το `Id=2`, χωρίς ακόμη να ολοκληρώσει τη δική του.
3. Το ηλεκτρονικό κατάστημα προσπαθεί να ενημερώσει το `Id=2`. Περιμένει το ταμείο.
4. Το ταμείο προσπαθεί να ενημερώσει το `Id=1`. Περιμένει το ηλεκτρονικό κατάστημα.

Κάθε συναλλαγή περιμένει να ολοκληρωθεί η άλλη. Καμία δεν μπορεί να συνεχίσει.

Αυτό ονομάζεται deadlock, δηλαδή αδιέξοδο από κυκλική αναμονή.

Ο SQL Server εντοπίζει το αδιέξοδο, ακυρώνει μία από τις συναλλαγές και επιστρέφει το σφάλμα 1205. Η άλλη μπορεί πλέον να συνεχίσει.

Πώς αποφεύγουμε τον συγκεκριμένο κύκλο

Αλλάζουμε τον κώδικα ώστε και οι δύο εφαρμογές να ενημερώνουν πρώτα το Id=1 και μετά το Id=2.

Το παρακάτω εκτελείται ξεχωριστά για κάθε αγορά:

BEGIN TRANSACTION;

UPDATE Counters
SET Value = Value + 1
WHERE Id = 1;

UPDATE Counters
SET Value = Value + 1
WHERE Id = 2;

COMMIT;

Τώρα η εκτέλεση μπορεί να γίνει έτσι:

Το ηλεκτρονικό κατάστημα ενημερώνει το Id=1.
Το ταμείο προσπαθεί επίσης να ενημερώσει το Id=1 και περιμένει. Η δεύτερη εντολή του, για το Id=2, δεν έχει εκτελεστεί ακόμη.
Το ηλεκτρονικό κατάστημα ενημερώνει το Id=2 και κάνει commit, δηλαδή οριστικοποιεί τις αλλαγές του.
Το ταμείο συνεχίζει ενημερώνει το Id=1, μετά το Id=2 και κάνει commit.

Εδώ περιμένει μόνο το ταμείο. Το ηλεκτρονικό κατάστημα μπορεί να ολοκληρωθεί.

Αυτή είναι απλή αναμονή, γνωστή ως blocking. Δεν υπάρχει ο προηγούμενος κύκλος.

Τι κρατάμε στην πράξη

Οι σχετικές εφαρμογές πρέπει να ενημερώνουν τα κοινά δεδομένα με συνεπή σειρά.
Κρατάμε μικρή τη διάρκεια των συναλλαγών.
Αν ακυρωθεί μια συναλλαγή λόγω deadlock, μπορούμε να επαναλάβουμε ολόκληρη την εργασία από την αρχή, με περιορισμένες προσπάθειες.
Αν τα deadlocks επαναλαμβάνονται, εξετάζουμε ποιες εντολές περιμένουν ποιες.

Η ίδια σειρά πρόσβασης αποτρέπει τον συγκεκριμένο κύκλο του παραδείγματος. Άλλοι συνδυασμοί εντολών και δεδομένων μπορεί να προκαλέσουν διαφορετικά deadlocks.

TransactionScope πότε το χρησιμοποιούμε και πώς διαφέρει από το BeginTransactionAsync

nikosst — Wed, 04 Nov 2026 14:13:30 +0000

Θέλουμε να αποθηκεύσουμε μια παραγγελία και το ιστορικό της.

Αν αποθηκευτεί η παραγγελία αλλά αποτύχει το ιστορικό, η απαίτηση της εφαρμογής μας είναι να ακυρωθούν και τα δύο.

Αυτό σημαίνει ότι θέλουμε οι δύο αποθηκεύσεις να ανήκουν στην ίδια συναλλαγή δηλαδή να οριστικοποιηθούν μαζί ή να ακυρωθούν μαζί.

Το BeginTransactionAsync() μπορεί ήδη να καλύψει αυτή την ανάγκη. Το TransactionScope προσφέρει έναν διαφορετικό τρόπο οργάνωσης της συμμετοχής στη συναλλαγή.

1. Με ένα DbContext συνήθως αρκεί το BeginTransactionAsync

Το DbContext είναι το αντικείμενο μέσω του οποίου διαβάζουμε και γράφουμε δεδομένα με το EF Core.

Στο παράδειγμα, το db είναι ένα ήδη ρυθμισμένο context και το order μια νέα παραγγελία:

await using (var transaction =
    await db.Database.BeginTransactionAsync())
{
    db.Orders.Add(order);
    await db.SaveChangesAsync();

    db.OrderHistory.Add(new OrderHistory
    {
        OrderId = order.Id,
        Message = "Δημιουργήθηκε παραγγελία"
    });

    await db.SaveChangesAsync();

    await transaction.CommitAsync();
}

Οι δύο αποθηκεύσεις χρησιμοποιούν το ίδιο db και τη συναλλαγή που ανοίξαμε σε αυτό.

Αν αποτύχει η δεύτερη αποθήκευση και βγούμε από το μπλοκ χωρίς commit, η ενεργή συναλλαγή ακυρώνεται.

Δεν χρειαζόμαστε TransactionScope μόνο και μόνο επειδή έχουμε δύο αποθηκεύσεις.

Το ίδιο ισχύει αν μεταφέρουμε τις αποθηκεύσεις σε διαφορετικές μεθόδους: εφόσον χρησιμοποιούν το ίδιο context και την ίδια ενεργή συναλλαγή, παραμένουν μαζί.

2. Ποια ανάγκη καλύπτει το TransactionScope

Ας αλλάξουμε λίγο το παράδειγμα:

Η παραγγελία αποθηκεύεται μέσω EF Core.
Ένα παλιότερο κομμάτι της εφαρμογής γράφει το ιστορικό απευθείας με SQL.

Έχουμε δύο τρόπους αποθήκευσης που πρέπει να συμφωνούν.

Μπορούμε να τους συνδέσουμε στην ίδια συναλλαγή δίνοντας ρητά την κοινή σύνδεση και τη συναλλαγή όπου χρειάζεται.

Το TransactionScope προσφέρει μια άλλη επιλογή: κάνει διαθέσιμη μια κοινή συναλλαγή όσο εκτελείται ο κώδικας μέσα στο scope.

Το κρίσιμο σημείο είναι ο τρόπος συμμετοχής.

Για SQL Server, η βιβλιοθήκη Microsoft.Data.SqlClient χειρίζεται τη σύνδεση της εφαρμογής με τη βάση. Όταν ανοίξει μια σύνδεση μέσα σε ενεργό TransactionScope, μπορεί να εντοπίσει την κοινή συναλλαγή και να συμμετάσχει αυτόματα, με τις κατάλληλες ρυθμίσεις.

Έτσι, οι εντολές που εκτελούνται μέσω αυτής της σύνδεσης συμμετέχουν στη συναλλαγή χωρίς να τους δώσουμε ξεχωριστά το αντικείμενο transaction.

Αυτή η διαθέσιμη «τρέχουσα συναλλαγή» ονομάζεται ambient transaction. Τεκμηρίωση Microsoft

3. Παράδειγμα με EF Core και απευθείας SQL

Χρησιμοποιούμε μία σύνδεση προς SQL Server και για τις δύο αποθηκεύσεις.

Πριν δούμε τον κώδικα:

connectionString: τα στοιχεία σύνδεσης προς τη βάση.
SqlConnection: το αντικείμενο που χειρίζεται αυτή τη σύνδεση.
options: οι ρυθμίσεις που λένε στο EF να χρησιμοποιήσει τη συγκεκριμένη σύνδεση.
command: μια εντολή SQL που θα στείλουμε στη βάση.

Οι επιλογές του scope σημαίνουν:

Επιλογή	Σημασία
`Required`	Χρησιμοποίησε υπάρχουσα κοινή συναλλαγή ή δημιούργησε μία.
`ReadCommitted`	Μη διαβάζεις μη οριστικοποιημένες αλλαγές άλλων συναλλαγών.
`Enabled`	Διατήρησε την κοινή συναλλαγή διαθέσιμη και μετά από `await`.

Το παράδειγμα προϋποθέτει ένα ShopDbContext που δέχεται τις ρυθμίσεις στον constructor και έναν πίνακα OrderHistory με πεδία OrderId και Message.

using Microsoft.Data.SqlClient;
using Microsoft.EntityFrameworkCore;
using System.Transactions;

try
{
    using (var scope = new TransactionScope(
        TransactionScopeOption.Required,
        new TransactionOptions
        {
            IsolationLevel =
                System.Transactions.IsolationLevel.ReadCommitted
        },
        TransactionScopeAsyncFlowOption.Enabled))
    {
        await using (var connection =
            new SqlConnection(connectionString))
        {
            await connection.OpenAsync();

            var options =
                new DbContextOptionsBuilder<ShopDbContext>()
                    .UseSqlServer(connection)
                    .Options;

            await using var db = new ShopDbContext(options);

            // Πρώτη αποθήκευση: μέσω EF Core.
            db.Orders.Add(order);
            await db.SaveChangesAsync();

            // Δεύτερη αποθήκευση: απευθείας SQL.
            await using var command = connection.CreateCommand();

            command.CommandText =
                "INSERT INTO OrderHistory (OrderId, Message) " +
                "VALUES (@orderId, N'Δημιουργήθηκε παραγγελία');";

            command.Parameters.AddWithValue("@orderId", order.Id);

            await command.ExecuteNonQueryAsync();
        }

        scope.Complete();
    }
}
catch (Exception ex)
{
    Console.Error.WriteLine(ex.Message);
    throw;
}

Η παράμετρος @orderId μεταφέρει το ID της παραγγελίας στην SQL εντολή.

Παρατήρησε ότι:

Δημιουργούμε πρώτα το scope.
Ανοίγουμε τη σύνδεση μέσα σε αυτό.
Το EF και η απευθείας SQL χρησιμοποιούν την ίδια σύνδεση.
Καλούμε Complete() μόνο αφού πετύχουν και οι δύο αποθηκεύσεις.

Δεν καλούμε BeginTransactionAsync() μέσα στο scope. Η σύνδεση έχει ήδη συμμετάσχει στη συναλλαγή του.

4. Τι γίνεται σε επιτυχία ή αποτυχία

Αν αποτύχει η SQL εντολή του ιστορικού, η εκτέλεση δεν φτάνει στο Complete().

Βγαίνουμε από το using και η συναλλαγή ακυρώνεται. Ακυρώνεται επομένως και η παραγγελία που έγραψε το EF.

Το catch καταγράφει και προωθεί το σφάλμα. Δεν χρειάζεται να καλέσει ξεχωριστά RollbackAsync() για τη συναλλαγή του scope.

Αν πετύχουν όλα, το Complete() δηλώνει ότι η εργασία ολοκληρώθηκε επιτυχώς.

Το Complete δεν σημαίνει ότι έγινε ήδη το τελικό commit.

Αν το scope δημιούργησε τη συναλλαγή, η διαδικασία του commit γίνεται στην έξοδο από το using. Αν συμμετέχει σε εξωτερική συναλλαγή, η τελική ολοκλήρωση εξαρτάται από εκείνον που την ελέγχει. Τεκμηρίωση Microsoft

5. Θα μπορούσαμε να χρησιμοποιήσουμε BeginTransactionAsync και εδώ;

Ναι.

Θα χρειαζόταν να χρησιμοποιήσουμε την ίδια σύνδεση και να δώσουμε την ανοιχτή συναλλαγή στην απευθείας SQL εντολή.

Η Microsoft παρουσιάζει και αυτόν τον τρόπο συνδυασμού EF Core και SQL. Κοινή συναλλαγή μεταξύ διαφορετικών τρόπων πρόσβασης

Η επιλογή επομένως είναι:

Τρόπος	Πώς συμμετέχουν οι εντολές
`BeginTransactionAsync()`	Ανοίγουμε μια συγκεκριμένη συναλλαγή και τη χρησιμοποιούμε ρητά όπου χρειάζεται.
`TransactionScope`	Οι βιβλιοθήκες που υποστηρίζουν αυτόν τον μηχανισμό μπορούν να εντοπίσουν την κοινή συναλλαγή.

Το scope μπορεί να είναι βολικό όταν περισσότερα τμήματα πρόσβασης σε δεδομένα υποστηρίζουν αυτόν τον μηχανισμό και θέλουμε να περιορίσουμε τη μεταφορά του αντικειμένου transaction μεταξύ τους.

Για μια απλή εφαρμογή με ένα DbContext, θα ξεκινούσα συνήθως με BeginTransactionAsync().

6. Οι λεπτομέρειες που χρειάζονται προσοχή

Το scope δεν περιλαμβάνει αυτόματα κάθε ενέργεια του κώδικα. Μια αποστολή email ή μια κλήση υπηρεσίας πληρωμών δεν ακυρώνεται επειδή ακυρώθηκε η συναλλαγή της βάσης.

Η σύνδεση στο παράδειγμα ανοίγει μέσα στο scope. Αν ήταν ήδη ανοιχτή πριν από αυτό, δεν πρέπει να υποθέσουμε ότι συμμετέχει αυτόματα.

Με άλλη βάση χρειάζεται έλεγχος υποστήριξης. Η συμπεριφορά εξαρτάται από τη βιβλιοθήκη που συνδέει την εφαρμογή με τη βάση.

Πολλές συνδέσεις μπορεί να απαιτήσουν πρόσθετο συντονισμό. Μπορεί να προκύψει κατανεμημένη συναλλαγή: διαφορετικοί πόροι πρέπει να συμφωνήσουν για το κοινό commit. Στο σύγχρονο .NET, η σχετική υποστήριξη του System.Transactions είναι για Windows από .NET 7 και μπορεί να απαιτεί την υπηρεσία συντονισμού MSDTC. Το παράδειγμα χρησιμοποιεί μία σύνδεση.

Το scope δεν προσφέρει ασύγχρονο commit/rollback. Η ολοκλήρωσή του κατά την έξοδο από το using είναι συγχρονιστική.

Υποστήριξη και περιορισμοί του TransactionScope στο EF Core

Αν το TransactionScope δημιουργήσει νέα συναλλαγή και δεν επιλέξουμε διαφορετική ρύθμιση, χρησιμοποιεί Serializable. Πρόκειται για αυστηρή προστασία από ταυτόχρονες αλλαγές, βοηθά να παραμένουν έγκυρες οι αποφάσεις που βασίζονται στα δεδομένα που διαβάσαμε, αλλά μπορεί να προκαλέσει περισσότερη αναμονή. Προεπιλεγμένο επίπεδο απομόνωσης

Για να καταλάβεις τι σημαίνουν τα ReadCommitted και Serializable, διάβασε το Isolation levels με απλά παραδείγματα.

nikosstit@gmail.com

Isolation levels με απλά παραδείγματα

nikosst — Wed, 04 Nov 2026 14:12:42 +0000

Η αγορά σου διαβάζει ότι ένα προϊόν κοστίζει 100€.

Πριν ολοκληρωθεί, ένας διαχειριστής προσπαθεί να αλλάξει την τιμή σε 120€.

Χρειαζόμαστε κανόνες για το τι επιτρέπεται να διαβάσει η αγορά και πότε κάποια εργασία πρέπει να περιμένει.

Αυτούς τους κανόνες επιλέγουμε μέσω του επιπέδου απομόνωσης isolation level.

Στα παραδείγματα, η αγορά και η αλλαγή τιμής εκτελούνται σε ξεχωριστές συναλλαγές. Οι εξηγήσεις αφορούν SQL Server.

ReadCommitted βλέπουμε οριστικοποιημένες αλλαγές

Διαβάζουμε αλλαγές άλλων συναλλαγών μόνο αφού οριστικοποιηθούν, δηλαδή αφού γίνει commit.

Διαβάζουμε τιμή 100€.
Ο διαχειριστής την αλλάζει σε 120€ και κάνει commit.
Ξαναδιαβάζουμε και βρίσκουμε 120€.

Άρα, δύο αναγνώσεις μέσα στη δική μας συναλλαγή μπορούν να δώσουν διαφορετικές τιμές.

Είναι συνηθισμένη αφετηρία για καθημερινές εργασίες.

ReadUncommitted βλέπουμε και προσωρινές αλλαγές

Επιτρέπεται να διαβάσουμε μια αλλαγή πριν οριστικοποιηθεί.

Η τιμή είναι 100€.
Ο διαχειριστής την αλλάζει προσωρινά σε 80€.
Διαβάζουμε 80€.
Ο διαχειριστής ακυρώνει την αλλαγή με rollback.
Η τιμή παραμένει 100€.

Βασιστήκαμε σε μια τιμή που τελικά ακυρώθηκε.

Το χρησιμοποιούμε μόνο όταν αποδεχόμαστε συνειδητά τέτοια ασυνεπή αποτελέσματα.

RepeatableRead δεν αλλάζουν οι γραμμές που διαβάσαμε

Θέλουμε να ξαναδιαβάσουμε το ίδιο προϊόν χωρίς να έχει αλλάξει ενδιάμεσα από άλλη συναλλαγή.

Διαβάζουμε τιμή 100€.
Ο διαχειριστής προσπαθεί να την αλλάξει σε 120€.
Η αλλαγή του περιμένει.
Ξαναδιαβάζουμε και βρίσκουμε 100€.

Η προστασία διαρκεί μέχρι να ολοκληρωθεί η συναλλαγή μας.

Υπάρχει όμως ένας περιορισμός μπορούν να προστεθούν νέα προϊόντα.

Αν αναζητήσουμε όλα τα προϊόντα έως 100€, κάποιος μπορεί να προσθέσει νέο προϊόν των 90€. Στην επόμενη ίδια αναζήτηση μπορεί να εμφανιστεί και αυτό.

Τεκμηρίωση Microsoft για τα επίπεδα απομόνωσης

Serializable προστατεύουμε και τα αποτελέσματα της αναζήτησης

Έχουμε δύο υπαλλήλους που χρησιμοποιούν την ίδια εφαρμογή και βάση SQL Server:

Ο Νίκος ζητά μια αναφορά με όλα τα προϊόντα που κοστίζουν έως 100€.
Η Μαρία καταχωρίζει ένα νέο προϊόν που κοστίζει 90€.

Η εφαρμογή δημιουργεί την αναφορά μέσα σε συναλλαγή με Serializable.

Η σειρά είναι:

1. Η εφαρμογή του Νίκου ξεκινά τη συναλλαγή και διαβάζει τα προϊόντα έως 100€.
2. Πριν ολοκληρωθεί αυτή η συναλλαγή, η Μαρία πατά «Αποθήκευση» για το νέο προϊόν των 90€.
3. Η εφαρμογή στέλνει στη βάση την εντολή προσθήκης. Αυτή η εντολή περιμένει, επειδή το νέο προϊόν θα άλλαζε τα αποτελέσματα της αναζήτησης του Νίκου.
4. Αν η πρώτη συναλλαγή επαναλάβει την αναζήτηση, δεν εμφανίζεται το νέο προϊόν της Μαρίας.
5. Όταν ολοκληρωθεί η πρώτη συναλλαγή με commit, η προσθήκη της Μαρίας μπορεί να συνεχιστεί.

Η συναλλαγή διαρκεί όσο εκτελείται η εργασία στη βάση, όχι όσο ο Νίκος κοιτάζει την αναφορά στην οθόνη.

Αυτή είναι η επιπλέον προστασία του Serializable, εμποδίζει άλλες συναλλαγές να προσθέσουν αποτελέσματα στην ίδια αναζήτησή μας όσο διαρκεί η συναλλαγή.

Το κόστος είναι ότι άλλες εργασίες μπορεί να περιμένουν περισσότερο.

Snapshot διαβάζουμε μια σταθερή εικόνα

Η βάση μάς επιτρέπει να διαβάζουμε μια σταθερή αρχική εικόνα των δεδομένων, μαζί με τις δικές μας αλλαγές.

Διαβάζουμε τιμή 100€.
Ο διαχειριστής αλλάζει την τιμή σε 120€ και κάνει commit.
Ξαναδιαβάζουμε και εξακολουθούμε να βλέπουμε 100€.

Η διαφορά από το RepeatableRead είναι ότι εδώ ο διαχειριστής μπορεί να αποθηκεύσει την αλλαγή του ενώ εμείς συνεχίζουμε να διαβάζουμε την παλιότερη εικόνα.

Είναι χρήσιμο για αναφορές με πολλές αναζητήσεις που πρέπει να βασίζονται στην ίδια χρονική εικόνα.

Χρειάζεται ενεργοποίηση στη βάση. Αν επιχειρήσουμε ενημερώσεις, μπορεί να εμφανιστούν συγκρούσεις με αλλαγές άλλων συναλλαγών. Δεν παρέχει όλες τις εγγυήσεις του Serializable.

Τεκμηρίωση Microsoft για Snapshot

Πώς επιλέγουμε επίπεδο στο EF Core

Δίνουμε την επιλογή στη BeginTransactionAsync():

await using var transaction =
    await db.Database.BeginTransactionAsync(
        System.Data.IsolationLevel.ReadCommitted);

// Αναγνώσεις και αλλαγές στη βάση.

await transaction.CommitAsync();

Το ReadCommitted είναι η προεπιλογή του SQL Server. Η ακριβής συμπεριφορά του εξαρτάται και από τις ρυθμίσεις της βάσης. Τεκμηρίωση Microsoft

Επιλέγουμε επίπεδο σύμφωνα με την ανάγκη της εργασίας αν αρκούν οριστικοποιημένα δεδομένα, αν χρειαζόμαστε σταθερή εικόνα ή αν πρέπει να προστατεύσουμε μια απόφαση μέχρι να ολοκληρωθεί η συναλλαγή.

nikosstit@gmail.com

BeginTransactionAsync CommitAsync και RollbackAsync με απλό παράδειγμα

nikosst — Wed, 04 Nov 2026 14:11:48 +0000

Έστω ότι μια διαδικασία αποθηκεύει πρώτα παραγγελία και μετά τιμολόγιο.

Θέλουμε να αποθηκευτούν και τα δύο. Αν αποτύχει κάποιο βήμα, θέλουμε να ακυρωθούν οι αλλαγές της διαδικασίας.

Χρησιμοποιούμε τρεις βασικές μεθόδους:

Μέθοδος	Σημασία
`BeginTransactionAsync()`	Ξεκίνα τη συναλλαγή.
`CommitAsync()`	Οριστικοποίησε τις αλλαγές της.
`RollbackAsync()`	Ακύρωσε τις αλλαγές της.

Παράδειγμα

Το db είναι το αντικείμενο πρόσβασης στη βάση μέσω EF Core.

await using var transaction =
    await db.Database.BeginTransactionAsync();

var order = new Order
{
    ProductId = 7,
    Quantity = 2
};

db.Orders.Add(order);
await db.SaveChangesAsync();

db.Invoices.Add(new Invoice
{
    OrderId = order.Id
});

await db.SaveChangesAsync();

await transaction.CommitAsync();

Η πρώτη αποθήκευση γράφει την παραγγελία και μας δίνει το ID της.

Η δεύτερη γράφει το τιμολόγιο.

Το CommitAsync() οριστικοποιεί τη συναλλαγή.

Το await using εξασφαλίζει τον καθαρισμό της όταν φύγουμε από αυτό το τμήμα κώδικα. Αν η δεύτερη αποθήκευση αποτύχει πριν φτάσουμε στο commit, η ενεργή συναλλαγή ακυρώνεται κατά την αποδέσμευσή της.

Το SaveChanges δεν είναι το ίδιο με το Commit

Μέσα σε δικό μας transaction:

SaveChangesAsync() σημαίνει «στείλε τις αλλαγές στη βάση».
CommitAsync() σημαίνει «οριστικοποίησε τη συναλλαγή».

Το commit δεν αποθηκεύει μόνο του αλλαγές που υπάρχουν ακόμη αποκλειστικά στη μνήμη. Τεκμηρίωση Microsoft

1. Αυτόματο rollback όταν αποτύχει η διαδικασία

Αποθηκεύουμε παραγγελία και τιμολόγιο μαζί. Τα order και invoice είναι τα αντίστοιχα αντικείμενα που έχουμε ετοιμάσει.

try
{
    await using var transaction =
        await db.Database.BeginTransactionAsync();

    db.Orders.Add(order);
    await db.SaveChangesAsync();

    invoice.OrderId = order.Id;
    db.Invoices.Add(invoice);
    await db.SaveChangesAsync();

    await transaction.CommitAsync();
}
catch (Exception ex)
{
    Console.Error.WriteLine(ex.Message);
    throw;
}

Αν αποτύχει η αποθήκευση του τιμολογίου, βγαίνουμε από το try χωρίς commit.

Το await using φροντίζει να ολοκληρωθεί η χρήση της συναλλαγής. Εφόσον αυτή παραμένει ενεργή χωρίς commit, ακυρώνεται και η εισαγωγή της παραγγελίας.

Δεν χρειάζεται να προσθέσουμε ούτε RollbackAsync() ούτε finally για αυτή την ακύρωση.

Το catch εδώ καταγράφει το σφάλμα και το προωθεί. Δεν είναι αυτό που προκαλεί το αυτόματο rollback.

2. RollbackAsync όταν θέλουμε ακύρωση τώρα και συνεχίζουμε

Δημιουργούμε μια παραγγελία και επιχειρούμε να μειώσουμε το απόθεμα.

Η παρακάτω ενημέρωση γίνεται μόνο αν το απόθεμα επαρκεί. Η ExecuteUpdateAsync() επιστρέφει πόσες γραμμές ενημερώθηκαν.

Αν επιστρέψει 0, ακυρώνουμε την παραγγελία πριν συνεχίσουμε με την ενημέρωση του πελάτη.

await using var transaction =
    await db.Database.BeginTransactionAsync();

db.Orders.Add(order);
await db.SaveChangesAsync();

int updated = await db.Products
    .Where(p =>
        p.Id == order.ProductId &&
        p.Stock >= order.Quantity)
    .ExecuteUpdateAsync(setters => setters
        .SetProperty(
            p => p.Stock,
            p => p.Stock - order.Quantity));

if (updated == 0)
{
    await transaction.RollbackAsync();
}
else
{
    await transaction.CommitAsync();
}

// Η δική μας μέθοδος που ενημερώνει τον πελάτη.
await NotifyCustomerAsync(order.Id, updated == 1);

Εδώ δεν προέκυψε απαραίτητα σφάλμα. Η έλλειψη αποθέματος είναι αποτέλεσμα ελέγχου.

Καλούμε RollbackAsync() ώστε η ακύρωση να έχει ολοκληρωθεί πριν καλέσουμε την ενημέρωση του πελάτη. Δεν περιμένουμε να φτάσουμε στο τέλος του μπλοκ που περιέχει το await using.

Ο κανόνας είναι απλός:

Με await using, η ενεργή συναλλαγή ακυρώνεται αυτόματα όταν βγούμε από το μπλοκ χωρίς commit.
Καλούμε RollbackAsync() όταν θέλουμε να την ακυρώσουμε νωρίτερα, ενώ η εκτέλεση συνεχίζεται.
Μετά από επιτυχημένο commit, δεν μπορούμε να ακυρώσουμε εκείνη τη συναλλαγή με rollback.

nikosstit@gmail.com

Τι είναι ένα transaction και τι κάνει ήδη το EF Core

nikosst — Wed, 04 Nov 2026 13:13:09 +0000

Μια αγορά χρειάζεται δύο αλλαγές:

Να δημιουργηθεί η παραγγελία.
Να μειωθεί το απόθεμα.

Αν αποθηκευτεί μόνο η παραγγελία, η αγορά έχει μείνει μισή.

Ένα transaction, δηλαδή μια συναλλαγή, ομαδοποιεί αλλαγές ώστε να ολοκληρωθούν όλες μαζί ή να ακυρωθούν όλες μαζί.

Ένα απλό παράδειγμα

Θέλουμε να αποθηκεύσουμε μια παραγγελία και μια καταγραφή ιστορικού.

Το db είναι ένα ήδη ρυθμισμένο DbContext: το αντικείμενο μέσω του οποίου διαβάζουμε και γράφουμε δεδομένα με το EF Core.

db.Orders.Add(new Order
{
    ProductId = 7,
    Quantity = 2
});

db.AuditEntries.Add(new AuditEntry
{
    Message = "Δημιουργήθηκε παραγγελία"
});

await db.SaveChangesAsync();

Το Add() καταγράφει στη μνήμη τι θέλουμε να προσθέσουμε.

Το SaveChangesAsync() στέλνει τις αλλαγές στη βάση.

Με τις προεπιλεγμένες ρυθμίσεις και υποστήριξη συναλλαγών, το EF αποθηκεύει τις αλλαγές αυτής της κλήσης ατομικά: όλες μαζί ή καμία. Τεκμηρίωση Microsoft

Πότε χρειάζεται προσοχή

Δύο ξεχωριστές αποθηκεύσεις δεν αποτελούν αυτόματα μία κοινή συναλλαγή:

db.Orders.Add(order);
await db.SaveChangesAsync();

db.Invoices.Add(invoice);
await db.SaveChangesAsync();

Αν αποτύχει η δεύτερη κλήση, η παραγγελία μπορεί να έχει ήδη αποθηκευτεί.

Το ίδιο DbContext δεν σημαίνει ότι υπάρχει συνεχώς ανοιχτό transaction.

Όταν πολλά βήματα πρέπει να ολοκληρωθούν μαζί, μπορούμε να ανοίξουμε δική μας συναλλαγή. Αυτό καλύπτει το επόμενο άρθρο.

BeginTransactionAsync CommitAsync και RollbackAsync με απλό παράδειγμα

nikosstit@gmail.com

Retry με Polly v8 στο .NET: πόσες φορές χτυπάμε το κουδούνι;

nikosst — Tue, 03 Nov 2026 21:39:09 +0000

Ένας διανομέας χτυπάει το κουδούνι. Δεν ακούς. Περιμένει λίγο, ξαναχτυπάει και ανοίγεις.

Αυτό είναι το Retry: επαναλαμβάνουμε μια αποτυχημένη ενέργεια όταν υπάρχει πιθανότητα η επόμενη προσπάθεια να πετύχει.

Φυσικά, ο διανομέας χρειάζεται όριο. Ο γείτονας του τρίτου δεν χρωστάει να ακούσει όλα τα retries μας.

Στο .NET, η Polly v8 μάς βοηθά να ορίσουμε πότε ξαναπροσπαθούμε, πόσο περιμένουμε και πότε σταματάμε.

Πότε το χρησιμοποιούμε

Σε πιθανώς προσωρινές αστοχίες: ένα API κάνει restart, μια σύνδεση διακόπτεται ή ο server επιστρέφει 503 Service Unavailable.

Ένα λανθασμένο request ή ένα πρόβλημα δικαιωμάτων χρειάζεται διόρθωση. Όπως και η λάθος διεύθυνση παράδοσης.

Στο παράδειγμα θα επαναλαμβάνουμε μόνο τις κλήσεις που αποτυγχάνουν με 503.

1. Δημιουργία και NuGet

Με εγκατεστημένο .NET 10 SDK:

dotnet new console -n RetryDemo -f net10.0
cd RetryDemo
dotnet add package Polly.Core --version 8.5.2

Χρησιμοποιούμε συγκεκριμένη έκδοση της σειράς v8 για το παράδειγμα. NuGet: Polly.Core

Θα έχουμε τρία αρχεία:

RetryDemo/
├── Program.cs
├── CatalogClient.cs
└── DemoCatalogHandler.cs

2. Η πολιτική — Program.cs

Αντικαθιστούμε το υπάρχον περιεχόμενο:

using System.Net;
using Polly;
using Polly.Retry;
using Polly.Timeout;

var pipeline = new ResiliencePipelineBuilder()
    .AddTimeout(TimeSpan.FromSeconds(5))
    .AddRetry(new RetryStrategyOptions
    {
        ShouldHandle = new PredicateBuilder()
            .Handle<HttpRequestException>(exception =>
                exception.StatusCode == HttpStatusCode.ServiceUnavailable),
        MaxRetryAttempts = 2,
        Delay = TimeSpan.FromMilliseconds(200),
        BackoffType = DelayBackoffType.Exponential,
        UseJitter = true,
        OnRetry = arguments =>
        {
            Console.WriteLine($"Retry {arguments.AttemptNumber + 1}");
            return default;
        }
    })
    .Build();

using var httpClient = new HttpClient(new DemoCatalogHandler())
{
    BaseAddress = new Uri("https://catalog.example/")
};

var catalog = new CatalogClient(httpClient, pipeline);

try
{
    Console.WriteLine(await catalog.GetProductAsync(CancellationToken.None));
}
catch (Exception exception)
    when (exception is HttpRequestException or TimeoutRejectedException)
{
    Console.WriteLine("Ο κατάλογος δεν είναι διαθέσιμος.");
}

Οι ρυθμίσεις σημαίνουν:

ShouldHandle: retry μόνο για 503.
MaxRetryAttempts = 2: μία αρχική προσπάθεια και μέχρι δύο επαναλήψεις.
Delay: βασική αναμονή 200 ms.
Exponential: η αναμονή αυξάνεται.
UseJitter: οι καθυστερήσεις μεταβάλλονται ώστε πολλοί clients να μη συγχρονίζονται.

Η Polly σταματά μόλις πετύχει η κλήση ή εξαντληθούν οι επιτρεπόμενες επαναλήψεις. Polly: Retry

Το εξωτερικό AddTimeout βάζει συνολικό όριο πέντε δευτερολέπτων, μαζί με τις αναμονές. Η ακύρωση λειτουργεί συνεργατικά μέσω του cancellation token. Polly: Timeout

3. Η HTTP κλήση — CatalogClient.cs

Δημιουργούμε το αρχείο:

using Polly;

public sealed class CatalogClient(
    HttpClient httpClient,
    ResiliencePipeline pipeline)
{
    public async Task<string> GetProductAsync(CancellationToken cancellationToken)
    {
        return await pipeline.ExecuteAsync(async token =>
        {
            using var response = await httpClient.GetAsync("products/1", token);
            response.EnsureSuccessStatusCode();
            return await response.Content.ReadAsStringAsync(token);
        }, cancellationToken);
    }
}

Το ExecuteAsync εκτελεί την κλήση μέσα στην pipeline.

Το EnsureSuccessStatusCode() μετατρέπει μια αποτυχημένη HTTP απάντηση σε HttpRequestException. Αν το status είναι 503, η πολιτική επιτρέπει επανάληψη.

Κάθε προσπάθεια χρησιμοποιεί το token της pipeline και αποδεσμεύει την απάντησή της με using.

4. Η προσομοίωση — DemoCatalogHandler.cs

Για εύκολη δοκιμή, ένας HTTP handler δημιουργεί τις απαντήσεις τοπικά: δύο φορές 503 και μετά 200.

using System.Net;

public sealed class DemoCatalogHandler : HttpMessageHandler
{
    private int _attempts;

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();

        var attempt = Interlocked.Increment(ref _attempts);
        var status = attempt < 3
            ? HttpStatusCode.ServiceUnavailable
            : HttpStatusCode.OK;

        Console.WriteLine($"HTTP προσπάθεια {attempt}: {(int)status}");

        return Task.FromResult(new HttpResponseMessage(status)
        {
            Content = new StringContent("Mechanical keyboard")
        });
    }
}

Το URL του παραδείγματος είναι ενδεικτικό. Τις απαντήσεις τις δίνει ο handler.

Για πραγματικό API, χρησιμοποιούμε new HttpClient() στη θέση του new HttpClient(new DemoCatalogHandler()) και ορίζουμε την πραγματική BaseAddress.

5. Εκτέλεση

dotnet run

Αποτέλεσμα:

HTTP προσπάθεια 1: 503
Retry 1
HTTP προσπάθεια 2: 503
Retry 2
HTTP προσπάθεια 3: 200
Mechanical keyboard

Σε κάθε νέα εκκίνηση της εφαρμογής, το σενάριο ξεκινά από την αρχή.

Και η αντικαταβολή;

Αν μια πληρωμή ολοκληρωθεί αλλά χαθεί η απάντηση, ένα timeout δεν αποδεικνύει ότι η χρέωση απέτυχε.

Γι’ αυτό, σε ενέργειες που αλλάζουν δεδομένα, χρειαζόμαστε ασφαλή επανάληψη — για παράδειγμα, idempotency key που αναγνωρίζει και διαχειρίζεται σωστά ο server.

Ο διανομέας ξαναχτυπάει. Η ίδια αντικαταβολή πρέπει να καταχωριστεί μία φορά.

Πού μπαίνει στην αρχιτεκτονική

Οι ευθύνες εδώ είναι μικρές και σαφείς: το Program συνθέτει την εφαρμογή, το CatalogClient διαβάζει δεδομένα και ο δοκιμαστικός handler προσομοιώνει τον πάροχο.

Σε μια εφαρμογή με Clean Architecture, ο HTTP client και η πολιτική resilience ανήκουν στην Infrastructure. Το Application χρησιμοποιεί ένα interface για την ανάγνωση, διατηρώντας τις τεχνικές λεπτομέρειες έξω από το use case.

nikosstit@gmail.com

SOAP με απλά λόγια

nikosst — Mon, 02 Nov 2026 21:20:11 +0000

Καταλαβαίνουμε το SOAP βήμα βήμα, με ένα απλό παράδειγμα προϊόντος, XML και JSON, λίγο C# και μια καθαρή εικόνα της Clean Architecture.

Έχεις ένα ηλεκτρονικό κατάστημα και θέλεις να εμφανίσεις την τιμή ενός προϊόντος. Η τιμή βρίσκεται στο σύστημα του προμηθευτή σου. Η εφαρμογή σου πρέπει να τη ζητήσει, να πάρει μια απάντηση και να εμφανίσει το σωστό ποσό στον πελάτη.

Ας υποθέσουμε ότι ο προμηθευτής χρησιμοποιεί SOAP. Θα ακολουθήσουμε αυτή τη μία επικοινωνία από την αρχή μέχρι το τέλος: ζητάμε την τιμή του προϊόντος 123 και παίρνουμε την απάντηση 19.90 EUR.

Το SOAP είναι ένας συμφωνημένος τρόπος επικοινωνίας μεταξύ εφαρμογών. Η λέξη «πρωτόκολλο» σημαίνει εδώ ότι οι δύο πλευρές ακολουθούν κοινούς κανόνες για τα μηνύματα που ανταλλάσσουν. Το SOAP χρησιμοποιεί XML για τη μορφή αυτών των μηνυμάτων. Εισαγωγή του W3C στο SOAP.

Στο παράδειγμά μας, η επικοινωνία είναι αυτή:

Το κατάστημά μας                         Ο προμηθευτής

«Πόσο κοστίζει το προϊόν 123;»  ────────►
                              ◄────────  «Κοστίζει 19,90 ευρώ»

Οι εφαρμογές μεταφέρουν αυτή την ερώτηση και την απάντηση σε μια συγκεκριμένη δομή. Πρώτα θα καταλάβουμε την XML και μετά θα τη βάλουμε μέσα σε ένα μήνυμα SOAP.

Η XML οργανώνει τις πληροφορίες με ετικέτες. Για παράδειγμα:

<Product>
  <Id>123</Id>
  <Price>19.90</Price>
</Product>

Μπορούμε να το διαβάσουμε σαν πρόταση: «Υπάρχει ένα προϊόν. Ο κωδικός του είναι 123 και η τιμή του είναι 19.90».

Το <Product> ανοίγει το στοιχείο του προϊόντος και το </Product> το κλείνει. Μέσα του υπάρχουν δύο μικρότερα στοιχεία: το Id και το Price. Αυτή η σχέση δημιουργεί μια δομή σαν δέντρο, όπου κάθε στοιχείο μπορεί να περιέχει άλλα στοιχεία ή μια τιμή.

Τα ονόματα έχουν σημασία: το <Price> είναι διαφορετικό από το <price>, επειδή η XML ξεχωρίζει πεζά και κεφαλαία. Επίσης, κάθε στοιχείο πρέπει να κλείνει σωστά και τα στοιχεία να μπαίνουν το ένα μέσα στο άλλο με σωστή σειρά. Βασικοί κανόνες XML.

Η XML επιτρέπει και attributes, δηλαδή πρόσθετες πληροφορίες μέσα στο αρχικό tag:

<Price currency="EUR">19.90</Price>

Εδώ το 19.90 είναι το περιεχόμενο του στοιχείου Price. Το currency="EUR" είναι ένα attribute που μας λέει ότι το ποσό είναι σε ευρώ.

Το SOAP βάζει την πληροφορία μέσα σε έναν τυποποιημένο φάκελο. Στο δικό μας αίτημα θέλουμε να καλέσουμε τη λειτουργία GetPrice, δηλαδή «βρες τιμή», για το προϊόν 123:

<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:shop="urn:shop">
  <soap:Body>
    <shop:GetPrice>
      <shop:ProductId>123</shop:ProductId>
    </shop:GetPrice>
  </soap:Body>
</soap:Envelope>

Το διαβάζουμε από έξω προς τα μέσα:

Το Envelope είναι ο εξωτερικός φάκελος του μηνύματος.
Το Body είναι το μέρος που περιέχει την πληροφορία που στέλνουμε.
Το GetPrice είναι η λειτουργία που ζητάμε από την υπηρεσία.
Το ProductId δίνει τον κωδικό του προϊόντος: 123.

Το SOAP ορίζει τα Envelope και Body. Ο προμηθευτής ορίζει τα GetPrice και ProductId, σύμφωνα με τη δική του υπηρεσία. Έτσι ξέρουμε ποιο κομμάτι αφορά τον γενικό τρόπο επικοινωνίας και ποιο αφορά τη συγκεκριμένη δουλειά που θέλουμε να γίνει. Δομή μηνύματος SOAP.

Μπορεί να βλέπεις και ένα Header πριν από το Body. Είναι προαιρετικό και μεταφέρει πρόσθετες πληροφορίες για την επεξεργασία του μηνύματος. Στο απλό μας παράδειγμα δεν το χρειαζόμαστε.

Τα soap: και shop: είναι μικρά αναγνωριστικά που ξεχωρίζουν δύο ομάδες στοιχείων. Το soap: συνδέεται με τους κανόνες του SOAP και το shop: με τα στοιχεία της υπηρεσίας μας. Οι δηλώσεις xmlns δείχνουν σε ποιο namespace, δηλαδή σε ποια ομάδα ονομάτων, ανήκει κάθε prefix.

Κράτησε αυτή τη λεπτομέρεια για την ανάγνωση του XML: κάποιος μπορεί να χρησιμοποιεί s: αντί για soap:. Εφόσον το συνδέει με το ίδιο namespace, η σημασία παραμένει ίδια. Ο κώδικάς μας θα αναγνωρίζει το namespace και το όνομα του στοιχείου. Namespaces στην XML.

Το αίτημα φτάνει στη διεύθυνση της υπηρεσίας. Αυτή η διεύθυνση ονομάζεται endpoint. Στο παράδειγμά μας, η εφαρμογή στέλνει το XML με HTTP POST. Η υπηρεσία διαβάζει τον κωδικό 123, αναζητά την τιμή και επιστρέφει ένα νέο XML μήνυμα.

Χρησιμοποιούμε τη μορφή SOAP 1.1 σε όλα τα παραδείγματα, ώστε να ακολουθούμε σταθερά τους ίδιους κανόνες. Για μια πραγματική υπηρεσία, ο πάροχος δίνει το endpoint και τις απαιτούμενες ρυθμίσεις αποστολής. Μεταφορά SOAP 1.1 μέσω HTTP.

Η απάντηση της υποθετικής υπηρεσίας μας είναι:

<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:shop="urn:shop">
  <soap:Body>
    <shop:GetPriceResponse>
      <shop:Price currency="EUR">19.90</shop:Price>
    </shop:GetPriceResponse>
  </soap:Body>
</soap:Envelope>

Ο φάκελος παραμένει ίδιος. Το περιεχόμενο του Body έχει αλλάξει: τώρα περιέχει GetPriceResponse, δηλαδή την απάντηση στη λειτουργία που καλέσαμε.

Η πληροφορία που χρειαζόμαστε βρίσκεται εδώ:

<shop:Price currency="EUR">19.90</shop:Price>

Άρα, η τιμή είναι 19.90 και το νόμισμα EUR. Στο XML η δεκαδική τιμή γράφεται με τελεία· στην οθόνη μπορούμε να την εμφανίσουμε ως 19,90 €. Η διαδρομή που ακολουθούμε για να τη βρούμε είναι:

Envelope → Body → GetPriceResponse → Price

Αυτή είναι και η διαδρομή που θα ακολουθήσει ο κώδικάς μας.

Αν κάτι αποτύχει, η απάντηση μπορεί να περιέχει Fault. Για παράδειγμα, ο προμηθευτής μπορεί να επιστρέψει ένα SOAP σφάλμα όταν δεν μπορεί να επεξεργαστεί το αίτημα. Το Fault βρίσκεται μέσα στο Body και περιγράφει το πρόβλημα. Ένας κανονικός SOAP client ελέγχει και αυτή την περίπτωση. Παρακάτω θα διαβάσουμε την επιτυχημένη απάντηση του παραδείγματος. Σφάλματα SOAP.

Στο C# διαβάζουμε την απάντηση σαν δέντρο. Ας υποθέσουμε ότι η HTTP κλήση έχει ήδη ολοκληρωθεί και το XML της απάντησης βρίσκεται σε μια μεταβλητή responseXml, ως κείμενο.

using System;
using System.Xml;
using System.Xml.Linq;

var document = XDocument.Parse(responseXml);

XNamespace soap = "http://schemas.xmlsoap.org/soap/envelope/";
XNamespace shop = "urn:shop";

var priceElement = document.Root?
    .Element(soap + "Body")?
    .Element(shop + "GetPriceResponse")?
    .Element(shop + "Price");

if (priceElement is null)
    throw new InvalidOperationException("Δεν βρέθηκε τιμή στην απάντηση.");

decimal price = XmlConvert.ToDecimal(priceElement.Value);
string currency = priceElement.Attribute("currency")?.Value ?? "";

Console.WriteLine($"Τιμή: {price} {currency}");

Ας το δούμε βήμα βήμα:

Το XDocument.Parse(responseXml) διαβάζει το κείμενο και δημιουργεί ένα δέντρο XML.
Τα δύο XNamespace αντιστοιχούν στα namespaces που είδαμε στην απάντηση.
Το document.Root μάς δίνει το εξωτερικό στοιχείο, το Envelope.
Με κάθε Element(...) κατεβαίνουμε ένα επίπεδο: στο Body, μετά στο GetPriceResponse και τέλος στο Price.
Το priceElement.Value διαβάζει το κείμενο 19.90. Το XmlConvert.ToDecimal το μετατρέπει σε αριθμό τύπου decimal.
Το Attribute("currency") διαβάζει το νόμισμα EUR.

Τα ? στην αλυσίδα επιτρέπουν στην αναζήτηση να σταματήσει αν λείπει κάποιο στοιχείο. Ο έλεγχος if μάς δίνει τότε ένα κατανοητό σφάλμα, αντί να συνεχίσουμε σαν να βρήκαμε τιμή.

Έτσι, από ένα μεγάλο XML μήνυμα καταλήγουμε σε δύο απλές τιμές της εφαρμογής: έναν αριθμό και ένα νόμισμα. Ανάγνωση XML με LINQ to XML, Μετατροπή σε decimal.

Το JSON μπορεί να περιγράψει την ίδια πληροφορία με διαφορετική γραφή. Η τιμή του προϊόντος μας θα μπορούσε να εμφανίζεται έτσι:

{
  "price": 19.90,
  "currency": "EUR"
}

Το XML χρησιμοποιεί tags και attributes. Το JSON χρησιμοποιεί ονόματα πεδίων και τιμές. Για ένα τόσο απλό μήνυμα, το JSON είναι συνήθως πιο σύντομο και διαβάζεται εύκολα ως αντικείμενο.

Αυτό που θέλουμε να περιγράψουμε	XML	JSON
Τιμή προϊόντος	Περιεχόμενο του στοιχείου `Price`	Τιμή του πεδίου `price`
Νόμισμα	Attribute `currency="EUR"`	Πεδίο `"currency": "EUR"`
Οργάνωση	Στοιχεία μέσα σε άλλα στοιχεία	Αντικείμενα και πίνακες

Η βασική διάκριση είναι η εξής: XML και JSON είναι μορφές δεδομένων. Το SOAP είναι πρωτόκολλο επικοινωνίας που χρησιμοποιεί XML. Το JSON από μόνο του δεν ορίζει πού στέλνουμε ένα μήνυμα ή ποια λειτουργία θα εκτελέσει ο παραλήπτης. Προδιαγραφή JSON.

Το WSDL μάς λέει τι περιμένει η υπηρεσία. Επιστρέφοντας στον προμηθευτή μας, πρέπει κάπως να μάθουμε ότι η λειτουργία λέγεται GetPrice, ότι δέχεται ProductId και ποια μορφή έχει η απάντηση.

Αυτές τις πληροφορίες περιγράφει το WSDL, ένα αρχείο που λειτουργεί σαν τεχνικός οδηγός της υπηρεσίας. Περιλαμβάνει τις διαθέσιμες λειτουργίες, τα μηνύματα που ανταλλάσσονται και τις διευθύνσεις επικοινωνίας. Έτσι, ο προγραμματιστής μπορεί να υλοποιήσει τη σύνδεση βάσει συγκεκριμένης συμφωνίας. Περιγραφή υπηρεσιών με WSDL.

Συχνά το project περιέχει ήδη έναν client που έχει δημιουργηθεί από το WSDL. Τον αναγνωρίζεις από τις μεθόδους που αντιστοιχούν στις λειτουργίες της υπηρεσίας. Αυτός αναλαμβάνει την κατασκευή και την ανάγνωση των μηνυμάτων, ώστε ο υπόλοιπος κώδικας να καλεί συνηθισμένες μεθόδους C#. Δημιουργία SOAP client σε .NET.

Τα DTD και XSD αφορούν τους κανόνες των δεδομένων. Ένα XML μπορεί να είναι σωστά γραμμένο, αλλά να λείπει μια πληροφορία που απαιτεί η υπηρεσία. Για παράδειγμα, το αίτημα μπορεί να έχει σωστά tags αλλά να μην περιέχει κωδικό προϊόντος.

Το DTD είναι ένας τρόπος περιγραφής της επιτρεπόμενης δομής ενός XML εγγράφου. Μπορεί να ορίζει ποια στοιχεία πρέπει να υπάρχουν και με ποια σειρά. Στα μηνύματα SOAP, όμως, απαγορεύεται η δήλωση DOCTYPE, μέσω της οποίας δηλώνεται DTD. DTD στην XML, Περιορισμός στα μηνύματα SOAP.

Στα συμβόλαια SOAP συναντάμε συνήθως XSD. Το XSD μπορεί να ορίζει και τύπους δεδομένων: για παράδειγμα, ότι η τιμή είναι δεκαδικός αριθμός. Έτσι, όπου εφαρμόζεται επικύρωση με αυτό το schema, η τιμή 19.90 μπορεί να γίνει δεκτή, ενώ το κείμενο δεκαεννέα ευρώ απορρίπτεται από το ίδιο αριθμητικό πεδίο. Εισαγωγή στο XML Schema.

Οι τρεις έννοιες συνδέονται με το παράδειγμά μας ως εξής:

Έννοια	Τι μας λέει για την υπηρεσία τιμών
SOAP	Πώς οργανώνουμε το μήνυμα που ανταλλάσσουμε.
WSDL	Ποια λειτουργία καλούμε και πώς επικοινωνούμε μαζί της.
XSD	Ποια στοιχεία και ποιους τύπους δεδομένων περιμένει το συμβόλαιο.

Στην Clean Architecture δίνουμε στον κώδικα SOAP μια συγκεκριμένη θέση. Η εφαρμογή του καταστήματος χρειάζεται την τιμή του προϊόντος. Ο τρόπος με τον οποίο μιλάμε με τον προμηθευτή ανήκει στη σύνδεση με το εξωτερικό σύστημα.

Μπορούμε να οργανώσουμε αυτή τη μικρή διαδρομή ως εξής:

Μέρος της εφαρμογής	Ευθύνη στο παράδειγμά μας
Application	Ορίζει ότι χρειάζεται να μπορεί να ζητήσει την τιμή ενός προϊόντος.
Infrastructure	Καλεί την υπηρεσία SOAP και μετατρέπει την απάντηση σε δεδομένα της εφαρμογής.
API	Δέχεται το αίτημα του δικού μας χρήστη και επιστρέφει το αποτέλεσμα.

Στο Application μπορούμε να έχουμε ένα interface, δηλαδή μια συμφωνία για τη λειτουργία «βρες τιμή». Η κλάση που υλοποιεί τη σύνδεση SOAP βρίσκεται στο Infrastructure και ακολουθεί αυτή τη συμφωνία. Ο κώδικας ανάγνωσης XML που είδαμε ανήκει εκεί, μαζί με την υπόλοιπη επικοινωνία με τον προμηθευτή.

Η βασική αρχή είναι ότι ο κώδικας της επιχειρηματικής λειτουργίας εξαρτάται από αυτή τη συμφωνία. Η υλοποίηση της εξωτερικής σύνδεσης εξαρτάται επίσης από τη συμφωνία του Application. Με αυτόν τον τρόπο, η επιχειρηματική λειτουργία μπορεί να χρησιμοποιήσει διαφορετική υλοποίηση όταν αλλάξει ο τρόπος επικοινωνίας. Η αρχή των εξαρτήσεων στην Clean Architecture.

Η διαδρομή των δεδομένων είναι πλέον ξεκάθαρη:

Ο χρήστης ζητά την τιμή
          ↓
Η εφαρμογή ζητά τα δεδομένα από τον προμηθευτή
          ↓
Η σύνδεση SOAP στέλνει το XML και διαβάζει την απάντηση
          ↓
Η εφαρμογή παίρνει την τιμή 19.90 και το νόμισμα EUR
          ↓
Ο χρήστης βλέπει 19,90 €

Οι εταιρείες χρησιμοποιούν SOAP όταν εξυπηρετεί τις διασυνδέσεις τους. Μπορεί ο προμηθευτής να διαθέτει αυτή τη συγκεκριμένη υπηρεσία ή μια εταιρεία να έχει ήδη πολλές λειτουργικές συνδέσεις που βασίζονται σε αυτή. Η αλλαγή απαιτεί συντονισμό και ελέγχους, οπότε χρειάζεται αντίστοιχο όφελος για την επιχείρηση.

Για τον προγραμματιστή που αναλαμβάνει τη σύνδεση, το πρακτικό σημείο εκκίνησης είναι το ίδιο: βρίσκει ποια λειτουργία πρέπει να καλέσει, τι περιμένει το αίτημα και πού βρίσκεται η πληροφορία στην απάντηση. Στο δικό μας παράδειγμα, όλη αυτή η επικοινωνία εξυπηρετεί μία απλή ανάγκη: να εμφανιστεί η σωστή τιμή του προϊόντος στην οθόνη.

nikosstit@gmail.com

FusionCache στο .NET: Πώς ένας Barista μπορεί να μας μάθει το Caching ☕

nikosst — Sun, 01 Nov 2026 23:46:44 +0000

FusionCache στο .NET: Πώς ένας Barista μπορεί να μας μάθει το Caching ☕

Εισαγωγή

Φαντάσου ότι μπαίνεις κάθε πρωί στο ίδιο coffee shop και παραγγέλνεις τον αγαπημένο σου καφέ.

Την πρώτη φορά, ο barista σε ρωτάει:

— Τι θα θέλατε;

— Έναν cappuccino με γάλα αμυγδάλου, χωρίς ζάχαρη.

Ο barista ετοιμάζει τον καφέ και εξυπηρετεί την παραγγελία σου.

Την επόμενη ημέρα επιστρέφεις. Αυτή τη φορά, πριν προλάβεις να μιλήσεις, ο barista σε αναγνωρίζει:

— Έναν cappuccino με γάλα αμυγδάλου, χωρίς ζάχαρη;

— Ακριβώς!

Ο barista δεν χρειάστηκε να σε ρωτήσει ξανά. Θυμόταν την προηγούμενη παραγγελία σου.

Αυτή η απλή ιδέα βρίσκεται πίσω από μία από τις σημαντικότερες τεχνικές βελτιστοποίησης στις εφαρμογές: το Caching.

Στον κόσμο του .NET, μία από τις βιβλιοθήκες που μας βοηθούν να υλοποιήσουμε αυτή τη λογική είναι η FusionCache.

Σκοπός αυτού του άρθρου είναι να κατανοήσουμε τι είναι το FusionCache, γιατί το χρειαζόμαστε, πώς λειτουργεί και πώς μπορούμε να το χρησιμοποιήσουμε σε μία πραγματική εφαρμογή .NET.

1. Τι είναι το Caching;

Ας ξεκινήσουμε από τα βασικά.

Όταν μία εφαρμογή χρειάζεται δεδομένα, συνήθως τα αναζητά σε κάποια πηγή, όπως:

Μία βάση δεδομένων.
Ένα εξωτερικό API.
Ένα αρχείο.
Μία υπηρεσία άλλου συστήματος.

Για παράδειγμα, έχουμε ένα API που επιστρέφει τα στοιχεία ενός προϊόντος.

public async Task<Product?> GetProductAsync(int id)
{
    return await _dbContext.Products
        .FirstOrDefaultAsync(x => x.Id == id);
}

Κάθε φορά που καλείται αυτή η μέθοδος, εκτελείται ένα ερώτημα στη βάση δεδομένων.

Αν το ίδιο προϊόν ζητηθεί 100 φορές, η εφαρμογή μπορεί να εκτελέσει 100 φορές την ίδια αναζήτηση.

Αυτό δεν είναι απαραίτητα αποδοτικό.

Εδώ έρχεται το Caching.

Caching είναι η προσωρινή αποθήκευση δεδομένων, ώστε να μπορούμε να τα επαναχρησιμοποιήσουμε χωρίς να χρειάζεται να αναζητήσουμε ξανά την αρχική πηγή.

Αντί να ρωτάμε κάθε φορά τη βάση δεδομένων, αποθηκεύουμε προσωρινά το αποτέλεσμα.

Την επόμενη φορά που θα χρειαστούμε το ίδιο δεδομένο, το αναζητούμε πρώτα στην Cache.

Αν υπάρχει, το επιστρέφουμε αμέσως.

Αν δεν υπάρχει, αναζητούμε τα δεδομένα από την αρχική πηγή και αποθηκεύουμε το αποτέλεσμα.

Αυτή είναι η βασική ιδέα.

2. Κατανοώντας το Caching μέσα από το παράδειγμα του barista

Ας επιστρέψουμε στο coffee shop.

Θα αντιστοιχίσουμε τα βασικά στοιχεία του Caching με την καθημερινή λειτουργία του καταστήματος.

Έννοια	Παράδειγμα με τον barista
Cache	Η μνήμη του barista
Cache Key	Το αναγνωριστικό του πελάτη
Cached Value	Η αγαπημένη παραγγελία του πελάτη
Cache Hit	Ο barista θυμάται την παραγγελία
Cache Miss	Ο barista δεν θυμάται και ρωτά ξανά
Expiration	Ο barista ξεχνά την παλιά παραγγελία μετά από κάποιο διάστημα

Ας δούμε τη διαδικασία.

Πρώτη επίσκεψη — Cache Miss

Ο πελάτης παραγγέλνει για πρώτη φορά.

Ο barista δεν γνωρίζει τις προτιμήσεις του. Ρωτάει, καταγράφει την παραγγελία και την εξυπηρετεί.

Στην εφαρμογή μας, αυτό σημαίνει ότι δεν υπάρχει το ζητούμενο δεδομένο στην Cache. Επομένως, πρέπει να το αναζητήσουμε στην αρχική πηγή.

Δεύτερη επίσκεψη — Cache Hit

Ο ίδιος πελάτης επιστρέφει.

Ο barista θυμάται την παραγγελία του και δεν χρειάζεται να τον ρωτήσει ξανά.

Στην εφαρμογή μας, το δεδομένο υπάρχει ήδη στην Cache και επιστρέφεται χωρίς νέο ερώτημα στη βάση δεδομένων.

Αυτό ακριβώς θέλουμε να πετύχουμε.

3. Τι είναι το Cache Key και γιατί είναι σημαντικό;

Ο barista πρέπει να γνωρίζει σε ποιον πελάτη αντιστοιχεί κάθε παραγγελία.

Δεν αρκεί να θυμάται ότι κάποιος παραγγέλνει cappuccino. Πρέπει να γνωρίζει ποιος είναι ο συγκεκριμένος πελάτης.

Αντίστοιχα, στην εφαρμογή μας χρειαζόμαστε ένα Cache Key.

Το Cache Key είναι ένα μοναδικό αναγνωριστικό που χρησιμοποιούμε για να αποθηκεύσουμε και να αναζητήσουμε ένα δεδομένο.

Για παράδειγμα:

var cacheKey = "product:42";

Αυτό το κλειδί μπορεί να αντιστοιχεί στο προϊόν με ID 42.

Ένα άλλο προϊόν θα έχει διαφορετικό κλειδί:

var cacheKey = "product:43";

Με αυτόν τον τρόπο, μπορούμε να αποθηκεύουμε πολλά διαφορετικά δεδομένα χωρίς να μπερδεύονται μεταξύ τους.

Στην πράξη, τα Cache Keys πρέπει να σχεδιάζονται προσεκτικά. Για παράδειγμα, αν τα δεδομένα εξαρτώνται από τον χρήστη, το κλειδί μπορεί να περιλαμβάνει και το User ID.

var cacheKey = $"user:{userId}:orders";

Έτσι, οι παραγγελίες κάθε χρήστη αποθηκεύονται ξεχωριστά.

4. Τι είναι το FusionCache;

Το FusionCache είναι μία open-source βιβλιοθήκη για .NET, η οποία προσφέρει ένα πιο ολοκληρωμένο μοντέλο caching.

Δεν είναι απλώς μία αποθήκη δεδομένων.

Συνδυάζει διαφορετικούς μηχανισμούς caching και προσφέρει επιπλέον δυνατότητες, όπως:

In-memory caching.
Distributed caching.
Fail-safe.
Cache stampede protection.
Backplane notifications.
Διαχείριση λήξης δεδομένων.
Ανθεκτικότητα σε προσωρινά προβλήματα εξωτερικών υπηρεσιών.

Η βασική ιδέα είναι να έχουμε μία ενιαία προσέγγιση για το caching, χωρίς να χρειάζεται να υλοποιούμε μόνοι μας όλες αυτές τις λειτουργίες.

Για να καταλάβουμε πώς λειτουργεί, πρέπει πρώτα να γνωρίσουμε δύο βασικές έννοιες: το L1 και το L2 Cache.

5. Τι είναι το L1 και το L2 Cache;

Ας υποθέσουμε ότι το coffee shop έχει δύο τρόπους να θυμάται τις παραγγελίες.

Ο πρώτος είναι η προσωπική μνήμη κάθε barista.

Ο δεύτερος είναι ένα κοινό τετράδιο στο οποίο καταγράφονται οι παραγγελίες, ώστε να μπορούν να τις δουν όλοι οι barista.

Αυτή η αναλογία μάς βοηθά να κατανοήσουμε τα δύο επίπεδα caching.

L1 Cache — In-Memory Cache

Το L1 Cache είναι η τοπική μνήμη της εφαρμογής.

Στο παράδειγμά μας, είναι η προσωπική μνήμη του barista.

Αν ένας barista θυμάται την παραγγελία σου, μπορεί να σε εξυπηρετήσει αμέσως.

Στο .NET, τα δεδομένα αποθηκεύονται στη μνήμη της συγκεκριμένης διεργασίας (application process).

Πλεονεκτήματα:

Πολύ γρήγορη πρόσβαση.
Δεν απαιτεί επικοινωνία με εξωτερική υπηρεσία.
Μικρό latency.

Υπάρχει όμως ένας σημαντικός περιορισμός.

Αν έχουμε περισσότερα από ένα application instances, κάθε instance έχει τη δική του τοπική μνήμη.

L2 Cache — Distributed Cache

Τώρα ας υποθέσουμε ότι το coffee shop έχει τρεις barista.

Ο καθένας θυμάται τις παραγγελίες που έχει εξυπηρετήσει προσωπικά.

Όμως, αν ένας πελάτης εξυπηρετηθεί από διαφορετικό barista, ο δεύτερος μπορεί να μη γνωρίζει την παραγγελία του.

Για να αντιμετωπίσουμε αυτό το πρόβλημα, δημιουργούμε ένα κοινό τετράδιο.

Όλοι οι barista μπορούν να ανατρέξουν σε αυτό και να βρουν τις καταγεγραμμένες παραγγελίες.

Στην αρχιτεκτονική των εφαρμογών, αυτό αντιστοιχεί στο Distributed Cache.

Ένα συνηθισμένο παράδειγμα είναι το Redis.

Το Redis βρίσκεται έξω από τη μνήμη της εφαρμογής και μπορεί να χρησιμοποιείται από πολλά διαφορετικά application instances.

Χαρακτηριστικό	L1 Cache	L2 Cache
Αποθήκευση	Τοπική μνήμη	Εξωτερική υπηρεσία
Πρόσβαση	Πολύ γρήγορη	Μέσω δικτύου
Κοινή χρήση	Όχι αυτόματα	Ναι
Παράδειγμα	Memory Cache	Redis

Το FusionCache μπορεί να συνδυάσει αυτά τα δύο επίπεδα.

Πρώτα αναζητά τα δεδομένα στο L1. Αν δεν τα βρει, μπορεί να αναζητήσει στο L2. Αν δεν υπάρχουν ούτε εκεί, εκτελεί το factory που ανακτά τα δεδομένα από την αρχική πηγή.

6. Τι είναι τα διαφορετικά Application Instances;

Αυτή είναι μία έννοια που αξίζει να κατανοήσουμε καλά.

Ας υποθέσουμε ότι έχουμε μία εφαρμογή .NET η οποία εξυπηρετεί πολλούς χρήστες.

Για να αντιμετωπίσουμε την αυξημένη κίνηση, την εκτελούμε σε τρία διαφορετικά instances.

                 Users
                   |
                   |
              Load Balancer
                   |
          ---------------------
          |         |         |
          v         v         v
       App 1     App 2     App 3
          |         |         |
          v         v         v
        L1        L1        L1
          |         |         |
          -------- Redis -------

Κάθε application instance είναι μία ξεχωριστή εκτέλεση της εφαρμογής.

Αυτό σημαίνει ότι:

Το App 1 έχει τη δική του μνήμη.
Το App 2 έχει τη δική του μνήμη.
Το App 3 έχει τη δική του μνήμη.

Ακόμη και αν όλα εκτελούν τον ίδιο κώδικα, δεν μοιράζονται αυτόματα την τοπική τους μνήμη.

Για παράδειγμα:

Ο χρήστης ζητά το προϊόν 42.
Το Load Balancer στέλνει το request στο App 1.
Το App 1 αναζητά το προϊόν στη δική του L1 Cache.
Δεν το βρίσκει, οπότε αναζητά στο Redis.
Αν δεν υπάρχει ούτε στο Redis, το ανακτά από τη βάση δεδομένων.
Το αποτέλεσμα αποθηκεύεται στην Cache.

Λίγο αργότερα, ο ίδιος χρήστης ζητά ξανά το προϊόν 42.

Αυτή τη φορά το request μπορεί να φτάσει στο App 2.

Το App 2 δεν έχει απαραίτητα το προϊόν στη δική του L1 Cache. Μπορεί όμως να το βρει στο κοινό Redis.

Αυτός είναι ένας από τους βασικούς λόγους που χρησιμοποιούμε Distributed Caching.

Προσοχή: Το application instance δεν είναι το ίδιο πράγμα με το object instance της κλάσης FusionCache. Είναι διαφορετικές έννοιες. Κάθε application instance έχει τη δική του διεργασία και τη δική του τοπική μνήμη.

7. Πώς λειτουργεί το FusionCache στην πράξη;

Ας δούμε τη διαδικασία με ένα απλό παράδειγμα.

Έχουμε μία εφαρμογή που επιστρέφει πληροφορίες προϊόντων.

Θέλουμε να αποφύγουμε την επαναλαμβανόμενη αναζήτηση του ίδιου προϊόντος στη βάση δεδομένων.

Η λογική είναι:

Request
   |
   v
FusionCache
   |
   v
Check L1 Cache
   |
   |-- Found --> Return Data
   |
   |-- Not Found
          |
          v
       Check L2 Cache
          |
          |-- Found --> Return Data
          |
          |-- Not Found
                 |
                 v
             Database
                 |
                 v
             Store Result
                 |
                 v
             Return Data

Το σημαντικό είναι ότι ο κώδικας της εφαρμογής μας δεν χρειάζεται να διαχειρίζεται χειροκίνητα κάθε επίπεδο.

Χρησιμοποιεί το FusionCache ως ενιαίο σημείο πρόσβασης.

8. Υλοποίηση FusionCache σε .NET

Ας περάσουμε σε ένα πρακτικό παράδειγμα.

Βήμα 1: Εγκατάσταση του NuGet Package

Εγκαθιστούμε το package:

dotnet add package ZiggyCreatures.FusionCache

Βήμα 2: Registration στο Program.cs

Στο Program.cs προσθέτουμε:

builder.Services.AddFusionCache();

Με αυτόν τον τρόπο δηλώνουμε το FusionCache στο Dependency Injection container.

Βήμα 3: Χρήση μέσω Dependency Injection

Ας υποθέσουμε ότι έχουμε ένα ProductService.

public class ProductService
{
    private readonly IFusionCache _cache;
    private readonly AppDbContext _dbContext;

    public ProductService(
        IFusionCache cache,
        AppDbContext dbContext)
    {
        _cache = cache;
        _dbContext = dbContext;
    }

    public async Task<Product?> GetProductAsync(int id)
    {
        var cacheKey = $"product:{id}";

        return await _cache.GetOrSetAsync(
            cacheKey,
            async _ =>
            {
                return await _dbContext.Products
                    .FirstOrDefaultAsync(x => x.Id == id);
            },
            TimeSpan.FromMinutes(5)
        );
    }
}

Ας δούμε τι συμβαίνει.

1. Δημιουργούμε το Cache Key

var cacheKey = $"product:{id}";

Το κλειδί προσδιορίζει ποιο προϊόν αναζητούμε.

2. Καλούμε το GetOrSetAsync

return await _cache.GetOrSetAsync(...)

Αυτή είναι η βασική μέθοδος που χρησιμοποιούμε για να αναζητήσουμε ένα δεδομένο στην Cache ή να το δημιουργήσουμε αν δεν υπάρχει.

3. Ορίζουμε το Factory

async _ =>
{
    return await _dbContext.Products
        .FirstOrDefaultAsync(x => x.Id == id);
}

Το factory είναι η λειτουργία που εκτελείται όταν το δεδομένο δεν υπάρχει στην Cache και πρέπει να ανακτηθεί από την αρχική πηγή.

Στο παράδειγμά μας, η αρχική πηγή είναι η βάση δεδομένων.

4. Ορίζουμε τη διάρκεια

TimeSpan.FromMinutes(5)

Το αποτέλεσμα παραμένει στην Cache για πέντε λεπτά, σύμφωνα με τη διάρκεια που έχουμε ορίσει.

Την επόμενη φορά που θα ζητηθεί το ίδιο προϊόν μέσα σε αυτό το διάστημα, το FusionCache μπορεί να επιστρέψει το αποθηκευμένο αποτέλεσμα χωρίς να εκτελέσει ξανά το factory.

9. Τι είναι το Expiration;

Επιστρέφουμε στο coffee shop.

Ο barista θυμάται την παραγγελία σου σήμερα.

Αλλά τι γίνεται αν επιστρέψεις μετά από έξι μήνες;

Μπορεί να έχει αλλάξει η προτίμησή σου. Ίσως πλέον παραγγέλνεις espresso αντί για cappuccino.

Δεν θέλουμε να κρατάμε όλες τις πληροφορίες για πάντα.

Αυτό ακριβώς αντιμετωπίζει το Expiration.

Το Expiration καθορίζει για πόσο χρονικό διάστημα ένα δεδομένο θεωρείται έγκυρο στην Cache.

Για παράδειγμα:

TimeSpan.FromMinutes(5)

Σημαίνει ότι η συγκεκριμένη καταχώρηση έχει διάρκεια πέντε λεπτών.

Μετά τη λήξη της, η εφαρμογή θα χρειαστεί να ανακτήσει ξανά τα δεδομένα.

Η διάρκεια πρέπει να επιλέγεται με βάση τη φύση των δεδομένων.

Για παράδειγμα:

Τα στοιχεία ενός προϊόντος μπορεί να έχουν διάρκεια αρκετών λεπτών.
Τα δεδομένα ενός καταλόγου που αλλάζει σπάνια μπορεί να έχουν μεγαλύτερη διάρκεια.
Τα δεδομένα που αλλάζουν συνεχώς χρειάζονται μικρότερη διάρκεια ή διαφορετική στρατηγική ενημέρωσης.

Δεν υπάρχει μία ιδανική διάρκεια για όλα τα δεδομένα.

10. Τι είναι το Backplane;

Ας επιστρέψουμε στο coffee shop με τους τρεις barista.

Ο πρώτος barista έχει αποθηκεύσει στη μνήμη του ότι ο πελάτης προτιμά cappuccino.

Κάποια στιγμή, ο πελάτης αλλάζει την παραγγελία του και πλέον θέλει espresso.

Ο πρώτος barista ενημερώνει το κοινό τετράδιο.

Όμως, τι γίνεται αν οι υπόλοιποι barista εξακολουθούν να θυμούνται την παλιά παραγγελία;

Χρειαζόμαστε έναν μηχανισμό ενημέρωσης.

Στο FusionCache, αυτός ο μηχανισμός ονομάζεται Backplane.

Το Backplane επιτρέπει σε διαφορετικά application instances να ενημερώνονται όταν συμβαίνουν συγκεκριμένες αλλαγές στην Cache.

Για παράδειγμα:

Το App 1 ενημερώνει ή αφαιρεί ένα cached value.
Εκπέμπεται μία ειδοποίηση μέσω του Backplane.
Τα υπόλοιπα application instances λαμβάνουν την ειδοποίηση.
Μπορούν να αντιδράσουν ανάλογα, για παράδειγμα αφαιρώντας την αντίστοιχη τοπική καταχώρηση.

Έτσι μειώνουμε τον κίνδυνο να συνεχίσουν διαφορετικά instances να χρησιμοποιούν παλιά δεδομένα.

Το Redis μπορεί να χρησιμοποιηθεί και ως Distributed Cache και ως Backplane, αλλά πρόκειται για διαφορετικούς ρόλους και αντίστοιχες ρυθμίσεις.

Σημαντικό: Το Backplane δεν είναι απαραίτητα ένας μηχανισμός μεταφοράς ολόκληρων των cached values. Ο βασικός του ρόλος είναι η επικοινωνία και η ενημέρωση των instances για αλλαγές στην Cache.

11. Τι είναι το Fail-Safe;

Ας υποθέσουμε ότι ο barista θυμάται την αγαπημένη σου παραγγελία.

Μία ημέρα, όμως, το σύστημα του καταστήματος παρουσιάζει πρόβλημα και δεν μπορεί να αναζητήσει νέες πληροφορίες.

Τι θα ήταν προτιμότερο;

Να μη σου δώσει καθόλου καφέ ή να χρησιμοποιήσει την τελευταία γνωστή παραγγελία σου;

Σε πολλές περιπτώσεις, η δεύτερη επιλογή είναι προτιμότερη.

Αυτή είναι η βασική ιδέα του Fail-Safe.

Το FusionCache μπορεί, εφόσον έχει ενεργοποιηθεί και ρυθμιστεί κατάλληλα, να επιστρέψει μία προηγούμενη cached τιμή ακόμη και αν η προσπάθεια ανανέωσης των δεδομένων αποτύχει.

Για παράδειγμα:

Έχουμε αποθηκεύσει τα στοιχεία ενός προϊόντος.
Η διάρκεια της κανονικής Cache λήγει.
Το FusionCache προσπαθεί να ανακτήσει νέα δεδομένα από τη βάση.
Η βάση δεδομένων δεν είναι προσωρινά διαθέσιμη.
Αν υπάρχει διαθέσιμη παλαιότερη τιμή μέσα στα όρια του Fail-Safe, μπορεί να επιστραφεί αυτή.

Αυτό βοηθά την εφαρμογή να συνεχίσει να εξυπηρετεί αιτήματα ακόμη και όταν μία εξωτερική εξάρτηση παρουσιάζει προσωρινό πρόβλημα.

Φυσικά, δεν είναι κατάλληλο για κάθε είδους δεδομένα. Για παράδειγμα, δεν θα θέλαμε απαραίτητα να επιστρέψουμε παλιά δεδομένα για ένα οικονομικό υπόλοιπο ή μία κρίσιμη συναλλαγή.

Το Fail-Safe πρέπει να χρησιμοποιείται με βάση τις απαιτήσεις της κάθε επιχειρησιακής λειτουργίας.

12. Τι είναι το Cache Stampede;

Ας υποθέσουμε ότι το αγαπημένο σου coffee shop έχει μία πολύ δημοφιλή προσφορά.

Η πληροφορία της προσφοράς έχει αποθηκευτεί στην Cache και εξυπηρετεί χιλιάδες χρήστες.

Ξαφνικά, η Cache λήγει.

Πολλοί χρήστες ζητούν ταυτόχρονα την ίδια πληροφορία.

Αν κάθε request ξεκινήσει ξεχωριστά μία αναζήτηση στη βάση δεδομένων, μπορεί να δημιουργηθεί πολύ μεγάλο φορτίο.

Αυτό το φαινόμενο ονομάζεται Cache Stampede.

Στην πράξη, πολλά ταυτόχρονα requests προσπαθούν να ανακτήσουν το ίδιο δεδομένο επειδή δεν υπάρχει πλέον στην Cache.

Το FusionCache προσφέρει προστασία από αυτό το φαινόμενο, συντονίζοντας τις ταυτόχρονες προσπάθειες ανάκτησης για το ίδιο cache key.

Έτσι αποφεύγουμε πολλές περιττές εκτελέσεις του ίδιου factory μέσα στην ίδια εφαρμογή.

Σε περιβάλλον με πολλά application instances, για ισχυρότερο συντονισμό μεταξύ τους μπορεί να χρειαστεί πρόσθετη distributed locking λύση ή κατάλληλη επέκταση.

13. Πότε πρέπει να χρησιμοποιούμε FusionCache;

Το FusionCache είναι ιδιαίτερα χρήσιμο όταν:

Έχουμε εφαρμογές με μεγάλο αριθμό requests.
Θέλουμε να μειώσουμε τα επαναλαμβανόμενα queries στη βάση δεδομένων.
Ανακτούμε δεδομένα από αργά εξωτερικά APIs.
Η εφαρμογή μας εκτελείται σε πολλαπλά application instances.
Θέλουμε συνδυασμό τοπικής και distributed Cache.
Χρειαζόμαστε μεγαλύτερη ανθεκτικότητα σε προσωρινές αποτυχίες εξωτερικών υπηρεσιών.

Δεν σημαίνει, όμως, ότι πρέπει να κάνουμε caching παντού.

Για δεδομένα που αλλάζουν συνεχώς ή απαιτούν πάντα την πιο πρόσφατη τιμή, πρέπει να εξετάζουμε προσεκτικά αν το caching είναι κατάλληλο.

Επίσης, πρέπει να σχεδιάζουμε σωστά τα Cache Keys, τις διάρκειες και την ακύρωση των cached values.

14. Συμπέρασμα

Ας επιστρέψουμε για τελευταία φορά στο coffee shop.

Ο καλός barista δεν χρειάζεται να ρωτάει κάθε πελάτη ξανά και ξανά για την παραγγελία του.

Θυμάται τις προτιμήσεις του, γνωρίζει πότε χρειάζεται να ενημερώσει τις πληροφορίες του και συνεργάζεται με τους υπόλοιπους barista ώστε να προσφέρει μία γρήγορη και συνεπή εξυπηρέτηση.

Ακριβώς αυτή τη λογική προσπαθούμε να πετύχουμε και στις εφαρμογές μας.

Το FusionCache μάς προσφέρει έναν ολοκληρωμένο μηχανισμό caching στο .NET, συνδυάζοντας διαφορετικά επίπεδα αποθήκευσης και δυνατότητες που βοηθούν στην απόδοση και την ανθεκτικότητα της εφαρμογής.

Το σημαντικότερο είναι να κατανοήσουμε ότι το caching δεν είναι απλώς η αποθήκευση ενός αποτελέσματος στη μνήμη.

Είναι μία αρχιτεκτονική επιλογή που επηρεάζει την απόδοση, τη συνέπεια των δεδομένων και τη συμπεριφορά της εφαρμογής μας.

Και όπως ένας καλός barista θυμάται τι προτιμάς, έτσι και μία καλά σχεδιασμένη εφαρμογή πρέπει να γνωρίζει πότε μπορεί να επαναχρησιμοποιήσει δεδομένα και πότε χρειάζεται να αναζητήσει καινούργια.

Happy coding! ☕

Χρήσιμες πηγές

Ασφαλές deploy στο Azure App Service με Deployment Slots βήμα βήμα

nikosst — Sun, 01 Nov 2026 09:11:17 +0000

Πρακτικός οδηγός για staging slots, σωστά settings, warm-up, ελέγχους, swap και rollback, με εξήγηση του γιατί σε κάθε βήμα.

Ένα deployment μπορεί να ολοκληρωθεί επιτυχώς και η εφαρμογή να αποτυγχάνει στο πρώτο πραγματικό αίτημα.

Το build πέρασε. Τα αρχεία ανέβηκαν. Το pipeline έγινε πράσινο. Όμως μια σύνδεση με τη βάση, ένα ξεχασμένο secret ή ένα σφάλμα κατά την εκκίνηση αρκεί για να μετατρέψει την επόμενη επίσκεψη ενός χρήστη σε HTTP 500.

Τα Deployment Slots του Azure App Service μας επιτρέπουν να εγκαταστήσουμε και να ελέγξουμε τη νέα έκδοση πριν αναλάβει την εξυπηρέτηση των χρηστών. Έτσι, το deployment και η διάθεση της έκδοσης στο κοινό γίνονται δύο διακριτά βήματα.

Σε αυτόν τον οδηγό θα ακολουθήσουμε μια συγκεκριμένη διαδρομή

Build → Deploy στο staging → Έλεγχοι → Swap → Παρακολούθηση
                                        ↓
                              Rollback, αν χρειαστεί

Θα δούμε και τον λόγο ύπαρξης κάθε βήματος. Γιατί το ζητούμενο είναι να γνωρίζουμε με ποια στοιχεία αποφασίζουμε ότι μια έκδοση είναι έτοιμη για production.

Τι είναι τα Deployment Slots

Ένα deployment slot είναι μια ενεργή εφαρμογή μέσα στο ίδιο App Service, με δικό της hostname. Συνήθως κρατάμε δύο slots

Production, που εξυπηρετεί τους χρήστες.
Staging, όπου προετοιμάζουμε την επόμενη έκδοση.

Τα deployment slots διατίθενται στα tiers Standard, Premium και Isolated. Το διαθέσιμο πλήθος εξαρτάται από το plan. Microsoft Learn για τα deployment slots.

Ας υποθέσουμε ότι έχουμε την έκδοση v1 σε production και θέλουμε να διαθέσουμε τη v2:

Στάδιο	Production	Staging
Πριν από την αλλαγή	v1	—
Μετά το deployment	v1	v2
Μετά τους ελέγχους	v1	v2, ελεγμένη
Μετά το swap	v2	v1
Αν κάνουμε rollback με νέο swap	v1	v2

Αυτή είναι μια πρακτική εφαρμογή της λογικής blue-green deployment: προετοιμάζουμε μια δεύτερη έκδοση και αλλάζουμε ποια εξυπηρετεί το production. Η Microsoft προτείνει deployment σε nonproduction slot, ελέγχους και προώθηση μέσω swap. Deployment best practices.

Πώς βοηθούν στην ασφάλεια του release

Σκεφτείτε μια εφαρμογή παραγγελιών. Η νέα έκδοση λειτουργεί τοπικά, αλλά στο Azure δεν μπορεί να διαβάσει ένα απαραίτητο secret.

Με έλεγχο στο staging, έχουμε τη δυνατότητα να εντοπίσουμε το πρόβλημα πριν προωθήσουμε την έκδοση. Η απόφαση για release περιμένει μέχρι να έχουμε λειτουργική εφαρμογή και επιτυχημένους ελέγχους.

Αν εμφανιστεί πρόβλημα μετά την προώθηση, η προηγούμενη έκδοση παραμένει διαθέσιμη στο άλλο slot. Αυτό μας δίνει μια συγκεκριμένη επιλογή επαναφοράς, αντί να αρχίζουμε εκείνη τη στιγμή να αναζητούμε παλιό build.

Οι πόροι του plan παραμένουν κοινόχρηστοι

Τα slots χρησιμοποιούν τους πόρους του ίδιου App Service plan. Ένα βαρύ load test στο staging μπορεί επομένως να επηρεάσει το production. Η δυνατότητα των slots δεν έχει ξεχωριστή χρέωση, αλλά εξακολουθούμε να πληρώνουμε το plan και τις συνδεδεμένες υπηρεσίες. App Service plans.

Για το runbook που ακολουθεί χρησιμοποιούμε το staging για προετοιμασία release και σύντομους λειτουργικούς ελέγχους. Τα απαιτητικά performance tests χρειάζονται κατάλληλο περιβάλλον και χωρητικότητα.

Βήμα 1 Προετοιμάζουμε εφαρμογή και κριτήρια επιτυχίας

Θα θεωρήσουμε ότι έχουμε ήδη:

Ένα App Service που λειτουργεί, σε plan με υποστήριξη slots.
Δικαιώματα δημιουργίας slot, αλλαγής ρυθμίσεων, deployment και swap.
Ένα έτοιμο, ελεγμένο artifact της νέας έκδοσης, εδώ release.zip.
Runtime στο App Service συμβατό με την εφαρμογή.
Logs και μετρήσεις για να αξιολογήσουμε το release.

Το παράδειγμα αφορά App Service με deployment κώδικα μέσω ZIP. Οι εντολές γράφονται για Azure Cloud Shell σε Bash. Για custom containers αλλάζει το βήμα εγκατάστασης του artifact.

Πριν ξεκινήσουμε, ορίζουμε τι πρέπει να αποδείξει ο έλεγχος. Για μια εφαρμογή παραγγελιών, για παράδειγμα:

Η εφαρμογή εκκινεί κανονικά.
Μπορεί να επικοινωνήσει με τις απαραίτητες υπηρεσίες.
Ένας χρήστης συνδέεται και βλέπει τις παραγγελίες του.
Επιστρέφεται το αναμενόμενο release identifier.

Τα /health/ready και /version που χρησιμοποιούμε παρακάτω είναι endpoints που υλοποιούμε στην εφαρμογή μας. Το πρώτο πρέπει να επιστρέφει 200 όταν η εφαρμογή είναι έτοιμη και, για παράδειγμα, 503 όταν αποτυγχάνει μια κρίσιμη εξάρτηση. Το δεύτερο επιστρέφει την έκδοση του build, όπως {"version":"2.0.0"}.

Το readiness endpoint κρατά τους ελέγχους σύντομους, χωρίς εγγραφές ή άλλες παρενέργειες. Η απόκρισή του δεν πρέπει να αποκαλύπτει secrets ή εσωτερικά διαγνωστικά στοιχεία.

Γιατί έχει σημασία: με συγκεκριμένα κριτήρια, το «μου άνοιξε η αρχική σελίδα» παύει να είναι ο μοναδικός έλεγχος πριν από το release.

Βήμα 2 Δημιουργούμε το staging slot

Από το Azure Portal ανοίγουμε το App Service και επιλέγουμε Deployment → Deployment slots → Add. Δίνουμε όνομα staging και επιλέγουμε αντιγραφή configuration από το production.

Η αντιγραφή configuration δεν αντιγράφει τον κώδικα της εφαρμογής. Επίσης, ένα private endpoint δεν αντιγράφεται αυτόματα στο νέο slot. Δημιουργία deployment slot.

Η αντίστοιχη διαδικασία με Azure CLI είναι:

# Οι αποτυχίες σε pipelines εντολών πρέπει να είναι ορατές.
set -o pipefail

# Αντικαθιστούμε τις τιμές με τα δικά μας στοιχεία.
az account set --subscription "<SUBSCRIPTION_ID>"

RG="rg-myapp-prod"
APP="my-existing-app"
SLOT="staging"

az webapp deployment slot create \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --configuration-source "$APP" \
  --output none

Στο --configuration-source, το όνομα της εφαρμογής αναφέρεται στο production. Azure CLI για deployment slots.

Γιατί έχει σημασία: χρησιμοποιούμε το production configuration ως αφετηρία. Στο επόμενο βήμα προσαρμόζουμε όσα πρέπει να διαφέρουν, πριν εγκαταστήσουμε κώδικα που θα μπορούσε να χρησιμοποιήσει λάθος υπηρεσίες.

Βήμα 3 Ξεχωρίζουμε σωστά τις ρυθμίσεις κάθε περιβάλλοντος

Αυτό το βήμα χρειάζεται ιδιαίτερη προσοχή.

Ένας έλεγχος στο staging μπορεί να στείλει πραγματικό email ή να γράψει στην production βάση, αν η εφαρμογή χρησιμοποιεί τις αντίστοιχες συνδέσεις.

Για κάθε ρύθμιση αποφασίζουμε αν πρέπει να παραμένει συνδεδεμένη με το περιβάλλον. Στο Portal, μέσα στο αντίστοιχο slot, πηγαίνουμε στις Settings → Environment variables και ενεργοποιούμε Deployment slot setting όπου χρειάζεται. Τα slot-specific settings παραμένουν στο slot μετά την ολοκλήρωση του swap. Ρυθμίσεις εφαρμογής.

Ένα ενδεικτικό πλάνο είναι:

Ρύθμιση	Production	Staging	Deployment slot setting
Σύνδεση βάσης	Production database	Test database	Ναι
Payment provider	Live λογαριασμός	Sandbox λογαριασμός	Ναι
Email provider	Κανονική αποστολή	Test inbox	Ναι
API εξωτερικής υπηρεσίας	Production endpoint	Test endpoint	Ναι

Ελέγχουμε τις τιμές και τη σήμανση και στα δύο slots.

Για secrets χρησιμοποιούμε, όπου ταιριάζει, Azure Key Vault references, με διαφορετικά secrets ανά περιβάλλον και slot-specific ρυθμίσεις. Έτσι τα credentials διαχειρίζονται κεντρικά και δεν χρειάζεται να μπουν στο repository. Ελέγχουμε τόσο τα δικαιώματα ανάγνωσης όσο και τη δικτυακή πρόσβαση στο vault. Key Vault references.

Τα managed identities είναι ρυθμίσεις ανά slot. Ελέγχουμε ξεχωριστά τι μπορεί να προσπελάσει κάθε identity. Managed identities στο App Service.

Γιατί έχει σημασία: θέλουμε να προωθήσουμε μια έκδοση της εφαρμογής, διατηρώντας τις σωστές συνδέσεις για το περιβάλλον που θα την εκτελεί.

Οι αλλαγές στα app settings προκαλούν επανεκκίνηση της εφαρμογής. Προγραμματίζουμε την αρχική ρύθμιση του production ως αλλαγή υποδομής και την ολοκληρώνουμε πριν από τα τακτικά releases. Azure CLI configuration.

Βήμα 4 Προστατεύουμε την πρόσβαση στο staging

Το staging έχει δικό του hostname. Το ότι δεν του στέλνουμε production traffic δεν σημαίνει ότι το περιεχόμενό του είναι ιδιωτικό.

Ρυθμίζουμε πρόσβαση για την ομάδα και τον deployment runner μέσω των κατάλληλων access restrictions ή δικτυακών ελέγχων. Ελέγχουμε και το SCM/Kudu endpoint, που έχει δικούς του κανόνες πρόσβασης. App Service access restrictions.

Γιατί έχει σημασία: μια ανέκδοτη λειτουργία μπορεί να είναι προσβάσιμη απευθείας από το hostname του staging. Οι κανόνες πρόσβασης καθορίζουν ποιος μπορεί να τη δει και ποιος μπορεί να εκτελέσει τους ελέγχους μας.

Στο παράδειγμα, τα επόμενα HTTP requests εκτελούνται από επιτρεπόμενο δίκτυο. Αν έχουμε περιορίσει την πρόσβαση σε VNet, χρησιμοποιούμε runner μέσα σε αυτό το δίκτυο.

Βήμα 5 Ρυθμίζουμε ουσιαστικό warm-up

Το warm-up δίνει στη νέα έκδοση χρόνο να προετοιμαστεί πριν αναλάβει production traffic.

Ορίζουμε το endpoint που θα ελέγχεται κατά το swap και απαιτούμε HTTP 200:

# Αρχική ρύθμιση production. Μπορεί να προκαλέσει restart.
az webapp config appsettings set \
  --resource-group "$RG" \
  --name "$APP" \
  --settings \
    WEBSITE_SWAP_WARMUP_PING_PATH=/health/ready \
    WEBSITE_SWAP_WARMUP_PING_STATUSES=200 \
  --output none

# Ίδια πολιτική στο staging.
az webapp config appsettings set \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --settings \
    WEBSITE_SWAP_WARMUP_PING_PATH=/health/ready \
    WEBSITE_SWAP_WARMUP_PING_STATUSES=200 \
  --output none

Χωρίς ρητή ρύθμιση των αποδεκτών statuses, το swap warm-up θεωρεί έγκυρους όλους τους HTTP κωδικούς. Επομένως, ακόμη και μια απόκριση σφάλματος μπορεί να θεωρηθεί επαρκής. App settings για deployment slots.

Το endpoint πρέπει να υπάρχει και στην προηγούμενη και στη νέα έκδοση, ώστε να μπορεί να χρησιμοποιηθεί και κατά την επαναφορά. Ελέγχουμε επίσης ότι τα probes φτάνουν στην εφαρμογή χωρίς redirect σε σελίδα σύνδεσης.

Γιατί έχει σημασία: ο έλεγχος αποδεικνύει όσα έχουμε υλοποιήσει σε αυτόν. Μια στατική απόκριση 200 δεν ελέγχει αν λειτουργεί η σύνδεση με τη βάση.

Το App Service Health check λειτουργεί συμπληρωματικά

Στο Portal, από Monitoring → Health check, μπορούμε να ορίσουμε το ίδιο readiness path για συνεχή παρακολούθηση των instances. Το Health check βοηθά στη δρομολόγηση αιτημάτων μακριά από unhealthy instances και είναι διαφορετικός μηχανισμός από το swap warm-up.

Κρατάμε συνεπή ρύθμιση στα δύο slots: το Health check configuration ανταλλάσσεται στο swap. Για να αξιοποιείται πλήρως η δυνατότητα χρειάζονται τουλάχιστον δύο ενεργά replicas της εφαρμογής και επαρκής χωρητικότητα. App Service Health check.

Βήμα 6 Κάνουμε deploy τη νέα έκδοση στο staging

Το release.zip περιέχει την έτοιμη εφαρμογή στη ρίζα του, χωρίς έναν επιπλέον εξωτερικό φάκελο. Για .NET, για παράδειγμα, πακετάρουμε τα περιεχόμενα του αποτελέσματος του dotnet publish. Δημιουργία ZIP package.

Από τον φάκελο όπου βρίσκεται το artifact εκτελούμε:

az webapp deploy \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --src-path ./release.zip \
  --type zip

Το --slot "$SLOT" καθορίζει τον προορισμό του deployment. Azure CLI webapp deploy.

Γιατί έχει σημασία: εγκαθιστούμε τη νέα έκδοση στον χώρο προετοιμασίας. Η απόφαση να την προωθήσουμε στο production ακολουθεί τους ελέγχους.

Στο pipeline κρατάμε το artifact συνδεδεμένο με συγκεκριμένο commit ή release identifier. Η έκδοση που ελέγχουμε είναι αυτή που θα προωθήσουμε, χωρίς ενδιάμεσο rebuild.

Βήμα 7 Ελέγχουμε την εφαρμογή στο staging

Ανακτούμε τα πραγματικά hostnames από το Azure:

STAGING_HOST=$(az webapp show \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --query defaultHostName --output tsv)

PROD_HOST=$(az webapp show \
  --resource-group "$RG" \
  --name "$APP" \
  --query defaultHostName --output tsv)

Έπειτα ελέγχουμε readiness και έκδοση:

curl --fail-with-body --silent --show-error --max-time 20 \
  --write-out '\nHTTP %{http_code}\n' \
  "https://$STAGING_HOST/health/ready"

curl --fail-with-body --silent --show-error --max-time 20 \
  "https://$STAGING_HOST/version" \
  | jq -e '.version == "2.0.0"'

Για το readiness περιμένουμε ακριβώς HTTP 200. Στον δεύτερο έλεγχο αντικαθιστούμε το 2.0.0 με την αναμενόμενη έκδοση του artifact. Αν τα endpoints απαιτούν application authentication, τα requests χρειάζονται τα κατάλληλα credentials.

Ακολουθούν τα smoke tests: σύντομοι έλεγχοι βασικών λειτουργιών. Στο παράδειγμά μας δοκιμάζουμε σύνδεση χρήστη, ανάγνωση παραγγελιών και μια ελεγχόμενη δοκιμαστική παραγγελία στο test περιβάλλον.

Ελέγχουμε παράλληλα logs και exceptions. Ένας λειτουργικός έλεγχος μπορεί να φαίνεται επιτυχημένος, ενώ μια δευτερεύουσα διεργασία αποτυγχάνει στο παρασκήνιο.

Γιατί έχει σημασία: ελέγχουμε συμπεριφορά, πρόσβαση στις εξαρτήσεις και ταυτότητα της έκδοσης. Ένα επιτυχημένο upload αποδεικνύει ότι μεταφέρθηκε το artifact.

Βήμα 8 Κάνουμε τελικό έλεγχο και swap

Πριν προχωρήσουμε, σταματάμε παράλληλα deployments ή άλλες αλλαγές στο ίδιο staging slot. Θέλουμε να προωθήσουμε ακριβώς την έκδοση που μόλις ελέγξαμε.

Προαιρετικός έλεγχος με swap with preview

Το preview εφαρμόζει τις σχετικές ρυθμίσεις του target στο source slot και παύει τη διαδικασία πριν από την αλλαγή δρομολόγησης. Έτσι μπορούμε να ελέγξουμε τη νέα έκδοση με τις ρυθμίσεις του production. Δεν υποστηρίζεται όταν είναι ενεργό το App Service Authentication σε οποιοδήποτε από τα δύο slots. Swap with preview.

az webapp deployment slot swap \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --target-slot production \
  --action preview

Εδώ το staging μπορεί να χρησιμοποιεί production connections. Περιορίζουμε τους ελέγχους σε ελεγχόμενες ενέργειες χωρίς παρενέργειες και έχουμε ήδη αντιμετωπίσει migrations κατά την εκκίνηση και background workers.

Η identity και η VNet integration παραμένουν του source slot. Συνεπώς ελέγχουμε την πρόσβασή του στις production εξαρτήσεις κατά την προετοιμασία, ακόμη και για swap χωρίς preview. Ρυθμίσεις που δεν ανταλλάσσονται.

Αν αποφασίσουμε να ακυρώσουμε το εκκρεμές preview:

az webapp deployment slot swap \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --target-slot production \
  --action reset

Προώθηση στο production

Όταν οι έλεγχοι έχουν ολοκληρωθεί, εκτελούμε:

az webapp deployment slot swap \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --target-slot production \
  --action swap

Η εντολή εκτελεί κανονικό swap ή ολοκληρώνει ένα επιτυχημένο preview. Επιλέγουμε source το staging και target το production. Azure CLI slot swap.

Το App Service προετοιμάζει τη νέα έκδοση πριν αλλάξει τη δρομολόγηση. Αυτό περιορίζει τη διακοπή που προκαλεί ένα release. Η συνολική διαθεσιμότητα εξακολουθεί να εξαρτάται από την εφαρμογή, τις εξαρτήσεις και τον χειρισμό επανεκκινήσεων. Αρχιτεκτονικές πρακτικές για το App Service, οδηγός αξιοπιστίας.

Γιατί έχει σημασία: η προώθηση γίνεται ως συγκεκριμένη αλλαγή, αφού έχουμε συγκεντρώσει στοιχεία ότι η έκδοση είναι έτοιμη.

Βήμα 9 Επαληθεύουμε το production και παρακολουθούμε

Μετά το swap επαναλαμβάνουμε τους ελέγχους στο production:

curl --fail-with-body --silent --show-error --max-time 20 \
  --write-out '\nHTTP %{http_code}\n' \
  "https://$PROD_HOST/health/ready"

curl --fail-with-body --silent --show-error --max-time 20 \
  "https://$PROD_HOST/version" \
  | jq -e '.version == "2.0.0"'

Αν η εφαρμογή εξυπηρετείται μέσω custom domain, Front Door ή άλλου proxy, ελέγχουμε και το πραγματικό δημόσιο URL. Εκεί επαληθεύουμε ολόκληρη τη διαδρομή που ακολουθούν οι χρήστες.

Στο εργαλείο παρακολούθησης, όπως το Application Insights, συγκρίνουμε με την προηγούμενη κατάσταση:

Αποτυχημένα requests και νέες exceptions.
Χρόνους απόκρισης, ιδιαίτερα p95.
Αποτυχίες επικοινωνίας με εξαρτήσεις.
CPU, μνήμη και επανεκκινήσεις.
Επιτυχία βασικών επιχειρησιακών ενεργειών, όπως η ολοκλήρωση παραγγελίας.

Πριν από το release έχουμε ορίσει ποια επιδείνωση απαιτεί επαναφορά και ποιος παίρνει την απόφαση. Το διάστημα παρακολούθησης πρέπει να καλύπτει αντιπροσωπευτική κίνηση και τις σημαντικές διεργασίες της εφαρμογής. Safe deployment practices.

Γιατί έχει σημασία: μια αστοχία μπορεί να εμφανίζεται μόνο σε συγκεκριμένους χρήστες ή δεδομένα. Η παρακολούθηση συνδέει το release με την πραγματική λειτουργία της υπηρεσίας.

Βήμα 10 Κάνουμε rollback όταν χρειάζεται

Αν η προηγούμενη έκδοση παραμένει στο staging και είναι συμβατή με την τρέχουσα κατάσταση των δεδομένων, μπορούμε να ανταλλάξουμε ξανά τα ίδια slots:

az webapp deployment slot swap \
  --resource-group "$RG" \
  --name "$APP" \
  --slot "$SLOT" \
  --target-slot production \
  --action swap

Ακόμη και για rollback, κρατάμε το production ως target. Η ανταλλαγή επαναφέρει την προηγούμενη έκδοση στο production. Azure CLI slot swap.

Ελέγχουμε ξανά readiness, την προηγούμενη έκδοση στο /version και τις βασικές λειτουργίες. Μέχρι να επιβεβαιωθεί το release, αποφεύγουμε νέο deployment στο staging που θα αντικαταστήσει την έκδοση επαναφοράς. Διατήρηση προηγούμενης έκδοσης για επαναφορά.

Γιατί έχει σημασία: η δυνατότητα rollback είναι χρήσιμη όταν ξέρουμε τι επαναφέρουμε, πότε θα το κάνουμε και πώς θα επιβεβαιώσουμε το αποτέλεσμα.

Η βάση δεδομένων χρειάζεται δικό της σχέδιο

Το slot swap δεν αναιρεί database migrations ή αλλαγές στα δεδομένα.

Ας υποθέσουμε ότι η v2 καταργεί τη στήλη FullName και χρησιμοποιεί τις FirstName και LastName. Αν επαναφέρουμε τη v1, εκείνη θα συνεχίσει να ζητά τη στήλη που έχει ήδη διαγραφεί.

Για τέτοιες αλλαγές σχεδιάζουμε σταδιακή μετάβαση, γνωστή ως expand and contract:

Προσθέτουμε τα νέα πεδία, διατηρώντας το παλιό schema λειτουργικό.
Διαθέτουμε έκδοση που υποστηρίζει τη μεταβατική κατάσταση και κρατά τα δεδομένα συμβατά με την προηγούμενη έκδοση για το διάστημα rollback.
Μεταφέρουμε τα υπάρχοντα δεδομένα και ελέγχουμε τη συνέπειά τους.
Αφαιρούμε το παλιό πεδίο σε επόμενο release, όταν δεν απαιτείται πλέον η παλιά έκδοση.

Τα migrations εκτελούνται ως ελεγχόμενο βήμα, με δικό τους σχέδιο αποτυχίας. Αποφεύγουμε ανεξέλεγκτες καταστροφικές αλλαγές κατά την εκκίνηση, ιδιαίτερα όταν το preview μπορεί να συνδέσει τη νέα έκδοση με production δεδομένα.

Η επαναφορά αλλαγών σε schema και άλλα stateful στοιχεία απαιτεί ιδιαίτερη πρόβλεψη. Well-Architected guidance για ασφαλή deployments.

Background jobs και κατάσταση εφαρμογής

Δύο ενεργές εκδόσεις μπορούν να εκτελούν δύο φορές μια εργασία, αν δεν έχουμε σχεδιάσει τον συντονισμό τους. Για queue consumers, schedulers και αποστολές email προβλέπουμε απομονωμένες δοκιμαστικές ουρές, συντονισμό εκτέλεσης και idempotency, δηλαδή ασφαλή χειρισμό επαναλαμβανόμενης επεξεργασίας.

Για WebJobs υπάρχουν ειδικές ρυθμίσεις απενεργοποίησης στο staging. Ελέγχουμε όμως ολόκληρη τη συμπεριφορά κατά το swap και το preview: η προσωρινή εφαρμογή production settings χρειάζεται πρόβλεψη και για τυχόν flags που ενεργοποιούν εργασίες. WebJobs στο App Service.

Εξετάζουμε επίσης τι χρειάζεται να επιβιώσει από ένα restart: sessions, αρχεία χρηστών και εργασίες μεγάλης διάρκειας. Τα αποθηκεύουμε και τα διαχειριζόμαστε με τρόπο που επιτρέπει τη μετάβαση μεταξύ εκδόσεων.

Πώς μεταφέρουμε τη διαδικασία σε pipeline

Αφού κατανοήσουμε τη ροή, την αυτοματοποιούμε:

Build και tests
    ↓
Αποθήκευση artifact με συγκεκριμένη έκδοση
    ↓
Deploy στο staging
    ↓
Readiness και smoke tests
    ↓
Έγκριση ή αυτόματα κριτήρια προώθησης
    ↓
Swap στο production
    ↓
Επαλήθευση και παρακολούθηση
    ↓
Ολοκλήρωση release ή ελεγχόμενο rollback

Κάθε αποτυχία πρέπει να σταματά την προώθηση. Επίσης, επιτρέπουμε ένα release κάθε φορά ανά εφαρμογή, ώστε ένα δεύτερο pipeline να μη μεταβάλει το slot που ελέγχει το πρώτο.

Η αυτοματοποίηση αποκτά αξία όταν επαναλαμβάνει ελέγχους με σαφή κριτήρια. Καταγράφουμε commit, artifact, αποτελέσματα ελέγχων και χρόνο swap, ώστε να γνωρίζουμε τι εκτελείται και γιατί προωθήθηκε.

Checklist πριν από το release

[ ] Το staging εκτελεί το αναμενόμενο artifact.
[ ] Οι συνδέσεις, τα secrets και τα slot-specific settings είναι σωστά.
[ ] Έχουν ελεγχθεί δικαιώματα identity και δικτυακή πρόσβαση.
[ ] Το readiness endpoint ελέγχει κρίσιμες εξαρτήσεις και το warm-up απαιτεί 200.
[ ] Τα smoke tests έχουν περάσει.
[ ] Έχουμε αντιμετωπίσει migrations και background jobs.
[ ] Δεν εκτελείται άλλο deployment στο ίδιο slot.
[ ] Έχουμε ορίσει κριτήρια rollback και κρατάμε την προηγούμενη έκδοση διαθέσιμη.
[ ] Μετά το swap θα ελέγξουμε το πραγματικό δημόσιο URL και τη συμπεριφορά των χρηστών.

Τα deployment slots μάς δίνουν χρόνο για έλεγχο πριν από την προώθηση και μια πρακτική διαδρομή επιστροφής μετά από αυτήν. Η σημασία τους φαίνεται τη στιγμή που ένα release παρουσιάζει πρόβλημα: έχουμε ήδη προετοιμάσει τις επόμενες κινήσεις μας.

Decorator pattern σε CQRS handlers με authorization και telemetry στο .NET

nikosst — Sun, 01 Nov 2026 08:48:21 +0000

Πρόσθεσε authorization και telemetry γύρω από CQRS handlers στο .NET, με Dependency Injection, OpenTelemetry και tests, χωρίς MediatR.

Ένας handler εκτελεί ένα use case: διαβάζει δεδομένα, υπολογίζει ένα αποτέλεσμα ή καταχωρίζει μια αλλαγή. Συχνά όμως θέλουμε να ελέγξουμε δικαιώματα πριν από την εκτέλεσή του και να μετρήσουμε τη διάρκεια ολόκληρης της κλήσης.

Με το Decorator pattern μπορούμε να προσθέσουμε αυτές τις συμπεριφορές γύρω από τον handler, κρατώντας το ίδιο interface. Κάθε decorator κρατά έναν εσωτερικό handler και αποφασίζει τι θα κάνει πριν, μετά ή γύρω από την κλήση του.

Σε αυτό το άρθρο θα γράψουμε authorization και telemetry decorators για CQRS handlers στο .NET, θα τους συνδέσουμε με Dependency Injection και θα ελέγξουμε ότι η αλυσίδα λειτουργεί. Θα καλέσουμε τους handlers απευθείας, χωρίς MediatR.

Για να ακολουθήσεις, χρειάζεται βασική εξοικείωση με interfaces, generics, async/await και το DI του ASP.NET Core. Τα snippets προορίζονται για ASP.NET Core project με .NET 10 και ενεργοποιημένα implicit usings. Βάλε τους τύπους σε ξεχωριστά αρχεία· οι προσθήκες στο Program.cs επισημαίνονται στα αντίστοιχα σημεία.

Ένα use case με authorization και telemetry

Ας φανταστούμε ένα εσωτερικό εργαλείο μιας πιτσαρίας. Ένας υπάλληλος ζητά την τιμή μιας πίτσας με συγκεκριμένα υλικά.

Η κύρια δουλειά είναι να υπολογίσουμε την τιμή. Θέλουμε επίσης:

Να ελέγξουμε αν ο υπάλληλος έχει δικαίωμα να χρησιμοποιήσει τη λειτουργία.
Να μετρήσουμε τη διάρκεια και να καταγράψουμε αν η εκτέλεση ολοκληρώθηκε ή απέτυχε.

Μπορούμε να βάλουμε όλον αυτόν τον κώδικα στην ίδια μέθοδο. Αν όμως οι ίδιοι έλεγχοι και οι ίδιες μετρήσεις χρειάζονται σε πολλές λειτουργίες, θα αρχίσουμε να τους επαναλαμβάνουμε.

Με decorators μπορούμε να χωρίσουμε τη δουλειά:

Telemetry decorator
└── Authorization decorator
    └── Handler που υπολογίζει την τιμή

Κάθε επίπεδο κρατά το επόμενο, προσφέρει το ίδιο συμβόλαιο κλήσης και προσθέτει τη δική του συμπεριφορά. Ο κώδικας που καλεί τον handler δεν χρειάζεται να γνωρίζει πόσα επίπεδα υπάρχουν.

Οι απαραίτητοι όροι

Ένα query είναι ένα αίτημα για ανάγνωση ή υπολογισμό δεδομένων, χωρίς να αλλάζουμε την αποθηκευμένη κατάσταση της εφαρμογής. Για παράδειγμα: «υπολόγισε την τιμή αυτής της πίτσας».

Ένα command είναι ένα αίτημα που ζητά αλλαγή. Για παράδειγμα: «καταχώρισε αυτή την παραγγελία».

Ένας handler είναι η κλάση που εκτελεί το αντίστοιχο αίτημα.

Ο διαχωρισμός των λειτουργιών ανάγνωσης από τις λειτουργίες αλλαγής είναι η βασική ιδέα του CQRS. Μπορείς να ξεκινήσεις με διαφορετικά requests και handlers στην ίδια εφαρμογή και στην ίδια βάση δεδομένων.

Το CQRS δεν απαιτεί MediatR. Στο παράδειγμα θα καλέσουμε τους handlers απευθείας, μέσα από δικά μας interfaces.

Το κοινό συμβόλαιο των handlers

public interface IRequest<TResult>
{
}

public interface IQuery<TResult> : IRequest<TResult>
{
}

public interface ICommand<TResult> : IRequest<TResult>
{
}

public interface IRequestHandler<TRequest, TResult>
    where TRequest : IRequest<TResult>
{
    Task<TResult> HandleAsync(
        TRequest request,
        CancellationToken cancellationToken = default);
}

Τα TRequest και TResult είναι θέσεις για τύπους που θα ορίσουμε όταν χρησιμοποιήσουμε το interface.

Για παράδειγμα, το IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto> σημαίνει: «handler που δέχεται ένα GetPizzaPriceQuery και επιστρέφει ένα PizzaPriceDto μέσα σε Task».

Η γραμμή where TRequest : IRequest<TResult> περιορίζει ποιοι τύποι μπορούν να χρησιμοποιηθούν ως requests.

Commands και queries έχουν διαφορετικά interfaces για να δηλώνουν την πρόθεσή τους, αλλά οι handlers τους μοιράζονται ένα κοινό συμβόλαιο. Έτσι, ο ίδιος generic decorator μπορεί να χρησιμοποιηθεί και για τα δύο.

Το IRequestHandler<TRequest, TResult> είναι το κοινό interface που θα υλοποιούν τόσο ο πραγματικός handler όσο και οι decorators του.

Δηλώνουμε ποιο δικαίωμα απαιτείται

Θα χρησιμοποιήσουμε ένα μικρό attribute, δηλαδή μια δήλωση που προσθέτει πληροφορία σε μια κλάση:

[AttributeUsage(AttributeTargets.Class, Inherited = false)]
public sealed class RequiresPermissionAttribute : Attribute
{
    public string Permission { get; }

    public RequiresPermissionAttribute(string permission)
    {
        if (string.IsNullOrWhiteSpace(permission))
        {
            throw new ArgumentException(
                "A permission is required.", nameof(permission));
        }

        Permission = permission;
    }
}

Το attribute δηλώνει την απαίτηση. Δεν εκτελεί μόνο του κανέναν έλεγχο. Ο authorization decorator θα διαβάσει αυτή την πληροφορία και θα την εφαρμόσει.

Το query και ο handler υπολογισμού της τιμής

Το query περιγράφει τις επιλογές του υπαλλήλου. Το DTO είναι ένα απλό αντικείμενο με τα δεδομένα που θέλουμε να επιστρέψουμε.

[RequiresPermission("pizza.prices.read")]
public sealed record GetPizzaPriceQuery(
    bool ExtraCheese,
    bool Mushrooms,
    bool Olives) : IQuery<PizzaPriceDto>;

public sealed record PizzaPriceDto(
    string Description,
    decimal Total);

Ο handler παρακάτω υπολογίζει την τιμή στη μνήμη. Η υλοποίηση παραμένει απλή, ώστε να επικεντρωθούμε στους decorators γύρω από την εκτέλεσή του.

public sealed class GetPizzaPriceHandler
    : IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto>
{
    public Task<PizzaPriceDto> HandleAsync(
        GetPizzaPriceQuery request,
        CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();

        string description = "Πίτσα με σάλτσα ντομάτας";
        decimal total = 6.00m;

        if (request.ExtraCheese)
        {
            description += ", έξτρα τυρί";
            total += 1.50m;
        }

        if (request.Mushrooms)
        {
            description += ", μανιτάρια";
            total += 1.00m;
        }

        if (request.Olives)
        {
            description += ", ελιές";
            total += 0.50m;
        }

        return Task.FromResult(new PizzaPriceDto(description, total));
    }
}

Ο υπολογισμός γίνεται στη μνήμη, γι’ αυτό χρησιμοποιούμε Task.FromResult. Διατηρούμε το ασύγχρονο συμβόλαιο ώστε ένας άλλος handler να μπορεί, για παράδειγμα, να κάνει await σε μια κλήση προς τη βάση δεδομένων.

Ο συγκεκριμένος handler ασχολείται με τις επιλογές και την τιμή. Δεν ελέγχει τον χρήστη και δεν περιέχει κώδικα μετρήσεων. Σε μια μεγαλύτερη εφαρμογή, οι κανόνες τιμολόγησης μπορούν να βρίσκονται σε ξεχωριστό μοντέλο του domain.

Authorization πριν εκτελεστεί ο handler

Οι πληροφορίες που χρειαζόμαστε για τον χρήστη

Το authorization απαντά στην ερώτηση «επιτρέπεται αυτός ο χρήστης να εκτελέσει αυτή τη λειτουργία;».

Ο decorator χρειάζεται να γνωρίζει αν ο χρήστης έχει συνδεθεί και αν έχει το απαραίτητο δικαίωμα:

public interface ICurrentUser
{
    bool IsAuthenticated { get; }
    bool HasPermission(string permission);
}

Το interface μάς επιτρέπει να πάρουμε αυτές τις πληροφορίες χωρίς να εξαρτάται ο decorator από το HttpContext του ASP.NET Core.

Θα χρησιμοποιήσουμε επίσης δύο δικά μας exceptions, ώστε να ξεχωρίζουμε τις διαφορετικές απορρίψεις:

public sealed class AuthenticationRequiredException : Exception
{
    public AuthenticationRequiredException()
        : base("Authentication is required.")
    {
    }
}

public sealed class PermissionDeniedException : Exception
{
    public PermissionDeniedException(string permission)
        : base($"Missing permission: {permission}.")
    {
    }
}

Ο authorization decorator

using System.Reflection;

public sealed class AuthorizationHandler<TRequest, TResult>
    : IRequestHandler<TRequest, TResult>
    where TRequest : IRequest<TResult>
{
    private static readonly RequiresPermissionAttribute? Requirement =
        typeof(TRequest).GetCustomAttribute<RequiresPermissionAttribute>();

    private readonly IRequestHandler<TRequest, TResult> _inner;
    private readonly ICurrentUser _currentUser;

    public AuthorizationHandler(
        IRequestHandler<TRequest, TResult> inner,
        ICurrentUser currentUser)
    {
        _inner = inner;
        _currentUser = currentUser;
    }

    public Task<TResult> HandleAsync(
        TRequest request,
        CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();

        if (Requirement is null)
        {
            throw new InvalidOperationException(
                $"Request {typeof(TRequest).Name} must declare a permission.");
        }

        if (!_currentUser.IsAuthenticated)
        {
            throw new AuthenticationRequiredException();
        }

        if (!_currentUser.HasPermission(Requirement.Permission))
        {
            throw new PermissionDeniedException(Requirement.Permission);
        }

        return _inner.HandleAsync(request, cancellationToken);
    }
}

Το _inner είναι ο handler που βρίσκεται μέσα στον decorator. Επειδή υλοποιεί το ίδιο interface, μπορεί να είναι είτε ο πραγματικός handler είτε ένας άλλος decorator.

Ο decorator πρώτα ελέγχει τις προϋποθέσεις. Αν όλα είναι εντάξει, καλεί τον εσωτερικό handler:

return _inner.HandleAsync(request, cancellationToken);

Αν ο χρήστης δεν έχει δικαίωμα, πετά exception και ο εσωτερικός handler δεν εκτελείται. Ένας decorator μπορεί λοιπόν να σταματήσει σκόπιμα την κλήση, όταν αυτό είναι μέρος της ευθύνης του.

Το GetCustomAttribute διαβάζει το attribute από τον τύπο του request. Το αποτέλεσμα αποθηκεύεται στο static readonly πεδίο, οπότε δεν επαναλαμβάνουμε αυτή την αναζήτηση σε κάθε κλήση για τον ίδιο συνδυασμό generic τύπων.

Στο παράδειγμά μας, κάθε request που περνά από αυτόν τον decorator πρέπει να δηλώνει permission. Αν το ξεχάσουμε, η εκτέλεση σταματά με σφάλμα ρύθμισης. Για δημόσια requests θα χρειαζόταν μια ρητή πολιτική που να επιτρέπει την ανώνυμη πρόσβαση.

Από τον χρήστη του API στο ICurrentUser

Σε ένα ASP.NET Core API μπορούμε να διαβάσουμε τα permissions από τα claims του χρήστη:

using Microsoft.AspNetCore.Http;

public sealed class HttpCurrentUser : ICurrentUser
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public HttpCurrentUser(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public bool IsAuthenticated =>
        _httpContextAccessor.HttpContext?
            .User.Identity?.IsAuthenticated == true;

    public bool HasPermission(string permission)
    {
        return IsAuthenticated
            && _httpContextAccessor.HttpContext!
                .User.HasClaim("permission", permission);
    }
}

Εδώ υποθέτουμε ότι το authentication της εφαρμογής έχει ήδη ρυθμιστεί και δημιουργεί ένα claim τύπου permission για κάθε δικαίωμα. Αν η εφαρμογή σου χρησιμοποιεί άλλο μοντέλο δικαιωμάτων, αλλάζει αυτή η υλοποίηση του ICurrentUser.

Το API πρέπει επίσης να μεταφράζει τα exceptions στις κατάλληλες HTTP απαντήσεις:

Exception	HTTP απάντηση
`AuthenticationRequiredException`	401 Unauthorized
`PermissionDeniedException`	403 Forbidden

Αυτή η αντιστοίχιση γίνεται στο κεντρικό error handling του API. Τα exceptions από μόνα τους δεν αλλάζουν τον HTTP status code. Το ASP.NET Core παρέχει το IExceptionHandler γι’ αυτή τη δουλειά, σε συνδυασμό με το exception handling middleware. Δες την τεκμηρίωση για το error handling.

Οι συγκεκριμένοι έλεγχοι αφορούν ένα γενικό permission. Μια λειτουργία που ανοίγει συγκεκριμένη παραγγελία μπορεί να χρειάζεται επιπλέον έλεγχο ιδιοκτησίας ή πρόσβασης στα δεδομένα της.

Telemetry γύρω από την εκτέλεση

Τι θέλουμε να μετρήσουμε

Με τον όρο telemetry εννοούμε εδώ τις πληροφορίες που συλλέγουμε για την εκτέλεση μιας λειτουργίας:

Πόσο χρόνο χρειάστηκε.
Αν ολοκληρώθηκε, απέτυχε ή ακυρώθηκε.
Πού βρίσκεται μέσα στη συνολική διαδρομή ενός request.

Θα χρησιμοποιήσουμε δύο APIs του .NET:

Το ActivitySource, για να δημιουργούμε ένα span, δηλαδή μια καταγραφή της συγκεκριμένης εκτέλεσης μέσα σε ένα trace.
Το Meter, για να καταγράφουμε μετρήσεις διάρκειας. Το histogram είναι ο τύπος μέτρησης που χρησιμοποιούμε για τις διάρκειες.

Οι πηγές των μετρήσεων

using System.Diagnostics;
using System.Diagnostics.Metrics;

public static class CqrsDiagnostics
{
    public const string SourceName = "PizzaApp.Cqrs";

    public static readonly ActivitySource Activities = new(SourceName);

    private static readonly Meter Meter = new(SourceName);

    public static readonly Histogram<double> Duration =
        Meter.CreateHistogram<double>(
            name: "pizzaapp.cqrs.duration",
            unit: "ms",
            description: "Duration of CQRS requests.");
}

Τα κρατάμε για όλη τη διάρκεια της εφαρμογής, αντί να δημιουργούμε νέες πηγές σε κάθε request.

Ο telemetry decorator

using System.Diagnostics;

public sealed class TelemetryHandler<TRequest, TResult>
    : IRequestHandler<TRequest, TResult>
    where TRequest : IRequest<TResult>
{
    private readonly IRequestHandler<TRequest, TResult> _inner;

    public TelemetryHandler(IRequestHandler<TRequest, TResult> inner)
    {
        _inner = inner;
    }

    public async Task<TResult> HandleAsync(
        TRequest request,
        CancellationToken cancellationToken = default)
    {
        string requestName = typeof(TRequest).Name;

        using var activity =
            CqrsDiagnostics.Activities.StartActivity(requestName);

        var stopwatch = Stopwatch.StartNew();
        string outcome = "success";

        try
        {
            return await _inner.HandleAsync(request, cancellationToken);
        }
        catch (OperationCanceledException)
            when (cancellationToken.IsCancellationRequested)
        {
            outcome = "cancelled";
            throw;
        }
        catch (Exception)
        {
            outcome = "failure";
            activity?.SetStatus(ActivityStatusCode.Error);
            throw;
        }
        finally
        {
            activity?.SetTag("cqrs.outcome", outcome);

            CqrsDiagnostics.Duration.Record(
                stopwatch.Elapsed.TotalMilliseconds,
                new KeyValuePair<string, object?>(
                    "cqrs.request", requestName),
                new KeyValuePair<string, object?>(
                    "cqrs.outcome", outcome));
        }
    }
}

Ας διαβάσουμε τη ροή με απλά λόγια:

Ξεκινά η καταγραφή και το χρονόμετρο.
Καλείται ο εσωτερικός handler.
Το await περιμένει να ολοκληρωθεί η εργασία του.
Αν υπάρξει σφάλμα, καταγράφουμε την αποτυχία και ξαναπετάμε το exception.
Το finally καταγράφει τη διάρκεια σε κάθε περίπτωση.

Το throw; επιτρέπει στον κώδικα που έκανε την κλήση να λάβει το αρχικό exception. Το telemetry δεν μετατρέπει μια αποτυχία σε επιτυχημένο αποτέλεσμα.

Το using var κλείνει το activity όταν τελειώσει η μέθοδος. Το activity?. σημαίνει «κάνε αυτή την κλήση μόνο αν υπάρχει activity», επειδή η StartActivity() μπορεί να επιστρέψει null όταν δεν υπάρχει ενδιαφερόμενος listener. Δες την τεκμηρίωση του ActivitySource.

Στα tags του histogram χρησιμοποιούμε το όνομα του request και λίγες σταθερές τιμές αποτελέσματος. IDs παραγγελιών και email χρηστών θα δημιουργούσαν πάρα πολλούς διαφορετικούς συνδυασμούς μετρήσεων.

Το cancelled αφορά ακύρωση που ζητήθηκε μέσω του token της κλήσης. Άλλο OperationCanceledException καταγράφεται εδώ ως αποτυχία. Σε μεγαλύτερη εφαρμογή μπορείς να ορίσεις πιο αναλυτική ταξινόμηση των αποτελεσμάτων.

Πώς βλέπουμε το telemetry με OpenTelemetry

Ο decorator παράγει τα δεδομένα. Χρειαζόμαστε επίσης ένα σύστημα που τα συλλέγει και έναν exporter, δηλαδή ένα εξάρτημα που τα στέλνει στον επιλεγμένο προορισμό.

Για ένα τοπικό παράδειγμα σε ASP.NET Core μπορούμε να χρησιμοποιήσουμε τον console exporter:

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.Console
dotnet add package OpenTelemetry.Instrumentation.AspNetCore

Στο Program.cs, πριν από το builder.Build():

using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddSource(CqrsDiagnostics.SourceName)
        .AddConsoleExporter())
    .WithMetrics(metrics => metrics
        .AddMeter(CqrsDiagnostics.SourceName)
        .AddConsoleExporter());

Το AddSource συνδέει τα activities μας με τη συλλογή traces. Το AddMeter συνδέει το histogram με τη συλλογή metrics.

Ο console exporter βοηθά στην τοπική ανάπτυξη. Για αποστολή σε ένα σύστημα παρακολούθησης μπορείς να χρησιμοποιήσεις έναν OTLP exporter και την αντίστοιχη ρύθμιση προορισμού. Δες την τεκμηρίωση των OpenTelemetry exporters.

Συνδέουμε τους decorators με Dependency Injection

Πρώτα η σύνθεση με new

Το Dependency Injection, ή DI, είναι ο μηχανισμός με τον οποίο η εφαρμογή παρέχει σε μια κλάση τις εξαρτήσεις που χρειάζεται.

Πριν το χρησιμοποιήσουμε, ας δούμε τι θέλουμε να κατασκευάσει. Αν έχουμε ήδη ένα ICurrentUser με το όνομα currentUser:

IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto> handler =
    new GetPizzaPriceHandler();

handler = new AuthorizationHandler<GetPizzaPriceQuery, PizzaPriceDto>(
    handler,
    currentUser);

handler = new TelemetryHandler<GetPizzaPriceQuery, PizzaPriceDto>(handler);

PizzaPriceDto result = await handler.HandleAsync(
    new GetPizzaPriceQuery(
        ExtraCheese: true,
        Mushrooms: true,
        Olives: false));

Αν ο χρήστης έχει το απαιτούμενο δικαίωμα, η τιμή που επιστρέφεται είναι 8,50 €.

Ξεκινάμε με την κανονική υλοποίηση και προσθέτουμε ένα αντικείμενο γύρω της κάθε φορά. Κάθε ανάθεση κρατά ως εσωτερικό handler την αλυσίδα που έχουμε ήδη κατασκευάσει.

Ένα ρητό registration χωρίς επιπλέον βιβλιοθήκη

Στο ASP.NET Core μπορούμε να δηλώσουμε την ίδια κατασκευή μέσα σε ένα factory:

using Microsoft.Extensions.DependencyInjection;

public static class PizzaPriceRegistration
{
    public static IServiceCollection AddPizzaPriceQuery(
        this IServiceCollection services)
    {
        services.AddHttpContextAccessor();
        services.AddScoped<ICurrentUser, HttpCurrentUser>();
        services.AddScoped<GetPizzaPriceHandler>();

        services.AddScoped<
            IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto>>(provider =>
        {
            IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto> handler =
                provider.GetRequiredService<GetPizzaPriceHandler>();

            handler = new AuthorizationHandler<
                GetPizzaPriceQuery, PizzaPriceDto>(
                    handler,
                    provider.GetRequiredService<ICurrentUser>());

            handler = new TelemetryHandler<
                GetPizzaPriceQuery, PizzaPriceDto>(handler);

            return handler;
        });

        return services;
    }
}

Και στο Program.cs:

builder.Services.AddPizzaPriceQuery();

Το factory είναι απλώς ο κώδικας που λέει στο DI πώς να κατασκευάσει την αλυσίδα. Όταν κάποια κλάση ζητήσει IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto>, θα πάρει τον εξωτερικό TelemetryHandler, ο οποίος κρατά τους υπόλοιπους μέσα του.

Χρησιμοποιούμε Scoped lifetime: τα συγκεκριμένα services συνδέονται με το ενεργό DI scope, που στο ASP.NET Core συνήθως αντιστοιχεί σε ένα HTTP request.

Καταχωρούμε και τον πραγματικό handler ως service. Έτσι το container διαχειρίζεται τον κύκλο ζωής του. Αυτό έχει σημασία αν αργότερα ο handler αποκτήσει πόρους που χρειάζονται Dispose. Οι decorators του παραδείγματος δεν κατέχουν τέτοιους πόρους. Δες τις οδηγίες του .NET για το DI και το disposal.

Για πολλούς handlers μπορεί να αξίζει μια δοκιμασμένη λύση αυτόματου decoration. Το ρητό registration εδώ κρατά ορατό τον τρόπο κατασκευής, χωρίς reflection πάνω στα registrations ή πρόσθετο μηχανισμό υποδομής.

Η σειρά αλλάζει τι παρατηρούμε

Στήσαμε αυτή την αλυσίδα:

Κλήση HandleAsync
└── TelemetryHandler
    └── AuthorizationHandler
        └── GetPizzaPriceHandler

Η εκτέλεση ξεκινά από τον εξωτερικό decorator:

Το telemetry ξεκινά τη μέτρηση.
Το authorization ελέγχει τα δικαιώματα.
Ο handler υπολογίζει την τιμή, αν επιτραπεί η εκτέλεση.
Το αποτέλεσμα ή το exception επιστρέφει προς τα έξω.
Το telemetry καταγράφει το αποτέλεσμα και τη διάρκεια.

Επειδή το telemetry είναι εξωτερικό, βλέπει και τις απορρίψεις του authorization. Αν αντιστρέφαμε τη σειρά, μια απόρριψη θα συνέβαινε πριν φτάσουμε στον telemetry decorator.

Η σειρά των decorators μπορεί να αλλάξει ουσιαστικά τη συμπεριφορά της εφαρμογής. Για παράδειγμα, ένας έλεγχος πρόσβασης πρέπει να γίνεται πριν επιστρέψουμε προστατευμένα δεδομένα από cache.

Ο κώδικας που καλεί τον handler

Σε ένα API με ρυθμισμένο authentication, authorization και error handling, το endpoint μπορεί να ζητήσει το κοινό interface:

app.MapGet("/pizza/price", async (
    bool extraCheese,
    bool mushrooms,
    bool olives,
    IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto> handler,
    CancellationToken cancellationToken) =>
{
    var query = new GetPizzaPriceQuery(extraCheese, mushrooms, olives);

    var result = await handler.HandleAsync(query, cancellationToken);

    return Results.Ok(result);
})
.RequireAuthorization();

Το endpoint γνωρίζει το request και το αποτέλεσμα. Η κατασκευή των decorators βρίσκεται στο registration.

Το RequireAuthorization() εφαρμόζει την πολιτική του HTTP endpoint. Ο decorator επιβάλλει τον έλεγχο του use case όταν αυτό καλείται μέσω της διακοσμημένης αλυσίδας, ακόμη και από άλλο σημείο της εφαρμογής.

Αν ένα background job χρειάζεται να καλέσει το use case, πρέπει να του παρέχουμε κατάλληλη ταυτότητα και υλοποίηση του ICurrentUser. Η HttpCurrentUser απαιτεί ενεργό HTTP context για να αναγνωρίσει χρήστη.

Έλεγχοι ότι η αλυσίδα λειτουργεί

Μπορούμε να ελέγξουμε ξεχωριστά τον υπολογισμό, τον decorator και τη σύνδεσή τους. Τα παρακάτω tests χρησιμοποιούν xUnit.

Ο handler υπολογίζει την τιμή

using Xunit;

public sealed class PizzaPriceHandlerTests
{
    [Fact]
    public async Task Returns_price_for_the_selected_ingredients()
    {
        var handler = new GetPizzaPriceHandler();

        var result = await handler.HandleAsync(
            new GetPizzaPriceQuery(true, true, false));

        Assert.Equal(8.50m, result.Total);
        Assert.Equal(
            "Πίτσα με σάλτσα ντομάτας, έξτρα τυρί, μανιτάρια",
            result.Description);
    }
}

Δεν χρειάζεται να δημιουργήσουμε χρήστη ή telemetry για να ελέγξουμε τον υπολογισμό.

Ο authorization decorator σταματά την κλήση

Για να ελέγξουμε τον decorator, χρειαζόμαστε έναν ψεύτικο χρήστη και έναν handler που μας λέει αν κλήθηκε:

public sealed class FakeCurrentUser : ICurrentUser
{
    private readonly string[] _permissions;

    public bool IsAuthenticated { get; }

    public FakeCurrentUser(bool isAuthenticated, params string[] permissions)
    {
        IsAuthenticated = isAuthenticated;
        _permissions = permissions;
    }

    public bool HasPermission(string permission)
    {
        return _permissions.Contains(permission);
    }
}

public sealed class SpyPizzaPriceHandler
    : IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto>
{
    public bool WasCalled { get; private set; }

    public Task<PizzaPriceDto> HandleAsync(
        GetPizzaPriceQuery request,
        CancellationToken cancellationToken = default)
    {
        WasCalled = true;

        return Task.FromResult(new PizzaPriceDto("Test pizza", 6.00m));
    }
}

Το test ελέγχει και το exception και το ότι ο εσωτερικός handler δεν εκτελέστηκε:

using Xunit;

public sealed class AuthorizationHandlerTests
{
    [Fact]
    public async Task Does_not_call_inner_when_permission_is_missing()
    {
        var inner = new SpyPizzaPriceHandler();
        var user = new FakeCurrentUser(isAuthenticated: true);

        var handler = new AuthorizationHandler<
            GetPizzaPriceQuery, PizzaPriceDto>(inner, user);

        await Assert.ThrowsAsync<PermissionDeniedException>(() =>
            handler.HandleAsync(new GetPizzaPriceQuery(false, false, false)));

        Assert.False(inner.WasCalled);
    }

    [Fact]
    public async Task Calls_inner_when_permission_is_granted()
    {
        var inner = new SpyPizzaPriceHandler();
        var user = new FakeCurrentUser(true, "pizza.prices.read");

        var handler = new AuthorizationHandler<
            GetPizzaPriceQuery, PizzaPriceDto>(inner, user);

        await handler.HandleAsync(new GetPizzaPriceQuery(false, false, false));

        Assert.True(inner.WasCalled);
    }
}

Το DI εφαρμόζει πράγματι τον έλεγχο

Τα προηγούμενα tests κατασκευάζουν τον decorator απευθείας. Χρειαζόμαστε και έναν έλεγχο ότι το registration επιστρέφει τη σωστή αλυσίδα:

using Microsoft.Extensions.DependencyInjection;
using Xunit;

public sealed class PizzaPriceRegistrationTests
{
    [Fact]
    public async Task Resolved_handler_enforces_permissions()
    {
        var services = new ServiceCollection();
        services.AddPizzaPriceQuery();

        // Στο test αντικαθιστούμε τον χρήστη του HTTP request.
        services.AddScoped<ICurrentUser>(_ =>
            new FakeCurrentUser(isAuthenticated: true));

        using var provider = services.BuildServiceProvider(
            new ServiceProviderOptions
            {
                ValidateScopes = true,
                ValidateOnBuild = true
            });

        using var scope = provider.CreateScope();

        var handler = scope.ServiceProvider.GetRequiredService<
            IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto>>();

        Assert.IsType<
            TelemetryHandler<GetPizzaPriceQuery, PizzaPriceDto>>(handler);

        await Assert.ThrowsAsync<PermissionDeniedException>(() =>
            handler.HandleAsync(new GetPizzaPriceQuery(false, false, false)));
    }
}

Αυτό το test θα αποτύχει αν το registration παρακάμψει το authorization, ακόμη κι αν ο εξωτερικός τύπος παραμείνει TelemetryHandler.

Για τον telemetry decorator, χρήσιμοι έλεγχοι είναι ότι καταγράφει span και διάρκεια, διατηρεί τα exceptions και ξεχωρίζει τη ζητημένη ακύρωση. Αυτά μπορούν να ελεγχθούν με ActivityListener και MeterListener, χωρίς εξωτερικό σύστημα παρακολούθησης.

Πού ανήκει κάθε κομμάτι σε Clean Architecture

Σε μια εφαρμογή που ακολουθεί Clean Architecture, μια λογική οργάνωση για το παράδειγμα είναι:

Περιοχή	Περιεχόμενο
Domain	Το μοντέλο της πίτσας και οι κανόνες τιμολόγησης
Application	Requests, handlers, `ICurrentUser`, `permission` attribute, authorization decorator
Infrastructure	Telemetry decorator και τεχνικές συνδέσεις
API	`HttpCurrentUser`, endpoints, HTTP error handling και σύνθεση του DI

Το Application ορίζει τι πληροφορίες χρειάζεται από τον χρήστη μέσω του ICurrentUser. Το API παρέχει την υλοποίηση που διαβάζει τον χρήστη του HTTP request.

Η δομή των φακέλων μπορεί να διαφέρει ανά project. Το ουσιαστικό είναι οι κανόνες της εφαρμογής να μη χρειάζονται το HTTP ή έναν συγκεκριμένο προμηθευτή telemetry για να εκτελεστούν.

Παγίδες που αξίζει να προσέξεις

Να ξεχάσεις την κλήση του εσωτερικού αντικειμένου

Αν ένας decorator κάνει μόνο τη δική του δουλειά και δεν καλέσει το _inner, η κανονική λειτουργία δεν θα εκτελεστεί. Αυτό πρέπει να συμβαίνει μόνο όταν είναι σκόπιμο, όπως στην απόρριψη πρόσβασης ή σε ένα έγκυρο cache hit.

Να ζητήσεις το ίδιο interface μέσα από το factory

Μέσα στο factory του IRequestHandler<GetPizzaPriceQuery, PizzaPriceDto>, μην ζητήσεις από το DI να σου δώσει ξανά αυτό το ίδιο service για να το χρησιμοποιήσεις ως _inner.

Το DI θα προσπαθεί να κατασκευάσει το ίδιο service από την αρχή και θα δημιουργηθεί κυκλική εξάρτηση. Γι’ αυτό στο παράδειγμα ζητάμε τον συγκεκριμένο GetPizzaPriceHandler και χτίζουμε την αλυσίδα γύρω του.

Να παρακάμψεις τους decorators

Αν ένα endpoint δημιουργήσει μόνο του new GetPizzaPriceHandler(), δεν περνά από το authorization ή το telemetry.

Το pattern δεν επιβάλλει από μόνο του τη χρήση του. Ο κώδικας της εφαρμογής πρέπει να ζητά το διακοσμημένο interface, και τα tests της σύνθεσης να επιβεβαιώνουν ότι το DI το κατασκευάζει σωστά.

Να ξεχάσεις το await ή το CancellationToken

Ένας telemetry decorator πρέπει να περιμένει την ασύγχρονη εργασία πριν ολοκληρώσει τη μέτρηση. Διαφορετικά μπορεί να μετρήσει μόνο τον χρόνο δημιουργίας του Task.

Κάθε decorator πρέπει επίσης να προωθεί το CancellationToken στον επόμενο handler. Έτσι η δυνατότητα ακύρωσης δεν χάνεται στη μέση της αλυσίδας.

Να καταπιείς το exception

Αν καταγράψεις ένα σφάλμα και επιστρέψεις ένα «κανονικό» αποτέλεσμα, ο καλών μπορεί να νομίσει ότι η εργασία ολοκληρώθηκε. Σε έναν decorator παρακολούθησης, συνήθως καταγράφεις και κάνεις throw;.

Να συνδυάσεις ασύμβατα lifetimes

Ένας singleton δεν πρέπει να κρατά ένα service που ανήκει σε request scope. Εδώ κρατάμε την αλυσίδα και το ICurrentUser ως scoped services και ενεργοποιούμε το scope validation στα tests.

Να κρύψεις ειδικούς κανόνες ενός use case σε έναν γενικό decorator

Ένας γενικός decorator μπορεί να εφαρμόζει μια κοινή πολιτική δικαιωμάτων ή μετρήσεων. Ένας ειδικός κανόνας όπως «αν η παραγγελία ξεπερνά ένα ποσό, χρειάζεται έγκριση υπευθύνου» πρέπει να φαίνεται στη λογική του αντίστοιχου use case ή του domain.

Το Decorator μπορεί να χρησιμοποιηθεί και στο domain, όταν εκφράζει καθαρά τη συμπεριφορά του μοντέλου. Το πρόβλημα εδώ είναι να κρύβουμε έναν ειδικό επιχειρησιακό κανόνα σε έναν γενικό decorator που εφαρμόζεται σε πολλά διαφορετικά requests.

Πότε αξίζει να χρησιμοποιήσεις Decorator

Το pattern είναι χρήσιμο όταν θέλεις να συνδυάζεις ανεξάρτητες προσθήκες γύρω από ένα αντικείμενο, διατηρώντας το ίδιο συμβόλαιο κλήσης.

Συνηθισμένες εφαρμογές είναι το logging, οι μετρήσεις, οι έλεγχοι πρόσβασης και το caching. Ένας decorator μπορεί επίσης να εφαρμόζει retries, αρκεί η επανάληψη της συγκεκριμένης πράξης να είναι ασφαλής. Μια επανάληψη σε καταχώριση παραγγελίας, για παράδειγμα, χρειάζεται πρόβλεψη ώστε να μη δημιουργήσει δεύτερη παραγγελία.

Δεν χρειάζεται να το προσθέτεις σε κάθε κλάση. Αν μια μικρή λειτουργία εκφράζεται καθαρά με λίγες γραμμές, τα επιπλέον αντικείμενα μπορεί να κάνουν τον κώδικα δυσκολότερο στην παρακολούθηση. Η χρησιμότητα του pattern κρίνεται από το αν διευκολύνει την επέκταση και την κατανόηση της συγκεκριμένης εφαρμογής.

Η διαφορά από άλλα wrappers

Η λέξη wrapper περιγράφει γενικά ένα αντικείμενο που κρατά και χρησιμοποιεί ένα άλλο. Ο σκοπός του καθορίζει ποιο pattern εφαρμόζουμε.

Έννοια	Κύριος σκοπός
Decorator	Προσθέτει συμπεριφορά γύρω από ένα αντικείμενο, διατηρώντας το κοινό συμβόλαιο.
Adapter	Προσαρμόζει μια υπάρχουσα υλοποίηση στο interface που χρειάζεται ο κώδικας που την καλεί.
Proxy	Παρεμβάλλεται στην πρόσβαση σε ένα αντικείμενο, για παράδειγμα για απομακρυσμένη πρόσβαση ή καθυστερημένη δημιουργία.

Ένας authorization wrapper μπορεί να περιγραφεί και ως protection proxy. Οι ονομασίες βοηθούν να εξηγήσουμε την πρόθεση του κώδικα, αλλά δεν έχουν πάντα απόλυτα όρια.

Το ASP.NET Core middleware και τα MediatR pipeline behaviors επιτρέπουν επίσης την εκτέλεση κώδικα πριν ή μετά από την επόμενη λειτουργία. Έχουν όμως δικά τους συμβόλαια και μηχανισμούς σύνθεσης. Το middleware λειτουργεί στην αλυσίδα HTTP, ενώ οι decorators που γράψαμε τυλίγουν το δικό μας interface handler.

Τι να κρατήσεις από το παράδειγμα

Ο πραγματικός handler υπολογίζει την τιμή. Ο authorization decorator ελέγχει αν επιτρέπεται η εκτέλεση. Ο telemetry decorator παρακολουθεί ολόκληρη την κλήση και καταγράφει τη διάρκεια και το αποτέλεσμά της.

Η σύνθεση στο DI ορίζει ποιος decorator βρίσκεται εξωτερικά και ποιος καλείται στη συνέχεια. Στο παράδειγμά μας, το telemetry περιβάλλει και το authorization, οπότε βλέπει και τις απορρίψεις πρόσβασης.

Αν δεις έναν decorator στον κώδικα, αναζήτησε το κοινό interface, το εσωτερικό αντικείμενο και την επιπλέον δουλειά γύρω από την κλήση του. Για να ελέγξεις τη χρήση του στην εφαρμογή, ακολούθησε και το registration: εκεί φαίνεται ποια αλυσίδα λαμβάνει τελικά ο κώδικας που ζητά τον handler.

Decorator pattern στην C# βήμα βήμα με μια πίτσα

nikosstit@gmail.com

Decorator pattern στην C# βήμα βήμα με μια πίτσα

nikosst — Thu, 29 Oct 2026 07:36:03 +0000

Κατανόησε το Decorator pattern στην C# με ένα απλό παράδειγμα πίτσας και συνδύασε προσθήκες χωρίς κλάση για κάθε πιθανό συνδυασμό.

Έχεις μια βασική πίτσα. Ο πελάτης μπορεί να προσθέσει έξτρα τυρί, μανιτάρια, ελιές ή όποιον συνδυασμό θέλει.

Πώς θα το έγραφες στον κώδικα;

Θα έφτιαχνες μια διαφορετική κλάση για κάθε πιθανό συνδυασμό; Θα άλλαζες συνέχεια την κλάση της βασικής πίτσας;

Το Decorator pattern προσφέρει μια άλλη επιλογή: ξεκινάς με ένα αντικείμενο και προσθέτεις δυνατότητες γύρω του, μία κάθε φορά.

Σε αυτό το άρθρο θα το δούμε με την πίτσα, βήμα βήμα: από το κοινό interface μέχρι τον συνδυασμό των υλικών κατά την εκτέλεση.

Για να ακολουθήσεις το παράδειγμα, αρκεί να γνωρίζεις κλάσεις, constructors και interfaces.

Το πρόβλημα με τους συνδυασμούς

Ας υποθέσουμε ότι η πιτσαρία έχει αυτές τις τιμές:

Επιλογή	Τιμή
Βασική πίτσα με σάλτσα ντομάτας	6,00 €
Έξτρα τυρί	+1,50 €
Μανιτάρια	+1,00 €
Ελιές	+0,50 €

Ο ένας πελάτης θέλει μόνο τυρί. Ο άλλος τυρί και μανιτάρια. Ο τρίτος μανιτάρια και ελιές.

Αν έφτιαχνες μια κλάση για κάθε συνδυασμό, θα κατέληγες με ονόματα όπως:

PlainPizza
PizzaWithExtraCheese
PizzaWithMushrooms
PizzaWithOlives
PizzaWithExtraCheeseAndMushrooms
PizzaWithExtraCheeseAndOlives
PizzaWithMushroomsAndOlives
PizzaWithExtraCheeseAndMushroomsAndOlives

Με κάθε νέο υλικό αυξάνονται οι πιθανοί συνδυασμοί. Δεν θέλουμε να γράφουμε μια νέα κλάση για κάθε παραγγελία που μπορεί να σκεφτεί ο πελάτης.

Θέλουμε να γράψουμε κάθε προσθήκη μία φορά και να μπορούμε να τη συνδυάζουμε με τις υπόλοιπες.

Η ιδέα σε μία πρόταση

Ένας decorator κρατά μέσα του ένα άλλο αντικείμενο, προσφέρει τις ίδιες μεθόδους και προσθέτει τη δική του δουλειά όταν τις καλούμε.

Στο παράδειγμά μας, η πίτσα με έξτρα τυρί θα κρατά μέσα της μια πίτσα. Όταν ζητήσουμε την τιμή της, θα πάρει την τιμή της εσωτερικής πίτσας και θα προσθέσει την τιμή του τυριού.

Ας το γράψουμε.

Βήμα 1 Ορίζουμε τι μπορεί να κάνει μια πίτσα

Χρειαζόμαστε δύο πληροφορίες: την περιγραφή και την τιμή.

public interface IPizza
{
    string GetDescription();
    decimal GetPrice();
}

Το interface είναι ένα κοινό συμβόλαιο. Οποιαδήποτε κλάση υλοποιεί το IPizza πρέπει να παρέχει αυτές τις δύο μεθόδους.

Άρα, αν έχουμε μια μεταβλητή τύπου IPizza, μπορούμε να ζητήσουμε περιγραφή και τιμή χωρίς να γνωρίζουμε ποια συγκεκριμένη κλάση βρίσκεται από πίσω.

Βήμα 2 Φτιάχνουμε τη βασική πίτσα

public sealed class PlainPizza : IPizza
{
    public string GetDescription()
    {
        return "Πίτσα με σάλτσα ντομάτας";
    }

    public decimal GetPrice()
    {
        return 6.00m;
    }
}

Το m στο 6.00m δηλώνει αριθμό τύπου decimal, τον οποίο χρησιμοποιούμε εδώ για τις χρηματικές τιμές.

Προς το παρόν έχουμε μόνο μια απλή πίτσα:

IPizza pizza = new PlainPizza();

Console.WriteLine(pizza.GetDescription());
Console.WriteLine(pizza.GetPrice());

Η περιγραφή είναι «Πίτσα με σάλτσα ντομάτας» και η τιμή 6,00 €.

Βήμα 3 Προσθέτουμε έξτρα τυρί με έναν decorator

Θέλουμε να προσθέσουμε έξτρα τυρί χωρίς να αλλάξουμε την PlainPizza.

public sealed class ExtraCheeseDecorator : IPizza
{
    private readonly IPizza _pizza;

    public ExtraCheeseDecorator(IPizza pizza)
    {
        _pizza = pizza;
    }

    public string GetDescription()
    {
        return _pizza.GetDescription() + ", έξτρα τυρί";
    }

    public decimal GetPrice()
    {
        return _pizza.GetPrice() + 1.50m;
    }
}

Αυτή η κλάση είναι ο πρώτος μας decorator. Ας δούμε τι κάνει κάθε κομμάτι της.

Το : IPizza σημαίνει ότι προσφέρει τις ίδιες μεθόδους με τη βασική πίτσα: GetDescription() και GetPrice().

Το πεδίο _pizza κρατά την πίτσα στην οποία προσθέτουμε τυρί. Η πίτσα αυτή περνά στον constructor.

Η GetPrice() ζητά πρώτα την τιμή από την εσωτερική πίτσα και προσθέτει 1,50 €. Η GetDescription() ζητά την περιγραφή της και προσθέτει το κείμενο «έξτρα τυρί».

Η χρήση του είναι:

IPizza plainPizza = new PlainPizza();
IPizza pizzaWithCheese = new ExtraCheeseDecorator(plainPizza);

Έχουμε πλέον δύο αντικείμενα. Το ένα είναι η βασική πίτσα και το άλλο ο decorator που την κρατά μέσα του:

ExtraCheeseDecorator
└── PlainPizza

Όταν γράφουμε:

decimal total = pizzaWithCheese.GetPrice();

συμβαίνουν τα εξής:

Καλείται η GetPrice() του ExtraCheeseDecorator.
Ο decorator καλεί τη GetPrice() της PlainPizza και παίρνει 6.00m.
Προσθέτει 1.50m και επιστρέφει 7.50m.

Η PlainPizza εξακολουθεί να κοστίζει 6,00 €. Το νέο αντικείμενο pizzaWithCheese επιστρέφει 7,50 €.

Αυτό εννοούμε όταν λέμε ότι ο decorator προσθέτει συμπεριφορά χωρίς να αλλάζει το αρχικό αντικείμενο.

Βήμα 4 Φτιάχνουμε έναν decorator για κάθε επιπλέον υλικό

Τα μανιτάρια ακολουθούν την ίδια λογική:

public sealed class MushroomsDecorator : IPizza
{
    private readonly IPizza _pizza;

    public MushroomsDecorator(IPizza pizza)
    {
        _pizza = pizza;
    }

    public string GetDescription()
    {
        return _pizza.GetDescription() + ", μανιτάρια";
    }

    public decimal GetPrice()
    {
        return _pizza.GetPrice() + 1.00m;
    }
}

Και οι ελιές:

public sealed class OlivesDecorator : IPizza
{
    private readonly IPizza _pizza;

    public OlivesDecorator(IPizza pizza)
    {
        _pizza = pizza;
    }

    public string GetDescription()
    {
        return _pizza.GetDescription() + ", ελιές";
    }

    public decimal GetPrice()
    {
        return _pizza.GetPrice() + 0.50m;
    }
}

Κάθε decorator γνωρίζει μόνο τη δική του προσθήκη. Ο decorator για τις ελιές δεν χρειάζεται να γνωρίζει αν η πίτσα έχει ήδη τυρί ή μανιτάρια.

Βήμα 5 Προσθέτουμε υλικά ένα ένα

IPizza pizza = new PlainPizza();
// Βασική πίτσα: 6,00 €

pizza = new ExtraCheeseDecorator(pizza);
// Προσθέσαμε τυρί: 7,50 €

pizza = new MushroomsDecorator(pizza);
// Προσθέσαμε μανιτάρια: 8,50 €

pizza = new OlivesDecorator(pizza);
// Προσθέσαμε ελιές: 9,00 €

Console.WriteLine(pizza.GetDescription());
Console.WriteLine(pizza.GetPrice());

Η τελική περιγραφή είναι:

Πίτσα με σάλτσα ντομάτας, έξτρα τυρί, μανιτάρια, ελιές

Η τελική τιμή είναι 9,00 €.

Πρόσεξε αυτή τη γραμμή:

pizza = new MushroomsDecorator(pizza);

Στα δεξιά, δίνουμε στον νέο decorator ό,τι περιείχε μέχρι εκείνη τη στιγμή η μεταβλητή pizza: την πίτσα με έξτρα τυρί.

Στα αριστερά, κάνουμε τη μεταβλητή να δείχνει στο νέο αντικείμενο, το οποίο προσθέτει μανιτάρια.

Δεν σβήνεται η προηγούμενη πίτσα. Ο νέος decorator κρατά αναφορά σε αυτήν. Έτσι σχηματίζεται μια αλυσίδα:

OlivesDecorator
└── MushroomsDecorator
    └── ExtraCheeseDecorator
        └── PlainPizza

Η κλήση της GetPrice() ξεκινά από τις ελιές και προχωρά προς τη βασική πίτσα. Έπειτα τα αποτελέσματα επιστρέφουν προς τα έξω:

PlainPizza                 → 6,00 €
ExtraCheeseDecorator       → 6,00 + 1,50 = 7,50 €
MushroomsDecorator         → 7,50 + 1,00 = 8,50 €
OlivesDecorator            → 8,50 + 0,50 = 9,00 €

Βήμα 6 Αφήνουμε τον πελάτη να επιλέξει

Δεν χρειάζεται κάθε πίτσα να έχει όλα τα υλικά. Ας υποθέσουμε ότι οι παρακάτω τιμές προέρχονται από τις επιλογές του πελάτη:

bool wantsExtraCheese = true;
bool wantsMushrooms = false;
bool wantsOlives = true;

IPizza pizza = new PlainPizza();

if (wantsExtraCheese)
{
    pizza = new ExtraCheeseDecorator(pizza);
}

if (wantsMushrooms)
{
    pizza = new MushroomsDecorator(pizza);
}

if (wantsOlives)
{
    pizza = new OlivesDecorator(pizza);
}

Console.WriteLine(pizza.GetDescription());
Console.WriteLine(pizza.GetPrice());

Αυτή η παραγγελία έχει έξτρα τυρί και ελιές, άρα κοστίζει 8,00 €.

Αν ο πελάτης επιλέξει μόνο μανιτάρια, εφαρμόζεται μόνο ο MushroomsDecorator. Αν δεν επιλέξει τίποτα, παραμένει η PlainPizza.

Αυτό σημαίνει ότι συνδυάζουμε τις προσθήκες κατά την εκτέλεση του προγράμματος, ανάλογα με τις επιλογές που λαμβάνουμε.

Για να δοκιμάσεις την πίτσα σε ένα console project, βάλε στο Program.cs πρώτα ένα από τα παραδείγματα χρήσης και από κάτω το IPizza και τις τέσσερις κλάσεις. Τα παραδείγματα χρήσης είναι εναλλακτικά, οπότε δεν χρειάζεται να τα αντιγράψεις όλα μαζί.

Τι κάνει τελικά μια κλάση decorator

Ο ExtraCheeseDecorator έχει δύο βασικά χαρακτηριστικά:

Είναι IPizza, οπότε μπορούμε να τον χρησιμοποιήσουμε όπου περιμένουμε μια πίτσα.
Κρατά ένα IPizza, οπότε μπορεί να περιέχει είτε τη βασική πίτσα είτε άλλον decorator.

Ο constructor του δέχεται IPizza, όχι μόνο PlainPizza. Γι’ αυτό μπορεί να δεχτεί και μια πίτσα που έχει ήδη μανιτάρια ή ελιές.

Ο υπόλοιπος κώδικας συνεχίζει να καλεί τις ίδιες δύο μεθόδους:

string description = pizza.GetDescription();
decimal price = pizza.GetPrice();

Δεν χρειάζεται να εξετάσει πόσα αντικείμενα υπάρχουν στην αλυσίδα ή ποια υλικά έχει επιλέξει ο πελάτης.

Τι κερδίσαμε

Η βασική πίτσα έμεινε απλή. Κάθε υλικό γράφτηκε μία φορά και μπορεί να συνδυαστεί με τα υπόλοιπα.

Για να προσθέσουμε πιπεριά, μπορούμε να γράψουμε έναν PeppersDecorator. Δεν χρειάζεται να αλλάξουμε τις υπάρχουσες κλάσεις της πίτσας. Θα προσθέσουμε, βέβαια, την καινούργια επιλογή στο σημείο όπου διαβάζουμε τις επιλογές του πελάτη.

Αυτό συνδέεται με δύο αρχές του SOLID:

Single Responsibility: κάθε κλάση έχει μια συγκεκριμένη ευθύνη.
Open/Closed: επεκτείνουμε τη λειτουργικότητα με νέα κλάση, διατηρώντας τις υπάρχουσες υλοποιήσεις.

Το κοινό interface βοηθά επίσης τον κώδικα να εξαρτάται από το IPizza, αντί να γνωρίζει κάθε συγκεκριμένη κλάση.

Χρειάζεται κάθε πιτσαρία Decorator

Αν το μόνο που χρειάζεσαι είναι μια λίστα υλικών και το άθροισμα των τιμών τους, μια συλλογή από Topping αντικείμενα μπορεί να είναι απλούστερη λύση.

Εδώ χρησιμοποιούμε την πίτσα για να γίνει ορατός ο μηχανισμός του pattern: κάθε αντικείμενο ζητά το αποτέλεσμα του προηγούμενου και προσθέτει κάτι δικό του.

Η ίδια δομή γίνεται ιδιαίτερα χρήσιμη όταν η προσθήκη είναι μια ενέργεια γύρω από μια άλλη ενέργεια. Για παράδειγμα: «έλεγξε δικαιώματα πριν εκτελέσεις μια λειτουργία» ή «μέτρησε πόσο χρόνο χρειάστηκε».

Τι να κρατήσεις από το παράδειγμα

Ξεκινήσαμε με μια πίτσα των 6,00 €. Κάθε decorator πρόσθεσε την περιγραφή και την τιμή ενός υλικού, χρησιμοποιώντας την πίτσα που είχε ήδη δημιουργηθεί.

Ο μηχανισμός στηρίζεται σε τρία κομμάτια:

Ένα κοινό interface, το IPizza.
Ένα εσωτερικό αντικείμενο που υλοποιεί αυτό το interface.
Τη συμπεριφορά που προσθέτει ο decorator γύρω από την κλήση του.

Επειδή ένας decorator είναι και ο ίδιος IPizza, μπορεί να τυλιχτεί από έναν ακόμη decorator. Έτσι συνδυάζουμε προσθήκες κατά την εκτέλεση, χωρίς να χρειαζόμαστε μια διαφορετική κλάση για κάθε πιθανό συνδυασμό.

Decorator pattern σε CQRS handlers με authorization και telemetry στο .NET

nikosstit@gmail.com