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
- Otvorite službenu dokumentaciju za Identity Resolver.
- Pregledajte stranicu usluge i paketa.
- 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.
- 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/submiti 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.