Healthcheck endpoint /up, JSON API odpovědi a CORS v praxi

Monitoring a API rozhraní v moderním Laravelu 12

V éře kontejnerů a mikroslužeb musí každá aplikace poskytovat mechanismus, kterým Docker, Kubernetes nebo reverzní proxy Caddy ověřuje, zda je aplikace "živá" a schopná odbavovat požadavky (Healthcheck & Liveness Probe).

Laravel 12 přináší revoluci ve způsobu konfigurace aplikace: ruší starý Http/Kernel.php a vše centralizuje do souboru bootstrap/app.php.

Nativní Healthcheck endpoint /up

V bootstrap/app.php naší aplikace najdete tento zápis:

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->web(append: [
            EnsureStudentProfile::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })->create();

Parametr health: '/up' automaticky zaregistruje interní trasu /up. Tento endpoint:

1. Reaguje okamžitě s HTTP kódem 200 OK.
2. Má minimální režii, protože neprochází plnou sadou session ani autentizačních middlewarů.
3. Spouští interní diagnostický event Illuminate\Foundation\Events\DiagnosingHealth, na který mohou Service Provideři napojit kontrolu spojení s PostgreSQL databází nebo Redis cache.
4. Je ideálním cílem pro Docker direktivu HEALTHCHECK CMD curl -f http://localhost:80/up || exit 1.

Stavba lehkých JSON API endpointů v routes/web.php

Kromě standardních Blade pohledů naše aplikace vystavuje také monitorovací JSON endpoint /api/status:

Route::get('/api/status', function (): JsonResponse {
    return response()->json([
        'app' => config('app.name'),
        'php_version' => PHP_VERSION,
        'laravel_version' => app()->version(),
        'modules_count' => CourseModule::count(),
        'lessons_count' => CourseLesson::count(),
        'status' => 'ok',
    ]);
})->name('api.status');

Všimněte si:

• Explicitní návratový typ JsonResponse zajišťuje striktní typovou kontrolu v PHP 8.4.
• Pomocník response()->json(...) automaticky nastaví správnou hlavičku Content-Type: application/json a zformátuje pole pomocí json_encode() s ošetřením UTF-8 znaků.
• Data dynamicky zjišťují stav aplikace (počet modulů a lekcí v PostgreSQL).

Cross-Origin Resource Sharing (CORS)

Pokud by náš JSON endpoint chtěl konzumovat frontend z jiné domény (např. mobilní aplikace nebo externí dashboard), prohlížeč by vyslal předběžný požadavek OPTIONS (tzv. preflight request).

V Laravelu 12 lze CORS pravidla konfigurovat jednoduše přímo v bootstrap/app.php nebo v config/cors.php:

• allowed_origins: Seznam povolených domén (např. ['https://heatsharing.cz']).
• allowed_methods: Povolené HTTP slovesa (['GET', 'POST', 'OPTIONS']).
• allowed_headers: Povolené hlavičky (např. ['Content-Type', 'X-Requested-With']).