Vodiči

Laravel: Normalize Social Links with AI Identity Resolver

Laravel: Normalizacija poveznica na društvene mreže pomoću AI Identity Resolvera

Imenik zajednice može primiti tri različite poveznice za isti profil na društvenoj mreži prije nego što itko primijeti da je riječ o duplikatima. Parametri za praćenje, mobilni URL-ovi i kopirane reference na profile stvaraju varljiv dojam da je čišćenje nizova znakova jednostavno. S vremenom skup regularnih izraza postaje nepouzdan sustav za utvrđivanje identiteta.

Identity Resolver pruža bolje definiranu granicu: pošaljite podržanu referencu i primite normalizirani objekt javnog identiteta. U ovom vodiču izrađuje se funkcionalnost u Laravelu za zaprimanje poveznica na Facebook, Instagram i LinkedIn, uključujući trajnu pohranu, ograničeni broj ponovnih pokušaja, determinističke testove i operativne zaštitne mjere.

Pristup: ova krajnja točka ne zahtijeva token

  1. Otvorite službenu dokumentaciju za Identity Resolver.
  2. Pregledajte stranicu usluge i paketa.
  3. Za trenutačnu javnu krajnju točku nisu potrebni token računa ni API ključ. Nema tokena koji treba kopirati ni autorizacijskog zaglavlja koje treba konfigurirati.
  4. Za neobaveznu registraciju ili prijavu krenite sa stranice usluge i slijedite navigaciju za korisnički račun. Ove poveznice namjerno upotrebljavaju navedenu službenu ulaznu točku; stvaranje računa nije potrebno za ovu integraciju.

Točan zahtjev je GET https://ai.mihajlo.mk/api/identity-resolver/v1/resolve. Navedite platform i jedan podržani parametar: username, id, identifier, profile ili url. Naš obrazac prihvaća poveznice pa upotrebljava url.

curl --get \
  --connect-timeout 2 \
  --max-time 4 \
  --header 'Accept: application/json' \
  --data-urlencode 'platform=instagram' \
  --data-urlencode 'url=https://www.instagram.com/instagram/' \
  'https://ai.mihajlo.mk/api/identity-resolver/v1/resolve'

Izradite malu funkcionalnost za sinkrono zaprimanje

Upotrijebite PHP 8.3+, Composer, PDO SQLite i Laravel 12. Zahtjev prolazi kroz validaciju, namjenski klijent za razrješavanje identiteta i trajnu pohranu u bazu podataka. Svaka prijava ostaje na čekanju za moderiranje. Normalizacija utvrđuje javnu referencu; ona ne utvrđuje vlasništvo, privolu ni dopuštenje za objavu.

Sinkrono izvršavanje korisniku koji šalje prijavu odmah daje rezultat. Dva kratka pokušaja prema vanjskoj usluzi razumna su za ovaj mali obrazac; red čekanja uveo bi periodično provjeravanje i upravljanje životnim ciklusom, a ne bi poboljšao početno iskustvo.

composer create-project laravel/laravel community-directory "^12.0"
cd community-directory
touch database/database.sqlite
php artisan make:migration create_directory_submissions_table

Postavite ove vrijednosti u .env, zamijenivši putanju do baze podataka njezinom apsolutnom lokalnom putanjom. Ovdje nisu potrebni pristupni podaci jer ih ova krajnja točka ne zahtijeva.

DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/community-directory/database/database.sqlite
CACHE_STORE=database
SESSION_DRIVER=database
IDENTITY_RESOLVER_ENDPOINT=https://ai.mihajlo.mk/api/identity-resolver/v1/resolve

Dodajte ovu stavku unutar polja koje vraća config/services.php. Aplikacijski kod čita konfiguraciju, što omogućuje ispravan rad Laravelova predmemoriranja konfiguracije.

'identity_resolver' => [
    'endpoint' => env(
        'IDENTITY_RESOLVER_ENDPOINT',
        'https://ai.mihajlo.mk/api/identity-resolver/v1/resolve'
    ),
],

Projektu se dodaju tri klase za rad s vanjskom uslugom u direktoriju app/Services, jedan kontroler, jedan Blade obrazac i jedan funkcionalni test. Upotrebljava postojeći Laravelov web međusloj, migracije baze podataka i HTTP klijent.

Sačuvajte normalizirani objekt bez nagađanja o njegovoj shemi

Navedeni ugovor opisuje normalizirani objekt javnog identiteta bez nabrajanja polja odgovora. Sačuvajte cijeli taj objekt umjesto da izmišljate svojstva poput kanonskog URL-a ili trajnog korisničkog ID-ja. Nazivi platform, public_identity i nazivi pogrešaka u nastavku dio su lokalnih ugovora aplikacije.

Uredite generiranu migraciju:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('directory_submissions', function (Blueprint $table) {
            $table->id();
            $table->string('name', 120);
            $table->string('platform', 20);
            $table->json('normalized_identity');
            $table->string('status', 20)->default('pending');
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('directory_submissions');
    }
};

Izradite app/Services/ResolvedIdentity.php i app/Services/ResolverFailure.php:

<?php
// app/Services/ResolvedIdentity.php

namespace App\Services;

final readonly class ResolvedIdentity
{
    public function __construct(
        public string $platform,
        public \stdClass $publicIdentity,
    ) {}
}
<?php
// app/Services/ResolverFailure.php

namespace App\Services;

final class ResolverFailure extends \RuntimeException
{
    public function __construct(
        public readonly string $reason,
        public readonly int $httpStatus,
    ) {
        parent::__construct($reason);
    }
}

Nemojte raspršivati cijeli JSON radi uklanjanja duplikata osoba. Redoslijed objekata, neobavezni metapodaci i promjenjivi podaci o profilu mogu učiniti takav pristup nepouzdanim. Ograničenje jedinstvenosti zahtijeva dokumentirani identifikator platforme i izričitu politiku za promijenjena korisnička imena.

Ograničite mrežne zahtjeve i klasificirajte pogreške

Izradite app/Services/IdentityResolver.php. Kod jednom ponavlja pokušaj nakon pogreške povezivanja ili HTTP odgovora 502, 503 ili 504, uz nasumično odstupanje u vremenu čekanja. Kod neuspjele validacije, neuspjele autentikacije i ograničenja broja zahtjeva nema automatskog ponovnog pokušaja. Preusmjeravanja su onemogućena, a poslani URL-ovi prenose se samo kao parametri upita konfiguriranoj usluzi.

<?php

namespace App\Services;

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

final class IdentityResolver
{
    public function resolve(string $platform, string $url): ResolvedIdentity
    {
        $started = hrtime(true);

        for ($attempt = 1; $attempt <= 2; $attempt++) {
            try {
                $response = Http::acceptJson()
                    ->connectTimeout(2)
                    ->timeout(4)
                    ->withOptions(['allow_redirects' => false])
                    ->get(config('services.identity_resolver.endpoint'), [
                        'platform' => $platform,
                        'url' => $url,
                    ]);
            } catch (ConnectionException) {
                if ($attempt === 2) {
                    $this->fail('unavailable', 503);
                }

                $this->backoff();
                continue;
            }

            $status = $response->status();

            if (in_array($status, [502, 503, 504], true)
                && $attempt === 1) {
                $this->backoff();
                continue;
            }

            if ($status === 429) {
                $this->fail('rate_limited', 503, $status);
            }

            if (in_array($status, [400, 422], true)) {
                $this->fail('rejected', 422, $status);
            }

            if (! $response->successful()) {
                $this->fail('upstream_failure', 503, $status);
            }

            $body = $response->body();

            if (strlen($body) > 65536) {
                $this->fail('invalid_response', 502, $status);
            }

            try {
                $payload = json_decode(
                    $body, false, 32, JSON_THROW_ON_ERROR
                );
            } catch (\JsonException) {
                $this->fail('invalid_response', 502, $status);
            }

            if (! $payload instanceof \stdClass
                || count((array) $payload) === 0) {
                $this->fail('invalid_response', 502, $status);
            }

            Log::info('identity_resolver.completed', [
                'platform' => $platform,
                'attempts' => $attempt,
                'duration_ms' => (int) ((hrtime(true) - $started) / 1e6),
            ]);

            return new ResolvedIdentity($platform, $payload);
        }

        throw new \LogicException('Resolver attempt loop exhausted.');
    }

    private function backoff(): void
    {
        usleep(random_int(150000, 250000));
    }

    private function fail(
        string $reason,
        int $httpStatus,
        ?int $upstreamStatus = null,
    ): never {
        Log::warning('identity_resolver.failed', [
            'reason' => $reason,
            'upstream_status' => $upstreamStatus,
        ]);

        throw new ResolverFailure($reason, $httpStatus);
    }
}

Ukupno vremensko ograničenje za mrežne zahtjeve iznosi približno osam sekundi, uz dodatno vrijeme čekanja prije ponovnog pokušaja; u skladu s time konfigurirajte vremensko ograničenje nadređenog web zahtjeva. Provjera veličine primjenjuje se nakon spremanja odgovora u međuspremnik, a ne kao ograničenje tijekom preuzimanja. Validacija objekta štiti strukturni ugovor aplikacije; ne može provjeriti značenje nedokumentiranih polja.

Validirajte, normalizirajte pa trajno pohranite

Izradite app/Http/Controllers/DirectorySubmissionController.php. Oko mrežnog poziva namjerno nema transakcije baze podataka. Ako je zahtjev za razrješavanje odbijen ili usluga nije dostupna, ništa se ne zapisuje; uspješno razrješavanje zahtijeva jedan unos u bazu podataka.

<?php

namespace App\Http\Controllers;

use App\Services\IdentityResolver;
use App\Services\ResolverFailure;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Validation\Rule;

final class DirectorySubmissionController extends Controller
{
    public function store(
        Request $request,
        IdentityResolver $resolver,
    ): JsonResponse {
        $input = $request->validate([
            'name' => ['required', 'string', 'max:120'],
            'platform' => [
                'required',
                Rule::in(['facebook', 'instagram', 'linkedin']),
            ],
            'profile_url' => ['required', 'url:http,https', 'max:2048'],
        ]);

        try {
            $identity = $resolver->resolve(
                $input['platform'], $input['profile_url']
            );
        } catch (ResolverFailure $failure) {
            return response()->json(
                ['error' => $failure->reason],
                $failure->httpStatus,
                $failure->reason === 'rate_limited'
                    ? ['Retry-After' => '60'] : [],
            );
        }

        $id = DB::table('directory_submissions')->insertGetId([
            'name' => $input['name'],
            'platform' => $identity->platform,
            'normalized_identity' => json_encode(
                $identity->publicIdentity, JSON_THROW_ON_ERROR
            ),
            'status' => 'pending',
            'created_at' => now(),
            'updated_at' => now(),
        ]);

        return response()->json([
            'id' => $id,
            'status' => 'pending',
            'identity' => [
                'platform' => $identity->platform,
                'public_identity' => $identity->publicIdentity,
            ],
        ], 201);
    }
}

Preporuka za ponovni pokušaj nakon 60 sekundi pravilo je aplikacije, a ne tvrdnja o kvoti ili vremenu njezina obnavljanja na vanjskoj usluzi. I klijenti moraju ograničiti vlastite ponovne pokušaje. Ako se odgovor izgubi nakon unosa, mogu nastati dvostruke prijave; ova funkcionalnost dopušta ih radi moderiranja umjesto da se pretvara da je idempotentna na razini identiteta.

Dodajte ove rute u routes/web.php:

use App\Http\Controllers\DirectorySubmissionController;
use Illuminate\Support\Facades\Route;

Route::view('/directory/submit', 'directory-submit');

Route::post('/directory/submissions', [
    DirectorySubmissionController::class, 'store',
])->middleware('throttle:directory-submissions');

Zamijenite sadržaj datoteke app/Providers/AppServiceProvider.php sljedećim kodom:

<?php

namespace App\Providers;

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void {}

    public function boot(): void
    {
        RateLimiter::for(
            'directory-submissions',
            fn (Request $request) => Limit::perMinute(6)
                ->by($request->ip())
        );
    }
}

Izradite resources/views/directory-submit.blade.php. Prijave iz preglednika dobivaju uobičajena Laravelova preusmjeravanja pri neuspjeloj validaciji; nakon uspješne prijave prikazuje se JSON koji sadržava normalizirani objekt.

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Submit a directory profile</title>
@foreach ($errors->all() as $error)
    <p>{{ $error }}</p>
@endforeach
<form method="post" action="/directory/submissions">
    @csrf
    <label>Display name
        <input name="name" maxlength="120" required>
    </label>
    <label>Platform
        <select name="platform">
            <option value="facebook">Facebook</option>
            <option value="instagram">Instagram</option>
            <option value="linkedin">LinkedIn</option>
        </select>
    </label>
    <label>Profile link
        <input type="url" name="profile_url" maxlength="2048" required>
    </label>
    <button type="submit">Normalize and submit</button>
</form>
</html>

Testirajte ponašanje bez oslanjanja na javne profile

Izradite tests/Feature/DirectorySubmissionTest.php. Sintetički testni podaci u nastavku namjerno ne predstavljaju polja stvarnog odgovora usluge. Ovi testovi provjeravaju ponašanje prijenosa, mapiranje bez tumačenja sadržaja, trajnu pohranu i obradu pogrešaka.

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Http;
use Tests\TestCase;

class DirectorySubmissionTest extends TestCase
{
    use RefreshDatabase;

    protected function setUp(): void
    {
        parent::setUp();
        Http::preventStrayRequests();
    }

    private function input(): array
    {
        return [
            'name' => 'Community workshop',
            'platform' => 'instagram',
            'profile_url' => 'https://www.instagram.com/instagram/',
        ];
    }

    public function test_transient_failure_retries_then_persists(): void
    {
        $endpoint = config('services.identity_resolver.endpoint');

        Http::fake([
            $endpoint.'*' => Http::sequence()
                ->push('', 503)
                ->push(['synthetic_fixture' => true], 200),
        ]);

        $this->postJson('/directory/submissions', $this->input())
            ->assertCreated()
            ->assertJsonPath('status', 'pending')
            ->assertJsonPath(
                'identity.public_identity.synthetic_fixture', true
            );

        Http::assertSentCount(2);
        Http::assertSent(fn (Request $request) =>
            $request->method() === 'GET'
            && $request['platform'] === 'instagram'
            && $request['url'] === $this->input()['profile_url']
            && ! $request->hasHeader('Authorization')
        );

        $stored = DB::table('directory_submissions')->first();
        $this->assertTrue(
            json_decode($stored->normalized_identity)->synthetic_fixture
        );
    }

    public function test_rate_limit_is_not_retried(): void
    {
        Http::fake(['*' => Http::response('', 429)]);

        $this->postJson('/directory/submissions', $this->input())
            ->assertStatus(503)
            ->assertHeader('Retry-After', '60')
            ->assertJsonPath('error', 'rate_limited');

        Http::assertSentCount(1);
        $this->assertDatabaseCount('directory_submissions', 0);
    }

    public function test_array_payload_fails_closed(): void
    {
        Http::fake(['*' => Http::response('[]', 200)]);

        $this->postJson('/directory/submissions', $this->input())
            ->assertStatus(502)
            ->assertJsonPath('error', 'invalid_response');

        $this->assertDatabaseCount('directory_submissions', 0);
    }

    public function test_invalid_platform_never_calls_service(): void
    {
        $input = $this->input();
        $input['platform'] = 'unsupported';

        $this->postJson('/directory/submissions', $input)
            ->assertUnprocessable();

        Http::assertNothingSent();
    }
}
php artisan migrate
DB_CONNECTION=sqlite DB_DATABASE=:memory: php artisan test --filter=DirectorySubmissionTest
php artisan serve

Postavite aplikaciju uz jasno definirane operativne granice

Poslužujte Laravel putem njegova direktorija public, uz HTTPS i APP_DEBUG=false. Za postavljanje s jednom instancom čuvajte SQLite na trajnoj pohrani uz sigurnosne kopije. Više replika trebalo bi upotrebljavati zajedničku relacijsku bazu podataka, uključujući zajedničku predmemoriju i sesije u bazi podataka. Ispravno konfigurirajte pouzdane proxy poslužitelje kako bi ograničivač prema IP adresi vidio odgovarajuću adresu klijenta.

Tijekom postavljanja pokrenite php artisan migrate --force i php artisan config:cache. Nakon promjena konfiguracije ponovno učitajte dugotrajne radne procese aplikacije. Krajnju točku servisa za razrješavanje identiteta određujte kroz konfiguraciju postavljanja; nikada je nemojte prihvaćati iz zahtjeva.

Dnevnici bilježe kategorije pogrešaka, status vanjske usluge, pokušaje i trajanje uspješnih poziva bez zapisivanja URL-ova profila, tijela odgovora ili pristupnih podataka. Pratite broj pogrešaka i trendove latencije. Trajne odgovore 401 ili 403 istražite uz pomoć dokumentacije umjesto da dodajete autentikaciju na temelju nagađanja.

Uobičajene pogreške zahtijevaju različita rješenja: lokalni odgovori 419 upućuju na poteškoće sa sesijom ili CSRF zaštitom; odbijanje vanjske usluge znači da treba provjeriti poslanu platformu i podržanu referencu; ponovljeni odgovori 429 zahtijevaju smanjenje prometa; neispravno oblikovani uspješni odgovori zahtijevaju provjeru dokumentirane strukture odgovora. Nikada nemojte pretvarati takve slučajeve u uspješne unose u imenik.

Pohranjene objekte smatrajte nepouzdanim podacima. Pri svakom budućem prikazu primijenite odgovarajuće kodiranje, prije prikazivanja odredišta na koja se može kliknuti provjerite sheme poveznica i hostove prema popisu dopuštenih vrijednosti, ograničite pristup moderiranju i odredite rok čuvanja napuštenih prijava.

Provjerite cijeli tijek zaprimanja

  • Otvorite /directory/submit i pošaljite podržanu poveznicu za svaku platformu.
  • Potvrdite HTTP 201, normalizirani objekt odgovora i jedan redak u bazi podataka sa statusom na čekanju.
  • Potvrdite da se pri nevaljanom unosu ništa ne zapisuje i ne šalje vanjski zahtjev.
  • Pokrenite automatizirane provjere ponovnih pokušaja, ograničenja broja zahtjeva, neispravnih odgovora i trajne pohrane.
  • Provjerite da produkcijski dnevnici ne sadržavaju poslane reference ni tijela odgovora.
  • Potvrdite da je za objavu potrebna zasebna odluka ovlaštenog moderatora.

Koristan je rezultat usko definirana, pouzdana granica: poveznice za imenik ulaze kao neuređene reference, a izlaze kao objekti identiteta čiju strukturu određuje servis za razrješavanje. Odvajanje normalizacije od vlasništva, uklanjanja duplikata i objave olakšava današnje upravljanje funkcionalnošću i omogućuje sigurnije buduće proširenje.

Portret autora bloga

Mihajlo

Ja sam Mihajlo — programer vođen znatiželjom, disciplinom i stalnom željom da stvorim nešto smisleno. Dijelim uvide, tutorijale i besplatne usluge kako bih pomogao drugima da pojednostave svoj rad i rastu u svijetu softvera i umjetne inteligencije koji se neprestano razvija.