طراحی و توسعه API با TypeSpec

زبان طراحی مختصر API مایکروسافت نام جدیدی دارد و نقش بزرگتری در ساخت REST، OpenAPI، gRPC و سایر خدمات دارد.

مدتی پیش در مورد کاری که مایکروسافت برای بهبود API های Azure انجام می داد نوشتم. آن پروژه مجموعه‌ای از تعاریف API و SDK‌های ایجاد شده به‌طور خودکار را ارائه می‌دهد که پیوند برنامه‌های شما را به ابر و مدیریت سرویس‌های Azure با استفاده از کد آسان‌تر می‌کند.

پشت صحنه زبان جدیدی که مایکروسافت توسعه داده بود به نام CADL وجود داشت، زبان طراحی مختصر API. با تکیه بر مفاهیم TypeScript و Bicep، CADL به شما این امکان را می دهد که API ها را به گونه ای تعریف و توصیف کنید که استفاده از کد برای تعریف عملیات API و سپس کامپایل نتیجه را آسان می کند. به عنوان یک تعریف OpenAPI. همچنین به شما امکان می دهد نرده های محافظ و استانداردهای تعریف رایج را به عنوان کتابخانه تعریف کنید و به معماران و توسعه دهندگان کمک می کند تا در طرح های API همکاری کنند. CADL یک پله در طراحی API بود و قادر بود یک تعریف OpenAPI 500 خطی را تنها در ۵۰ خط کد ایجاد کند.

ابزارهایی مانند CADL برای پشتیبانی از پلتفرم‌های عظیمی مانند Azure کلیدی هستند که APIهای خود را چندین بار در روز کامپایل می‌کنند. آنها به APIهای ثابتی نیاز دارند که کاربران و سرویس ها بتوانند از آنها استفاده کنند. APIهای مدرن یک وابستگی کلیدی برای برنامه های مشتری، ابزارهای توسعه دهنده و موارد دیگر هستند. اطمینان از صحیح بودن تعاریف OpenAPI عمومی برای ارائه پشتیبانی لازم و همچنین اجازه دادن به سرویس میزبان برای استفاده از آزمایش‌های خودکار و تولید اسناد کلیدی است.

این آخرین شرط – مستندات – برای توسعه دهندگان بسیار مهم است. ممکن است زمان لازم برای نوشتن مستندات را نداشته باشید، بنابراین داشتن ابزارهایی که می‌توانند همزمان با ارائه مجموعه‌ای از نقاط پایانی قابل خواندن توسط ماشین، مستندات قابل استفاده تولید کنند، می‌تواند زمان زیادی را برای همه افراد درگیر صرفه‌جویی کند.

از CADL به TypeSpec

در حدود یک سال از آخرین باری که در مورد CADL نوشتم، چیزهای زیادی اتفاق افتاده است. واضح‌ترین تغییر نام جدید TypeSpec است که به میراث آن در زبان‌های تایپ شده قوی و نقش آن در تولید و حفظ مشخصات API اشاره می‌کند. مایکروسافت TypeSpec را بیش از یک زبان توصیف می کند و در عوض آن را “یک پلت فرم” می نامد. “، زیرا زبان و ابزارهای مورد نیاز برای قرار دادن انواع داده های رایج، الگوهای API و دستورالعمل های API را در اجزای قابل استفاده مجدد ترکیب می کند.

TypeSpec در داخل مایکروسافت به طور گسترده مورد استفاده قرار می گیرد، و از خانه اصلی خود در تیم Azure SDK به تیم Microsoft Graph، در میان دیگران، گسترش یافته است. داشتن دو تا از بزرگ‌ترین و مهم‌ترین تیم‌های API مایکروسافت که از TypeSpec استفاده می‌کنند نشانه خوبی برای بقیه ماست، زیرا هم اعتماد به جعبه ابزار را نشان می‌دهد و هم تضمین می‌کند که پروژه منبع باز زیربنایی دارای یک جامعه توسعه فعال است.

مطمئناً، پروژه منبع باز، میزبان شده در GitHub، بسیار فعال است. اخیراً TypeSpec 0.56 را منتشر کرده است و بیش از ۲۰۰۰ commit دریافت کرده است. بیشتر کد در TypeScript نوشته شده و در JavaScript کامپایل شده است، بنابراین در اکثر سیستم های توسعه اجرا می شود.

TypeSpec بین پلتفرم است و در هر جایی که Node.js اجرا شود اجرا خواهد شد. نصب از طریق npm انجام می شود. در حالی که می توانید از هر ویرایشگر برنامه نویسی برای نوشتن کد TypeSpec استفاده کنید، تیم توصیه می کند از Visual Studio Code به عنوان افزونه TypeSpec برای VS Code یک سرور زبان و پشتیبانی از متغیرهای محیطی رایج را فراهم می کند. این برنامه مانند اکثر برنامه‌های افزودنی زبان VS Code عمل می‌کند و ابزارهای تشخیصی، نکات برجسته نحوی و تکمیل کد IntelliSense را در اختیار شما قرار می‌دهد. پروژه‌های مقیاس بزرگ‌تر می‌توانند از یک پسوند مشابه برای ویژوال استودیو استفاده کنند.

زبان TypeSpec زیربنایی قابل توسعه است، بنابراین می توان انواع API جدید را به سرعت اضافه کرد و همچنین از زبان های سریال سازی داده ها پشتیبانی می کند. برنامه های افزودنی به صورت فایل های npm بسته بندی می شوند، بنابراین می توان آنها را با استفاده از ابزارها و پلتفرم های آشنا توزیع و به اشتراک گذاشت.

وب‌سایت TypeSpec شامل یک زمین بازی مفید است که به شما امکان می‌دهد مجموعه‌ای از تعاریف مختلف API را آزمایش کنید. با نمونه‌هایی از جمله REST، HTTP، بافرهای پروتکل و طرح‌واره JSON، می‌توانید به سرعت ببینید که چگونه کد نمونه به یک تعریف API کامپایل می‌شود. . در دسترس بودن تعاریف جایگزین می تواند به مهاجرت از یک نوع API به نوع دیگر کمک کند.

دیدن پشتیبانی از بافرهای پروتکل در TypeSpec خوب است، زیرا از این بافرها برای تعریف فراخوانی های gRPC استفاده می شود که برای ارائه API های میکروسرویس با کارایی بالا اهمیت فزاینده ای دارند. این پشتیبانی همچنین باید به توسعه بین ابری کمک کند، زیرا بافرهای پروتکل برای بسیاری از سرویس‌های پلتفرم Google Cloud استفاده می‌شوند.

شروع به کار با TypeSpec

نصب ساده است، و هنگامی که TypeSpec CLI، tsp دانلود شد، می توانید شروع به ساختن کنید اولین تعریف API این ابزار از یک فرآیند تعاملی برای انتخاب یک الگوی API و مجموعه ای مناسب از کتابخانه ها برای تعریف API مورد نظر شما استفاده می کند، به عنوان مثال openapi3 برای نسخه فعلی OpenAPI.

مرحله بعدی نصب وابستگی ها است. سپس آماده شروع ویرایش کد TypeSpec، کار در فایل main.tsp هستید. اطلاعات خوب زیادی در سایت اسناد رو به رشد وجود دارد، اگرچه بر کار با توضیحات HTTP یا OpenAPI متمرکز است. با این حال، اینها رویکردهای به اندازه کافی عمومی برای تعریف API ها هستند که باید بتوانید از آنها به عنوان راهنما برای سایر قالب های API و SDK استفاده کنید.

می‌توانید از طریق ساختن یک پایه، احساس خوبی در مورد نحوه کار با TypeSpec داشته باشید. REST API، آن را به عنوان توضیحات OpenAPI ارائه می کند. کار با کد TypeSpec بسیار آشنا خواهد بود، زیرا سینتکس اصلی مدیون زبان هایی مانند C# و TypeScript است. برای اولین تعریف API خود، قبل از تعریف سرویس خود، با وارد کردن کتابخانه ها برای HTTP و REST شروع کنید.

بیشتر ساختارها در TypeSpec حول دکوراتورها، توصیفگرهای خاص برای عناصر یک مشخصات API ساخته شده‌اند. این نیاز به شروع در سطح بالا و اضافه کردن جزئیات هنگام پر کردن API خود دارد. این رویکردی است که به خوبی کار می‌کند: شما با چیزهایی که می‌دانید، مانند نام‌های سرویس و نشانی‌های وب نقطه پایانی، شروع می‌کنید و از پارامترهایی برای افزودن پشتیبانی برای APIهایی که برای کار در بیش از یک منطقه طراحی شده‌اند، استفاده می‌کنید.

فضاهای نام عناصر مرتبط مانند نام برنامه ها، مسیرهای مورد استفاده برای دسترسی به منابع خاص و مدل داده زیربنایی را گرد هم می آورند. هنگامی که این جزئیات را به دست آوردید، می توانید شروع به اضافه کردن عملیات HTTP به مسیرهای خود و هر تماس خاصی که باید انجام شود، کنید. گزینه های دیگر به شما امکان می دهند پارامترهایی را به توضیحات اضافه کنید و به شما امکان می دهند ساختارهای پیچیده API را تعریف کنید. این رویکرد به این معنی است که می توانید از تکنیک های مشابه برای GraphQL و سایر خدمات مبتنی بر HTTP استفاده کنید. شما محدود به REST API نیستید.

هنگامی که توضیحات API خود را نوشتید، وقت آن است که آن را در قالب انتخابی خود تحویل دهید. برای REST API، می‌توانید از امیتر OpenAPI نسخه ۳ استفاده کنید و زمانی که کامپایلر TypeSpec را اجرا می‌کنید، آن را فراخوانی کنید. متناوبا، توضیحات شما می تواند به فایل پیکربندی پروژه فعلی شما اضافه شود، جایی که به طور خودکار هنگام اجرای کامپایلر فراخوانی می شود. امیترها یک قطعه کلیدی از TypeSpec هستند، زیرا کد شما را با توضیحات API ترسیم می کنند. مایکروسافت فریم ورک امیتر را ارائه می دهد که می توانید از آن برای سرعت بخشیدن به توسعه امیترهای خود استفاده کنید. . با این حال، ایجاد امیترها یکی از پیچیده ترین بخش های فرآیند باقی می ماند.

توجه داشته باشید که مایکروسافت اسناد جداگانه ای را برای استفاده از TypeSpec با Azure فراهم می کند. مجموعه ای از کتابخانه های عمومی دارد که استانداردهای API Azure را مدون می کند. این هدف در درجه اول کاربران داخلی مایکروسافت است، زیرا نشان می دهد که استفاده از TypeSpec به بررسی کد کمک می کند. آنچه در اینجا شاید بیشتر مفید باشد مجموعه ای از کتابخانه ها است که استانداردهای Azure را کدگذاری می کند، که می تواند برای کمک به شما در کشف بهترین شیوه های TypeSpec برای تعاریف OpenAPI استفاده شود.

ابزارهایی مانند TypeSpec بخش مهمی از زنجیره ابزار توسعه مدرن هستند. معماری‌های سرویس‌گرا به APIهایی با طراحی خوب و مستند نیاز دارند که باید قبل از شروع به نوشتن کد در دو طرف API تعریف شوند. بنابراین خوب است که ابزاری را ببینید که در ابتدا برای آسان‌تر کردن زندگی مهندسان مایکروسافت و انتشار گسترده‌تر ایجاد شده بود. جالب است که ببینیم یک جامعه TypeSpec گسترده‌تر چگونه تکامل می‌یابد، و چه کتابخانه‌ها و انتشارات دیگری را انجمن ایجاد خواهد کرد.