قالب مستند معماری نرم‌افزار

نسخه 2.2

تاریخ آخرین بازبینی: 99/09/02

سند زیر شامل بخشی از قالب پیشنهادی سند معماری نرم‌افزار است. هرچند همین بخش هم قابل استفاده و مفید است، جهت دریافت نسخه کامل و جدید قالب سند معماری نرم‌افزار، لطفاً با checkup@asta.ir تماس بگیرید.

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

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

سرفصل‌های مستند معماری در ادامه آمده است.

عنوان سامانه: ؟؟؟

سند معماری (SAD)

نسخه سند: ؟؟؟

تاریخ آخرین بازبینی: ؟؟؟

1. مقدمه

محدوده

توصیفی کوتاه از محدوده (scope) کاربرد سامانه موردنظر

فهرست تعاریف، اختصارات و واژه‌نامه

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

اهداف معماری

اهداف کلان معماری به شکل کوتاه (معمولا در حد یک پاراگراف) ذکر شود. 

محدودیت‌ها و استانداردها

(Constraints, Standards, Background)

محدودیت‌ها، استانداردها و بایدهایی که در طراحی معماری به آن‌ها توجه شده است، ذکر شوند. همچنین پیش‌زمینه‌ای (Background) که در کسب‌وکار (Business)، تیم توسعه (مثلاً تجربه‌های مشابه یا تخصص‌های موجود) و یا تصمیمات معماری از قبل وجود داشته است، ذکر شود. 

مراجع

اگر ارجاع به مستند یا مرجع دیگری لازم است، در این بخش ذکر شود.

2. نمای موارد کاربرد

← نمای موارد کاربرد

3. ویژگی‌های کیفی

در این بخش، ویژگی‌های غیرکارکردی (Nonfunctional) یا به عبارت دیگر ویژگی‌های کیفی (Quality Attributes) مورد نیاز در سامانه نرم‌افزاری موردنظر ذکر شود. به عنوان مثال امنیت، کارایی، مقیاس‌پذیری و ...

یکی از اهداف این فصل آن است که کارفرما یا بهره‌‌بردار مطمئن شود به همه نیازمندی‌های کیفی (غیرکارکردی) موردنظر وی در معماری سامانه نرم‌افزاری توجه شده است و راهکارهای لازم برای رسیدن به این نیازمندی‌ها در معماری نرم‌افزار پیش‌بینی و تبیین شده است.

این بخش به شکل یک جدول، مشابه جدول زیر بیان شود. مقادیر ستون «اندازه/محدوده مطلوب» به عنوان نمونه ذکر شده است. سطرهای لازم مطابق با نیازمندی‌های پروژه به این جدول اضافه شود. همان‌طور که در مثالهای موجود در این جدول مشهود است، برای هر ویژگی کیفی (مثلاً کارایی) معمولاً چند معیار ارزيابی ذکر می‌شود (مثلاً TPS و سرعت) و برای هر معیار ارزيابی اندازه یا بازه مطلوب نیز ذکر می‌شود.

توجه: در این بخش به ویژگی‌های پایه مانند کارایی، دسترس‌پذیری، مقیاس‌پذیری، آزمون‌پذیری، تغییرپذیری (قابلیت نگهداری و گسترش) و تعامل‌پذیری توجه ویژه شود و حتماً این موارد در جدول مربوطه ذکر شود.

ستون‌های اصلی این جدول عبارتند از:

• ویژگی کیفی موردنظر
• معیارهای ارزيابی
  • تعیین معیارهای مشخص (measurements یا metrics) برای ارزيابی وضعیت «ویژگی‌های کیفی» موردنظر. در این بخش، روش‌هایی برای محاسبه عددی مقدار ویژگی‎های کیفی مشخص می‎شود. به عبارت دیگر، ویژگی‌های کیفی، کمّی (quantify) می‌شوند. به عنوان مثال، برای ویژگی کیفی «کارایی» معیارهایی مثل TPS یا میانگین سرعت پاسخ به کاربر یا ... بیان می‌شود.
• تعیین مقدار یا محدوده مطلوب معیارهای ارزيابی
  • در این بخش، بازه‌ی مطلوب برای مقدار معیارهای مختلفِ ارزيابی بیان می‌شود. مثلا: برای مقدار TPS، حداقل به 100 تراکنش در ثانیه برسیم. یا حداکثر زمان پاسخ به هر کاربر 5 ثانیه باشد. یا حداقل به 100 کاربر هم‌زمان سرویس داده شود.

4. نمای منطقی

در این بخش، طراحی منطقی معماری توصیف می‌شود.

اجزای اصلی معماری

اجزای اصلی معماری شامل مولفه‌ها، زیرسیستم‌ها و سرویس‌ها توصیف می‌شوند. مهمترین کارکرد این بخش، توصیف نحوه تقسیم (شکست) این نرم‌افزار به اجزای اصلی آن است. وجود یک نمودار کلی شامل یک نمای مفهومی سطح بالا (conceptual view) در این بخش حیاتی است. بهتر است این بخش، متن کمتری داشته باشد و شامل یک یا چند نمودار گویا (حداقل یک نمودار و حداکثر پنج نمودار) باشد. به خصوص یک نمودار سطح بالا که اجزای اصلی (مؤلفه‌های کلان) معماری را نشان می‌دهد و حتی می‌تواند در قالب نمودارهای غیررسمی بیان شود (مثلاً برای هر جزء اصلی معماری یک مستطیل بکشید و ارتباطات بین اجزا را مشخص کنید).

اگر در معماری، به رویکرد Domain Driven Design توجه داشته‌اید، Bounded Context ها را در این بخش توصیف کنید.

در صورت نیاز فرایند و توالی تعاملات بین مؤلفه‌های مختلف هم در قالب نمودارهایی مثل sequence diagram ذکر شود که در آن‌ها نحوه‌ محقق شدن موارد کاربرد توسط زیرسیستم‌های اصلی نمایش داده می‌شود. اما همان‌طور که قبلاً ذکر شد، قبل از این نمودارهای توالی، ذکر یک نمودار ساده سطح بالا از مؤلفه‌های کلان سیستم ضروری است. به عبارت دیگر، حضور یک high-level conceptual view کمک می‌کند تقسیم‌بندی «ساختار» معماری نشان داده شود. همچنین حضور نمودارهای توالی (sequence-diagrams) برای برخی از موارد کاربرد اصلی سیستم، می‌تواند رفتار و  دینامیک ارتباطات اجزای معماری را نشان دهد.

برخی از سوالاتی که در این بخش پاسخ داده می‌شوند:

• معماری کلان این سامانه، چه اجزا و مولفه‌هایی (Element/Component) دارد؟
• ارتباطات و تعاملات بین مولفه‌های مختلف چگونه است؟
• برای برخی موارد کاربرد اصلی، گامها و فرایند محقق شدن مورد کاربرد توصیف شود و تأثیر و نقش هر گام در هر مؤلفه اصلی معماری، ذکر شود.   

توجه شود که این بخش در سطح معماری بیان شود و در سطح پیاده‌سازی توصیف نشود (جزییات کلاس‌ها و فرم‌ها و ... بیان نشود بلکه کلیات طرح کلان معماری بیان شود).

5. نمای استقرار (Deployment یا Physical)

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

جدول استقرار

از دید سخت‌افزاری، فیزیکی و محیط بهره‌برداری (مثلا دیتاسنتر)، فهرست سرورها و محیط‌های اجرایی (مانند ماشین‌های مجازی و فایروال‌ها و ...) مشخص شوند.

نکته: جزییاتی مثل IP سرورها در این مستند جای نگیرند.

ستون‌های جدول نمای استقرار:

• اسم ماشین: شناسه ماشین
• محل استقرار ماشین: نام دیتاسنتر
• توضیح کارکرد: شرح کوتاه مسئولیت این سرور در سیستم موردنظر. نوع سرور از قبیل Active/Passive یا Hot/Cold Spare بیان شود.
• نوع ماشین: ماشین مجازی یا سرور فیزیکی
• تعداد ماشین: تعداد ماشین‌های مورداستفاده از این جنس در سامانه موردنظر
• منابع مورداستفاده/موردنیاز ماشین: پردازنده (CPU)، حافظه اصلی (RAM) و حافظه جانبی به ازای هر ماشین

توجه: مجموع کل منابع مورداستفاده (تعداد سرورها و مجموع حافظه و پردازنده‌ها) هم حتماً در آخرین سطر این جدول ذکر شود.

زیرساخت و مجازی‌سازی

در این بخش، به این موضوعات اشاره شود:

• در صورت استفاده از مجازی‌سازی، زیرساخت مجازی‌‌سازی (مثل ESXi و ...) معرفی شود.
• در صورت استفاده از Containerها، زیرساخت مدیریت container ها (مثل Docker و Kubernetes) توصیف شود.
• در صورت استفاده از Container Orchestration، روش کار کلاستر توصیف شود، مثلاً ساختار ماشین‌های Master و Worker در Kubernetes توصیف شوند. 

فرایند کلان نصب

• «فرایند نصب» به صورت کلی توصیف شود: چگونه و با چه روال و ابزارهایی، نرم‌افزار در محیط عملیاتی نصب و بروزرسانی می‌شود؟

6. نمای پردازه (Process)

این بخش شامل جدول پردازه‌ها  و همچنین جدول ارتباطات بین پردازه‌ها است. هر پردازه، یک واحد اجرایی (Executable) است، مثلاً یک برنامه یا نخ (thread) اجرایی. 

• نگاشت پردازه‌ها روی سرورها هم مشخص می‌شود: هر پردازه روی چه سروری اجرا می‌شود (نگاشت پردازه‌ها روی نمای استقرار در همان جدول اول نمایش داده می‌شود)
• ویژگی‌های ارتباطات بین پردازه‌ها ذکر شود: مثل پروتکل ارتباطی و ...

منظور از پردازه، برنامه‌های اجرایی است که در نهایت در سرورها یا محیط بهره‌برداری، به اجرا درخواهند آمد. مثال: برنامه tomcat، برنامه دیتابیس اوراکل، برنامه مانیتورینگ abc، عامل (agent) نصب و به‌روزرسانی xyz. ذکر همه پردازه‌های در حال اجرا روی سرورها مهم است.

نکته: در صورتی که معماری شما مبتنی بر Docker است، به جای پردازه‌ها بهتر است Dockerها را توصیف کنید. در این صورت برای معرفی هر Dcoker ، توضیح کوتاهی درباره کارکرد هر Docker بدهید و مشخصاتی مثل Port و Volume‌ و محدودیت پردازنده و حافظه و اطلاعات مهم موجود در Dockerfile ها را ذکر نمایید.

رفع سوءتفاهم: منظور از پردازه، فرایندها (business process) یا گردش‌کارهای سازمانی (workflow) نیست. بلکه درباره برنامه‌ها و حتی گاهی بندهای اجرایی است (processes and threads). یعنی آن‌چه بر روی سیستم‌عامل سرورها اجرا خواهد شد.

اطلاعات پردازه‌ها را در جدولی مشابه جدول زیر توصیف کنید. 

توجه: در این بخش نیز مثل سایر بخش‌های این سند، بر اجزای داخلی سیستم تمرکز می‌شود. به عبارت دیگر سامانه‌های خارجی (سیستم‌های خارج از سیستم موردبررسی) در فهرست پردازه‌ها ذکر نشود.

همچنین ارتباطات بین پردازه‌ها، در جدولی مشابه جدول زیر و یا به صورت یک نمودار مناسب ارائه شود. سطرهای جدول زیر به عنوان نمونه و مثال ذکر شده‌اند. مثلاً اگر از رویکرد مایکروسرویس استفاده می‌کنید، می‌توانید ارتباط بین مایکروسرویس‌ها را در در یک نمودار Microservices Diagram (و یا مشابه جدول زیر) توصیف کنید.

7. نمای توسعه و پیاده‌سازی (Development یا Implementation)

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

این بخش فقط برای برنامه‌ها (کدها)یی که به صورت داخلی در تیم پروژه توسعه داده شدند ذکر شود. پردازه‌هایی مثل دیتابیس و وب‌سرور ، که توسط تیم پروژه تولید نشده‌اند، در این بخش جایی ندارند. برای تکمیل این بخش، می‌توان با مراجعه به مخزن کد (مثلاً git) لیست پروژه‌ها یا ماژول‌ها را استخراج کرد. 

این بخش حداقل شامل یک جدول خواهد بود که در هر سطر آن به یک پروژه (Source Project) یا یک بسته مهم و کلان (Package) یا یک ماژول (Module) اختصاص دارد. (در صورتی که ساختار کد بزرگ و پیچیده و مشتمل بر چندین مولفه است در جدول، بسته‌های آن را به تفکیک توضیح بدهید). در هر سطر جدول به این موارد اشاره می شود:

• عنوان پروژه یا بسته یا ماژول
• توضیح
• اهم فناوری‌ها و کتابخانه‌های مورد استفاده (با ذکر نسخه)
• وابستگی‌ها: سایر ماژول‌هایی که به آن‌ها وابسته است. 

اگر از رویکرد مایکروسرویس استفاده می‌کنید، هر یک از مایکروسرویس‌ها را به عنوان یک ماژول توصیف کنید.

8. نماهای متقاطع (اختیاری)

محتوای این بخش حذف شده است.

9. نحوه تحقق موارد کاربرد کلیدی

محتوای این بخش حذف شده است.

10. نمای تست

محتوای این بخش حذف شده است.

11. مدیریت لاگ

محتوای این بخش حذف شده است.

12. پایش (Monitoring)

محتوای این بخش حذف شده است.

13. نمای داده

در این بخش، تصمیمات مهمی که در زمینه داده‌های سامانه گرفته شده ذکر می‌شود. به عنوان مثال، نحوه ذخیره داده‌ها، نوع پایگاه داده‌های مورد استفاده (sql/nosql/…)، مدیریت داده‌ها و فراداده‌ها، الگوها و تکنیک‌های اصلی در لایه داده (مثل CQRS و محل استفاده از Cache)، فرایند‌های پشتیبان‌گیری و بازیافت داده‌ها، امنیت داده‌ها و ساختار داده‌های کلیدی سیستم.

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

14. نمای گزارش‌گیری

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

OLAP, Data-warehousing, Report Engines, Report Generators, Report Designers, Materialized View, Denormalization, Power BI, Jasper Reports, BERT,  ...

در این بخش، طراحی کلان امکاناتی که برای گزارش‌گیری تعبیه شده است، ذکر شود. با کمک محتوای این فصل، به سؤالات و دغدغه‌هایی مثل موارد زیر پاسخ داده می‌شود:

• در این سامانه نرم‌افزاری، چه نوع گزارش‌هایی قابل دریافت است؟ این گزارش‎‌ها توسط چه کاربران/نقشهایی قابل دریافت هستند؟
• چه ابزارها یا فناوری‌هایی برای تولید گزارش استفاده شده‌اند؟
• امکان طراحی گزارش (report designer) توسط کاربر یا مدیر وجود دارد؟
• گزارش‌ها در چه قالبها و فرمت‌هایی قابل مشاهده است؟ 

15. الگوها و تکنیک‌های مورد استفاده

محتوای این بخش حذف شده است.

16. ابزارها و فناوری‌ها

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

1. نام یک ابزار/استاندارد/الگو/فناوری
2. نسخه مورداستفاده
3. جایگاه استفاده (معنی یا تعریف فناوری ذکر نشود، بلکه در حداکثر یک جمله و یا حداکثر یک خط، جایگاه آن ذکر شود)

یک فهرست فرضی به عنوان نمونه در ادامه آمده است:

17. مهم‌ترین تصمیمات معماری

محتوای این بخش حذف شده است.

18. ریسک‌ها و بدهی‌های فنی

محتوای این بخش حذف شده است.

19. بهبودهای پیشنهادی در آینده

محتوای این بخش حذف شده است.

20. سایر نماهای مفید/لازم

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

ترتیب پیشنهادی برای تکمیل سند معماری

پیشنهاد می‌کنیم سند معماری با یک فرایند Iterative & incremental تکمیل شود. لزومی ندارد که فصل‌های این سند به ترتیب فوق تکمیل شوند. گامهای پیشنهادی:

1. چرخه اول: نگارش فضای مسأله.
   در این چرخه، یک دور (چرخه) تلاش شود و نیمه اول سند معماری که شامل «فضای مسأله» است، مستند شود. فضای مسأله شامل فصلهای «مقدمه»، «نمای موارد کاربرد» و «ویژگی‌های کیفی» است. پس از این چرخه، صورت مسأله و نیازمندی‌های کلان نرم‌افزار مشخص می‌شوند. ترتیب پیشنهادی:
   • مقدمه
   • نمای موارد کاربرد
   • ویژگی‌های کیفی
2. چرخه دوم: توصیف طراحی کلان سامانه نرم‌افزاری، شامل فصلهای «نمای منطقی» ، «نمای پردازه» و «ابزارها و فناوری‌ها». ترتیب پیشنهادی:
   • نمای پردازه
   • نمای استقرار
   • ابزارها و فناوری‌ها
   • بازنگری فصلهایی که قبلاً نگارش شده
3. چرخه سوم: تکمیل فصلهای اصلی جهت توصیف معماری کلان. ترتیب پیشنهادی:
   • نمای منطقی
   • نمای توسعه و پیاده‌سازی
   • نماهای متقاطع (در صورت نیاز)
   • بازنگری فصلهایی که قبلاً نگارش شده
4. چرخه چهارم. ترتیب پیشنهادی:
   • فصل نحوه تحقق موارد کاربرد کلیدی
   • نمای تست
   • نمای داده
   • الگوها و تکنیک‌های مورداستفاده
   • ریسک‌ها و بدهی‌های فنی
   • بازنگری فصلهایی که قبلاً نگارش شده
5. چرخه پنجم. ترتیب پیشنهادی:
   • سایر فصلهای باقی‌مانده
   • بازنگری فصلهایی که قبلاً نگارش شده

مراجع

برخی از مراجعی که در تهیه این قالب به آن‌ها توجه شده است، در ادامه آمده‌اند:

• www.cs.ubc.ca/~gregor/teaching/papers/4+1view-architecture.pdf
• Microservices patterns book (www.microservices.io)
• Simon Brown
  • http://www.codingthearchitecture.com/2016/05/31/agile_software_architecture_documentation.html
  • https://leanpub.com/software-architecture-for-developers
  • https://c4model.com/
  • https://structurizr.com/
• https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)
• https://github.com/unlight/solution-architecture/blob/master/README.md
• https://arc42.org/overview/
• https://wiki.sei.cmu.edu/confluence/display/SAD

چک‌لیست

قبل از ارسال یا تایید سند معماری، موارد زیر را دوباره چک کنید:

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

اشتباه‌های رایج در نگارش سند معماری

• اشتباه رایج: رعایت نشدن قالب سند
  • سند معماری طبق قالب باشد. انطباق با قالب سند معماری، مهم است.
  • همه بخش‌های مطرح‌شده در قالب سند معماری و با همان ترتیب، در مستندسازی پوشش داده شود.
• نویسنده سند معماری، یک فرد ارشد فنی (مثلا مدیر فنی، معمار نرم‌افزار یا ...) باشد که در جریان تصمیمات اصلی و کلان طراحی سامانه باشد.
  • این نکته برای سند معماری (SAD) است. در مورد سند SCD (سند توصیف ارتباطات سامانه) لازم نیست نویسنده‌ سند SCD معمار سامانه (یا یک فرد ارشد فنی) باشد. کسی که در جریان کلیات کارکرد و ارتباطات سامانه باشد می‌تواند سند SCD را بنویسد.
• انگیزش: توجه شود که سند معماری به درد تیم توسعه هم می‌خورد (خود شرکت پیمانکار ذی‌نفع تولید این سند است). اگر معماری سامانه مستند نشده، یک مخاطره (ریسک) برای تیم/شرکت توسعه‌دهنده هم هست. به این سند، فقط به عنوان یک نیازمندی از سمت کارفرما نگاه نشود. ذی‌نفعان مختلفی (طراحان، مدیران، کارفرما، برنامه‌نویسان و ...) در طول زمان ممکن است ازبخش‌هایی از سند معماری استفاده کنند.
• به سطح سند معماری توجه شود. در نمودارها و جداول سند معماری، معمولا درباره المان‌ها و ساختارهای سطح بالا صحبت می‌کنیم و درباره جزییات پیاده‌سازی صحبت نمی‌کنیم. مثلا نمودار sequence بین چند کلاس پروژه در سند معماری جای نمی‌گیرد ولی نمودار sequence بین چند کامپوننت سطح بالا ممکن است در معماری نمایش داده شود.
• به فلسفه‌ ایجاد سند معماری (SAD) توجه شود.
  • این سند دارای دو بخش اصلی است:
    • بخش اول: شامل بیان نیازمندی‌های کارکردی و غیرکارکردی سیستم (فضای مساله)
      • این بخش باید دقیق و شفاف باشد (مساله به خوبی بیان شود)
    • بخش دوم: بیان راهکارها و تکنیک‌ها برای پوشش نیازمندی‌های بخش اول از نماها/دیدگاه‌های مختلف (فضای راه‌حل)
      • فضای راه‌حل، باید مطابق با فضای مساله باشد.
      • هر مورد از محتوای این بخش باید سرنخی در بخش اول داشته باشد.

• اشتباه‌های رایج در بخش اول (فضای مساله)
  • اشتباه‌های رایج در بخش نمای Usecase (مورد کاربرد):
    • بیان نیازمندی‌ها به صورت یک عنوان و عدم ارایه توضیحات کافی  
    • تمرکز بیش از حد بر روی نمودارهای موارد کاربرد و عدم توجه به ارایه مطالب به صورت سازمان‌دهی‌شده و گویا
    • عدم تبیین کنشگرها (actorهای سامانه) به تفکیک کنشرگرهای انسانی و سیستمی
  • اشتباه‌های رایج در بخش ویژگی‌های کیفی
    • بیان کلی ویژگی‌های کیفی (مثلا امنیت و کارایی). نام بردن از ویژگی‌های کیفی کافی نیست و بی‌فایده است.
    • عدم ذکر  معیار ارزیابی. روش محاسبه میزان کیفیت در هر ویژگی کیفی باید ذکر شود (مثلاً معیار TPS برای کارایی)
    • عدم ذکر محدوده مطلوب (مثلا محدوده‌ی حداقل 100 برای معیار TPS)

• اشتباه‌های رایج در بخش دوم (فضای راه حل)
  • الزامات بخش نمای منطقی:
    • نحوه‌ ارتباط بین مولفه‌های اصلی سامانه مشخص شود.
      • عبارت مولفه اصلی در جمله قبل نقش کلیدی دارد. همانطور که ارتباطات بین سامانه‌های مختلف مهم است، ارتباط بین مولفه‌های مهم درون یک سامانه نیز مهم است.
    • هریک از نمودارهای ارایه‌شده مربوط به یک یا چند نیازمندی functional یا nonfunctional باشد.
    • مولفه‌ اصلی، یک صفحه‌ (مثلا یک فرم کاربری) یا یک موجودیت سطح پایین (در سطح پیاده‌سازی) در نظر گرفته نشود. بلکه یک کامپوننت یا موجودیت نرم‌افزاری سطح بالا (مهم در سطح معماری) باشد.
    •  موارد کاربرد کوچک و جزیی (مثل مورد کاربرد ورود به سامانه) نباید به صورت نمودار در این بخش توصیف شود.
    • صرفا ارایه یک یا چند نمودار کافی نیست و حتما بایستی شرحی در کنار نمودارها باشد.
  • الزامات بخش نمای پردازه و استقرار:
    • گاهی در نمای استقرار چندین سرور مشاهده می‌شود ولی در نمای پردازه فقط نام پردازه‌ها ذکر می‌شود.
      • دقیقا ذکر شود در هر سرور چه پردازه‌هایی در حال اجرا هستند.
    • در نمای استقرار، اطلاعاتی مثل IP سرورها ذکر نشود.
  • الزامات نمای توسعه و پیاده‌سازی:
    • بیان الگوهای کلی بی‌فایده است. در عوض باید بیان شود چه تقسیم‌بندی‌ها و تصمیماتی در سطح کد گرفته شده است. مثلا به جای ترسیم شکل یک معماری سه لایه، که احتمالا از اینترنت کپی شده است، تبیین شود که محتوای لایه‌ها در پروژه چگونه است و در هر لایه، چه بسته‌ها و کدهایی قرار می‌گیرد.
    • در این نما بایستی مولفه‌های اصلی و ارتباطاتشان مشخص شود.
    • هم‌چنین تصمیات کلیدی در پیاده‌سازی، بیان شود. مثلا ذکر شود بحث validation مربوط به موجودیت‌ها و درخواست‌های وب‌سرویس به صورت کد پیاده‌سازی شده و یا توصیف آن در فایل XML ذخیره می‌شود. نحوه‌ دسترسی به افراد در پایگاه‌داده جدا ذخیره شده است.
  • الزامات نمای تست:
    • معرفی ابزارهای تست
    • بیان سطوح تست
    • بیان تصمیمات کلان برای تست سامانه
    • نحوه مدیریت ارتباط تست‌ها با نیازمندی‌ها 
  • الزامات نمای لاگ:
    • بیان دقیق اطلاعات ذخیره‌شده در لاگ
      • مثلا بیان کلی این که «اطلاعات نشست کاربری لاگ می‌شود» کافی نیست.
  • الزامات نمای پایش:
    • بیان سناریوهایی مثل اندازه‌گیری میزان استفاده از شبکه و منابع سیستم کافی نیست.
    • نحوه استفاده از لاگ‌های سامانه (موضوع فصل قبل) برای پایش ذکر شود.
    • سناریوهای پایش (افراد/نقش‌ها/فرایندها/هشدارها/اقدام‌ها/...) بیان شود.
  • الزامات رایج در نمای داده:
    • تصمیمات اساسی در زمینه داده‌های سامانه ذکر شود. این تصمیمات فقط شامل مدل داده‌ها (مثلا جداول اصلی و مهم) نیست. بلکه مواردی مثل تکنیک‌های کلان مورد استفاده در لایه داده (مثلا نحوه و فناوری Cache و Backup/Restore و Data Migration و ...) ذکر شود.
  • الزامات در بخش روش‌ها و تکنیک‌های مورد استفاده:
    • قرار نیست جزییات روش‌ها بیان شود، بلکه به طور کلی بیان شود که برای هر مساله/نیازمندی دقیقا چه تکنیک‌هایی مورد استفاده قرار گرفته است.
  • الزامات در ابزارها و فناوری‌ها:
    • همه ابزارها و فناوری‌های مهم ذکر شود (مثلا گاهی با مقایسه این بخش با نمای پردازه، می‌توان فهمید که چه فناوری‌هایی استفاده می‌شوند ولی ذکر نشده‌اند).
    • ابزارهای توسعه نرم‌افزار ذکر شوند.

پیوست

فایل قالب پیشنهادی

محتوای این بخش حذف شده است.