وقتی تعداد سرویس های یک سازمان زیاد می شود، پیدا کردن پاسخ چند پرسش ساده دشوار می شود. مالک این API چه تیمی است؟ مخزن کد آن کجاست؟ مستندات معتبرش کدام است؟ اگر نیمه شب خطا بدهد با چه کسی باید تماس گرفت؟ Backstage Software Catalog برای گردآوری و نمایش اطلاعات نرم افزار و رابطه میان اجزای آن ساخته شده است. ارزش کاتالوگ فقط در داشتن یک فهرست زیبا نیست. کیفیت آن به این وابسته است که هر رکورد از کجا آمده، چه کسی مسئول اصلاح آن است و چگونه با تغییر واقعی نرم افزار به روز می شود.
Entity یک رکورد دارای هویت است
در کاتالوگ Backstage، Entity نماینده یک جزء قابل توصیف است. Component، API، Resource، System، Domain، User و Group از انواع شناخته شده این مدل هستند. هر نوع برای بیان جنبه متفاوتی از منظومه نرم افزار به کار می رود. یک سرویس اجرایی می تواند Component باشد، رابطی که عرضه می کند API باشد و پایگاه داده وابسته به آن Resource باشد. قراردادن همه چیز زیر یک نوع عمومی، نمایش اولیه را ساده می کند اما رابطه ها و جست وجوی بعدی را ضعیف می سازد.
هویت Entity از بخش هایی مانند kind، namespace و name ساخته می شود. این هویت با عنوان نمایشی یکی نیست. نام فنی باید در ارجاع ها پایدار بماند و قواعد نام گذاری باید از ابتدا مشخص باشد. اگر دو تیم برای یک سرویس دو نام متفاوت بسازند، کاتالوگ ممکن است دو موجودیت ظاهراً مستقل نشان دهد. بنابراین پیش از ورود انبوه اطلاعات، توافق بر سر هویت و مرز هر موجودیت از انتخاب رنگ و چیدمان صفحه مهم تر است.
فایل توصیف کنار کد چه مزیتی دارد؟
یکی از روش های متداول، نگه داشتن فایل توصیف Entity در مخزن کد است. این کار اطلاعات مالکیت و مستندات را به همان جریان بازبینی تغییرات نزدیک می کند. وقتی تیم مالک سرویس عوض می شود، اصلاح فایل می تواند بخشی از همان تغییر سازمانی باشد. تاریخچه Git نیز نشان می دهد چه کسی و در چه زمانی مقدار را تغییر داده است. این روش به تنهایی تضمین نمی کند داده درست باشد، اما مسئولیت اصلاح را قابل مشاهده تر می کند.
در مقابل، اگر فایل فقط یک بار هنگام راه اندازی نوشته شود و هیچ فرآیندی آن را بررسی نکند، به سرعت قدیمی می شود. بهتر است حداقل فیلدهای ضروری محدود و معنادار باشند. مجبور کردن تیم ها به پر کردن ده ها فیلد نامطمئن ممکن است حجم زیادی داده ظاهراً کامل اما غیرقابل اعتماد تولید کند. مالک، نوع جزء، چرخه عمر و پیوندهای اصلی نقطه شروع مناسبی هستند؛ جزئیات بیشتر باید بر اساس مصرف واقعی اضافه شوند.
Owner به معنی مسئولیت عملیاتی روشن
فیلد owner باید به تیم یا گروهی اشاره کند که مسئولیت آن جزء را می پذیرد. مالکیت صرفاً نام نویسنده اولیه کد نیست. یک سرویس ممکن است سال ها بعد توسط تیم دیگری نگهداری شود. همچنین مالک Component با مالک همه منابع زیرساختی وابسته به آن الزاماً یکسان نیست. باید روشن شود چه کسی پاسخگوی رفتار محصول است و چه کسی زیرساخت مشترک را اداره می کند.
برای یک سامانه پرداخت، گروه مالک ممکن است تیم پرداخت باشد، در حالی که پایگاه داده توسط تیم پلتفرم مدیریت شود. نمایش این دو رابطه به تشخیص سریع مسیر رسیدگی کمک می کند. اگر owner به یک حساب شخصی اشاره کند که سازمان را ترک کرده، کاتالوگ در زمان نیاز واقعی شکست می خورد. همگام سازی گروه ها با منبع هویت سازمانی و بررسی موجود بودن مالک، بخشی از کیفیت داده کاتالوگ است.
Component، System و Domain مرزهای متفاوت
Component معمولاً یک واحد نرم افزاری قابل شناسایی است. System مجموعه ای از اجزای مرتبط را با هدفی مشترک گرد هم می آورد. Domain نیز می تواند مرز وسیع تری از مسئولیت یا حوزه کسب و کار را نشان دهد. این لایه ها باید برای کاربر کاتالوگ مفید باشند. اگر هر Component یک System مستقل و هر System یک Domain مستقل داشته باشد، ساختار ممکن است فقط نام های تکراری تولید کند.
یک مثال عملی، حوزه تجارت با سیستم سفارش و چند جزء شامل API سفارش، پردازشگر رویداد و رابط مدیریت است. این تقسیم به تیم تازه وارد کمک می کند از تصویر کلی به جزء مورد نیاز برسد. با این حال کاتالوگ قرار نیست تمام نمودار سازمانی را عیناً بازسازی کند. ساختار خوب باید به پرسش های فنی روزمره پاسخ دهد و با تغییرات معمول سازمانی بیش از حد شکننده نباشد.
API و وابستگی های قابل فهم
ثبت API به شکل Entity مستقل باعث می شود رابط مصرفی از پیاده سازی فعلی جدا دیده شود. چند Component ممکن است یک API را مصرف کنند یا عرضه کنند. این رابطه ها برای تحلیل اثر تغییر مفید هستند. پیش از حذف یک نسخه رابط، تیم می تواند مصرف کننده های ثبت شده را پیدا کند. البته این فهرست فقط به اندازه داده ورودی کامل است و نباید بدون بررسی ترافیک واقعی، اثبات نبود مصرف کننده تلقی شود.
پیوند به تعریف OpenAPI یا قالب های دیگر باید به منبع معتبر و قابل دسترس اشاره کند. اگر مستندات کپی شده و جدا از کد اصلی باشند، تفاوت میان قرارداد مستند و رفتار واقعی ایجاد می شود. بهتر است تولید یا به روز رسانی تعریف رابط در چرخه انتشار دیده شود. کاتالوگ در این حالت درگاه دسترسی به قرارداد است و جریان مهندسی تیم مسئول درست نگه داشتن آن قرارداد باقی می ماند.
ورود داده، پردازش و Stitching
چرخه عمر Entity در Backstage چند مرحله دارد. داده می تواند از Location یا Entity Provider وارد شود، توسط پردازشگرها بررسی و تبدیل شود و در مرحله های بعد رابطه ها و نمای نهایی آن ساخته شود. این مسیر توضیح می دهد چرا تغییر یک فایل الزاماً در همان لحظه در صفحه نهایی دیده نمی شود. زمان پردازش، خطای منبع و خطای تبدیل هر کدام می توانند بر تازگی اطلاعات اثر بگذارند.
برای عیب یابی باید ابتدا معلوم شود رکورد اصلاً از منبع خوانده شده یا نه. سپس می توان اعتبار ساختار، نتیجه پردازش و رابطه های نهایی را بررسی کرد. ویرایش دستی داده مشتق شده معمولاً درمان پایدار نیست، زیرا اجرای بعدی پردازش ممکن است آن را دوباره از منبع بسازد. محل اصلاح باید همان منبعی باشد که مالکیت داده را بر عهده دارد. این اصل جلوی چرخه اصلاح موقت و بازگشت خطا را می گیرد.
Annotationها قرارداد میان کاتالوگ و افزونه ها هستند
Annotationها اغلب اطلاعات لازم برای اتصال Entity به ابزارهای دیگر را نگه می دارند. شناسه پروژه در یک سامانه CI، محل مستندات یا ارجاع به ابزار پایش نمونه هایی از این کاربرد هستند. این فیلدها نباید به انبار بی قاعده هر داده ممکن تبدیل شوند. نام و معنای annotation باید با افزونه مصرف کننده هماهنگ باشد و مقدار نامعتبر باید به شکلی قابل فهم گزارش شود.
وجود یک پیوند در کاتالوگ به معنی مجاز بودن دسترسی به مقصد نیست. ابزار مقصد باید همچنان احراز هویت و مجوز خودش را اعمال کند. همچنین نباید کلید API یا رمز در فایل عمومی توصیف Entity قرار گیرد. برای اتصال backend به سرویس خارجی، سازوکار پیکربندی و مدیریت راز مناسب لازم است. اطلاعات توصیفی کاتالوگ باید از اعتبارنامه عملیاتی جدا بماند، حتی اگر هر دو برای ساخت یک صفحه استفاده شوند.
منبع حقیقت برای هر فیلد را تعیین کنید
در سازمان بزرگ ممکن است نام تیم از سامانه هویت، مخزن از پلتفرم کد و وضعیت استقرار از Kubernetes بیاید. اگر چند منبع یک فیلد را تغییر دهند، باید قاعده تقدم مشخص باشد. در غیر این صورت هر همگام سازی می تواند مقدار دیگری را بازنویسی کند. نتیجه برای کاربر شبیه ناپایداری تصادفی است، در حالی که علت واقعی تعارض مالکیت داده است.
یک قرارداد ساده می تواند برای هر فیلد نام منبع، مسئول اصلاح و زمان مورد انتظار همگام سازی را ثبت کند. این قرارداد لازم نیست پیچیده باشد. برای مثال owner از فایل مخزن می آید، عضویت گروه از سامانه هویت می آید و آخرین استقرار از ابزار انتشار خوانده می شود. چنین تفکیکی به تیم پشتیبانی کمک می کند مشکل را به محل درست ارجاع دهد و از دستکاری اطلاعات در چند پنل جلوگیری کند.
حذف منبع و مسئله Entity رهاشده
حذف فایل یا قطع Provider می تواند موجودیت هایی ایجاد کند که دیگر منبع معتبر ندارند. رفتار دقیق پاکسازی و موجودیت های orphan باید با پیکربندی Backstage بررسی شود. حذف خودکار فوری همیشه انتخاب مناسبی نیست، زیرا قطع موقت منبع می تواند با حذف واقعی اشتباه شود. نگهداری نامحدود نیز کاتالوگ را پر از سرویس های بازنشسته و لینک های خراب می کند.
برای چرخه خروج، می توان ابتدا وضعیت بازنشستگی را ثبت کرد، وابستگی ها را بررسی کرد و سپس پس از مدت مشخص رکورد را حذف کرد. اگر سرویس هنوز مصرف کننده دارد، حذف نام آن از کاتالوگ آن وابستگی را از بین نمی برد. یک گزارش دوره ای از منابع ناموجود، مالکان نامعتبر و پیوندهای خراب می تواند کیفیت را حفظ کند. ارزش این گزارش زمانی است که هر مورد مسئول رسیدگی و موعد مشخص داشته باشد.
جست وجو باید از کیفیت داده تغذیه کند
کاربر معمولاً نام دقیق Entity را نمی داند. ممکن است با نام محصول، تیم یا قابلیت جست وجو کند. توضیح کوتاه و برچسب های معنادار در اینجا مفید هستند. با این حال برچسب گذاری افراطی با واژه های عمومی، دقت جست وجو را پایین می آورد. توضیح «سرویس مدیریت وضعیت پرداخت سفارش» از جمله کلی «یک سرویس مهم سازمان» قابل استفاده تر است.
برای ارزیابی، چند وظیفه واقعی به فردی خارج از تیم بدهید. از او بخواهید مالک یک API، مستندات راه اندازی و داشبورد عملیاتی آن را پیدا کند. زمان و نقاط سردرگمی را ثبت کنید. این آزمایش نشان می دهد کدام داده واقعاً به کار می آید. تعداد Entityهای ثبت شده به تنهایی معیار موفقیت نیست. کاتالوگی کوچک که پاسخ درست می دهد از فهرستی بزرگ با مالکیت مبهم ارزش بیشتری دارد.
دسترسی به کاتالوگ و اطلاعات داخلی
کاتالوگ می تواند نقشه دقیقی از سامانه های داخلی، وابستگی ها و ابزارهای عملیاتی بسازد. بنابراین سطح دسترسی به آن باید متناسب با حساسیت اطلاعات باشد. افزونه های مختلف ممکن است داده های متفاوتی نمایش دهند و کنترل دسترسی باید در مسیر backend نیز بررسی شود. پنهان کردن یک کارت در رابط کاربری مانع دریافت داده از API همان افزونه نمی شود.
در طراحی چند تیمی، باید روشن شود چه کسانی می توانند Entity ثبت کنند، منبع اضافه کنند یا مقادیر حساس را تغییر دهند. ورودی از مخزن نیز باید به عنوان داده پردازش شود و اعتبار آن بررسی شود. دامنه منابع مجاز و رفتار افزونه ها بخشی از سطح اعتماد سامانه هستند. این کنترل ها به معنی سخت کردن بی دلیل کار توسعه دهنده نیستند؛ هدف آن ها حفظ اعتبار همان فهرستی است که همه به آن تکیه می کنند.
راه اندازی مرحله ای و معیار پذیرش
شروع با یک سیستم واقعی و چند تیم معمولاً اطلاعات بیشتری از وارد کردن همزمان همه مخازن می دهد. برای همان محدوده، owner معتبر، APIهای اصلی، مستندات و مسیر رسیدگی به خطا را کامل کنید. سپس تغییر مالک، حذف مخزن و خرابی منبع را آزمایش کنید تا رفتار کاتالوگ در شرایط غیرعادی روشن شود. هرجا داده قدیمی می ماند، علت و مسئول آن را مشخص کنید.
معیار پذیرش می تواند این باشد که یک توسعه دهنده تازه وارد بتواند بدون پرسیدن در چند گروه پیام رسان، جزء مورد نیاز و تیم مسئول آن را پیدا کند. Backstage در این صورت حافظه مشترک قابل نگهداری سازمان می شود. این نتیجه از ترکیب مدل روشن، منابع معتبر و مسئولیت اصلاح به دست می آید؛ نصب پورتال فقط آغاز مسیر است.
