ساخت و تست API با هوش مصنوعی: از طراحی تا مستندات
نوشتن خود اندپوینت معمولاً کوتاهترین بخش کار است. وقت واقعی صرف اعتبارسنجی، ساختار خطا، تست و مستندات میشود — و دقیقاً همانجا کمک گرفتن میارزد.
نوشتن یک اندپوینت که داده را از دیتابیس بردارد و برگرداند، معمولاً بیست دقیقه است. چیزی که روز را میخورد جای دیگری است: اعتبارسنجی ورودی، تصمیمگیری دربارهی شکل خطاها، نوشتن تست برای حالتهایی که فکرشان را نکرده بودید، و مستنداتی که تیم موبایل بتواند از آن کار را شروع کند.
اینها دقیقاً همان کارهایی هستند که حوصلهبَرند و در عین حال الگومند. یعنی همانجایی که کمک گرفتن از یک ابزار هوشمند بیشترین بازده را دارد.
در ادامه مسیر کامل یک اندپوینت را میبینید، با تأکید بر جاهایی که خروجی خودکار قابل اعتماد است و جاهایی که نیست.
اول قرارداد، بعد کد
اشتباه رایج این است که مستقیم سراغ نوشتن هندلر میروند. اگر پیش از کد، قرارداد را بنویسید — یعنی مسیر، ورودی، خروجی و کدهای وضعیت — بقیهی کار خودش را میسازد.
برای این مرحله، توصیف را دقیق بدهید و بخواهید خروجی به شکل مشخصات OpenAPI باشد:
یک اندپوینت برای ثبت سفارش طراحی کن.
ورودی: شناسهی کاربر، فهرست اقلام (شناسه و تعداد)، کد تخفیف اختیاری.
خروجی موفق: شناسهی سفارش، مبلغ نهایی، وضعیت.
حالتهای خطا را هم مشخص کن: موجودی ناکافی، کد تخفیف نامعتبر،
کاربر مسدود.
خروجی را بهصورت OpenAPI 3 بده. توضیح فارسی برای هر فیلد بنویس.
جایی که فرض گذاشتی، زیر جدول بنویس چه فرضی کردی.آن خط آخر ارزشمندترین بخش است. فرضهایی که مدل میگذارد معمولاً همانهایی هستند که خودتان هم نامشخص رهایشان کرده بودید.
تولید کد اولیه و جایی که خطا میکند
برای اسکلت کار — مسیرها، مدلها، لایهی سرویس — خروجی معمولاً تمیز است. مشکل جای دیگری است: منطق کسبوکار خاص شما. مدل نمیداند که در سیستم شما تخفیف روی هزینهی ارسال اعمال نمیشود، و با اطمینان کامل کدی مینویسد که میکند.
دو خطای دیگر هم زیاد دیده میشوند: استفاده از نسخهی قدیمی یک کتابخانه، و ساختن نام بستهای که اصلاً وجود ندارد. هر دو در نگاه اول طبیعی بهنظر میرسند. توصیههای بیشتر دربارهی کار با کد تولیدشده در راهنمای برنامهنویسی آمده است.
کلید API، توکن، رشتهی اتصال دیتابیس و دادهی واقعی مشتری هیچوقت نباید در متن درخواست باشد. برای فهماندن ساختار، دادهی نمونه بسازید. این یک قاعدهی سختگیرانه نیست؛ شایعترین راه نشت اطلاعات در تیمهای کوچک همین است.
اعتبارسنجی و ساختار خطا
اینجا یکی از بهترین کاربردهاست. فهرستکردن همهی حالتهایی که یک ورودی میتواند خراب باشد، کار خستهکنندهای است که مدلها خوب انجامش میدهند.
یک نکتهی طراحی هم بگویید: بخواهید ساختار خطا در کل API یکسان باشد. تیمهای زیادی هستند که هر اندپوینتشان شکل متفاوتی از خطا برمیگرداند و کلاینت مجبور است برای هرکدام جدا کد بنویسد.
| مرحله | کیفیت خروجی خودکار | چه چیزی را خودتان بررسی کنید |
|---|---|---|
| طراحی قرارداد | خوب | فرضهایی که گذاشته |
| اسکلت کد | خوب | نسخهی کتابخانهها |
| منطق کسبوکار | ضعیف | همهچیز |
| اعتبارسنجی ورودی | خیلی خوب | قواعد خاص دامنه |
| تست حالت مرزی | خیلی خوب | کدامها واقعاً لازماند |
| مجوز و دسترسی | ضعیف | حتماً دستی مرور شود |
| مستندات | خوب | همخوانی با کد نهایی |
تست: بیشترین بازده همینجاست
اگر قرار است فقط یک بخش را بسپارید، تست را بسپارید. توصیف اندپوینت را بدهید و بخواهید فهرست حالتهای مرزی را بسازد — نه خود تست را، فقط فهرست را.
معمولاً چیزهایی میآورد که از قلم انداختهاید: آرایهی خالی، مقدار تکراری در فهرست اقلام، عدد اعشاری جایی که انتظار صحیح دارید، و درخواست همزمان روی یک منبع. بعد خودتان تصمیم بگیرید کدامها ارزش تستنوشتن دارند. دیدگاه کاملتر در راهنمای تست نرمافزار آمده است.
امنیت: جایی که نباید تکیه کنید
مدلها الگوهای امنیتی عمومی را میشناسند — تزریق SQL، خروجی فیلترنشده، رمز ذخیرهشده بهصورت متن ساده. ولی منطق مجوزدهی شما را نمیشناسند.
خطرناکترین حفرهی رایج در APIها همین است: اندپوینتی که شناسه میگیرد و بدون بررسی مالکیت، داده را برمیگرداند. کد از نظر ساختاری بیعیب است و مدل هم ایرادی نمیگیرد. ملاحظات کلیتر را در امنیت اطلاعات در کار با هوش مصنوعی جمع کردهایم.
مستندات که واقعاً خوانده شود
مستند خوب سه چیز دارد که مستند بد ندارد: یک نمونهی کامل درخواست، یک نمونهی کامل پاسخ، و توضیح اینکه در هر خطا مصرفکننده باید چه کار کند.
از روی فایل قرارداد، تولید این سه چیز سریع است. اگر میخواهید ساختار درستتری برای کل مستندات فنی داشته باشید، راهنمای نوشتن مستندات فنی را ببینید. مشخصات رسمی قالب هم در سایت OpenAPI در دسترس است.
دیباگ پاسخهای عجیب
وقتی یک درخواست جواب غیرمنتظره میدهد، بهجای توضیحدادن مسئله، متن دقیق درخواست و پاسخ را بگذارید و بگویید ترتیب علتهای محتمل را از محتملترین بنویسد. همین ترتیببندی، وقت جستوجو را کوتاه میکند. برای کدهای قدیمی که باید به ساختار تازه منتقل شوند هم راهنمای مهاجرت کد نکتههای عملی دارد. آزمایش سریع پرامپتها را میتوانید در نارنگی انجام دهید.
جمعبندی
الگوی مؤثری که در تیمها دیده میشود این است: قرارداد و تست و مستندات را بسپارید، منطق و مجوزدهی را خودتان بنویسید. این تقسیمبندی هم سرعت میدهد و هم جلوی خطاهای پرهزینه را میگیرد.
و یک عادت ساده که بیشترین اثر را دارد: هر بار که کدی تولید شد، قبل از اجرا از خودتان بپرسید «اگر این را یک کارآموز نوشته بود، کجایش را چک میکردم؟» — و همانجا را چک کنید.
برای ادامه، این مقالهها را ببینید:
