API-Design

Öffentliches API-Design und Kompatibilität

Wann dieses Skill verwendet werden sollte

Verwende dieses Skill, wenn:

• Öffentliche APIs für NuGet-Pakete oder Bibliotheken entworfen werden
• Änderungen an vorhandenen öffentlichen APIs vorgenommen werden
• Wire-Format-Änderungen für verteilte Systeme geplant werden
• Versionierungsstrategien implementiert werden
• Pull-Requests auf Breaking Changes überprüft werden

---

Die drei Arten der Kompatibilität

Typ	Definition	Umfang
API/Source	Code kompiliert gegen neuere Version	Öffentliche Methodensignaturen, Typen
Binary	Kompilierter Code läuft gegen neuere Version	Assembly-Layout, Method-Tokens
Wire	Serialisierte Daten sind von anderen Versionen lesbar	Netzwerkprotokolle, Persistenzformate

Das Brechen einer dieser Kompatibilitäten verursacht Reibung bei Upgrades für Benutzer.

---

Extend-Only Design

Die Grundlage stabiler APIs: niemals entfernen oder ändern, nur erweitern.

Drei Säulen

1. Vorherige Funktionalität ist unveränderlich – Einmal veröffentlicht, sind Verhalten und Signaturen eingefroren
2. Neue Funktionalität durch neue Konstrukte – Füge Überladungen, neue Typen, Opt-In-Funktionen hinzu
3. Entfernung erst nach Deprecation-Zeitraum – Jahre, nicht Releases

Vorteile

• Alter Code funktioniert weiterhin in neuen Versionen
• Neue und alte Pfade koexistieren
• Upgrades sind standardmäßig nicht-breaking
• Benutzer aktualisieren nach ihrem Zeitplan

Ressourcen:

• Extend-Only Design
• OSS Compatibility Standards

---

Richtlinien für API-Änderungen

Sichere Änderungen (Jedes Release)

// NEUE Überladungen mit Standardparametern hinzufügen
public void Process(Order order, CancellationToken ct = default);

// NEUE optionale Parameter zu vorhandenen Methoden hinzufügen
public void Send(Message msg, Priority priority = Priority.Normal);

// NEUE Typen, Interfaces, Enums hinzufügen
public interface IOrderValidator { }
public enum OrderStatus { Pending, Complete, Cancelled }

// NEUE Member zu vorhandenen Typen hinzufügen
public class Order
{
    public DateTimeOffset? ShippedAt { get; init; }  // NEU
}

Unsichere Änderungen (Niemals oder nur in Major-Version)

// Öffentliche Member ENTFERNEN oder UMBENENNEN
public void ProcessOrder(Order order);  // War: Process()

// Parametertypen oder -reihenfolge ÄNDERN
public void Process(int orderId);  // War: Process(Order order)

// Rückgabetypen ÄNDERN
public Order? GetOrder(string id);  // War: public Order GetOrder()

// Zugriffsmodifikatoren ÄNDERN
internal class OrderProcessor { }  // War: public

// Erforderliche Parameter ohne Standardwerte HINZUFÜGEN
public void Process(Order order, ILogger logger);  // Bricht Aufrufer!

Deprecation-Muster

// Schritt 1: Als veraltet markieren mit Version (jedes Release)
[Obsolete("Veraltet seit v1.5.0. Verwende ProcessAsync stattdessen.")]
public void Process(Order order) { }

// Schritt 2: Neue empfohlene API hinzufügen (gleiches Release)
public Task ProcessAsync(Order order, CancellationToken ct = default);

// Schritt 3: In der nächsten Major-Version entfernen (v2.0+)
// Erst nachdem Benutzer Zeit zur Migration hatten

---

API-Approval-Tests

Verhindere versehentliche Breaking Changes mit automatisierten API-Oberflächentests.

Verwenden von ApiApprover + Verify

dotnet add package PublicApiGenerator
dotnet add package Verify.Xunit

[Fact]
public Task ApprovePublicApi()
{
    var api = typeof(MyLibrary.PublicClass).Assembly.GeneratePublicApi();
    return Verify(api);
}

Erzeugt ApprovePublicApi.verified.txt:

namespace MyLibrary
{
    public class OrderProcessor
    {
        public OrderProcessor() { }
        public void Process(Order order) { }
        public Task ProcessAsync(Order order, CancellationToken ct = default) { }
    }
}

Jede API-Änderung lässt den Test fehlschlagen – der Reviewer muss Änderungen explizit genehmigen.

PR-Review-Prozess

1. PR enthält Änderungen an *.verified.txt-Dateien
2. Reviewer sehen die genauen API-Oberflächenänderungen im Diff
3. Breaking Changes sind sofort sichtbar
4. Bewusste Entscheidung zur Genehmigung erforderlich

---

Wire-Kompatibilität

Für verteilte Systeme müssen serialisierte Daten versionsübergreifend lesbar sein.

Anforderungen

Richtung	Anforderung
Rückwärts	Alte Schreiber → Neue Leser (aktuelle Version liest alte Daten)
Vorwärts	Neue Schreiber → Alte Leser (alte Version liest neue Daten)

Beide sind für nahtlose Rolling-Upgrades erforderlich.

Wire-Formate sicher weiterentwickeln

Phase 1: Leseseitige Unterstützung hinzufügen (Opt-In)

// Neuer Nachrichtentyp – Leser werden zuerst bereitgestellt
public sealed record HeartbeatV2(
    Address From,
    long SequenceNr,
    long CreationTimeMs);  // NEUES Feld

// Deserialisierer verarbeitet sowohl alte als auch neue Formate
public object Deserialize(byte[] data, string manifest) => manifest switch
{
    "Heartbeat" => DeserializeHeartbeatV1(data),   // Altes Format
    "HeartbeatV2" => DeserializeHeartbeatV2(data), // Neues Format
    _ => throw new NotSupportedException()
};

Phase 2: Schreibseite aktivieren (Opt-Out, nächstes Minor-Release)

// Konfiguration zum Aktivieren des neuen Formats (standardmäßig aus)
akka.cluster.use-heartbeat-v2 = on

Phase 3: Zum Standard machen (zukünftige Version)

Nachdem die Installationsbasis den leseseitigen Code übernommen hat.

Schema-basierte Serialisierung

Bevorzuge schema-basierte Formate gegenüber reflexionsbasierten:

Format	Typ	Wire-Kompatibilität
Protocol Buffers	Schema-basiert	Hervorragend – explizite Feldnummern
MessagePack	Schema-basiert	Gut – mit Verträgen
System.Text.Json	Schema-basiert (mit Source Gen)	Gut – explizite Eigenschaften
Newtonsoft.Json	Reflexionsbasiert	Schlecht – Typnamen im Payload
BinaryFormatter	Reflexionsbasiert	Schrecklich – niemals verwenden

Siehe Skill dotnet/serialization für Details.

---

Kapselungsmuster

Interne APIs

Markiere nicht-öffentliche APIs explizit:

// Attribut zur Dokumentation
[InternalApi]
public class ActorSystemImpl { }

// Namespace-Konvention
namespace MyLibrary.Internal
{
    public class InternalHelper { }  // Öffentlich für Erweiterbarkeit, nicht für Benutzer
}

Dokumentiere klar:

Typen in .Internal-Namespaces oder mit [InternalApi] markiert können sich zwischen beliebigen Releases ohne Vorankündigung ändern.

Versiegelte Klassen

// MACHEN: Nicht für Vererbung gedachte Klassen versiegeln
public sealed class OrderProcessor { }

// NICHT MACHEN: Versehentlich unversiegelt lassen
public class OrderProcessor { }  // Benutzer könnten erben, was Änderungen blockiert

Interface-Segregation

// MACHEN: Kleine, fokussierte Interfaces
public interface IOrderReader
{
    Order? GetById(OrderId id);
}

public interface IOrderWriter
{
    Task SaveAsync(Order order);
}

// NICHT MACHEN: Monolithische Interfaces (Methoden können nicht hinzugefügt werden, ohne zu brechen)
public interface IOrderRepository
{
    Order? GetById(OrderId id);
    Task SaveAsync(Order order);
    // Neue Methoden hinzufügen bricht alle Implementierungen!
}

---

Versionierungsstrategie

Semantische Versionierung (Praktisch)

Version	Erlaubte Änderungen
Patch (1.0.x)	Bugfixes, Sicherheitspatches
Minor (1.x.0)	Neue Funktionen, Deprecations, Entfernung veralteter APIs
Major (x.0.0)	Breaking Changes, Entfernung alter APIs

Schlüsselprinzipien

1. Keine Überraschungs-Breaks – Auch Major-Versionen sollten angekündigt und geplant sein
2. Erweiterungen jederzeit – Neue APIs können in jedem Release ausgeliefert werden
3. Vor dem Entfernen veraltet markieren – [Obsolete] für mindestens eine Minor-Version
4. Zeitpläne kommunizieren – Benutzer müssen Upgrades planen können

Chesterton's Fence

Bevor du etwas entfernst oder änderst, verstehe, warum es existiert.

Gehe davon aus, dass jede öffentliche API von jemandem verwendet wird. Wenn du sie ändern möchtest:

1. Vorschlag auf GitHub kommunizieren
2. Migrationspfad dokumentieren
3. Deprecation-Zeitraum bereitstellen
4. In geplantem Release ausliefern

---

Pull-Request-Checkliste

Bei der Überprüfung von PRs, die öffentliche APIs betreffen:

• Keine entfernten öffentlichen Member (stattdessen [Obsolete] verwenden)
• Keine geänderten Signaturen (stattdessen Überladungen hinzufügen)
• Keine neuen erforderlichen Parameter (Standardwerte verwenden)
• API-Approval-Test aktualisiert (*.verified.txt-Änderungen überprüft)
• Wire-Format-Änderungen sind Opt-In (zuerst leseseitig)
• Breaking Changes dokumentiert (Release-Notes, Migrationsanleitung)

---

Anti-Patterns

Als Fixes getarnte Breaking Changes

// "Bugfix", der Benutzer bricht
public async Task<Order> GetOrderAsync(OrderId id)  // War synchron!
{
    // "Gefixt" auf asynchron – bricht aber alle Aufrufer
}

// Richtig: Neue Methode hinzufügen, alte veraltet markieren
[Obsolete("Verwende GetOrderAsync stattdessen")]
public Order GetOrder(OrderId id) => GetOrderAsync(id).Result;

public async Task<Order> GetOrderAsync(OrderId id) { }

Stille Verhaltensänderungen

// Ändern von Standardwerten bricht Benutzer, die sich auf altes Verhalten verlassen
public void Configure(bool enableCaching = true)  // War: false!

// Richtig: Neuer Parameter mit neuem Namen
public void Configure(
    bool enableCaching = false,  // Ursprünglicher Standardwert beibehalten
    bool enableNewCaching = true)  // Neues Verhalten Opt-In

Polymorphe Serialisierung

// VERMEIDEN: Typnamen im Wire-Format
{ "$type": "MyApp.Order, MyApp", "Id": 123 }

// Umbenennen der Order-Klasse = Wire-Break!

// BEVORZUGEN: Explizite Diskriminatoren
{ "type": "order", "id": 123 }

---

Ressourcen

• Making Public API Changes
• Wire Format Changes
• Extend-Only Design
• OSS Compatibility Standards
• Semantic Versioning
• PublicApiGenerator