زبان مشترک نرمافزارها: HTTP، JSON و API
زبان مشترک نرمافزارها: درخواست و پاسخ HTTP، داده JSON، کلید و احراز هویت، خطا و تلاش دوباره، Webhook، و فراخوانی مدل زبانی پشت رابط مستقل از ارائهدهنده.
آنچه یاد میگیری
- خواندن و ساختن درخواست HTTP و تفسیر کد وضعیت
- پیمایش و اعتبارسنجی JSON تو در تو
- نگهداری امن کلید و شناخت OAuth در حد کاربرد
- طراحی تلاش دوباره برای 429 و 5xx بدون اقدام تکراری
- فراخوانی API مدل با خروجی ساختاریافته پشت یک رابط مستقل از ارائهدهنده (پروژه ۲)
پیشنیاز
- از پرامپت تا خروجی قابل اتکا
ابزارها
- Python 3.9 یا بالاتر (برای API آزمایشی محلی)
- curl یا یک کلاینت HTTP گرافیکی
- درخواست و پاسخ HTTP از دید سازنده ورکفلو
اجزای یک درخواست و پاسخ HTTP را بشناس، درخواست واقعی به یک API آزمایشی بفرست و از روی کد وضعیت بفهمی چه شد.
- JSON و ساختار داده
JSON را بخوان و بنویس، مسیر رسیدن به یک فیلد تودرتو را پیدا کن، ایرادهای نحوی و معنایی را تشخیص بده و داده تودرتو را به ردیف جدول تبدیل کن.
- احراز هویت و نگهداری کلید
کلید API چیست، کجا باید بماند و کجا نه؛ کلید را از محیط بخوان، برای هر کار کلید جدا با کمترین اختیار بگیر و بدان وقتی نشت کرد چه کنی.
- خطا، محدودیت نرخ و تلاش دوباره
خطا را دستهبندی کن، فقط خطای قابل تکرار را با فاصله افزایشی دوباره بفرست، سقف بگذار و با کلید ایدمپوتنسی جلوی تکرار POST را بگیر.
- Webhook: وقتی سرویسها به تو خبر میدهند
بهجای پرسیدن مداوم، بگذار سرویس خبر بدهد؛ امضای Webhook را بررسی کن، تحویل تکراری را بشناس، سریع پاسخ بده و کار سنگین را بعد انجام بده.
- فراخوانی API مدلها و انتزاع ارائهدهنده + پروژه ۲
مدل زبانی را از راه API صدا بزن، پشت یک رابط مستقل از ارائهدهنده، با اعتبارسنجی خروجی و سیاست خطا؛ و پروژه ۲ را تحویل بده.
درخواست و داده
موقعیت (ساختگی): ورکفلوی گزارش هفتگی برگ سبز از GET /orders?page=1&limit=3 شروع میکند و باید همه صفحهها را بخواند و مبلغ کل هفته و فروش هر کتاب را حساب کند.
تحویل بده: (۱) دنباله درخواستها تا صفحه آخر و شرط توقف؛ (۲) رفتار ورکفلو برای پاسخهای 401، 404 (برای مسیر غلط) و 503؛ (۳) قاعده تبدیل داده تودرتو به دو گزارش و ستونهایی که نباید جمع زده شوند؛ (۴) دو ایراد معنایی محتمل در داده (مثلاً مبلغ بهشکل رشته) و جای تشخیصشان.
- شرط توقف بر اساس next_page برابر null است (2)
- 401 توقف، 404 اصلاح مسیر، 503 تلاش دوباره محدود (2)
- مبلغ کل از سطح سفارش جمع زده میشود، نه سطح قلم (2)
- ایراد معنایی پیش از محاسبه بررسی میشود (2)
اتصال امن و مقاوم
موقعیت (ساختگی): درگاه پرداخت با Webhook امضاشده خبر «پرداخت موفق» میدهد و ورکفلو باید سفارش را در سامانه سفارش «آماده ارسال» کند (درخواست PATCH) و به مشتری پیامک بفرستد (POST به سرویس پیامک). تحویل بده: (۱) جدول کلیدها با اختیار و محل نگهداری برای سه اتصال؛ (۲) ترتیب کار گیرنده Webhook؛ (۳) سیاست خطا برای PATCH و POST پیامک با کلید ایدمپوتنسی؛ (۴) رفتار وقتی همان رویداد سه بار رسید.
- سه کلید جدا با کمترین اختیار؛ هیچکدام در کد یا لاگ (2)
- امضا روی بدنه خام پیش از هر کار؛ پاسخ سریع پیش از کار سنگین (2)
- پیامک با کلید ایدمپوتنسی از شناسه رویداد یا سفارش (2)
- رویداد تکراری تأیید میشود ولی پیامک دوباره فرستاده نمیشود (2)
فراخوانی مدل
موقعیت (ساختگی): پروژه ۲ با مدل محلی دقت ۷۰ درصد دارد. مدیر میخواهد یک ارائهدهنده میزبانیشده را امتحان کند که فقط لایه سازگار با OpenAI بدون اجرای response_format دارد.
تحویل بده: (۱) چه چیزهایی در پیکربندی عوض میشوند و چه چیزی در رفتار؛ (۲) آزمونهایی که پیش از تصمیم اجرا میکنی؛ (۳) معیار تصمیم (دقت، صف انسانی، توکن و هزینه، شرایط داده)؛ (۴) راه برگشت اگر نتیجه بدتر بود.
- LLM_SCHEMA_MODE برابر none و اتکا به اعتبارسنجی در کد (2)
- اجرای همان مجموعه آزمون و آزمون شکست روی هر دو (2)
- معیار تصمیم شامل شرایط داده و هزینه، نه فقط دقت (2)
- برگشت فقط با پیکربندی، بدون تغییر خط لوله (2)
آزمون عبور از دوره
در حدود ۴۵ دقیقه، با API آزمایشی برگ سبز (یا خروجیهای ضبطشده درسها) اینها را تحویل بده: (۱) تحلیل ده خط لاگ ساختگی HTTP با تصمیم درست برای هر کد وضعیت؛ (۲) اصلاح سه JSON مشکلدار و یک قاعده مسطحسازی؛ (۳) سیاست تلاش دوباره با کلید ایدمپوتنسی برای ثبت تیکت؛ (۴) ترتیب ششگامی گیرنده Webhook؛ (۵) اجرای classify_and_ticket.py با مدل آزمایشی روی failure-test.csv و توضیح هر چهار نتیجه.
- 4xx (بهجز 408 و 429) تکرار نمیشود و 401 یا 403 توقف و هشدار دارد.
- ایرادهای معنایی JSON جدا از نحوی تشخیص داده شدهاند.
- کلید ایدمپوتنسی از شناسه کار ساخته شده، نه از زمان یا عدد تصادفی هر تلاش.
- امضای Webhook پیش از هر پردازش و روی بدنه خام بررسی میشود.
- هیچ کلید واقعی یا داده واقعی در تحویلی نیست.