کاربرد و اصول استفاده از مدلهای مرزی در طراحی و توسعه واسط‌های برنامه سازی وAPI

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

مدل مرزی چیست؟

مدل مرزی (یا مدل داده‌ای مرزی) یک ساختار داده‌ای است که در مرزهای سیستم‌ها (مانند APIها) برای تبادل اطلاعات استفاده می‌شود. این مدل‌ها اغلب به‌عنوان DTO (Data Transfer Object) یا قرارداد (Contract) شناخته می‌شوند. اهداف اصلی آن‌ها عبارتند از:

1. استقلال سیستم‌ها: مدل‌های مرزی، ساختارهای داده‌ای داخلی یک سیستم را مخفی می‌کنند تا کلاینت و سرور (یا سرویس‌های مختلف) بتوانند بدون نیاز به دانستن جزئیات پیاده‌سازی داخلی یکدیگر ارتباط برقرار کنند. به‌عنوان مثال، طرح پایگاه داده یا منطق داخلی سرور نیازی به افشا برای کلاینت ندارد.
2.  ارتباط استاندارد: این مدل‌ها یک ساختار مشخص و ثابت (یا طرح‌واره) برای داده‌های تبادل‌شده تعریف می‌کنند و به‌عنوان یک قرارداد بین فرستنده و گیرنده عمل می‌کنند. این کار تضمین می‌کند که هر دو طرف فرمت و محتوای داده‌ها را درک کنند.
3.  قابلیت همکاری: مدل‌های مرزی امکان ارتباط بین سیستم‌هایی با زبان‌های برنامه‌نویسی یا پلتفرم‌های مختلف را با استفاده از فرمت‌های پذیرفته‌شده مانند JSON، XML یا Protobuf فراهم می‌کنند.
4.  کپسوله‌سازی: این مدل‌ها فقط داده‌های ضروری را نمایش می‌دهند و اطلاعات حساس یا غیرضروری را مخفی می‌کنند، که امنیت را بهبود می‌بخشد و وابستگی بین سیستم‌ها را کاهش می‌دهد.

 ویژگی‌های کلیدی مدل‌های مرزی

• سبک و متمرکز: مدل‌های مرزی معمولاً فقط شامل داده‌های موردنیاز برای یک درخواست یا پاسخ خاص API هستند و از فیلدهای غیرضروری اجتناب می‌کنند.
•  قابل سریال‌سازی: این مدل‌ها برای انتقال از طریق HTTP به‌راحتی به فرمت‌هایی مانند JSON یا XML سریال می‌شوند.
•  قابل نسخه‌بندی: از آنجا که APIها تکامل می‌یابند، مدل‌های مرزی اغلب نسخه‌بندی می‌شوند (مثلاً `/api/v1/resource`) تا تغییرات بدون اختلال در کلاینت‌های موجود مدیریت شوند.
•  غیرقابل تغییر (در برخی موارد): برای اطمینان از ثبات، گاهی مدل‌های مرزی به‌صورت غیرقابل تغییر طراحی می‌شوند تا از تغییرات ناخواسته در حین انتقال جلوگیری شود.
•  مستقل از فناوری: این مدل‌ها از زبان برنامه‌نویسی یا چارچوب مورداستفاده سیستم‌ها مستقل هستند.

نمونه‌های مدل‌های مرزی

مدل مرزی مبتنی بر JSON (مثلاً API REST):   برای یک endpoint API که اطلاعات کاربر را برمی‌گرداند، مدل مرزی ممکن است به این شکل باشد:

   {

     "id": "123",

     "name": "John Doe",

     "email": "john.doe@example.com"

   }

   این شیء JSON مدل مرزی است که داده‌های منتقل‌شده از سرور به کلاینت را نشان می‌دهد. پایگاه داده داخلی سرور ممکن است فیلدهای اضافی (مثل هش رمز عبور یا زمان آخرین ورود) داشته باشد، اما این‌ها در مدل مرزی گنجانده نمی‌شوند.

مدل مرزی مبتنی بر Protobuf (مثلاً gRPC):  در gRPC، مدل مرزی ممکن است در یک فایل `.proto` تعریف شود:

 message User {

     string id = 1;

     string name = 2;

     string email = 3;

   }

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

 نحوه کار مدل‌های مرزی در APIها

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

مدل مرزی به عنوان درخواست: وقتی کلاینت درخواستی به API ارسال می‌کند (مثلاً `POST /users`)، یک مدل مرزی در بدنه درخواست قرار می‌دهد. در حقیقت داده‌های مورد نظر را با ساختار تعیین شده کد گذاری کرده و در برده درخواست ارسال می‌کنیم.

curl --location 'http://localhost:8000/add/user' \
  --header 'content-type: application/json \
  --data '{
    "Name": "Johan Doh",
    "Age": 32
}'

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

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

HTTP/2 200 
server: openresty
date: Tue, 13 May 2025 00:34:29 GMT
content-type: application/json; charset=utf-8
vary: Accept-Encoding
content-encoding: gzip
X-Firefox-Spdy: h2

{"jsonrpc": "2.0", "id": 374, "result": []}

نگاشت به مدل‌های داخلی: در داخل سرور یا هر نرم افزاری، مدل مرزی اغلب به مدل‌های داده‌ای داخلی (مثلاً موجودیت‌های پایگاه داده یا اشیاء دامنه) نگاشت می‌شود. به‌عنوان مثال، سرور ممکن است JSON بالا را به یک موجودیت `User` در پایگاه داده نگاشت کند که شامل فیلدهای اضافی مانند `passwordHash` یا `role` است.

مزایای مدل‌های مرزی

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

چالش‌های مدل‌های مرزی

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

بهترین روش‌ها برای طراحی مدل‌های مرزی

1.  ساده نگه‌داشتن: فقط فیلدهای لازم برای مورد استفاده خاص را شامل کنید.
2.  نام‌گذاری شفاف: نام فیلدها باید بصری و مطابق با قراردادهای نام‌گذاری (مثل `camelCase` یا `snake_case`) باشد.
3. اعتبارسنجی ورودی‌ها: همیشه مدل‌های مرزی ورودی را اعتبارسنجی کنید تا با طرح‌واره موردانتظار مطابقت داشته باشند.
4.  نسخه‌بندی مدل‌ها: از نسخه‌بندی API یا تغییرات سازگار با نسخه‌های قبلی برای مدیریت به‌روزرسانی‌های مدل‌های مرزی استفاده کنید.
5.  مستندسازی مدل‌ها: از ابزارهایی مانند OpenAPI (Swagger) برای مستندسازی ساختار مدل‌های مرزی برای کلاینت‌ها استفاده کنید.
6. بهینه‌سازی عملکرد: از مدل‌های بزرگ و تودرتو که اندازه payload یا زمان پردازش را افزایش می‌دهند، اجتناب کنید.
7. استفاده از فرمت‌های استاندارد: برای APIهای REST از فرمت‌های پرکاربرد مانند JSON و برای gRPC از Protobuf استفاده کنید.

نتیجه گیری

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