Поддержка исправлений JSON в веб-API ASP.NET Core

В этой статье описывается обработка запросов JSON Patch в веб-API ASP.NET Core.

Поддержка исправлений JSON в веб-API ASP.NET Core основана на System.Text.Json сериализации и требует Microsoft.AspNetCore.JsonPatch.SystemTextJson пакета NuGet.

Что такое стандарт JSON Patch?

Стандарт патча JSON:

• Стандартный формат описания изменений, применяемых к документу JSON.

• Определяется в RFC 6902 и широко используется в API RESTful для выполнения частичных обновлений ресурсов JSON.

• Описывает последовательность операций, которые изменяют документ JSON, например:

  • add
  • remove
  • replace
  • move
  • copy
  • test

В веб-приложениях JSON Patch обычно используется в операции PATCH для частичного обновления ресурса. Вместо отправки всего ресурса для обновления клиенты могут отправлять документ исправления JSON, содержащий только изменения. Установка исправлений уменьшает размер полезной нагрузки и повышает эффективность.

Общие сведения о стандарте исправлений JSON см. в jsonpatch.com.

Поддержка исправлений JSON в веб-API ASP.NET Core

Поддержка JSON Patch в веб-API ASP.NET Core основана на System.Text.Json сериализации, начиная с .NET 10, с реализацией Microsoft.AspNetCore.JsonPatch на основе System.Text.Json сериализации. Эта функция:

• Требуется Microsoft.AspNetCore.JsonPatch.SystemTextJson пакет NuGet.
• Соответствует современным методикам .NET, используя библиотеку System.Text.Json , оптимизированную для .NET.
• Обеспечивает улучшенную производительность и сокращение использования памяти по сравнению с устаревшей реализацией Newtonsoft.Json. Дополнительные сведения о устаревшей Newtonsoft.Jsonреализации см. в версии .NET 9 этой статьи.

Note

Реализация Microsoft.AspNetCore.JsonPatch, основанная на сериализации System.Text.Json, не является заменой для устаревшей реализации на основе Newtonsoft.Json. Например, ExpandoObjectон не поддерживает динамические типы.

Important

Стандарт JSON Patch имеет присущие риски безопасности. Так как эти риски присущи стандарту исправлений JSON, реализация ASP.NET Core не пытается устранить связанные с ней риски безопасности. Разработчик отвечает за безопасное применение документа исправления JSON к целевому объекту. Дополнительные сведения см. в разделе "Устранение рисков безопасности ".

Включение поддержки исправлений JSON с помощью System.Text.Json

Чтобы включить поддержку System.Text.Json JSON-патчей, установите пакет NuGet Microsoft.AspNetCore.JsonPatch.SystemTextJson.

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson --prerelease

Этот пакет предоставляет JsonPatchDocument<TModel> класс для представления документа JSON Patch для объектов типа T и пользовательскую логику для сериализации и десериализации JSON Patch документов с помощью System.Text.Json. Ключевой метод класса JsonPatchDocument<TModel> — это ApplyTo(Object), который применяет операции патчей к целевому объекту типа T.

Код метода действия с применением JSON Patch

В контроллере API есть метод действия для JSON Patch, который:

• помечен атрибутом HttpPatchAttribute;
• принимает JsonPatchDocument<TModel> обычно с указанием FromBodyAttribute;
• вызывает ApplyTo(Object) для целевого документа, чтобы применить изменения.

Пример метода действия контроллера:

[HttpPatch("{id}", Name = "UpdateCustomer")]
public IActionResult Update(AppDb db, string id, [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    // Retrieve the customer by ID
    var customer = db.Customers.FirstOrDefault(c => c.Id == id);

    // Return 404 Not Found if customer doesn't exist
    if (customer == null)
    {
        return NotFound();
    }

    patchDoc.ApplyTo(customer, jsonPatchError =>
        {
            var key = jsonPatchError.AffectedObject.GetType().Name;
            ModelState.AddModelError(key, jsonPatchError.ErrorMessage);
        }
    );

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

    return new ObjectResult(customer);
}

Этот код из примера приложения работает со следующими Customer моделями и Order моделями:

namespace App.Models;

public class Customer
{
    public string Id { get; set; }
    public string? Name { get; set; }
    public string? Email { get; set; }
    public string? PhoneNumber { get; set; }
    public string? Address { get; set; }
    public List<Order>? Orders { get; set; }

    public Customer()
    {
        Id = Guid.NewGuid().ToString();
    }
}

namespace App.Models;

public class Order
{
    public string Id { get; set; }
    public DateTime? OrderDate { get; set; }
    public DateTime? ShipDate { get; set; }
    public decimal TotalAmount { get; set; }

    public Order()
    {
        Id = Guid.NewGuid().ToString();
    }
}

Ключевые действия примера метода действия:

• Извлечение клиента:
  • Метод извлекает Customer объект из базы данных AppDb с помощью предоставленного идентификатора.
  • Если объект Customer не найден, возвращается ответ 404 Not Found.
• Применение JSON-патча:
  • Метод ApplyTo(Object) применяет операции исправления JSON из patchDoc к полученному Customer объекту.
  • Если ошибки возникают во время приложения исправления, например недопустимые операции или конфликты, они фиксируются делегатом обработки ошибок. Этот делегат добавляет сообщения об ошибках в ModelState, используя имя типа затронутого объекта и сообщение об ошибке.
• Проверка ModelState:
  • После применения исправления метод проверяет ModelState на наличие ошибок.
  • Если ModelState недействительно, например, из-за ошибок патча, возвращает 400 Bad Request ответ с ошибками проверки.
• Верните обновленного клиента:
  • Если исправление успешно применено и ModelState допустимо, метод возвращает обновленный Customer объект в ответе.

Пример ответа об ошибке:

В следующем примере показано тело 400 Bad Request ответа для операции JSON Patch, когда указанный путь недопустим:

{
  "Customer": [
    "The target location specified by path segment 'foobar' was not found."
  ]
}

Применение документа JSON Patch к объекту

В следующих примерах показано, как использовать ApplyTo(Object) метод для применения документа JSON Patch к объекту.

Пример: применение JsonPatchDocument<TModel> к объекту

В следующем примере показано:

• Операции add, replace и remove.
• Операции с вложенными свойствами.
• Добавление нового элемента в массив.
• Использование преобразователя строкового перечисления JSON в документе JSON-обновления.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com",
    PhoneNumbers = [new() {Number = "123-456-7890", Type = PhoneNumberType.Mobile}],
    Address = new Address
    {
        Street = "123 Main St",
        City = "Anytown",
        State = "TX"
    }
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/FirstName", "value": "Jane" },
    { "op": "remove", "path": "/Email"},
    { "op": "add", "path": "/Address/ZipCode", "value": "90210" },
    { "op": "add", "path": "/PhoneNumbers/-", "value": { "Number": "987-654-3210",
                                                                "Type": "Work" } }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document
patchDoc!.ApplyTo(person);

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

В предыдущем примере приводятся следующие выходные данные обновленного объекта:

{
    "firstName": "Jane",
    "lastName": "Doe",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "TX",
        "zipCode": "90210"
    },
    "phoneNumbers": [
        {
            "number": "123-456-7890",
            "type": "Mobile"
        },
        {
            "number": "987-654-3210",
            "type": "Work"
        }
    ]
}

Метод ApplyTo(Object) обычно следует соглашениям и параметрам System.Text.Json обработки JsonPatchDocument<TModel>, включая поведение, управляемое следующими параметрами:

• JsonNumberHandling: считываются ли числовые свойства из строк.
• PropertyNameCaseInsensitive: Являются ли имена свойств чувствительными к регистру.

Основные различия между System.Text.Json и новой JsonPatchDocument<TModel> реализацией:

• Тип среды выполнения целевого объекта, а не объявленного типа, определяет, какие свойства ApplyTo(Object) патчи.
• System.Text.Json десериализация зависит от объявленного типа для определения подходящих свойств.

Пример. Применение JsonPatchDocument с обработкой ошибок

При применении документа исправления JSON могут возникать различные ошибки. Например, целевой объект может не иметь указанного свойства, или указанное значение может быть несовместимо с типом свойства.

JSON Patch поддерживает test операцию, которая проверяет, равно ли указанное значение целевому свойству. Если это не так, возвращается ошибка.

В следующем примере показано, как корректно обрабатывать эти ошибки.

Important

Объект, переданный методу ApplyTo(Object) , изменяется на месте. Вызывающий отвечает за отмену изменений, если какая-либо операция завершается ошибкой.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com"
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/Email", "value": "janedoe@gmail.com"},
    { "op": "test", "path": "/FirstName", "value": "Jane" },
    { "op": "replace", "path": "/LastName", "value": "Smith" }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document, catching any errors
Dictionary<string, string[]>? errors = null;
patchDoc!.ApplyTo(person, jsonPatchError =>
    {
        errors ??= new ();
        var key = jsonPatchError.AffectedObject.GetType().Name;
        if (!errors.ContainsKey(key))
        {
            errors.Add(key, new string[] { });
        }
        errors[key] = errors[key].Append(jsonPatchError.ErrorMessage).ToArray();
    });
if (errors != null)
{
    // Print the errors
    foreach (var error in errors)
    {
        Console.WriteLine($"Error in {error.Key}: {string.Join(", ", error.Value)}");
    }
}

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

В предыдущем примере приводятся следующие выходные данные:

Error in Person: The current value 'John' at path 'FirstName' is not equal 
to the test value 'Jane'.
{
    "firstName": "John",
    "lastName": "Smith",              <<< Modified!
    "email": "janedoe@gmail.com",     <<< Modified!
    "phoneNumbers": []
}

Снижение рисков безопасности

При использовании Microsoft.AspNetCore.JsonPatch.SystemTextJson пакета важно понимать и устранять потенциальные риски безопасности. В следующих разделах описаны выявленные риски безопасности, связанные с исправлением JSON, и рекомендуемые способы устранения рисков для обеспечения безопасного использования пакета.

Important

Это не исчерпывающий список угроз. Разработчики приложений должны проводить собственные проверки модели угроз, чтобы определить полный список конкретных приложений и при необходимости придумать соответствующие меры по устранению рисков. Например, приложения, которые делают коллекции доступными для операций исправления, должны учитывать потенциал для атак алгоритмической сложности, если эти операции вставляют или удаляют элементы в начале коллекции.

Чтобы свести к минимуму риски безопасности при интеграции функций исправлений JSON в свои приложения, разработчики должны:

• Проведение комплексных моделей угроз для их собственных приложений.
• Устранение выявленных угроз.
• Следуйте рекомендациям по устранению рисков в следующих разделах.

Отказ в обслуживании (DoS) через увеличение памяти

• Сценарий: вредоносный клиент отправляет copy операцию, которая дублирует графы больших объектов несколько раз, что приводит к чрезмерному потреблению памяти.
• Влияние: потенциальные условия исчерпанияOf-Memory (OOM), приводящие к сбоям в работе службы.
• Mitigation:
  • Перед вызовом ApplyTo(Object) проверьте входящие JSON-патчи на соответствие размера и структуры.
  • Проверка должна быть специфичной для приложения, но пример проверки может выглядеть следующим образом:

public void Validate(JsonPatchDocument<T> patch)
{
    // This is just an example. It's up to the developer to make sure that
    // this case is handled properly, based on the app needs.
    if (patch.Operations.Where(op=>op.OperationType == OperationType.Copy).Count()
                              > MaxCopyOperationsCount)
    {
        throw new InvalidOperationException();
    }
}

Подверсия бизнес-логики

• Сценарий. Операции исправления могут управлять полями с неявными инвариантными (например, внутренними флагами, идентификаторами или вычисляемыми полями), нарушая бизнес-ограничения.
• Влияние: проблемы целостности данных и непреднамеренное поведение приложения.
• Mitigation:
  • Используйте POCOs (простые объекты CLR) с явно определёнными свойствами, которые безопасно изменять.
    • Избегайте предоставления конфиденциальных или критически важных свойств безопасности в целевом объекте.
    • Если объект POCO не используется, проверьте исправленный объект после применения операций, чтобы убедиться, что бизнес-правила и инварианты не нарушаются.

Проверка подлинности и авторизация

• Сценарий. Неавторизованные или несанкционированные клиенты отправляют вредоносные запросы на исправление JSON.
• Влияние: несанкционированный доступ к изменению конфиденциальных данных или нарушению поведения приложения.
• Mitigation:
  • Защита конечных точек, принимаюющих запросы на исправление JSON с помощью надлежащих механизмов проверки подлинности и авторизации.
  • Ограничить доступ к доверенным клиентам или пользователям с соответствующими разрешениями.

Получение кода

Просмотреть или скачать образец кода. (Инструкция по скачиванию.)

Чтобы проверить этот пример, запустите приложение и отправьте HTTP-запросы со следующими параметрами:

• URL-адрес: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Метод HTTP: PATCH
• заголовок: Content-Type: application/json-patch+json;
• Текст: скопируйте и вставьте один из примеров документов исправлений JSON из папки проекта JSON .

Дополнительные ресурсы

• Спецификация IETF RFC 5789 для метода PATCH
• Спецификация IETF RFC 6902 для JSON Patch
• Указатель JSON IETF RFC 6901
• Исходный код JSON Patch для ASP.NET Core