کدهای قدیمی (Legacy codebases) اغلب بر اساس یک کامنت تک‌خطی زنده می‌مانند که نوشته شده است: «در محیط عملیاتی کار می‌کند» (works in prod). این وضعیت باعث می‌شود توسعه‌دهندگان نسبت به آنچه یک API در واقعیت برمی‌گرداند، کاملاً نابینا باشند. MonkeyCode مکانیزمی را فراهم می‌کند تا این حدس و گمان‌ها با یک «قرارداد زنده» جایگزین کند؛ قراردادی که همگام با کد منبع تکامل می‌یابد.
نگهداری از مستندات API نبردی همیشگی علیه «پوسیدگی» است. اکثر توسعه‌دهندگان یک بار مشخصات OpenAPI می‌نویسند و این سند به محض اولین تغییر در کد یا بازنویسی (Refactor) اولین مسیر (Route)، به یک فسیل تبدیل می‌شود. همان‌طور که در تحلیل قبلی ما درباره تأخیر در سرورهای مدل‌های رایگان اشاره کردیم، چالش اصلی این نیست که یک مدل بتواند مستندات بنویسد، بلکه این است که آن مستندات با آنچه در اپلیکیشن در حال اجراست، هم‌راستا بماند و صادق باشد.
تصور کنید وارث یک اپلیکیشن Flask هستید که نه تست دارد و نه مستندات. به‌جای اینکه تک‌تک هندلرهای کد را به‌صورت دستی بخوانید، اکنون می‌توانید فرآیند کشف قابلیت‌های API را کاملاً خودکار کنید. طبق یک راهنمای فنی که در ۳۱ اوت ۲۰۲۶ منتشر شد، این فرآیند از یک خط‌لوله چهارمرحله‌ای شامل استخراج، پیش‌نویس، ذخیره‌سازی و اعتبارسنجی شبانه تشکیل شده است.
خط‌لوله استخراج
در گام نخست، سیستم از ماژول inspect پایتون برای پیمایش نقشه URLهای Flask استفاده می‌کند. این اسکریپت دارایی‌های استاتیک (Static Assets) را نادیده می‌گیرد و کد منبع دقیق هر تابع نمایش (View Function) را ثبت می‌کند. نتیجه این کار، ایجاد فهرستی ساختاریافته از مسیرها، متدهای HTTP و منطق تولید پاسخ است.
برای اجرای این مرحله، اسکریپتی مانند extract_views.py روی app.url_map.iter_rules() پیمایش می‌کند. این ابزار به‌طور خاص قوانینی که با /static شروع می‌شوند را فیلتر می‌کند و متدها را با حذف HEAD و OPTIONS نرمال‌سازی می‌کند تا فقط روی افعال کاربردی HTTP تمرکز کند. خروجی نهایی شامل مسیر Route، متدهای مرتب‌شده و کد خام تابع است.
پیش‌نویس طرح با هوش مصنوعی
پس از استخراج کد، گردش‌کار یک درخواست به مدل MonkeyCode ارسال می‌کند. در اینجا از هوش مصنوعی زاینده (Generative AI) — شبیه به یک نویسنده فنی که کد را می‌خواند و ساختار آن را به زبان استاندارد ترجمه می‌کند — برای تولید یک JSON Schema بر اساس کد منبع استفاده می‌شود. در پرامپت ارسالی، از هوش مصنوعی خواسته می‌شود در نقش یک نویسنده قرارداد API عمل کند. برای اینکه خروجی مدل قطعی (Deterministic) و قابل اعتبارسنجی باشد، مقدار دمای مدل (Temperature) روی صفر تنظیم شده است.
این مرحله از پروژه متن‌باز MonkeyCode بهره می‌برد که در حال حاضر دسترسی رایگان به مدل با سهمیه ۱۰ میلیون توکن (Token) — تکه‌های کوچکی از متن که مدل تکه‌تکه می‌خورد — و یک نمونه سرور رایگان ارائه می‌دهد. برای مدیریت بهینه این منابع و جلوگیری از اتمام سریع سهمیه، می‌توان از راهکارهای ردیابی مصرف در APIهای رایگان استفاده کرد تا تداوم عملیات استخراج تضمین شود. پیاده‌سازی این بخش از اسکریپت contract_draft.py استفاده می‌کند که سه متغیر محیطی MONKEYCODE_API_BASE ،MONKEYCODE_API_KEY و MONKEYCODE_MODEL را به کار می‌گیرد. از مدل خواسته می‌شود خروجی را در قالب JSON خاصی شامل طرح (Schema)، امتیاز اطمینان (بین ۰.۰ تا ۱.۰) و یادداشت‌ها برگرداند. این پیش‌نویس‌ها سپس در پوشه contracts/ ذخیره می‌شوند و نام فایل‌ها برای جایگزینی اسلش‌ها با خط تیره (Underscore) نرمال‌سازی می‌گردد.
اعتبارسنجی شبانه
در مرحله نهایی، یک سرور رایگان به «نگهبان شب» تبدیل می‌شود. یک اسکریپت اعتبارسنج، طرح‌های تولیدشده را بارگذاری کرده و نقاط انتهایی (Endpoints) زنده را فراخوانی می‌کند. با استفاده از کتابخانه jsonschema و استنتاج (Inference) — لحظه‌ای که مدل واقعاً جواب تولید می‌کند — پاسخ‌های واقعی با قراردادهای پیش‌نویس شده مقایسه می‌شوند. این فرآیند از طریق cron زمان‌بندی شده تا هر شب اجرا شود و هرگونه «انحراف» (Drift) را پیش از رسیدن به محیط عملیاتی گزارش کند.
به‌عنوان مثال، اسکریپت validate_contracts.py را می‌توان با یک Cron Job مانند 30 3 * * * cd /opt/contract-watch && python validate_contracts.py >> nightly.log زمان‌بندی کرد. این کار تضمین می‌کند که هر صبح، توسعه‌دهنده گزارشی دریافت کند که کدام نقاط انتهایی قرارداد تولیدشده برای خودشان را نقض کرده‌اند. این یک روش ارزان و تکرارپذیر است تا متوجه شوید چه زمانی یک بازنویسی (Refactor)، ساختار Payload یک API را تغییر داده است، پیش از آنکه تیم فرانت‌اند این شکست را در محیط Production کشف کند.
چارچوب اعتماد
از آنجا که مدل‌های هوش مصنوعی ممکن است دچار توهم (Hallucination) — وقتی مدل با اطمینان چیزی می‌گوید که وجود ندارد — شوند، این سیستم از یک تریاژ مبتنی بر امتیاز اطمینان استفاده می‌کند. امتیاز اطمینان به عنوان یک سیگنال تریاژ عمل می‌کند تا تصمیم گرفته شود توجه گران‌بهای انسانی کجا صرف شود:
- اطمینان ۰.۸ تا ۱.۰: مسیرهای ساده CRUD بدون احراز هویت، به‌طور خودکار به عنوان قرارداد پذیرفته و اضافه می‌شوند.
- اطمینان ۰.۵ تا ۰.۷۹: مسیرهای دارای شرط یا احراز هویت، پیش از ادغام (Merge) نیاز به بررسی انسانی دارند.
- اطمینان زیر ۰.۵: پیش‌نویس مدل کاملاً دور ریخته شده و قرارداد باید به‌صورت دستی نوشته شود.
محدودیت‌های حیاتی
این سیستم یک راهکار جامع (Silver Bullet) نیست و برای APIهای JSON با ساختار پاسخ ساده طراحی شده است. بر اساس بررسی مستندات، این ابزار در موارد زیر شکاف‌های مشخصی دارد:
- انواع داده (Payload Types): ناتوانی در شناسایی داده‌های باینری یا قراردادهای پیام‌های WebSocket.
- شکاف‌های منطقی: ناتوانی در تشخیص تفاوت‌های ظریف در مدیریت خطاها؛ همچنین درخواست‌های نمونه ممکن است شاخه‌های عمیق کد را نادیده بگیرند.
- پاسخ‌های پویا: اعتبارسنج هر بار یک مسیر را بررسی می‌کند؛ اگر یک Endpoint بر اساس پارامترهای کوئری، طرح‌های متفاوتی برگرداند، نیاز به چندین فراخوانی نمونه برای هر مسیر است.
- محیط اجرا: اسکریپت‌ها فرض می‌کنند اپلیکیشن به‌صورت محلی اجرا می‌شود، به این معنی که کاربر باید Seed کردن دیتابیس و هدرهای احراز هویت را به‌صورت دستی مدیریت کند.
برای محیط‌های حساس مانند APIهای پرداخت یا یکپارچه‌سازی‌های حوزه سلامت، این گردش‌کار کافی نیست. اگر یک اشتباه در قرارداد منجر به ضرر مالی یا عدم انطباق قانونی شود، تایید رسمی (Formal Verification) و تست‌های نوشته شده توسط انسان همچنان اجباری است. این ابزار بیشتر برای سرویس‌های داخلی، نمونه‌های اولیه (Prototype) یا تحلیل کدهای قدیمی پیش از بازنویسی مناسب است.
این رویکرد، مستندسازی API را از یک سند ایستا به یک وظیفه در زنجیره یکپارچه‌سازی مداوم (CI) تبدیل می‌کند. با تبدیل قرارداد به یک موجود زنده، تیم‌ها می‌توانند بدون نیاز به بازبینی دستی و خسته‌کننده، ناشناخته‌های سیستم‌های قدیمی خود را کشف کنند.
توسعه‌دهندگان باید اکنون سرویس‌های داخلی خود را برای یافتن «پوسیدگی خاموش» بررسی کنند و تست کنند که آیا پیش‌نویس‌های مدل‌محور می‌توانند تغییرات پنهان در Payloadها را شناسایی کنند یا خیر. تکامل بعدی این مسیر، احتمالاً شامل عامل‌های هوش مصنوعی (AI Agents) خواهد بود که نه‌تنها انحراف را تشخیص می‌دهند، بلکه پیشنهاد اصلاح کد برای هم‌راستاسازی اپلیکیشن با قرارداد مورد نظر را ارائه می‌کنند.
گفتگو