استفاده از JSON Patch با ASP.NET Core

تصور کنید در حال ساخت یک API قدرتمند با ASP.NET Core هستید. کاربران شما می‌خواهند فقط بخش کوچکی از یک داده بزرگ را ویرایش کنند، مثلاً فقط نام خود را در پروفایلشان تغییر دهند. روش سنتی (استفاده از HTTP PUT) شما را مجبور می‌کند کل آبجکت کاربر را دوباره ارسال کنید. این کار نه تنها حجم درخواست‌ها را بالا می‌برد، بلکه پیچیدگی‌های ناخواسته نیز ایجاد می‌کند. ✨ اینجا است که استفاده از JSON Patch با ASP.NET Core به عنوان یک راه‌حل هوشمندانه و مدرن وارد میدان می‌شود.

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

در این مقاله جامع، به صورت گام به گام یاد می‌گیریم:

JSON Patch دقیقاً چیست و چه مشکلی را حل می‌کند؟
مزیت‌های کلیدی آن برای توسعه‌دهندگان ASP.NET Core کدامند؟
چگونه آن را در پروژه‌های خود پیاده‌سازی و استفاده کنیم؟

JSON Patch چیست و چرا باید به آن اهمیت دهیم؟

وقتی از متد HTTP PUT برای به‌روزرسانی یک منبع استفاده می‌کنید، باید کل موجودیت (Entity) را در بدنه درخواست ارسال نمایید. اگر کاربر فقط نام خود را تغییر دهد ولی شما کل آبجکت Person را بفرستید، فیلدهایی که ارسال نشده‌اند ممکن است null در نظر گرفته شوند. این رفتار می‌تواند منجر به از دست رفتن ناخواسته داده‌ها شود.

اما HTTP PATCH برای به‌روزرسانی‌های جزئی (Partial Updates) طراحی شده است. JSON Patch (RFC 6902) قراردادی است که مشخص می‌کند این تغییرات جزئی چگونه باید بیان شوند. درخواست JSON Patch یک آرایه از عملیات‌هاست که هر کدام به سرور می‌گوید دقیقاً چه کاری باید انجام دهد: «این فیلد را اضافه کن»، «آن مقدار را جایگزین کن» یا «این آیتم را از لیست حذف کن». بنابراین، ابهام از بین می‌رود و عملیات آپدیت کاملاً صریح و روشن انجام می‌شود. 🚀

مزیت‌های کلیدی استفاده از JSON Patch در ASP.NET Core

ادغام JSON Patch در پروژه‌های ASP.NET Core مزایای قابل توجهی به همراه دارد که فراتر از یک بهینه‌سازی ساده است.

📉 کاهش چشمگیر حجم Payload: شما فقط تغییرات را ارسال می‌کنید، نه کل آبجکت را. این موضوع باعث کاهش مصرف پهنای باند و افزایش سرعت پاسخ‌دهی API، به خصوص در اپلیکیشن‌های موبایل، می‌شود.
🎯 دقت و صراحت در عملیات: با مشخص کردن دقیق عملیات (add, replace, remove)، از آپدیت‌های ناخواسته یا از دست رفتن داده‌ها (مانند null شدن فیلدها) جلوگیری می‌کنید.
⚙️ عملیات‌های اتمی (Atomic): یک درخواست JSON Patch می‌تواند شامل چندین عملیات باشد. اگر حتی یکی از این عملیات‌ها با شکست مواجه شود، کل درخواست لغو می‌شود و داده‌ها در وضعیت پایدار باقی می‌مانند.
انعطاف‌پذیری بالا: به راحتی می‌توانید عملیات‌های پیچیده‌ای مانند جابه‌جایی یک آیتم در آرایه یا کپی کردن مقدار یک فیلد در فیلد دیگر را بدون منطق پیچیده سمت کلاینت انجام دهید.
✅ سازگاری با زبان‌های Strongly-Typed: این روش مشکل ابهام در زبان‌های strongly-typed مانند C# را به خوبی حل می‌کند. سرور دقیقاً می‌داند کدام فیلدها باید دست‌نخورده باقی بمانند.

آشنایی با عملیات‌های اصلی JSON Patch

هر عملیات در یک سند JSON Patch شامل سه بخش اصلی است: op (نوع عملیات)، path (مسیر فیلد مورد نظر) و value (مقدار جدید، در صورت نیاز). بیایید نگاهی به عملیات‌های کلیدی بیندازیم.

عملیات `add`

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

json

{ "op": "add", "path": "/friends/-", "value": "Mike" }

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

عملیات `remove`

یک مقدار را از مسیر مشخص شده حذف می‌کند. در C#، این کار معمولاً به معنای بازگرداندن مقدار به حالت پیش‌فرض (مثلاً null برای اشیاء یا 0 برای اعداد) است.

json

{ "op": "remove", "path": "/firstName" }

عملیات `replace`

مقدار موجود در یک مسیر را با مقدار جدیدی جایگزین می‌کند. این پرکاربردترین عملیات است.

json

{ "op": "replace", "path": "/firstName", "value": "Jim" }

عملیات `copy`

مقدار موجود در یک مسیر (from) را در مسیر دیگر (path) کپی می‌کند.

json

{ "op": "copy", "from": "/firstName", "path": "/lastName" }

عملیات `move`

مانند copy عمل می‌کند، با این تفاوت که مقدار را از مسیر مبدأ حذف کرده و به مسیر مقصد منتقل می‌کند.

json

{ "op": "move", "from": "/firstName", "path": "/lastName" }

عملیات `test`

این عملیات یک شرط را بررسی می‌کند. اگر مقدار موجود در مسیر با مقدار ارسالی برابر باشد، عملیات‌های بعدی در همان درخواست اجرا می‌شوند؛ در غیر این صورت، کل درخواست Patch با شکست مواجه می‌شود. این یک راه عالی برای جلوگیری از تداخل (Conflict) است.

json

[
  { "op": "test", "path": "/firstName", "value": "Bob" },
  { "op": "replace", "path": "/firstName", "value": "Jim" }
]

پیاده‌سازی گام به گام JSON Patch در ASP.NET Core

حالا که با مفاهیم آشنا شدیم، زمان آن است که استفاده از JSON Patch با ASP.NET Core را در محیط کدنویسی عملی کنیم.

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

برای استفاده از این قابلیت، باید کتابخانه مربوطه را در پروژه خود نصب کنید. مراحل زیر را دنبال کنید:

🛠️ نصب پکیج: کنسول Package Manager را باز کنید و دستور زیر را اجرا نمایید:

Install-Package Microsoft.AspNetCore.JsonPatch

🔗 ثبت در سرویس‌ها: در فایل Program.cs یا Startup.cs خود، باید پشتیبانی از JSON Patch را اضافه کنید. اگر از AddControllers استفاده می‌کنید، باید متد AddNewtonsoftJson را فراخوانی کنید:

builder.Services.AddControllers().AddNewtonsoftJson();

🚀 ثبت‌نام در پورتال توسعه: برای دریافت آخرین آپدیت‌ها و دسترسی به APIهای پیشرفته، پیشنهاد می‌شود به آدرس p.api.ir مراجعه کرده و در سیستم ثبت‌نام کنید. این کار به شما کمک می‌کند تا امنیت و پایداری APIهای خود را بهتر مدیریت کنید.

پیاده‌سازی در کنترلر (Controller)

برای دریافت درخواست‌های Patch، متد اکشن شما باید پارامتری از نوع JsonPatchDocument<T> دریافت کند. مثال زیر نحوه پیاده‌سازی را نشان می‌دهد:

csharp

[Route("api/[controller]")]
public class PersonController : Controller
{
    private static Person _person = new Person { FirstName = "Jim", LastName = "Smith" };

    [HttpPatch("update")]
    public IActionResult Patch([FromBody] JsonPatchDocument<Person> patchDoc)
    {
        if (patchDoc == null) return BadRequest();

        patchDoc.ApplyTo(_person); // اعمال تغییرات روی شیء

        if (!ModelState.IsValid) return BadRequest(ModelState);

        return Ok(_person);
    }
}

کاربردهای واقعی و سناریوهای پیشرفته

استفاده از JSON Patch فقط برای تغییر نام نیست! کاربردهای گسترده‌ای در پروژه‌های واقعی دارد.

⚡ بهینه‌سازی اپلیکیشن‌های موبایل: به دلیل محدودیت‌های ترافیکی موبایل، ارسال فقط فیلدهای تغییر یافته (مانند وضعیت آنلاین بودن کاربر) بسیار کارآمد است.
🧩 هماهنگی بین نسخه‌های مختلف کلاینت: کلاینت‌های قدیمی‌تر ممکن است تمام فیلدهای جدید مدل شما را نشناسند. با JSON Patch، آن‌ها فقط فیلدهایی که می‌شناسند را آپدیت می‌کنند و خطایی ایجاد نمی‌شود.
🛠️ مدیریت وضعیت در سیستم‌های توزیع شده: استفاده از عملیات test برای اطمینان از اینکه داده‌ها قبل از آپدیت توسط سیستم دیگری تغییر نکرده‌اند.

بهینه‌سازی عملیات با استفاده از AutoMapper

در پروژه‌های واقعی، شما معمولاً داده‌ها را در یک DTO دریافت کرده و سپس روی موجودیت پایگاه داده (Database Entity) اعمال می‌کنید. ادغام AutoMapper و JSON Patch یک راهکار عالی برای این کار است:

csharp

[HttpPatch("update/{id}")]
public IActionResult Patch(int id, [FromBody] JsonPatchDocument<PersonDTO> patchDoc)
{
    var personFromDb = _repository.GetById(id); // واکشی از دیتابیس
    var personDto = _mapper.Map<PersonDTO>(personFromDb); // تبدیل به DTO
    
    patchDoc.ApplyTo(personDto); // اعمال تغییرات روی DTO
    _mapper.Map(personDto, personFromDb); // نگاشت مجدد تغییرات روی موجودیت اصلی
    
    _repository.Update(personFromDb); // ذخیره در دیتابیس
    return Ok(personDto);
}

این زنجیره عملیاتی باعث می‌شود منطق برنامه شما تمیز و مقیاس‌پذیر باقی بمانند. ✅

نتیجه‌گیری و جمع‌بندی

استفاده از JSON Patch با ASP.NET Core یکی از بهترین روش‌ها برای ساخت APIهای حرفه‌ای، سریع و بهینه است. با استفاده از این استاندارد، شما نه تنها در پهنای باند صرفه‌جویی می‌کنید، بلکه پایداری و قابلیت اطمینان اپلیکیشن خود را نیز افزایش می‌دهید. اگر تا امروز از PUT برای تمام به‌روزرسانی‌ها استفاده می‌کردید، وقت آن است که به قدرت PATCH اعتماد کنید. 💡

آیا شما تجربه استفاده از این روش را در پروژه‌های خود دارید؟ خوشحال می‌شویم نظرات و سوالات خود را در بخش دیدگاه‌ها با ما در میان بگذارید تا با هم در مورد چالش‌های آن گفتگو کنیم!