ابزارها و روش‌های مستندسازی میکروسرویس‌ها

من فرض می‌کنم که شما حداقل با مفهوم میکروسرویس‌ها آشنا هستید -- سرویس‌هایی که به‌صورت آزاد مرتبط هستند که راه‌حل‌های مجزایی را برای موارد استفاده تجاری ارائه می‌کنند که می‌توانید برای رفع نیازها و تقاضای فعلی ترکیب کنید. الگوی معماری در سال‌های گذشته محبوبیت پیدا کرده است، و اگرچه همه کاملاً مطمئن نیستند که "انجام درست آن" چگونه به نظر می‌رسد، این مفهومی است که با نیازهای مدرن مطابقت دارد و برای آینده قابل پیش‌بینی اینجاست.

من به سازماندهی گروه Write the Docs (یک جامعه جهانی برای علاقه مندان به اسناد فنی) در برلین کمک می کنم. در طول ماه گذشته، افراد متعددی از من پرسیدند که چه ابزارها و شیوه‌هایی را برای مستندسازی میکروسرویس‌ها و معماری‌های کاربردی که از الگو استفاده می‌کنند، توصیه می‌کنم.

بعداً کمی در گوگل جستجو کردم، دیدم که دیگران همین سؤال را می‌پرسند، اما هیچ توصیه مشخصی نداشتند، بنابراین فکر کردم وقت آن رسیده که ایده‌ها را کنار بگذارم. من قصد دارم این پست مشکل را بیان کند، راه‌حل‌هایی ارائه دهد و بحث را برای کسانی که در این زمینه هستند برانگیزد. اینها صرفاً افکار من هستند، اما با هم می‌توانیم بهترین روش را تعیین کنیم و ایده‌هایی برای ابزار واقعی برای کمک ایجاد کنیم.

تعریف مشکل

هر میکروسرویس در اصل یک برنامه کاربردی "معمولی" است. از بسیاری جهات، می‌توانید بهترین شیوه‌های استاندارد را برای مستندسازی هر یک از آنها دنبال کنید (و اگر در این زمینه به کمک نیاز دارید، پست «یک دوره خرابی مستندات برای توسعه‌دهندگان» را توصیه می‌کنم). به نظر من، منطقه ای که توسعه دهندگان در آن گیر کرده اند، تجسم و مستندسازی نحوه تعامل میکروسرویس ها است.

مستندات موضوع محور

قبل از اینکه به سمت آینده‌اندیشی حرکت کنیم، می‌خواهم همه شما را به یک روش مستندسازی برگردانم که برای مدتی وجود داشته است اما حداقل از نظر مفهومی در اینجا کاربرد بالقوه دارد. مستندات مبتنی بر موضوع، اسناد را به مفاهیم مجزا (موضوعات) تقسیم می‌کند که می‌توانید آن‌ها را مطابق با موارد استفاده از اسناد خاص جمع آوری کنید.

برای مثال یک راهنمای شروع برای توسعه دهندگان ممکن است موضوعات نصب، پیکربندی و در حال اجرا را ترکیب کند. جایی که یک راهنمای شروع برای کاربران ممکن است موضوعات پیکربندی، اجرا و دستورات را ترکیب کند. همانطور که می بینید، آیتم های محتوای گسسته را با هم ترکیب می کند تا مناسب موارد استفاده مختلف باشد. آشنا بنظر رسیدن؟

توجه داشته باشید که ابزار سنتی برای مستندات مبتنی بر موضوع ممکن است کاملاً برای این مورد مناسب نباشد، زیرا اغلب گران، اختصاصی و به خودی خود یکپارچه است. با این حال، ما مطمئناً می توانیم عناصر ایده و ابزار را وام بگیریم.

نمایش تمام نقاط پایانی

در این پست Stack Overflow، پوستر می‌پرسد که چگونه می‌توان تمام نقاط پایانی را در همه سرویس‌ها نمایش داد، بدون توجه به اینکه کدام سرویس‌ها عمومی، فعال هستند و کدام نقاط پایانی در آنها یکسان هستند. با استفاده از رویکردی که در بالا ذکر شد، می‌توانیم صفحه‌ای ایجاد کنیم که تمام سرویس‌های ما را که به‌عنوان فعال و عمومی علامت‌گذاری شده‌اند، جستجو می‌کند و تمام نقاط پایانی در آن یکسان هستند. اگر سرویس یا نقطه پایانی را اضافه یا حذف کنید، صفحه به‌روزرسانی می‌شود تا این موضوع را منعکس کند.

نمایش تقاطع نقاط پایانی

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

توضیح نقطه پایانی

عالی است، اما تاکنون این رویکرد صرفاً در مورد نشان دادن عملکرد نقطه پایانی است. در مورد توضیح مفهومی این که چگونه اینها در یک برنامه کاربردی مبتنی بر میکروسرویس با هم تطابق می یابند، چطور؟ باز هم، در حالت ایده‌آل، این تکه‌های توضیح باید از پارادایم معماری و رویکرد مبحث محوری که ذکر کردم، وام گرفته شده و در زمینه‌های مختلف و متنوع قابل استفاده باشد.

همانند کد خود، باید این توضیحات را به اجزای گسسته و قابل استفاده مجدد تقسیم کنید. به عنوان مثال، اگر کاربری برای مشاهده وضعیت سفارش به برنامه شما برسد، این می تواند شامل چندین سرویس باشد: احراز هویت، سوابق کاربر، فهرست سفارش و وضعیت سفارش.

کاربری که برای بررسی جزئیات حساب وارد می‌شود می‌تواند شامل احراز هویت، سوابق کاربر و یک سرویس حساب باشد. بنابراین، شما باید توضیح مفهومی هر یک از این خدمات را جدا نگه دارید، احتمالاً در مخزن سرویس. در واقع، این احتمالاً همان کاری است که شما در حال انجام آن هستید.

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

ابزار برای خدمات مونتاژ اسناد

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

هیچ ابزار فعلی همه کارها را برای شما انجام نمی دهد، بنابراین من قطعاتی از پازل را ارائه می کنم که احساس می کنم می توانید به خوبی کار کنید و چگونه می توانند کمک کنند. من همچنین تعداد انگشت شماری از جایگزین ها را برای زبان های نشانه گذاری مختلف ارائه خواهم کرد، اما تحقیقات و تحقیقات بیشتر را به شما، بخش نظرات، یا با من در تماس خواهم بود.

از آنجایی که اکثر زبان‌های نشانه‌گذاری و مشخصات API همگی فرمت‌های قابل تجزیه هستند، یک برنامه‌نویس ماهر نیز باید بتواند راه‌حل‌های سفارشی خود را ارائه دهد، اگر چیزی که ارائه می‌دهم کمکی نکند.

شایان ذکر است که برخی از سرویس‌های تجاری یا سیستم‌های CMS مانند وجود دارند که می‌توانند برخی از این فرآیندها را برای شما انجام دهند، اما من احساس می‌کنم این برخلاف ذهنیت میکروسرویس است.

تبدیل

برای فعال کردن ترکیب اسناد در قالب‌های مختلف برای سهولت مدیریت و رندر، ممکن است لازم باشد برای ایجاد یک قالب یکپارچه تبدیل کنید.

Pandoc - یکی از ابزارهای مورد علاقه من. بین طیف گسترده ای از فرمت های نشانه گذاری، اما بدون فرمت های مشخصات API، تبدیل می شود.

Swagger2Markup - Swagger را به AsciiDoc یا Markdown تبدیل می کند.

مبدل مشخصات API - بین Swagger (V1 و 2)، Open API 3، API Blueprint، RAML، WADL و موارد دیگر تبدیل می شود.

apib2swagger - API Blueprint را به Swagger تبدیل می کند.

swagger2blueprint - Swagger را به API Blueprint تبدیل می کند.

ترانسفورماتور Apimatic (آنلاین) - بین طیف گسترده ای از مشخصات از جمله پستچی تبدیل می شود.

apiary2postman - تبدیل API Blueprint به Postman.

Blueman - تبدیل API Blueprint به Postman.

apib2json - تبدیل API Blueprint به JSON.

انتقال

Transclusion اصطلاحی است که من از آن به معنای گنجاندن محتوای یک سند در سند دیگر استفاده می کنم. ممکن است آن را پیوند، گنجاندن، ارجاع متقابل یا چیز دیگری بنامید. اما برای اهداف ما، نحوه گنجاندن انواع منابع اطلاعاتی (مرجع API و پیوند دادن متن توضیحی) در یک سری فایل برای رندر کردن خواهد بود. بسیاری از زبان‌های نشانه‌گذاری به‌طور پیش‌فرض این کار را برای شما انجام می‌دهند، در حالی که برخی دیگر به «تشویق» نیاز دارند.

Markdown به‌طور پیش‌فرض شامل فایل‌های دیگری نمی‌شود، اما شما گزینه‌هایی با هرکول، MultiMarkdown یا، به عنوان بخشی از خط لوله رندر خود، یک تولیدکننده سایت ثابت مانند Jekyll دارید.

Asciidoctor یک زنجیره ابزار پر استفاده برای Asciidoc یکپارچه از جمله منابع دیگر است.

reStructuredText می تواند به طور پیش فرض شامل فایل های خارجی باشد.

اگر می خواهید وارد دنیای موضوع محور شوید، دیتا شامل ارجاع متقابل برای کد و متن می شود. Docbook دارای اشیاء متنی و شامل است.

تفسیر

رندر کردن فایل‌های مونتاژ شده به HTML، PDF، ePub یا فرمت‌های دیگر، رفتار پیش‌فرض هر زبان نشانه‌گذاری مستندات است، بنابراین برای انتخاب گزینه‌ای، هر قالبی را که انتخاب می‌کنید، اسناد را بررسی کنید.

ایجاد سرویس(های)

من نمی توانم دیکته کنم که سرویس(های) اسناد شما به چه چیزی نیاز دارند، اما باید بتوان از کانتینرها برای مدیریت وابستگی های خود و سپس مجموعه ای از اسکریپت ها برای بررسی، جمع آوری، ارائه و ارائه اسناد استفاده کرد. اگر سرویس(ها) را پارامتری کنید تا اسناد متفاوتی را بر اساس آنچه تغذیه می کنید ایجاد کنید، امتیاز اضافی می دهید. به عنوان مثال، برای گنجاندن API ها یا قطعه های جداگانه بر اساس نیاز یا موارد استفاده تغییر دهید.

مراحل بعدی

بسیار خوب، اعتراف می کنم، در این مقاله دقیقاً به شما نگفته ام که چه کاری انجام دهید. در عوض، من یک سری ایده‌ها و منابع بالقوه را برای برانگیختن بحث ارائه کردم، و احتمالاً شما عاقل‌تر از زمانی که شروع به خواندن کردید نیستید.

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