سلام به همهٔ همراهان عزیز کارینا، با یک آموزش بسیار کاربردی دیگر در خدمت شما هستیم. اگر در پروژههای خود با نمایش قیمت لحظهای طلا یا ارز سروکار داشته باشید، حتماً میدانید که فراخوانی مستقیم API در هر بار باز شدن صفحه، هم سرعت سایت را کاهش میدهد و هم سهمیهٔ پلن شما را بیدلیل مصرف میکند. در این مطلب قصد داریم API قیمت در لاراول را به زبان ساده و به صورت کاملاً عملی بررسی کنیم.
محور این آموزش یک سناریوی واقعی است. فرض کنید یک فروشگاه اینترنتی طلا دارید که باید قیمت هر گرم طلای ۱۸ عیار و نرخ دلار را در صفحهٔ اصلی نشان دهد. علاوه بر این، قیمت نهایی هر محصول نیز باید از روی همین قیمت لحظهای محاسبه شود. برای این کار از Http Client لاراول، کش با Cache::remember، زمانبندی با Scheduler و در نهایت قالب Blade استفاده خواهیم کرد.
معماری پیشنهادی برای اتصال API قیمت در لاراول
پیش از نوشتن کد، بهتر است تصویر کلی را مشخص کنیم. یک خطای رایج این است که ریکوئست API مستقیماً داخل کنترلر یا حتی داخل فایل Blade نوشته شود. در نتیجه، با هر بازدید یک ریکوئست جدید ارسال میشود و اگر سرویس مقصد لحظهای کند شود، صفحهٔ سایت شما نیز منتظر میماند.
حالا راهحل این مشکل چیست؟ ما کار را به چند لایهٔ مستقل تقسیم میکنیم تا هر بخش فقط یک مسئولیت داشته باشد:
- تنظیمات: توکن و نشانی پایهٔ API در فایل
.envوconfig/services.phpنگهداری میشود. - سرویسکلاس: کلاس
KarinaPriceServiceتنها جایی است که با API ارتباط برقرار میکند. - کش: ریسپانس API برای چند دقیقه در کش لاراول ذخیره میشود تا ریکوئستهای تکراری ارسال نشوند.
- زمانبندی: یک دستور Artisan به کمک Scheduler، کش را در فواصل منظم تازه میکند.
- نمایش: کنترلر داده را از سرویس میگیرد و قالب 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 ارسال نمیشود.
دیدگاهها
هنوز دیدگاهی ثبت نشده است. اولین نفر باشید!