آموزش صفحه داخلی وب‌سرویس
نویسنده: باسینرژی
آخرین بروزرسانی: ۴ شهریور ۱۴۰۵
این صفحه شناسنامه اصلی هر وب‌سرویس است که تمامی اطلاعات فنی آن را به صورت متمرکز مستند می‌کند. در این محیط، برنامه‌نویسان بک‌اند (Back-end) می‌توانند به یک زبان مشترک در مورد نحوه عملکرد، ورودی‌ها و خروجی‌های یک API برسند. برای درک بهتر، امکانات این صفحه در بخش‌های مجزا و کاربردی دسته‌بندی شده‌اند.
۱. اطلاعات پایه و هویتی (سربرگ و توضیحات)
راهنمای مفهومی:
این بخش نمای کلی و شناسنامه وب‌سرویس را ارائه می‌دهد. اعضای تیم با نگاه به این قسمت سریعاً متوجه می‌شوند که این سرویس در چه مرحله‌ای از توسعه قرار دارد، آدرس آن چیست و چه منطق و هدفی را دنبال می‌کند.
راهنمای کاربردی:
در بالاترین قسمت صفحه (سربرگ) و بلافاصله زیر آن، اطلاعات هویتی و وضعیت سرویس قرار دارد:
- • وضعیت توسعه: تگ‌های رنگی (مانند Completed Doc یا Completed Create) در گوشه تصویر قرار دارند که مرحله پیشرفت کار روی این وب‌سرویس را مشخص می‌کنند.
- • مشخصات مسیردهی: شامل «نام سرویس»، «متد درخواست» (مثل GET یا POST با رنگ‌بندی متمایز) و «آدرس سرویس» (URL دقیق) است.
- • نیاز به احراز هویت: یک آیکون «قفل» در کنار نام سرویس وجود دارد که نشان می‌دهد آیا کلاینت برای فراخوانی این سرویس نیاز به لاگین (توکن احراز هویت) دارد یا خیر.
- • خلاصه و توضیحات: فیلدهایی برای ثبت هدف کلی سرویس و شرح دقیق منطق (Logic) آن. در تب توضیحات می‌توان الگوریتم‌ها و شروط بک‌اند را برای تیم مستند کرد.
- • تاریخچه (مشخصات فنی): تگ‌هایی که زمان دقیق ایجاد (مثلاً ۳۴۹ روز پیش) و آخرین به‌روزرسانی (مثلاً ۸۲ روز پیش) را همراه با آیکون کاربر نمایش می‌دهند.
۲. مدیریت ورودی‌ها (Inputs)
راهنمای مفهومی:
این بخش قرارداد بین کلاینت و سرور را برای ارسال داده‌ها تعیین می‌کند. تیم فنی در اینجا مشخص می‌کند که سرور برای اجرای صحیح عملیات خود، دقیقاً به چه اطلاعاتی از سمت کاربر یا نرم‌افزار نیاز دارد و این داده‌ها چگونه باید اعتبارسنجی شوند.
راهنمای کاربردی:
در این قسمت فیلدها و ابزارهای مربوط به ورودی‌های وب‌سرویس مدیریت می‌شوند:
- • سریالایزرها (Serializers): با دکمه آبی رنگ «+ افزودن سریالایزر»، امکان معرفی کلاس‌های اعتبارسنجی (Validator) برای بررسی صحت و فرمت داده‌های ارسالی فراهم می‌شود.
- • پارامترهای الزامی (Required): با دکمه «+ ورودی پارامتر الزامی»، فیلدهایی که ارسال آن‌ها در بدنه درخواست (Body) یا آدرس کاملاً اجباری است و بدون آن‌ها سرویس کار نمی‌کند، ثبت می‌شوند.
- • پارامترهای اختیاری (Optional): محلی برای ثبت فیلدهایی که ارسال آن‌ها دلخواه است و در صورت عدم ارسال، سرویس با خطا مواجه نمی‌شود (با دکمه مشابه برای افزودن ورودی اختیاری).
۳. مدیریت پیام‌ها و خروجی (Outputs)
راهنمای مفهومی:
این بخش استاندارد پاسخ‌دهی سرور را شفاف می‌کند. توسعه‌دهندگان فرانت‌اند با بررسی این قسمت دقیقاً می‌دانند در صورت موفقیت‌آمیز بودن درخواست یا بروز خطا، چه ساختار داده‌ای و چه پیام‌هایی را از سمت سرور دریافت خواهند کرد تا نرم‌افزار بر اساس آن‌ها واکنش نشان دهد.
راهنمای کاربردی:
نحوه پاسخ‌دهی سیستم در دو قالب اصلی مستند می‌شود:
- • لیست پیام‌ها (Messages): فهرستی از تمامی حالت‌های ممکن پاسخ (خطاها یا موفقیت). هر ردیف شامل یک کد اختصاصی، کد وضعیت HTTP (مثل خطای 400 یا موفقیت 200) و متن پیام است. دکمه‌ها و اکشن‌هایی برای افزودن پیام جدید، ویرایش یا حذف پیام‌های قبلی در این بخش تعبیه شده است.
- • نمونه خروجی (Response): یک بلوک برای نمایش ساختار استاندارد پاسخ سیستم به فرمت JSON. این ساختارِ درختی به برنامه‌نویس نشان می‌دهد که کلیدها (Keys) و مقادیر (Values) دریافتی چه نام و فرمتی خواهند داشت.
۴. یکپارچگی
راهنمای مفهومی:
این بخش به رهگیری کاربرد سرویس در کل پروژه و اطمینان از سلامت عملکرد آن کمک می‌کند. مدیران و تسترها از این طریق می‌فهمند خرابی این سرویس دقیقاً کدام صفحات محصول را از کار می‌اندازد و چگونه باید آن را تست کرد.
راهنمای کاربردی:
برای یکپارچه‌سازی و کنترل کیفیت سرویس، دو قابلیت وجود دارد:
- • صفحات مرتبط: با کلیک روی دکمه «+ افزودن صفحه»، می‌توانید تعیین و مستند کنید که این وب‌سرویس دقیقاً در کدام صفحاتِ رابط کاربری (UI) فراخوانی شده است.
- • تست کیس‌ها (Test Cases): محلی برای ثبت سناریوهای تست (شامل ورودی‌های نمونه و خروجی مورد انتظار). با ثبت این موارد، ارزیابی عملکرد سرویس توسط تیم تست (QA) به راحتی انجام می‌شود.
۵. ارتباطات تیمی (گفتگو و جریان‌ها)
راهنمای مفهومی:
همانند سایر صفحات داخلی، این بخش یک محیط ایزوله و اختصاصی برای بحث، دیباگ (رفع باگ) و رهگیری زمان صرف شده روی همین وب‌سرویس است تا تاریخچه تصمیمات فنی با سایر بخش‌های پروژه تداخل پیدا نکند.
راهنمای کاربردی:
در نوار سمت چپِ این صفحه، دو قابلیت کلیدی تعبیه شده است (مشابه آموزش صفحه داخلی):
- • بخش گفتگو (چت): امکان ایجاد تاپیک‌های بحث برای گزارش باگ یا هماهنگی فنی، ریپلای کردن، اختصاص پیام به کاربران خاص و تایید رفع مشکلات (با تیک تایید و هاله سبز رنگ دور پروفایل).
- • بخش جریان‌ها: در نوار پایینی، لیست افرادی که روی این وب‌سرویس کار کرده‌اند به همراه تاریخ و مدت زمانِ صرف شده نمایش داده می‌شود تا هزینه‌های زمانی توسعه این API به دقت رهگیری شود.
