curenect/api-adapter-toolchain

Curenect API Adapter and Service Development Toolchain

Maintainers

Details

gitlab.com/sl.is/adapter/api-adapter-toolchain

Source

Issues

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Forks: 0

1.0.0 2025-07-08 18:06 UTC

Requires

  • php: ^8.2

Requires (Dev)

Suggests

proprietary 5156466953b2b89368fc0e86cfca24b970505a96

  • Curenect Development Team <dev.woop@curenect.com>

apitestingadapterservicetoolchainopenapi

This package is not auto-updated.

Last update: 2025-07-24 13:50:57 UTC

README

Eine spezialisierte Toolchain für die Entwicklung von API-Adaptern und Services mit rollenspezialisierter Test-Strategie.

🎯 Konzept

API-Adapter (OpenAPI-Gatekeeper)

  • Intensive OpenAPI-Validierung (blocking)
  • Umfassende Model-Tests (auto-generiert)
  • Performance & Security Tests
  • Contract-Testing (API-Spezifikation)

Service (Orchestrator)

  • Mock-basierte Integration-Tests
  • E2E-Workflow-Validierung
  • Leichtgewichtige OpenAPI-Compliance
  • Business-Logic-Focus

🚀 Quick Start

Neue Projekte

# Adapter-Projekt erstellen
composer create-project curenect/api-adapter-toolchain my-api-adapter
cd my-api-adapter
php vendor/curenect/api-adapter-toolchain/scripts/setup-project.php . my-api-adapter adapter

# Service-Projekt erstellen
composer create-project curenect/api-adapter-toolchain my-service
cd my-service
php vendor/curenect/api-adapter-toolchain/scripts/setup-project.php . my-service service

Bestehende Projekte

# Toolchain installieren
composer require --dev curenect/api-adapter-toolchain

# Für Adapter-Projekte
composer run install-adapter

# Für Service-Projekte
composer run install-service

🛠️ Verwendung

Adapter-Entwicklung

# Setup
make setup
make docker-dev

# Intensive OpenAPI-Validierung
make validate-openapi-strict    # BLOCKING für CI

# Umfassende Tests
make test-comprehensive         # Alle Tests
make test-openapi-compliance    # OpenAPI-Compliance
make test-models               # Auto-generierte Model-Tests

# Quality (Level 8)
make quality                   # PHPStan Level 8, Psalm strict

Service-Entwicklung

# Setup
make setup
make docker-dev

# Effiziente Mock-basierte Tests
make test-e2e                  # E2E-Workflows mit Mock
make test-compliance           # Leichtgewichtige OpenAPI-Check
make test-integration          # Service-Integration

# Mock-Server
make mock-start               # Mock-API starten
make mock-stop               # Mock-API stoppen

# Quality (Level 6-7)
make quality                 # PHPStan Level 6-7, moderates Psalm

📁 Projekt-Struktur

Adapter-Struktur

my-api-adapter/
├── lib/                    # Generierte OpenAPI-Klassen
│   ├── Api/               # API-Klassen
│   └── Model/             # Model-Klassen
├── test/                  # Intensive Tests
│   ├── Api/              # API-Tests
│   ├── Model/            # Model-Tests (auto-generiert)
│   ├── OpenApi/          # OpenAPI-Compliance-Tests
│   ├── Performance/      # Performance-Tests
│   └── Security/         # Security-Tests
├── scripts/              # Validierungs-Scripts
├── openapi.yml          # OpenAPI-Spezifikation
└── Makefile             # Adapter-spezifische Commands

Service-Struktur

my-service/
├── src/                  # Symfony Service-Code
│   ├── Controller/
│   ├── Service/
│   └── Exception/
├── tests/               # Effiziente Tests
│   ├── Unit/           # Service-Logic-Tests
│   ├── Integration/    # Service-Integration-Tests
│   ├── E2E/           # Workflow-Tests (mit Mock)
│   └── Mock/          # Mock-Server-Konfiguration
├── config/            # Symfony-Konfiguration
└── Makefile          # Service-spezifische Commands

🔧 Konfiguration

Adapter-Konfiguration

  • PHPUnit: Strikte Coverage-Anforderungen (95%)
  • PHPStan: Level 8 (maximale Strenge)
  • Psalm: Error Level 1 (alle Fehler sind kritisch)
  • Docker: Optimiert für intensive Validierung

Service-Konfiguration

  • PHPUnit: Moderate Coverage-Anforderungen (85%)
  • PHPStan: Level 6-7 (balancierte Strenge)
  • Psalm: Error Level 3 (pragmatische Validierung)
  • Docker: Optimiert für schnelle Workflows

🔄 GitLab CI Integration

Permanente CI-Templates

Die Toolchain stellt GitLab CI Templates bereit, die per include eingebunden werden:

# .gitlab-ci.yml (automatische Erkennung)
include:
  - project: 'curenect/api-adapter-toolchain'
    file: '/ci/auto-detect-pipeline.yml'
    ref: main

# Oder explizit für Adapter:
include:
  - project: 'curenect/api-adapter-toolchain'
    file: '/ci/adapter-pipeline.yml'
    ref: main

# Oder explizit für Service:
include:
  - project: 'curenect/api-adapter-toolchain'
    file: '/ci/service-pipeline.yml'
    ref: main

Adapter-Pipeline (~45 min)

stages:
  - validate      # < 2 min  - BLOCKING OpenAPI Validation
  - test-models   # < 5 min  - Auto-generated Model Tests  
  - test-api      # < 10 min - API Integration Tests
  - quality       # < 8 min  - Static Analysis (PHPStan L8)
  - performance   # < 15 min - Performance & Security Tests
  - compliance    # < 5 min  - Contract Testing

Service-Pipeline (~25 min)

stages:
  - validate      # < 1 min  - Fast validation
  - test-unit     # < 3 min  - Service logic tests
  - test-e2e      # < 8 min  - Mock-based workflow tests
  - quality       # < 5 min  - Lighter static analysis
  - compliance    # < 2 min  - Lightweight OpenAPI compliance

Cross-Project-Features

# Service nutzt Adapter-Artefakte
include:
  - project: 'curenect/api-adapter-toolchain'
    file: '/ci/cross-project.yml'
    ref: main

variables:
  ADAPTER_PROJECT: "curenect/bestell-api-adapter"

📋 Verfügbare Commands

Gemeinsame Commands

  • make help - Alle verfügbaren Commands anzeigen
  • make setup - Projekt-Setup
  • make clean - Cleanup
  • make docker-dev - Development-Environment starten
  • make test - Tests ausführen
  • make quality - Quality-Checks
  • make ci - Komplette CI-Pipeline

Adapter-spezifische Commands

  • make validate-openapi-strict - Strenge OpenAPI-Validierung
  • make test-comprehensive - Umfassende Test-Suite
  • make test-openapi-compliance - OpenAPI-Compliance-Tests
  • make test-models - Auto-generierte Model-Tests
  • make test-performance - Performance-Tests
  • make test-security - Security-Tests

Service-spezifische Commands

  • make test-e2e - E2E-Workflow-Tests
  • make test-compliance - Leichtgewichtige Compliance-Checks
  • make mock-start/stop - Mock-Server-Kontrolle
  • make cache-clear - Symfony-Cache leeren
  • make routes - Verfügbare Routes anzeigen
  • make doctrine-migrate - Doctrine-Migrationen

🎭 Mock-Server-Integration

Adapter-Mocks

  • Für Integration-Tests
  • Performance-Baseline-Validierung
  • Security-Test-Szenarien

Service-Mocks

  • E2E-Workflow-Tests
  • Vertraut auf Adapter-Validierung
  • Fokus auf Business-Logic

🔍 Quality-Gates

Adapter (Gatekeeper)

  • Coverage: > 95%
  • PHPStan: Level 8, keine Fehler
  • Psalm: Error Level 1, blocking
  • OpenAPI: Strikte Validierung, blocking

Service (Orchestrator)

  • Coverage: > 85%
  • PHPStan: Level 6-7, moderate Strenge
  • Psalm: Error Level 3, warnings erlaubt
  • OpenAPI: Leichtgewichtige Compliance, non-blocking

🔧 Anpassungen

Projekt-spezifische Erweiterungen

# Makefile.local (automatisch included)
deploy: ## Deploy to staging
	@echo "Deploying to staging..."
	# Custom deployment logic

custom-test: ## Run custom tests
	@echo "Running custom tests..."
	# Custom test logic

Environment-Variablen

# .env für Adapter
ADAPTER_TEST_MODE=true
OPENAPI_VALIDATION_STRICT=true
PERFORMANCE_BASELINE_MS=100

# .env für Service
SERVICE_TEST_MODE=true
SYMFONY_ENV=dev
MOCK_API_BASE_URL=http://localhost:4011

🎯 Philosophie

Adapter = OpenAPI-Gatekeeper

  • Maximale Sicherheit durch intensive OpenAPI-Validierung
  • Umfassende Test-Abdeckung für alle Models und APIs
  • Performance- und Security-Anforderungen absichern
  • Contract-Compliance durchsetzen

Service = Orchestrator

  • Vertraut auf intensive Adapter-Validierung
  • Fokus auf Business-Logic und Workflows
  • Effiziente Mock-basierte Tests
  • Schnelles Feedback für Entwickler

🆘 Support

Hilfe anzeigen

make help                    # Projekt-Commands
composer run --list         # Toolchain-Commands

Debugging

make docker-dev             # Development-Environment
docker-compose logs         # Container-Logs
make quality               # Quality-Checks ausführen

📦 Installation und Setup

Permanente Integration (empfohlen)

Die Toolchain wird als dauerhaftes Composer-Package installiert:

composer require --dev curenect/api-adapter-toolchain

Permanente Vorteile:

  • Scripts bleiben in der Toolchain und werden über vendor/ aufgerufen
  • Konfigurationen nutzen includes für zentrale Wartung
  • Updates propagieren automatisch zu allen Projekten
  • Shared Testing-Classes für einheitliche Qualität

Verwendung nach Installation

# Toolchain-Status prüfen
make toolchain-status
composer run toolchain-status

# Updates prüfen und anwenden
make toolchain-check       # Verfügbare Updates anzeigen
make toolchain-update      # Updates anwenden

# Scripts permanent nutzen
make validate-openapi-strict    # Nutzt vendor/curenect/.../scripts/
make generate-model-tests       # Nutzt Toolchain-Scripts

# Konfigurationen per Include
# phpstan.neon → includes vendor/curenect/.../configs/phpstan.adapter.neon

Curenect API Adapter Toolchain - Spezialisierte Entwicklung für API-Adapter und Services