Podpora oprav JSON ve webovém rozhraní API ASP.NET Core

Tento článek vysvětluje, jak zpracovávat požadavky opravy JSON ve webovém rozhraní API ASP.NET Core.

Podpora oprav JSON ve webovém rozhraní API ASP.NET Core je založená na System.Text.Json serializaci a vyžaduje Microsoft.AspNetCore.JsonPatch.SystemTextJson balíček NuGet.

Co je standard JSON Patch?

Standard opravy JSON:

• Je standardní formát pro popis změn, které se mají použít u dokumentu JSON.

• Je definován v RFC 6902 a je široce používán v rozhraníCH RESTful API k provádění částečných aktualizací prostředků JSON.

• Popisuje posloupnost operací, které upravují dokument JSON, například:

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

Ve webových aplikacích se JSON Patch běžně používá v operaci PATCH k provádění částečných aktualizací prostředků. Místo odeslání celého prostředku pro aktualizaci můžou klienti odeslat dokument JSON Patch obsahující pouze změny. Patchování snižuje velikost přenášených dat a zlepšuje efektivitu.

Přehled standardu JSON Patch najdete na jsonpatch.com.

Podpora oprav JSON ve webovém rozhraní API ASP.NET Core

Podpora JSON Patch ve webovém rozhraní API ASP.NET Core je založená na System.Text.Json serializaci a počínaje rozhraním .NET 10 se implementuje Microsoft.AspNetCore.JsonPatch na základě System.Text.Json serializace. Tato funkce:

• Microsoft.AspNetCore.JsonPatch.SystemTextJson Vyžaduje balíček NuGet.
• V souladu s moderními postupy .NET využívá knihovnu System.Text.Json , která je optimalizovaná pro .NET.
• Poskytuje lepší výkon a snížené využití paměti v porovnání s implementací založenou na starší Newtonsoft.Jsonverzi. Další informace o starší Newtonsoft.Jsonimplementaci naleznete v verzi tohoto článku pro .NET 9.

Note

Implementace Microsoft.AspNetCore.JsonPatch založená na System.Text.Json serializaci není náhradou za starší implementaci založenou na Newtonsoft.Json. Nepodporuje například ExpandoObjectdynamické typy.

Important

Standard JSON Patch má vlastní bezpečnostní rizika. Vzhledem k tomu, že tato rizika jsou součástí standardu JSON Patch, implementace ASP.NET Core se nepokouší zmírnit vlastní rizika zabezpečení. Je zodpovědností vývojáře, aby se zajistilo, že dokument Opravy JSON je bezpečný pro cílový objekt. Další informace najdete v části Omezení rizik zabezpečení .

Povolit podporu JSON Patch s využitím System.Text.Json

Chcete-li povolit podporu pro JSON Patch, nainstalujte balíček NuGet System.Text.JsonMicrosoft.AspNetCore.JsonPatch.SystemTextJson.

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

Tento balíček poskytuje JsonPatchDocument<TModel> třídu představující dokument JSON Patch pro objekty typu T a vlastní logiky pro serializaci a deserializaci dokumentů JSON Patch pomocí System.Text.Json. Klíčovou metodou JsonPatchDocument<TModel> třídy je ApplyTo(Object), která aplikuje operace opravy na cílový objekt typu T.

Kód metody akce, který používá opravu JSON

V kontroleru rozhraní API metoda akce pro opravu JSON:

• Je opatřen poznámkami atributem HttpPatchAttribute .
• Přijímá , JsonPatchDocument<TModel>obvykle s FromBodyAttribute.
• Zavolá ApplyTo(Object) dokument opravy, aby změny použil.

Příklad metody akce kontroleru:

[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);
}

Tento kód z ukázkové aplikace funguje s následujícími Customer modely a Order modely:

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();
    }
}

Klíčové kroky metody ukázkové akce:

• Načtení zákazníka:
  • Metoda načte Customer objekt z databáze AppDb pomocí zadaného ID.
  • Pokud se nenajde žádný Customer objekt, vrátí 404 Not Found odpověď.
• Použít opravu JSON:
  • Metoda ApplyTo(Object) použije operace JSON Patch z patchDoc na načtený Customer objekt.
  • Pokud během aplikace oprav dojde k chybám, jako jsou neplatné operace nebo konflikty, zachytí se delegátem zpracování chyb. Tento delegát přidá k ModelState chybové zprávy pomocí názvu typu dotčeného objektu a chybové hlášky.
• Ověřit ModelState:
  • Po použití opravy metoda zkontroluje chyby v ModelState.
  • Pokud je ModelState neplatný, například kvůli chybám opravných balíčků, vrátí 400 Bad Request odpověď s chybami ověření.
• Vrácení aktualizovaného zákazníka:
  • Pokud je oprava úspěšně použita a ModelState je platná, metoda vrátí aktualizovaný Customer objekt v odpovědi.

Příklad odpovědi na chybu:

Následující příklad ukazuje text 400 Bad Request odpovědi pro operaci JSON Patch, pokud je zadaná cesta neplatná:

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

Použití dokumentu opravy JSON u objektu

Následující příklady ukazují, jak použít metodu ApplyTo(Object) k použití dokumentu JSON Patch na objekt.

Příklad: Aplikujte JsonPatchDocument<TModel> na objekt

Následující příklad ukazuje:

• Operace add, replace a remove.
• Operace s vnořenými vlastnostmi
• Přidání nové položky do pole
• Použití převaděče výčtu řetězců JSON v dokumentu opravy 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));

Předchozí příklad vede k následujícímu výstupu aktualizovaného objektu:

{
    "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"
        }
    ]
}

Metoda ApplyTo(Object) obecně dodržuje konvence a možnosti System.Text.Json zpracování JsonPatchDocument<TModel>, včetně chování řízeného následujícími možnostmi:

• JsonNumberHandling: Určuje, zda jsou číselné vlastnosti načteny z řetězců.
• PropertyNameCaseInsensitive: Zda názvy vlastností rozlišují velká a malá písmena.

Hlavní rozdíly mezi System.Text.Json a novou JsonPatchDocument<TModel> implementací:

• Typ modulu runtime cílového objektu, nikoli deklarovaný typ, určuje, které vlastnosti ApplyTo(Object) se opravují.
• System.Text.Json deserializace spoléhá na deklarovaný typ pro identifikaci způsobilých vlastností.

Příklad: Použití jsonPatchDocument se zpracováním chyb

Při použití dokumentu opravy JSON může dojít k různým chybám. Například cílový objekt nemusí mít zadanou vlastnost nebo zadaná hodnota může být nekompatibilní s typem vlastnosti.

JSON Patch podporuje test operaci, která kontroluje, jestli se zadaná hodnota rovná cílové vlastnosti. Pokud ne, vrátí chybu.

Následující příklad ukazuje, jak tyto chyby řádně zpracovat.

Important

Objekt předaný ApplyTo(Object) metodě je změněn na místě. Volající zodpovídá za zahození změn v případě selhání jakékoli operace.

// 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));

Výsledkem předchozího příkladu je následující výstup:

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": []
}

Zmírnění rizik zabezpečení

Při používání Microsoft.AspNetCore.JsonPatch.SystemTextJson balíčku je důležité pochopit a zmírnit potenciální rizika zabezpečení. Následující části popisují identifikovaná bezpečnostní rizika spojená s opravou JSON a poskytují doporučená omezení rizik pro zajištění zabezpečeného používání balíčku.

Important

Nejedná se o vyčerpávající seznam hrozeb. Vývojářiaplikacích aplikací musí provádět vlastní kontroly modelu hrozeb, aby mohli podle potřeby určit komplexní seznam specifických pro konkrétní aplikaci a podle potřeby přijít s vhodnými omezeními rizik. Například aplikace, které zpřístupňují kolekce operacím oprav, by měly zvážit potenciál útoků na algoritmickou složitost, pokud tyto operace vloží nebo odeberou prvky na začátku kolekce.

Aby vývojáři mohli minimalizovat rizika zabezpečení při integraci funkcí oprav JSON do svých aplikací, měli by:

• Spusťte komplexní modely hrozeb pro své vlastní aplikace.
• Vyřešte zjištěné hrozby.
• Postupujte podle doporučených omezení rizik v následujících částech.

Odepření služby (DoS) prostřednictvím amplifikace paměti

• Scénář: Škodlivý klient odešle operaci, která několikrát duplikuje copy grafy velkých objektů, což vede k nadměrné spotřebě paměti.
• Dopad: Možné podmínkyOf-Memory (OOM), které mohou způsobit přerušení služeb.
• Mitigation:
  • Před voláním ApplyTo(Object)ověřte příchozí dokumenty JSON Patch pro velikost a strukturu .
  • Ověření musí být specifické pro aplikaci, ale ukázkové ověření může vypadat nějak takto:

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();
    }
}

Podvracení obchodní logiky

• Scénář: Operace oprav můžou manipulovat s poli s implicitními invarianty (například s interními příznaky, ID nebo vypočítanými poli), porušením obchodních omezení.
• Dopad: Problémy s integritou dat a nezamýšlené chování aplikací
• Mitigation:
  • Použijte objekty POCOs (Plain Old CLR) s explicitně definovanými vlastnostmi, které jsou bezpečné k úpravě.
    • Vyhněte se zveřejnění citlivých nebo kritických vlastností zabezpečení v cílovém objektu.
    • Pokud se objekt POCO nepoužívá, ověřte po použití operací opravený objekt, abyste zajistili, že nedojde k porušení obchodních pravidel a invariantů.

Autentizace a autorizace

• Scénář: Neověřené nebo neautorizované klienty odesílají škodlivé požadavky na opravu JSON.
• Dopad: Neoprávněný přístup k úpravě citlivých dat nebo narušení chování aplikace
• Mitigation:
  • Ochrana koncových bodů, které přijímají žádosti o opravu JSON, pomocí správných mechanismů ověřování a autorizace
  • Omezte přístup k důvěryhodným klientům nebo uživatelům s příslušnými oprávněními.

Získání kódu

Zobrazení nebo stažení vzorového kódu (postup stahování).

Ukázku otestujete spuštěním aplikace a odesláním požadavků HTTP s následujícím nastavením:

• Adresa URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Metoda HTTP: PATCH
• Záhlaví: Content-Type: application/json-patch+json
• Text: Zkopírujte a vložte jednu z ukázek dokumentu opravy JSON ze složky projektu JSON .

Dodatečné zdroje

• Specifikace metody IETF RFC 5789 PATCH
• Specifikace oprav JSON IETF RFC 6902
• IETF RFC 6901 JSON Pointer
• zdrojový kód opravy JSON pro ASP.NET Core