Laravel: Нормализирање врски до социјални мрежи со решавач на идентитети со вештачка интелигенција
Директориум на заедницата може да добие три различни врски за ист профил на социјална мрежа пред некој да забележи дека станува збор за дупликат. Параметрите за следење, мобилните URL-адреси и копираните референци до профили прават прочистувањето на низите да изгледа измамно едноставно. Со текот на времето, збирката од регуларни изрази станува несигурен систем за идентификација.
Identity Resolver нуди подобра граница: испратете поддржана референца и добијте нормализиран објект со јавен идентитет. Во овој туторијал се создава Laravel функционалност за прием на врски до Facebook, Instagram и LinkedIn, вклучувајќи трајно зачувување, ограничени повторни обиди, детерминистички тестови и оперативни заштитни мерки.
Пристап: за оваа крајна точка не е потребен токен
- Отворете ја официјалната документација за Identity Resolver.
- Прегледајте ја страницата за услугата и плановите.
- За тековната јавна крајна точка не е потребен токен за сметка или API-клуч. Нема токен што треба да се копира ниту заглавие за авторизација што треба да се конфигурира.
- За незадолжителна регистрација или најава, започнете од страницата на услугата и следете ја навигацијата за сметката. Овие врски намерно ја користат дадената официјална почетна точка; создавање сметка не е потребно за оваа интеграција.
Точното барање е GET https://ai.mihajlo.mk/api/identity-resolver/v1/resolve. Наведете platform и поддржан параметар username, id, identifier, profile или url. Нашиот формулар прифаќа врски, па затоа користи 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'
Создајте мала, синхрона функционалност за прием
Користете PHP 8.3+, Composer, PDO SQLite и Laravel 12. Барањето поминува низ валидација, наменски клиент за разрешување идентитет и зачувување во база на податоци. Секое поднесување останува во исчекување на модерација. Нормализацијата утврдува јавна референца; таа не утврдува сопственост, согласност или дозвола за објавување.
Синхроното извршување му дава непосреден резултат на подносителот. Два кратки обида кон надворешната услуга се разумни за овој мал формулар; редица би додала периодично проверување и управување со животниот циклус без да го подобри првичното искуство.
composer create-project laravel/laravel community-directory "^12.0"
cd community-directory
touch database/database.sqlite
php artisan make:migration create_directory_submissions_table
Поставете ги овие вредности во .env, заменувајќи ја патеката до базата со нејзината апсолутна локална патека. Тука не треба да има акредитиви бидејќи оваа крајна точка не ги бара.
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
Додајте го овој запис во низата што ја враќа config/services.php. Кодот на апликацијата ја чита конфигурацијата, со што кеширањето на конфигурацијата во Laravel функционира правилно.
'identity_resolver' => [
'endpoint' => env(
'IDENTITY_RESOLVER_ENDPOINT',
'https://ai.mihajlo.mk/api/identity-resolver/v1/resolve'
),
],
Проектот додава три класи за интеграциската граница во app/Services, еден контролер, еден Blade формулар и еден функционален тест. Ги користи постојните веб-посреднички компоненти, миграции на базата и HTTP-клиент на Laravel.
Зачувајте го нормализираниот објект без да ја нагаѓате неговата шема
Доставениот договор опишува нормализиран објект со јавен идентитет без да ги набројува полињата во одговорот. Зачувајте го целиот објект наместо да измислувате својства како канонска URL-адреса или траен кориснички ID. Наведените platform, public_identity и имиња на грешки се локални договори на самата апликација.
Уредете ја генерираната миграција:
<?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');
}
};
Создајте ги app/Services/ResolvedIdentity.php и 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);
}
}
Не хеширајте го целиот JSON за да ги отстраните дупликатите за лица. Редоследот на полињата во објектот, незадолжителните метаподатоци и променливите детали на профилот може да го направат тој пристап неуспешен. Ограничување за единственост бара документиран идентификатор на платформата и изрична политика за променети кориснички имиња.
Ограничете ги мрежните операции и класифицирајте ги грешките
Создајте го app/Services/IdentityResolver.php. Тој прави уште еден обид при грешки во поврзувањето и HTTP 502, 503 или 504, со случајно варирање на времето на чекање. При грешки во валидацијата, грешки во автентикацијата и ограничувања на бројот на барања нема автоматски повторен обид. Пренасочувањата се оневозможени, а доставените URL-адреси се испраќаат само како параметри на барањето до конфигурираната услуга.
<?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);
}
}
Вкупното дозволено време за мрежните барања е приближно осум секунди плус времето на чекање меѓу обидите; соодветно конфигурирајте го временското ограничување на веб-барањето што ги опфаќа. Проверката на големината се применува по баферирањето, а не како ограничување при преземање со стриминг. Валидацијата на објектот го заштитува структурниот договор на апликацијата; таа не може да го провери значењето на недокументираните полиња.
Валидирајте, нормализирајте, па зачувајте
Создајте го app/Http/Controllers/DirectorySubmissionController.php. Намерно нема трансакција на базата околу мрежниот повик. При одбиено или недостапно разрешување не се запишува ништо; успешното разрешување бара едно внесување во базата.
<?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);
}
}
Препораката за повторен обид по 60 секунди е политика на апликацијата, а не тврдење за квотата или времето на ресетирање на надворешната услуга. Клиентите исто така мора да ги ограничат сопствените повторни обиди. Изгубен одговор по внесувањето може да создаде дупликатни поднесувања; овој систем за прием ги дозволува за модерација наместо да се преправа дека има идемпотентност на ниво на идентитет.
Додајте ги овие рути во 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');
Заменете го app/Providers/AppServiceProvider.php со:
<?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())
);
}
}
Создајте го resources/views/directory-submit.blade.php. Поднесувањата од прелистувач добиваат вообичаени пренасочувања при неуспешна валидација во Laravel; успешните поднесувања прикажуваат JSON што го содржи нормализираниот објект.
<!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>
Тестирајте го однесувањето без да зависите од јавни профили
Создајте го tests/Feature/DirectorySubmissionTest.php. Синтетичкиот тест-податок подолу намерно не претставува ниту едно поле како дел од вистински одговор на услугата. Овие тестови го проверуваат однесувањето при пренос, непрозирното пресликување, зачувувањето и обработката на грешки.
<?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
Пуштете ја апликацијата со јасни оперативни граници
Опслужувајте го Laravel преку неговиот директориум public со HTTPS и APP_DEBUG=false. За распоредување со една инстанца, чувајте го SQLite на трајна меморија со резервни копии. Повеќе реплики треба да користат заедничка релациска база на податоци, вклучувајќи заеднички кеш и сесии складирани во базата. Правилно конфигурирајте ги доверливите прокси-сервери за ограничувачот по IP да ја гледа предвидената адреса на клиентот.
При распоредувањето, извршете ги php artisan migrate --force и php artisan config:cache. Повторно вчитајте ги долготрајните работни процеси на апликацијата по промените во конфигурацијата. Крајната точка на услугата за разрешување нека се контролира преку конфигурацијата при распоредување; никогаш не прифаќајте ја од барање.
Дневниците ги прикажуваат категориите на грешки, статусот на надворешната услуга, бројот на обиди и времетраењето на успешните повици без да ги бележат URL-адресите на профилите, телата на одговорите или акредитивите. Следете ги бројот на грешки и трендовите на доцнење. Испитајте ги постојаните одговори 401 или 403 според документацијата наместо да додавате автентикација по претпоставка.
Вообичаените грешки бараат различни решенија: локалните одговори 419 укажуваат на проблем со сесијата или CSRF; одбивањето од надворешната услуга значи дека треба да ги проверите доставената платформа и поддржаната референца; повторените одговори 429 бараат намалување на сообраќајот; неправилно оформените успешни одговори бараат проверка на документираната структура на одговорот. Никогаш не претворајте ги овие состојби во успешни записи во директориумот.
Третирајте ги зачуваните објекти како недоверливи податоци. Екранирајте ги при секое идно прикажување, дозволете само однапред одобрени шеми и хостови на врски пред да ги прикажете како одредишта на кои може да се кликне, ограничете го пристапот за модерација и дефинирајте период на чување за напуштените поднесувања.
Проверете ја целата патека на прием
- Отворете го
/directory/submitи поднесете поддржана врска за секоја платформа. - Потврдете дека има HTTP 201, нормализиран објект во одговорот и еден ред во базата што чека модерација.
- Потврдете дека невалидниот внес не запишува ништо и не прави надворешно барање.
- Извршете ги автоматизираните проверки за повторни обиди, ограничување на бројот на барања, неправилно оформени одговори и зачувување.
- Проверете дали продукциските дневници ги изоставуваат доставените референци и телата на одговорите.
- Потврдете дека објавувањето бара посебна одлука од овластен модератор.
Корисниот резултат е тесно дефинирана, сигурна граница: врските за директориумот влегуваат како неуредни референци и излегуваат како објекти со идентитет што ги обезбедува услугата за разрешување. Одвојувањето на нормализацијата од сопственоста, отстранувањето дупликати и објавувањето ја прави функционалноста полесна за одржување денес и побезбедна за проширување утре.