11 KiB
11 KiB
مشخصات درس‌نامه: سرویس Third-Party چیست و چرا نباید چرخ را از نو بسازیم؟
- شناسه در سیلابس:
L10.2 - فصل: فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
- نوع محتوا: 📘 درس‌نامه متنی
- زمان تقریبی مطالعه: ۱۲ دقیقه
- پیش‌نیازهای مستقیم:
L10.1(اهداف فصل دهم)
۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- درک کند (Understand): مفهوم سرویس‌های شخص ثالث (Third-Party Services) و فلسفه استفاده از قطعات آماده نرم‌افزاری (Lego-Bricks Architecture) را در توسعه پرسرعت محصول شرح دهد.
- تحلیل/ارزیابی کند (Evaluate): دوراهی ساختن در برابر خریدن/استفاده از سرویس آماده (Build vs Buy) را از منظر هزینه مالی، زمان عرضه به بازار (Time to Market) و الزامات قانونی مقایسه کند.
- درک کند (Understand): چرا درخواست به سرویس‌های حساس شخص ثالث (پیامک، پرداخت، مدل‌های زبانی) حتماً باید از طریق سرور (Next.js Server Actions / Route Handlers) انجام شود تا کلیدهای محرمانه فاش نشوند.
- به‌کار ببندد (Apply): معماری کلی ارتباط پروژه پورتفولیو با سرویس‌های ارتباطی، مالی و هوش مصنوعی را روی نمودار جریان سیستم رسم و پیاده نماید.
۲. محدوده و مرزهای محتوا (Scope & Boundaries)
آنچه باید پوشش داده شود (In-Scope):
- استعاره کارخانه لگو در برابر ساخت پلاستیک از نفت خام:
- توسعه‌دهنده مدرن کارخانه‌دار نیست؛ یک معمار زبردست است که قطعات باکیفیت و تخصصی را کنار هم می‌چیند.
- کالبدشکافی دوراهی استراتژیک ساخت یا خرید (Build vs Buy):
- برای ارسال پیامک: بستن قرارداد با اپراتورها، راه‌اندازی دکل، مجوزهای مخابراتی (چند ماه و صدها میلیون تومان) در برابر ثبت‌نام ۲ دقیقه‌ای در کاوه‌نگار یا SMS.ir.
- برای پرداخت: راه‌اندازی سرور اختصاصی، دریافت نماد اعتماد و پروتکل‌های شاپرک در برابر اتصال سندباکس زرین‌پال در چند خط کد.
- دسته‌بندی اصلی سرویس‌های ابری در دنیای وب مدرن:
- سرویس‌های ارتباطی و نوتیفیکیشن (Communication: SMS & Email).
- سرویس‌های مالی و درگاه‌های پرداخت (Fintech: Payment Gateways).
- سرویس‌های هویتی و دسترسی (Identity & OAuth: Google, GitHub).
- سرویس‌های ابری داده و فایل (BaaS: Supabase Database & Storage).
- سرویس‌های هوش مصنوعی زاینده (AI Model APIs: OpenAI, OpenRouter, AvalAI).
- جریان فنی تبادل داده با سرویس‌های بیرونی:
- مرورگر کاربر دکمه را می‌زند
\rightarrowدرخواست امن به سرور پروژه شما می‌رسد\rightarrowسرور شما کلید اختصاصی را الصاق کرده و به سرور سرویس ثالث می‌فرستد\rightarrowپاسخ JSON دریافت و وضعیت کاربر آپدیت می‌شود.
- مرورگر کاربر دکمه را می‌زند
- معماری امنیت: سرور امن در برابر مرورگر ناامن:
- چرا نباید کلیدهای پرداخت یا پیامک مستقیماً در کدهای کلاینت جاوااسکریپت قرار گیرند.
- کال‌اوت‌های آموزشی و هشدار کوئرا:
- کال‌اوت بنفش (
<details class="violet">): مفهوم وب‌هوک (Webhook)؛ وقتی سرویس خارجی به سرور شما اطلاع‌رسانی معکوس می‌کند. - کال‌اوت سبز (
<details class="green">): محیط‌های رایگان و اعتبارهای هدیه آغازین سرویس‌های بومی و بین‌المللی برای تست. - کال‌اوت قرمز (
<details class="red">): وابستگی انحصاری (Vendor Lock-in) و اهمیت جداسازی کد از سرویس با لایه واسط (Adapter Pattern).
- کال‌اوت بنفش (
آنچه نباید وارد آن شویم (Out-of-Scope):
- نوشتن کدهای تفصیلی ارسال پیامک یا پرداخت (درس‌های ۱۰.۴ و ۱۰.۷).
- معماری مایکروسرویس‌های توزیع‌شده سازمانی (فصل ۱۶).
۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|---|---|---|
| Third-Party Integration | یکپارچه‌سازی با سرویس ثالث | اتصال و هماهنگ‌سازی نرم‌افزار با یک پلتفرم خارجی از طریق پروتکل‌های استاندارد وب |
| Build vs Buy | دوراهی ساخت یا خرید | تصمیم استراتژیک مهندسی درباره توسعه داخلی یک ماژول یا استفاده از سرویس‌های آماده موجود |
| Webhook | وب‌هوک / قلاب وب | سازوکار اعلان خودکار از طرف سرویس خارجی به آدرس سرور شما هنگام رخ دادن یک رویداد |
| Adapter Pattern | الگوی آداپتور یا لایه واسط | شیوه طراحی کد به نحوی که تعویض یک سرویس‌دهنده (مثلاً کاوه‌نگار با SMS.ir) به کمترین تغییر در کل پروژه منجر شود |
| Server-Side Proxy | پروکسی سمت سرور | ارسال درخواست‌ها از طریق سرور خودی به منظور مخفی‌سازی کلیدهای اختصاصی از دید کاربران |
۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ
images/ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
- تصویر کاور درس:
images/cover.png- موضوع: تقابل ساخت دستی یک قطعه مکانیکی پیچیده و پرزحمت با استفاده از قطعات لگوی دیجیتال مدرن و براق.
- دیاگرام معماری پورتفولیو و قطعات متصل:
images/portfolio-integrations-architecture.png- موضوع: معماری سیستم پورتفولیو در مرکز با فلش‌های متصل به کاوه‌نگار (پیامک)، لیارا (ایمیل)، زرین‌پال (پرداخت)، سوپابیس (دیتابیس/Auth) و OpenRouter (هوش مصنوعی).
- تفاوت درخواست امن سروری با درخواست ناامن کلاینتی:
images/secure-server-vs-client-flow.png- موضوع: اینفوگرافیک مقایسه‌ای: مسیر قرمز (مرورگر کلید را مستقیماً می‌فرستد و هک می‌شود) در برابر مسیر سبز (مرورگر به Next.js Server Action پیام می‌دهد و سرور کلید را محرمانه ارسال می‌کند).
۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)
- تیتر اصلی:
# سرویس Third-Party چیست و چرا نباید چرخ را از نو بسازیم؟ - مقدمه: اگر برای سفر با هواپیما مجبور بودید خودتان کارخانه هواپیماسازی راه بیندازید، هیچ‌کس هرگز مسافرت نمی‌رفت!
- جدول کاور درس
- استعاره جعبه ابزار و قطعات پیش‌ساخته در مهندسی:
- چرا ارزش شما در اتصال هوشمندانه قطعات برای حل مسئله کاربر است، نه در بازنویسی پروتکل‌های مخابراتی و بانکی.
- جدول مقایسه‌ای Build vs Buy در ۵ بُعد کلیدی:
- مقایسه هزینه، زمان تا راه‌اندازی، امنیت، نگهداری و مقیاس‌پذیری.
- نقشه اکوسیستم سرویس‌های شخص ثالث در پورتفولیوی شخصی:
- نقش پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی در ساخت یک تجربه کاربری فوق‌العاده.
- باکس نکته Quera (
<details class="violet">): وب‌هوک‌ها چگونه کار می‌کنند؟ تفاوت این که ما مدام استعلام بگیریم (Polling) یا اینکه سرویس خودش زنگ بزند (Webhook). - اصل ایمنی حیاتی: کلیدهای محرمانه هرگز به مرورگر کاربر نمی‌روند!
- توضیح ساده نحوه میانجی‌گری Next.js Server Actions برای محافظت از سرمایه و اعتبار شما.
- باکس هشدار Quera (
<details class="red">): خطر قفل شدن به یک شرکت خاص (Vendor Lock-in) و توصیه به تمیز نوشتن کد با توابع واسط. - باکس انرژی‌بخش Quera (
<details class="green">): خوشبختانه تقریباً تمام سرویس‌های مدرن دارای پنل‌های آزمایشی و سهمیه تست رایگان هستند. - جمع‌بندی درس‌نامه: تسلط مفهومی بر سرویس‌های شخص ثالث و ورود به دنیای خواندن مستندات فنی API و مدیریت امن متغیرها در درس بعدی.
۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- استعاره قطعات لگو و دوراهی Build vs Buy به صورت شفاف و قانع‌کننده تحلیل شود.
- پنج دسته اصلی سرویس‌های ابری با مثال‌های متناسب با نیاز ایران معرفی گردند.
- چرخه درخواست امن سمت سرور برای حفظ کلیدهای اختصاصی به صورت گرافیکی و متنی تبیین شود.
- مفهوم وب‌هوک (Webhook) به زبان ساده آموزش داده شود.