furt/devdocs/furt_development_process.md

Entwicklungsprozess für Furt API-Gateway

Erstellt: 03.06.2025
Letzte Aktualisierung: 03.06.2025
Version: 1.0
Verantwortlich: Claude / DAW-Team
Dateipfad: devdocs/development-process.md

Zweck dieses Dokuments

Dieses Dokument definiert den verbindlichen Prozess für die Entwicklung und Änderung von Code im Rahmen des Furt API-Gateway-Projekts. Es ergänzt die allgemeinen Entwicklungsrichtlinien um API-Gateway-spezifische Patterns und Multi-Service-Koordination.

Es richtet sich an alle Projektbeteiligten, die am Gateway oder Services entwickeln.

Verwandte Dokumente

Dieses Dokument steht im Zusammenhang mit folgenden anderen Dokumenten:

• KONZEPT.md: Zentrale Referenz und Konzeptdokumentation, devdocs/KONZEPT.md
• TESTING_GUIDELINES.md: API-Gateway-spezifische Test-Standards, devdocs/TESTING_GUIDELINES.md
• ARCHITECTURE.md: Detaillierte Systemarchitektur, devdocs/ARCHITECTURE.md

Änderungshistorie

Version	Datum	Änderungen	Autor
1.0	03.06.2025	Initiale Version für Furt API-Gateway	Claude / DAW-Team

1. Grundprinzipien für API-Gateway-Entwicklung

1.1 Service-First-Entwicklung

Jede Entwicklungsaufgabe muss im Kontext des Service-Ökosystems betrachtet werden:

• Gateway-Änderungen betreffen potenziell alle Services
• Service-Änderungen können Gateway-Anpassungen erfordern
• API-Contracts zwischen Gateway und Services sind kritisch
• Breaking Changes erfordern koordinierte Rollouts

1.2 API-Contract-Driven Development

Bevor Code geschrieben wird, müssen API-Contracts definiert werden:

• OpenAPI-Spezifikation für neue Endpunkte
• Service-Interface-Definition für neue Services
• Authentication/Authorization-Requirements für alle APIs
• Error-Response-Standards konsistent halten

1.3 Security-First-Pattern

Sicherheit wird bei jeder Änderung mitgedacht:

• API-Key-Berechtigungen bei neuen Endpunkten definieren
• Input-Validation für alle eingehenden Requests
• Rate-Limiting für neue Services konfigurieren
• IP-Restrictions wo angemessen anwenden

2. Verbindlicher Entwicklungsprozess für Furt

2.1 Vorbereitung

1. Requirements-Analyse mit Service-Impact

   • Welche Services sind betroffen?
   • Welche Gateway-Komponenten benötigen Änderungen?
   • Sind Breaking Changes erforderlich?
   • Welche API-Contracts müssen definiert/aktualisiert werden?

2. Explizite Anfrage nach relevanten Dateien

   • Gateway-Dateien: internal/gateway/, configs/gateway.yaml
   • Service-Dateien: internal/services/[service]/, configs/services/
   • API-Dokumentation: docs/api/, OpenAPI-Specs
   • Integration-Tests: tests/integration/

3. Analyse der Service-Integration-Pattern

   • Bestehende Service-Registry-Einträge
   • Routing-Patterns und Middleware-Chain
   • Authentifizierungs-Flows
   • Health-Check-Mechanismen

2.2 Design und Planung

1. API-First-Design dokumentieren

   • OpenAPI-Spezifikation vor der Implementierung schreiben
   • Request/Response-Schemas definieren
   • HTTP-Status-Codes und Error-Handling spezifizieren
   • Authentication-Requirements dokumentieren

2. Service-Integration-Strategy festlegen

   • Wie wird der Service im Gateway registriert?
   • Welche Health-Check-URL wird verwendet?
   • Welche Timeout-Werte sind angemessen?
   • Braucht der Service Admin-UI-Integration?

3. Breaking-Change-Impact analysieren

   • Betrifft die Änderung bestehende API-Contracts?
   • Sind koordinierte Service-Updates erforderlich?
   • Müssen Client-Integrationen (Hugo-Shortcodes) angepasst werden?
   • Ist eine API-Versionierung (v1 → v2) notwendig?

4. Configuration-Strategy bestimmen

   • Welche neuen Config-Parameter werden benötigt?
   • Sind Environment-Variable für Secrets erforderlich?
   • Wie wird die Config zwischen Gateway und Service koordiniert?

2.3 Implementierung

1. Multi-Component-Development-Order

   Für neue Services:

   1. Service-Struktur scaffolden (service-generator.sh)
   2. Service-Logik implementieren (Standalone-Mode)
   3. Gateway-Integration hinzufügen
   4. Integration-Tests schreiben
   5. Deployment-Scripts anpassen
   

   Für Gateway-Änderungen:

   1. Gateway-Kern-Logik implementieren
   2. Middleware/Auth-Anpassungen
   3. Service-Integration testen
   4. Health-Check-Aggregation
   5. Admin-Interface-Updates
   

   Für API-Änderungen:

   1. OpenAPI-Spec aktualisieren
   2. Gateway-Routing anpassen
   3. Service-Endpunkt implementieren
   4. Input-Validation hinzufügen
   5. Integration-Tests erweitern
   

2. Koordinierte Entwicklung bei Service-Updates

   • Gateway-kompatible Änderungen zuerst (additive APIs)
   • Service-Tests mit Gateway-Integration
   • Backward-Compatibility während Übergangsphase
   • Coordinated Deployment bei Breaking Changes

3. Configuration-Management während Entwicklung

   • Development-Configs in configs/[component].dev.yaml
   • Environment-Variable-Mapping dokumentieren
   • Config-Validation bei Service-Start implementieren
   • Hot-Reload für Development (wo möglich)

2.4 Testing-Integration

1. Multi-Layer-Testing-Strategy

   • Unit-Tests: Für Gateway- und Service-Komponenten isoliert
   • Integration-Tests: Gateway ↔ Service-Kommunikation
   • API-Tests: End-to-End API-Contract-Validation
   • Load-Tests: Gateway-Performance mit mehreren Services

2. Test-Coordination-Pattern

   // Beispiel: Service-Integration-Test
   func TestGatewayServiceIntegration(t *testing.T) {
       // 1. Start Test-Service
       service := startTestService(t, serviceConfig)
       defer service.Close()
   
       // 2. Configure Gateway with Test-Service
       gateway := startTestGateway(t, gatewayConfigWithService(service.URL))
       defer gateway.Close()
   
       // 3. Test Gateway → Service communication
       testServiceAPIThroughGateway(t, gateway, service)
   }
   

3. Breaking-Change-Test-Strategy

   • Backward-Compatibility-Tests bei API-Änderungen
   • Version-Migration-Tests bei Breaking Changes
   • Client-Integration-Tests (Hugo-Shortcode-Kompatibilität)

3. Service-spezifische Entwicklungs-Pattern

3.1 Neue Service-Entwicklung

1. Service-Scaffolding

   ./scripts/service-generator.sh newsletter
   # Erstellt komplette Service-Struktur
   

2. Service-Interface-Implementation

   // Jeder Service muss dieses Interface implementieren
   type Service interface {
       // Gateway-Integration
       HandleRequest(w http.ResponseWriter, r *http.Request)
       HealthCheck() HealthStatus
   
       // Standalone-Mode
       HandleWithAuth(w http.ResponseWriter, r *http.Request)
   
       // Lifecycle
       Start(ctx context.Context, config ServiceConfig) error
       Stop(ctx context.Context) error
   
       // Service-Metadata
       GetServiceInfo() ServiceInfo
   }
   

3. Service-Registration im Gateway

   # configs/gateway.yaml
   services:
     newsletter:
       enabled: true
       path_prefix: "/v1/newsletter"
       upstream: "http://127.0.0.1:8083"
       health_check: "/health"
       timeout: 15s
       auth_required: true
       rate_limit:
         requests_per_minute: 60
   

3.2 Service-API-Design-Standards

1. Einheitliche Request-Patterns

   // Standard Request-Wrapper
   type APIRequest struct {
       RequestID string                 `json:"request_id,omitempty"`
       Data      interface{}            `json:"data"`
       Meta      map[string]interface{} `json:"meta,omitempty"`
   }
   
   // Standard Response-Wrapper
   type APIResponse struct {
       Success   bool                   `json:"success"`
       Data      interface{}            `json:"data,omitempty"`
       Error     *APIError              `json:"error,omitempty"`
       Meta      map[string]interface{} `json:"meta,omitempty"`
       RequestID string                 `json:"request_id,omitempty"`
   }
   

2. Konsistente Error-Handling

   // Standard Error-Format
   type APIError struct {
       Code    string `json:"code"`
       Message string `json:"message"`
       Details string `json:"details,omitempty"`
   }
   
   // Standard Error-Codes
   const (
       ErrInvalidInput     = "INVALID_INPUT"
       ErrUnauthorized     = "UNAUTHORIZED"
       ErrServiceUnavailable = "SERVICE_UNAVAILABLE"
       ErrRateLimitExceeded = "RATE_LIMIT_EXCEEDED"
   )
   

3. Health-Check-Standards

   // Standard Health-Response
   type HealthStatus struct {
       Status    string            `json:"status"`
       Version   string            `json:"version"`
       Uptime    time.Duration     `json:"uptime"`
       Checks    map[string]string `json:"checks"`
       Timestamp time.Time         `json:"timestamp"`
   }
   
   // Status-Werte
   const (
       HealthStatusHealthy   = "healthy"
       HealthStatusDegraded  = "degraded"
       HealthStatusUnhealthy = "unhealthy"
   )
   

3.3 Gateway-Integration-Pattern

1. Service-Discovery-Integration

   // Gateway registriert Services automatisch
   func (g *Gateway) RegisterService(name string, config ServiceConfig) error {
       service := &ServiceProxy{
           Name:        name,
           PathPrefix:  config.PathPrefix,
           Upstream:    config.Upstream,
           HealthCheck: config.HealthCheck,
           // ...
       }
   
       g.services[name] = service
       g.updateRouting()
       return nil
   }
   

2. Request-Middleware-Chain

   // Standard Middleware-Order für alle Services
   func (g *Gateway) buildMiddlewareChain(serviceName string) []Middleware {
       return []Middleware{
           LoggingMiddleware,
           AuthenticationMiddleware,
           RateLimitingMiddleware(serviceName),
           ValidationMiddleware,
           ProxyMiddleware(serviceName),
       }
   }
   

4. Configuration-Management-Pattern

4.1 Hierarchische Konfiguration

// Config-Loading-Reihenfolge
func LoadConfig(serviceName string) (*Config, error) {
    config := &Config{}
    
    // 1. Default-Values
    config.ApplyDefaults()
    
    // 2. Base-Config-File
    config.LoadFromFile("configs/" + serviceName + ".yaml")
    
    // 3. Environment-specific
    if env := os.Getenv("ENVIRONMENT"); env != "" {
        config.LoadFromFile("configs/" + serviceName + "." + env + ".yaml")
    }
    
    // 4. Environment-Variables
    config.LoadFromEnv()
    
    // 5. Command-Line-Flags
    config.LoadFromFlags()
    
    return config.Validate()
}

4.2 Service-Gateway-Config-Coordination

# Gateway-Config für Service
services:
  formular2mail:
    config_sync: true
    config_endpoint: "/config"
    config_push_on_change: true

# Service erhält Config vom Gateway

4.3 Secrets-Management

// Secrets werden nie in Config-Files gespeichert
type ServiceConfig struct {
    // Public config
    Port     string `yaml:"port"`
    LogLevel string `yaml:"log_level"`
    
    // Secrets via Environment
    APIKey     string `env:"SERVICE_API_KEY"`
    DBPassword string `env:"DB_PASSWORD"`
}

5. Security-First-Development-Pattern

5.1 Authentication-Integration

// Jeder Service-Endpunkt bekommt Auth-Context
type AuthContext struct {
    APIKey      string
    Permissions []string
    ClientIP    string
    UserAgent   string
    RequestID   string
}

func (s *Service) HandleRequest(w http.ResponseWriter, r *http.Request) {
    // Auth-Context wird vom Gateway gesetzt
    authCtx := r.Context().Value("auth").(*AuthContext)
    
    // Service-spezifische Permission-Checks
    if !authCtx.HasPermission("service:" + s.name + ":write") {
        http.Error(w, "Forbidden", http.StatusForbidden)
        return
    }
    
    // ... Service-Logik
}

5.2 Input-Validation-Standards

// Standard Validation-Middleware
func ValidationMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 1. Content-Type validation
        if !isValidContentType(r.Header.Get("Content-Type")) {
            http.Error(w, "Invalid Content-Type", http.StatusBadRequest)
            return
        }
        
        // 2. Content-Length limits
        if r.ContentLength > MaxRequestSize {
            http.Error(w, "Request too large", http.StatusRequestEntityTooLarge)
            return
        }
        
        // 3. Request-Body validation (service-specific)
        if err := validateRequestBody(r); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        
        next.ServeHTTP(w, r)
    })
}

5.3 Rate-Limiting-Strategy

// Service-spezifische Rate-Limits
type RateLimitConfig struct {
    RequestsPerMinute int           `yaml:"requests_per_minute"`
    BurstSize         int           `yaml:"burst_size"`
    PerAPIKey         bool          `yaml:"per_api_key"`
    PerIP             bool          `yaml:"per_ip"`
    Whitelist         []string      `yaml:"whitelist"`
}

// Gateway-Level Rate-Limiting
func (g *Gateway) GetRateLimit(serviceName, apiKey, clientIP string) *RateLimit {
    config := g.getRateLimitConfig(serviceName)
    key := buildRateLimitKey(config, apiKey, clientIP)
    return g.rateLimiter.GetLimit(key)
}

6. Breaking-Change-Management

6.1 API-Versionierung-Strategy

// URL-basierte Versionierung
// /v1/mail/send  → formular2mail v1
// /v2/mail/send  → formular2mail v2

// Gateway-Routing für mehrere Versionen
services:
  formular2mail-v1:
    path_prefix: "/v1/mail"
    upstream: "http://127.0.0.1:8081"
  formular2mail-v2:
    path_prefix: "/v2/mail"  
    upstream: "http://127.0.0.1:8084"

6.2 Backward-Compatibility-Pattern

// Service unterstützt mehrere API-Versionen
func (s *FormularService) HandleRequest(w http.ResponseWriter, r *http.Request) {
    version := extractAPIVersion(r.URL.Path) // v1, v2
    
    switch version {
    case "v1":
        s.handleV1Request(w, r)
    case "v2":  
        s.handleV2Request(w, r)
    default:
        s.handleLatestRequest(w, r)
    }
}

6.3 Migration-Pattern

// Coordinated Service-Migration
type MigrationPlan struct {
    FromVersion string
    ToVersion   string
    Steps       []MigrationStep
}

type MigrationStep struct {
    Name        string
    Component   string // "gateway" | "service"
    Action      string // "deploy" | "config" | "test"
    Rollback    func() error
}

7. Checkliste für API-Gateway-Entwicklung

7.1 Vor Implementierungsbeginn

• Service-Impact analysiert: Welche Services sind betroffen?
• API-Contract definiert: OpenAPI-Spec erstellt/aktualisiert?
• Gateway-Integration geplant: Routing, Auth, Rate-Limiting?
• Config-Strategy festgelegt: Neue Parameter dokumentiert?
• Breaking-Change-Assessment: Versionierung erforderlich?
• Security-Requirements: Auth, Validation, Rate-Limiting?
• Test-Strategy: Unit, Integration, API-Tests geplant?

7.2 Während der Implementierung

• Service-Interface-Compliance: Standard-Interface implementiert?
• Error-Handling-Consistency: Standard-Error-Format verwendet?
• Health-Check-Integration: Standardisierte Health-Endpoint?
• Logging-Standards: Strukturierte Logs mit Request-IDs?
• Config-Validation: Startup-Config-Checks implementiert?
• Auth-Integration: Gateway-Auth-Context respektiert?
• Documentation-Update: API-Docs und Service-Docs aktualisiert?

7.3 Nach Implementierungsabschluss

• Integration-Tests: Gateway ↔ Service-Tests bestehen?
• API-Contract-Tests: OpenAPI-Compliance validiert?
• Performance-Tests: Load-Tests mit Gateway durchgeführt?
• Security-Tests: Auth, Input-Validation, Rate-Limiting getestet?
• Deployment-Scripts: Service-Deployment automatisiert?
• Monitoring-Integration: Health-Checks und Metriken?
• Documentation-Complete: Service-Integration dokumentiert?

8. Troubleshooting-Pattern

8.1 Service-Integration-Debugging

// Standard Debug-Endpoints für Services
func (s *Service) RegisterDebugEndpoints() {
    http.HandleFunc("/debug/config", s.debugConfig)
    http.HandleFunc("/debug/health-detail", s.debugHealthDetail)  
    http.HandleFunc("/debug/metrics", s.debugMetrics)
    http.HandleFunc("/debug/auth", s.debugAuth)
}

// Gateway Debug-Endpoints
func (g *Gateway) RegisterDebugEndpoints() {
    http.HandleFunc("/debug/services", g.debugServices)
    http.HandleFunc("/debug/routing", g.debugRouting)
    http.HandleFunc("/debug/auth-keys", g.debugAuthKeys)
}

8.2 Request-Tracing

// Request-ID-Propagation durch alle Services
func (g *Gateway) addRequestID(r *http.Request) *http.Request {
    requestID := r.Header.Get("X-Request-ID")
    if requestID == "" {
        requestID = generateRequestID()
    }
    
    // Für Service-Weiterleitung
    r.Header.Set("X-Request-ID", requestID)
    
    // Für Logging
    ctx := context.WithValue(r.Context(), "request_id", requestID)
    return r.WithContext(ctx)
}

9. Zusammenfassung: API-Gateway-Entwicklungs-Goldene-Regeln

1. API-Contract-First: OpenAPI-Spec vor Code-Implementation
2. Service-Integration-Aware: Jede Änderung auf Service-Impact prüfen
3. Security-by-Default: Auth, Validation, Rate-Limiting bei jedem Endpunkt
4. Configuration-Hierarchie: Defaults → Environment → Service-specific
5. Multi-Layer-Testing: Unit → Integration → API → E2E
6. Breaking-Change-Coordination: Versionierung und Migration planen
7. Health-Check-Integration: Jeder Service braucht standardisierten Health-Endpoint
8. Request-Tracing: Request-IDs durch gesamte Pipeline propagieren

---

Wichtiger Hinweis: Diese Entwicklungs-Pattern sind spezifisch für das Furt API-Gateway-System optimiert und sollten bei jeder Entwicklungsaufgabe konsultiert werden, um konsistente und gut integrierte Services zu gewährleisten.