آموزش برنامه‌نویسی

اتصال API قیمت در لاراول با Http Client، Cache و Scheduler

در این آموزش یک سرویس‌کلاس لاراول برای دریافت قیمت طلا و دلار از API کارینا می‌سازیم، ریسپانس را با Cache::remember کش می‌کنیم، با Scheduler به‌روز نگه می‌داریم و در Blade نمایش می‌دهیم.

  • ۱۲ دقیقه مطالعه

سلام به همهٔ همراهان عزیز کارینا، با یک آموزش بسیار کاربردی دیگر در خدمت شما هستیم. اگر در پروژه‌های خود با نمایش قیمت لحظه‌ای طلا یا ارز سروکار داشته باشید، حتماً می‌دانید که فراخوانی مستقیم API در هر بار باز شدن صفحه، هم سرعت سایت را کاهش می‌دهد و هم سهمیهٔ پلن شما را بی‌دلیل مصرف می‌کند. در این مطلب قصد داریم API قیمت در لاراول را به زبان ساده و به صورت کاملاً عملی بررسی کنیم.

محور این آموزش یک سناریوی واقعی است. فرض کنید یک فروشگاه اینترنتی طلا دارید که باید قیمت هر گرم طلای ۱۸ عیار و نرخ دلار را در صفحهٔ اصلی نشان دهد. علاوه بر این، قیمت نهایی هر محصول نیز باید از روی همین قیمت لحظه‌ای محاسبه شود. برای این کار از Http Client لاراول، کش با Cache::remember، زمان‌بندی با Scheduler و در نهایت قالب Blade استفاده خواهیم کرد.

معماری پیشنهادی برای اتصال API قیمت در لاراول

پیش از نوشتن کد، بهتر است تصویر کلی را مشخص کنیم. یک خطای رایج این است که ریکوئست API مستقیماً داخل کنترلر یا حتی داخل فایل Blade نوشته شود. در نتیجه، با هر بازدید یک ریکوئست جدید ارسال می‌شود و اگر سرویس مقصد لحظه‌ای کند شود، صفحهٔ سایت شما نیز منتظر می‌ماند.

حالا راه‌حل این مشکل چیست؟ ما کار را به چند لایهٔ مستقل تقسیم می‌کنیم تا هر بخش فقط یک مسئولیت داشته باشد:

  1. تنظیمات: توکن و نشانی پایهٔ API در فایل .env و config/services.php نگهداری می‌شود.
  2. سرویس‌کلاس: کلاس KarinaPriceService تنها جایی است که با API ارتباط برقرار می‌کند.
  3. کش: ریسپانس API برای چند دقیقه در کش لاراول ذخیره می‌شود تا ریکوئست‌های تکراری ارسال نشوند.
  4. زمان‌بندی: یک دستور Artisan به کمک Scheduler، کش را در فواصل منظم تازه می‌کند.
  5. نمایش: کنترلر داده را از سرویس می‌گیرد و قالب Blade فقط آن را نمایش می‌دهد.

برای اینکه تفاوت روش‌ها را بهتر متوجه شوید، جدول زیر سه رویکرد رایج را با هم مقایسه می‌کند:

روشتعداد ریکوئست به APIسرعت بارگذاری صفحهرفتار هنگام قطعی API
فراخوانی مستقیم در کنترلربه ازای هر بازدیدوابسته به زمان پاسخ APIصفحه با خطا مواجه می‌شود
فقط Cache::rememberیک بار در هر بازهٔ کشسریع، به جز اولین بازدید پس از انقضاپس از انقضای کش، داده‌ای در دسترس نیست
Scheduler به‌همراه کش و نسخهٔ پشتیبانفقط در زمان‌های تعیین‌شدههمیشه سریعآخرین قیمت معتبر نمایش داده می‌شود

بنابراین در ادامه، برای اتصال API قیمت در لاراول روش سوم را پیاده‌سازی می‌کنیم؛ زیرا هم برای کاربر سریع‌تر است و هم مصرف سهمیهٔ API را قابل پیش‌بینی می‌کند.

گام اول: تنظیم توکن API و فایل config

تمام APIهای کارینا از طریق HTTPS و با نشانی پایهٔ https://karinaco.net/api/v1 فراخوانی می‌شوند. توکن API نیز در هدر Authorization و به شکل Bearer ارسال می‌شود. شما عزیزان پس از انتخاب پلن، توکن خود را از پنل کاربری کارینا دریافت می‌کنید.

توکن هرگز نباید داخل کد قرار بگیرد. به همین دلیل، ابتدا آن را در فایل .env پروژه تعریف می‌کنیم. به مثال زیر توجه کنید:

# توکن API کارینا را در این قسمت قرار دهید
KARINA_API_TOKEN=your-api-token-here
KARINA_API_URL=https://karinaco.net/api/v1

# مدت زمان نگهداری قیمت در کش (ثانیه)
KARINA_CACHE_TTL=600

سپس این مقادیر را در فایل config/services.php معرفی می‌کنیم تا در سراسر پروژه از طریق تابع config() در دسترس باشند:

<?php

return [

    // ... سایر سرویس‌های پروژه

    'karina' => [
        // توکن فقط از متغیر محیطی خوانده می‌شود
        'token' => env('KARINA_API_TOKEN'),
        'base_url' => env('KARINA_API_URL', 'https://karinaco.net/api/v1'),
        // مقدار پیش‌فرض: ۱۰ دقیقه
        'cache_ttl' => (int) env('KARINA_CACHE_TTL', 600),
    ],

];
نکته: اگر روی سرور پروداکشن دستور php artisan config:cache را اجرا می‌کنید، تابع env() بیرون از فایل‌های config مقدار null برمی‌گرداند. لذا همیشه از config('services.karina.token') استفاده کنید، نه از env() در کد اصلی.

گام دوم: ساخت سرویس‌کلاس با Laravel Http

در اینجاست که Http Client به کمک ما می‌آید و فراخوانی API قیمت در لاراول را بسیار ساده می‌کند. این ابزار در واقع یک لایهٔ خوانا روی Guzzle است و امکاناتی مانند تعیین Timeout، تلاش مجدد و ارسال توکن را با چند متد زنجیره‌ای در اختیار ما قرار می‌دهد. مستندات کامل آن را می‌توانید در مستندات رسمی Laravel Http Client مطالعه کنید.

ابتدا فایل app/Services/KarinaPriceService.php را می‌سازیم و متد fetch را در آن می‌نویسیم. این متد فقط یک کار انجام می‌دهد: ارسال ریکوئست و اعتبارسنجی ریسپانس. به مثال زیر توجه کنید:

<?php

namespace App\Services;

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

class KarinaPriceService
{
    /**
     * دریافت مستقیم داده از API کارینا (بدون کش)
     * مثال: fetch('gold/price') یا fetch('dollar/price')
     */
    public function fetch(string $endpoint): array
    {
        try {
            $response = Http::baseUrl(config('services.karina.base_url'))
                ->withToken(config('services.karina.token'))
                ->acceptJson()
                ->connectTimeout(5)  // حداکثر ۵ ثانیه برای برقراری اتصال
                ->timeout(10)        // حداکثر ۱۰ ثانیه منتظر پاسخ می‌مانیم
                ->retry(2, 300, throw: false) // در صورت خطا، یک بار دیگر با تأخیر ۳۰۰ میلی‌ثانیه تلاش می‌کنیم
                ->get($endpoint);
        } catch (ConnectionException $e) {
            throw new RuntimeException('Karina API connection failed: ' . $e->getMessage(), 0, $e);
        }

        // بررسی کد وضعیت HTTP و کلید success در ریسپانس
        if ($response->failed() || $response->json('success') !== true) {
            throw new RuntimeException('Invalid response from Karina API, status: ' . $response->status());
        }

        // در صورت کم شدن سهمیه، یک هشدار در لاگ ثبت می‌کنیم
        $remaining = $response->json('quota.remaining');
        if ($remaining !== null && $remaining < 50) {
            Log::notice('Karina API quota is running low', ['remaining' => $remaining]);
        }

        return $response->json('data');
    }
}

یک مثال می‌زنم تا موضوع را بهتر متوجه شوید. اگر این متد را با مقدار gold/price صدا بزنیم، ریکوئست به اندپوینت GET /gold/price ارسال می‌شود. جالب است بدانید که ریسپانس کامل API به صورت زیر خواهد بود:

{
    "success": true,
    "data": {
        "metal": "gold",
        "karat": 18,
        "price": 18809000,
        "currency": "IRT",
        "unit": "gram",
        "is_stale": false,
        "updated_at": "1405/05/01 20:10:03"
    },
    "quota": {
        "unlimited": false,
        "remaining": 120
    }
}

همان‌طور که می‌بینید، قیمت به تومان و تاریخ به‌روزرسانی به تقویم شمسی برگردانده می‌شود. متد fetch فقط بخش data را برمی‌گرداند؛ زیرا بقیهٔ پروژه به کلیدهای success و quota نیازی ندارد. به عبارت دیگر، جزئیات API فقط داخل همین کلاس باقی می‌ماند.

چند نکتهٔ مهم در این کد وجود دارد که بهتر است به آن‌ها توجه فرمایید:

  • متد withToken هدر Authorization: Bearer را به صورت خودکار می‌سازد.
  • تعیین timeout و connectTimeout باعث می‌شود یک API کند، کل پروژه را متوقف نکند.
  • پارامتر throw: false در متد retry اجازه می‌دهد خودمان وضعیت ریسپانس را بررسی کنیم.
  • خطای اتصال به یک RuntimeException تبدیل می‌شود تا لایه‌های بالاتر فقط با یک نوع خطا سروکار داشته باشند.

کش کردن ریسپانس با Cache::remember

حالا که دریافت داده آماده است، باید جلوی ریکوئست‌های تکراری را بگیریم؛ زیرا مهم‌ترین بخش بهینه‌سازی API قیمت در لاراول همین کش است. متد Cache::remember ابتدا کش را بررسی می‌کند؛ اگر مقدار وجود داشت، همان را برمی‌گرداند. در غیر این صورت، تابع داده‌شده را اجرا و نتیجه را برای مدت مشخص ذخیره می‌کند.

با این حال، یک مسئلهٔ مهم باقی می‌ماند: اگر کش منقضی شود و دقیقاً در همان لحظه API در دسترس نباشد، چه اتفاقی می‌افتد؟ برای همین، علاوه بر کش اصلی، یک نسخهٔ پشتیبان دائمی از آخرین قیمت معتبر نیز نگه می‌داریم. متدهای زیر را به همان کلاس اضافه کنید:

    /**
     * دریافت قیمت از کش؛ در صورت نبود کش، از API خوانده می‌شود
     */
    public function get(string $endpoint): ?array
    {
        $key = $this->cacheKey($endpoint);

        try {
            return Cache::remember($key, $this->ttl(), function () use ($endpoint, $key) {
                $data = $this->fetch($endpoint);

                // آخرین قیمت معتبر را برای زمان قطعی API نگه می‌داریم
                Cache::forever($key . ':last', $data);

                return $data;
            });
        } catch (RuntimeException $e) {
            Log::warning('Karina price fallback used', ['endpoint' => $endpoint, 'error' => $e->getMessage()]);

            // اگر نسخهٔ پشتیبان هم وجود نداشته باشد، null برگردانده می‌شود
            return Cache::get($key . ':last');
        }
    }

    /**
     * به‌روزرسانی اجباری کش (برای استفاده در Scheduler)
     */
    public function refresh(string $endpoint): array
    {
        $data = $this->fetch($endpoint);
        $key = $this->cacheKey($endpoint);

        Cache::put($key, $data, $this->ttl());
        Cache::forever($key . ':last', $data);

        return $data;
    }

    private function cacheKey(string $endpoint): string
    {
        // مثال: karina:gold/price
        return 'karina:' . trim($endpoint, '/');
    }

    private function ttl(): int
    {
        return config('services.karina.cache_ttl');
    }

در این ساختار، متد get برای نمایش در صفحات و متد refresh برای به‌روزرسانی زمان‌بندی‌شده استفاده می‌شود. از طرفی، چون در صورت بروز خطا هیچ مقداری داخل Cache::remember ذخیره نمی‌شود، خطای موقت API هرگز به‌عنوان قیمت در کش باقی نمی‌ماند.

تذکر: اگر پروژهٔ شما روی چند سرور اجرا می‌شود، درایور کش file مناسب نیست؛ زیرا هر سرور کش جداگانه‌ای خواهد داشت. در این حالت از درایورهای مشترک مانند Redis یا database استفاده کنید.

گام سوم: به‌روزرسانی خودکار قیمت‌ها با Scheduler

تا اینجا، اولین بازدیدکننده پس از انقضای کش باید منتظر پاسخ API بماند. برای حذف این تأخیر، یک دستور Artisan می‌سازیم که قیمت‌ها را در پس‌زمینه تازه کند. ابتدا دستور زیر را اجرا کنید:

php artisan make:command RefreshKarinaPrices

سپس فایل ساخته‌شده در مسیر app/Console/Commands را به شکل زیر تکمیل کنید. به مثال زیر توجه کنید:

<?php

namespace App\Console\Commands;

use App\Services\KarinaPriceService;
use Illuminate\Console\Command;
use RuntimeException;

class RefreshKarinaPrices extends Command
{
    protected $signature = 'karina:refresh-prices';

    protected $description = 'به‌روزرسانی قیمت طلا و دلار از API کارینا';

    // اندپوینت‌هایی که سایت به آن‌ها نیاز دارد
    private array $endpoints = ['gold/price', 'dollar/price'];

    public function handle(KarinaPriceService $prices): int
    {
        $failed = 0;

        foreach ($this->endpoints as $endpoint) {
            try {
                $data = $prices->refresh($endpoint);
                $this->info("{$endpoint}: {$data['price']} IRT ({$data['updated_at']})");
            } catch (RuntimeException $e) {
                // خطای یک اندپوینت نباید مانع به‌روزرسانی بقیه شود
                $failed++;
                $this->error("{$endpoint}: {$e->getMessage()}");
            }
        }

        return $failed === 0 ? self::SUCCESS : self::FAILURE;
    }
}

اگر این دستور را به صورت دستی با php artisan karina:refresh-prices اجرا کنید، برای هر اندپوینت یک خط شامل قیمت به تومان و زمان به‌روزرسانی در ترمینال چاپ می‌شود. در نتیجه، پیش از فعال‌سازی زمان‌بندی می‌توانید از درستی توکن و اتصال مطمئن شوید.

حالا نوبت تعریف زمان‌بندی است. در نسخه‌های جدید لاراول، زمان‌بندی‌ها در فایل routes/console.php تعریف می‌شوند (در نسخه‌های قدیمی‌تر، متد schedule در فایل app/Console/Kernel.php همین نقش را دارد):

<?php

use Illuminate\Support\Facades\Schedule;

// هر ۵ دقیقه قیمت‌ها تازه می‌شوند؛ اجرای هم‌زمان دو نسخه از دستور ممکن نیست
Schedule::command('karina:refresh-prices')
    ->everyFiveMinutes()
    ->withoutOverlapping();

توجه فرمایید که بازهٔ اجرای Scheduler (۵ دقیقه) کوتاه‌تر از عمر کش (۱۰ دقیقه) انتخاب شده است. بنابراین کش پیش از انقضا تازه می‌شود و کاربران تقریباً هیچ‌گاه منتظر پاسخ API نمی‌مانند. در نهایت، برای اجرای Scheduler روی سرور پروداکشن، کران‌جاب زیر را اضافه کنید:

# اجرای Scheduler لاراول در هر دقیقه
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

گام چهارم: نمایش قیمت طلا و دلار در Blade

اکنون که داده‌های API قیمت در لاراول همیشه در کش آماده هستند، کنترلر فقط کافی است آن‌ها را از سرویس بخواند. لاراول سرویس‌کلاس را به صورت خودکار از طریق Dependency Injection به متد کنترلر تزریق می‌کند. به مثال زیر توجه کنید:

<?php

namespace App\Http\Controllers;

use App\Services\KarinaPriceService;

class PriceController extends Controller
{
    public function index(KarinaPriceService $prices)
    {
        $gold = $prices->get('gold/price');
        $dollar = $prices->get('dollar/price');

        // محاسبهٔ قیمت یک محصول نمونه: وزن × قیمت هر گرم × (۱ + درصد اجرت)
        $weight = 3.5; // گرم
        $wagePercent = 18;
        $productPrice = $gold
            ? (int) round($weight * $gold['price'] * (1 + $wagePercent / 100))
            : null;

        return view('prices.index', compact('gold', 'dollar', 'productPrice'));
    }
}

سپس مسیر صفحه را در فایل routes/web.php تعریف می‌کنیم:

<?php

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

Route::get('/prices', [PriceController::class, 'index'])->name('prices.index');

در نهایت، فایل resources/views/prices/index.blade.php را می‌سازیم. دقت کنید که همیشه حالت نبودن داده نیز در قالب پیش‌بینی شده باشد:

<section class="price-box">
    @if ($gold)
        <p>قیمت هر گرم طلای {{ $gold['karat'] }} عیار: {{ number_format($gold['price']) }} تومان</p>
        <p>قیمت گردنبند ۳.۵ گرمی با اجرت ۱۸٪: {{ number_format($productPrice) }} تومان</p>
        <small>آخرین به‌روزرسانی: {{ $gold['updated_at'] }}</small>

        @if ($gold['is_stale'])
            <p>قیمت نمایش‌داده‌شده ممکن است به‌روز نباشد.</p>
        @endif
    @else
        <p>در حال حاضر قیمت طلا در دسترس نیست. لطفاً دقایقی بعد مراجعه کنید.</p>
    @endif

    @if ($dollar)
        <p>نرخ دلار: {{ number_format($dollar['price']) }} تومان</p>
    @endif
</section>

با فرض اینکه قیمت هر گرم طلا همان مقدار ریسپانس نمونه، یعنی ۱۸,۸۰۹,۰۰۰ تومان باشد، خروجی کد بالا به صورت زیر خواهد بود:

قیمت هر گرم طلای 18 عیار: 18,809,000 تومان
قیمت گردنبند ۳.۵ گرمی با اجرت ۱۸٪: 77,681,170 تومان
آخرین به‌روزرسانی: 1405/05/01 20:10:03

برای مثال، عدد ۷۷,۶۸۱,۱۷۰ از ضرب ۳.۵ گرم در قیمت هر گرم و سپس افزودن ۱۸ درصد اجرت به دست آمده است. همچنین دستور {{ }} در Blade خروجی را به صورت خودکار Escape می‌کند؛ لذا نمایش داده‌های دریافتی از API از نظر امنیتی مشکلی ایجاد نمی‌کند.

خطاهای رایج در پیاده‌سازی API قیمت در لاراول

در پایان، به چند اشتباه پرتکرار اشاره می‌کنیم که همراهان کارینا معمولاً در پروژه‌های واقعی با آن‌ها روبه‌رو می‌شوند:

  • فراموش کردن کران‌جاب: بدون اجرای schedule:run، دستور به‌روزرسانی هرگز اجرا نمی‌شود و فقط Cache::remember کار می‌کند.
  • نداشتن Timeout: بدون تعیین زمان انتظار، یک API کند می‌تواند پردازش‌های PHP سرور را برای مدت طولانی مشغول نگه دارد.
  • کش کردن خطا: اگر ریسپانس ناموفق را بدون بررسی کلید success ذخیره کنید، تا پایان عمر کش قیمت اشتباه نمایش داده می‌شود.
  • نمایش قیمت بدون تاریخ: در سایت‌های طلا و ارز، نمایش updated_at کنار قیمت، اعتماد کاربر را افزایش می‌دهد.
  • نادیده گرفتن تست: با Http::fake می‌توانید ریسپانس API را در تست‌ها شبیه‌سازی کنید تا سهمیهٔ واقعی مصرف نشود.

به طور کلی، اگر همین الگو را برای API قیمت در لاراول رعایت کنید، افزودن ارزهای دیگر فقط به اضافه کردن یک اندپوینت جدید به آرایهٔ $endpoints نیاز دارد. برای مثال، برای نمودار تغییرات قیمت می‌توانید از اندپوینت gold/prices در API تاریخچه قیمت طلا با همین سرویس‌کلاس استفاده کنید.

اگر قصد دارید این آموزش را روی پروژهٔ خود پیاده کنید، می‌توانید از API قیمت طلا و API قیمت دلار کارینا استفاده کنید. پیش از شروع نیز پیشنهاد می‌شود پلن‌های کارینا را بررسی کنید تا سهمیهٔ مناسب پروژهٔ خود را انتخاب نمایید.

حرف آخر اینکه: جداسازی فراخوانی API در یک سرویس‌کلاس، کش کردن ریسپانس و تازه‌سازی آن با Scheduler، صفحات شما را از سرعت و پایداری API مستقل می‌کند. در نتیجه، کاربران همیشه سریع‌ترین پاسخ و آخرین قیمت معتبر را خواهند دید.

خب به پایان آموزش «اتصال API قیمت در لاراول با Http Client، Cache و Scheduler» رسیدیم. امیدوارم این مبحث مورد توجه شما واقع شده باشد. چنانچه ابهام، اشکال یا سؤالی داشتید و یا مورد خاصی در پروژه‌هایتان تجربه کرده‌اید، می‌توانید در بخش دیدگاه‌ها با ما و بقیهٔ همراهان کارینا به اشتراک بگذارید. همچنین پیشنهاد می‌گردد بلاگ کارینا را دنبال کنید تا از جدیدترین آموزش‌های تخصصی بهره‌مند شوید.

پرسش و پاسخ

سوالات متداول

آیا می‌توانم توکن API را مستقیماً داخل سرویس‌کلاس بنویسم؟

خیر، توکن باید در فایل .env قرار بگیرد و از طریق config خوانده شود. به این ترتیب توکن وارد مخزن کد نمی‌شود و تغییر آن نیز ساده است.

بهترین مدت زمان کش برای قیمت طلا و ارز چقدر است؟

این مقدار به نیاز کسب‌وکار و سهمیهٔ پلن شما بستگی دارد. نکتهٔ مهم این است که بازهٔ اجرای Scheduler کوتاه‌تر از عمر کش باشد تا کش پیش از انقضا تازه شود.

اگر API کارینا موقتاً پاسخ ندهد، سایت من چه چیزی نمایش می‌دهد؟

در الگوی این آموزش، آخرین قیمت معتبر در یک کلید دائمی کش نگهداری می‌شود و در زمان خطا همان نمایش داده می‌شود. اگر هیچ داده‌ای وجود نداشته باشد، قالب Blade پیام مناسبی نشان می‌دهد.

آیا این روش در نسخه‌های قدیمی‌تر لاراول هم کار می‌کند؟

بله، منطق سرویس‌کلاس و کش تغییری نمی‌کند و فقط محل تعریف زمان‌بندی متفاوت است. در نسخه‌های قدیمی‌تر، زمان‌بندی را در متد schedule فایل app/Console/Kernel.php بنویسید.

چگونه بدون مصرف سهمیهٔ API برای سرویس‌کلاس تست بنویسم؟

با استفاده از Http::fake می‌توانید یک ریسپانس نمونه برای اندپوینت تعریف کنید. در این حالت هیچ ریکوئست واقعی به API ارسال نمی‌شود.

اشتراک‌گذاری
همه مطالب مجله

دیدگاه‌ها

هنوز دیدگاهی ثبت نشده است. اولین نفر باشید!

دیدگاه خود را بنویسید