JSON-javítás támogatása a ASP.NET Core webes API-ban

Ez a cikk bemutatja, hogyan kezelheti a JSON-javítás kéréseit egy ASP.NET Core webes API-ban.

A JSON Patch támogatása a ASP.NET Core webes API-ban szerializáláson System.Text.Json alapul, és a Microsoft.AspNetCore.JsonPatch.SystemTextJson NuGet-csomagot igényli.

Mi a JSON Patch szabvány?

A JSON-javítás szabványa:

• A JSON-dokumentumokra alkalmazandó módosítások leírásának szabványos formátuma.

• Az RFC 6902-ben van definiálva, és széles körben használják a RESTful API-kban a JSON-erőforrások részleges frissítéséhez.

• A JSON-dokumentumokat módosító műveletek sorozatát ismerteti, például:

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

A webalkalmazásokban a JSON-javítást gyakran használják a PATCH műveletben az erőforrás részleges frissítéséhez. Ahelyett, hogy a teljes erőforrást elküldené egy frissítéshez, az ügyfelek küldhetnek egy JSON Patch-dokumentumot, amely csak a módosításokat tartalmazza. A javítás csökkenti a hasznos adatok méretét és javítja a hatékonyságot.

A JSON-javítás szabványának áttekintéséhez tekintse meg a jsonpatch.com.

JSON-javítás támogatása a ASP.NET Core webes API-ban

A JSON Patch támogatása az ASP.NET Core webes API-ban a System.Text.Json szerializáláson alapul, és a .NET 10-től kezdve a Microsoft.AspNetCore.JsonPatch szerializáláson alapuló System.Text.Json implementálást valósítja meg. Ez a funkció:

• A NuGet-csomag Microsoft.AspNetCore.JsonPatch.SystemTextJson szükséges.
• A .NET-hez optimalizált kódtár használatával igazodik a System.Text.Json modern .NET-eljárásokhoz.
• Jobb teljesítményt és kevesebb memóriahasználatot biztosít az örökölt Newtonsoft.Jsonimplementációhoz képest. Az örökölt Newtonsoft.Jsonimplementációval kapcsolatos további információkért tekintse meg a cikk .NET 9-es verzióját.

Note

A Microsoft.AspNetCore.JsonPatch-alapú szerializáción alapuló System.Text.Json implementáció nem helyettesíti a régi Newtonsoft.Json-alapú implementációt. Nem támogatja például ExpandoObjecta dinamikus típusokat.

Important

A JSON Patch szabvány belső biztonsági kockázatokkal jár. Mivel ezek a kockázatok a JSON Patch szabványhoz tartoznak, a ASP.NET Core-implementáció nem próbálja csökkenteni az eredendő biztonsági kockázatokat. A fejlesztő felelőssége annak biztosítása, hogy a JSON Patch-dokumentum biztonságosan alkalmazható legyen a célobjektumra. További információ: A biztonsági kockázatok mérséklése szakasz.

A JSON-javítás támogatásának engedélyezése System.Text.Json

A JSON-javítás támogatásának System.Text.Jsonengedélyezéséhez telepítse a Microsoft.AspNetCore.JsonPatch.SystemTextJson NuGet-csomagot.

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

Ez a csomag egy JsonPatchDocument<TModel> osztályt biztosít a JSON Patch dokumentumok T típusú objektumokhoz való reprezentálásához, valamint egyedi logikát a JSON Patch dokumentumok System.Text.Json szerializálásához és deszerializálásához. A JsonPatchDocument<TModel> osztály kulcsmetódusa a ApplyTo(Object), amely a javításműveleteket egy T típusú célobjektumra alkalmazza.

A JSON-javítást alkalmazó műveletmetódus kódja

Egy API-vezérlőben a JSON-javítás műveletmetódusa:

• A(z) HttpPatchAttribute attribútummal van megjelölve.
• Elfogad egy JsonPatchDocument<TModel>, általában a FromBodyAttribute.
• A módosítások alkalmazásához ApplyTo(Object) hívja meg a módosítási dokumentumot.

Példa vezérlőműveleti módszerre:

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

A mintaalkalmazásból származó kód a következőkkel Customer és Order modellekkel működik:

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

A mintaműveleti módszer fő lépései:

• Kérje le az ügyfelet:
  • A metódus egy Customer objektumot kér le az adatbázisból AppDb a megadott azonosító használatával.
  • Ha nem található Customer objektum, 404 Not Found választ ad.
• JSON-javítás alkalmazása:
  • A ApplyTo(Object) metódus a patchDoc JSON Patch-műveleteit alkalmazza a lekért Customer objektumra.
  • Ha a javításalkalmazás során hibák lépnek fel, például érvénytelen műveletek vagy ütközések, a hibakezelő meghatalmazott rögzíti őket. Ez a meghatalmazott hibaüzeneteket ad hozzá az ModelState érintett objektum típusnevének és a hibaüzenetnek a használatával.
• ModelState ellenőrzése:
  • A javítás alkalmazása után a metódus ellenőrzi a ModelState hibákat.
  • Ha a ModelState érvénytelen, például javítási hibák miatt, akkor 400 Bad Request választ ad vissza az érvényesítési hibákkal.
• Visszatéríti a frissített ügyfelet:
  • Ha a javítás sikeresen alkalmazva van, és az ModelState érvényes, a metódus visszaadja a frissített Customer objektumot a válaszban.

Példa hibaválasz:

Az alábbi példa egy JSON-javításművelet válaszának törzsét 400 Bad Request mutatja be, ha a megadott elérési út érvénytelen:

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

JSON Patch-dokumentum alkalmazása objektumra

Az alábbi példák bemutatják, hogyan alkalmazhat JSON Patch-dokumentumot egy objektumra a ApplyTo(Object) metódus használatával.

Példa: Alkalmazzon egy JsonPatchDocument<TModel> egy objektumra

Az alábbi példa a következőket mutatja be:

• A add, replace és remove műveletek.
• Műveletek beágyazott tulajdonságokon.
• Új elem hozzáadása tömbhöz.
• JSON-sztring Enum-konverter használata egy JSON módosító dokumentumban.

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

Az előző példa a frissített objektum következő kimenetét eredményezi:

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

A ApplyTo(Object) módszer általában a System.Text.Json konvencióit és lehetőségeit követi az JsonPatchDocument<TModel> feldolgozásához, beleértve a következő beállítások által szabályozott viselkedést is:

• JsonNumberHandling: Azt jelzi, hogy a numerikus tulajdonságok sztringekből vannak-e beolvasva.
• PropertyNameCaseInsensitive: A tulajdonságnevek megkülönböztetik-e a kis- és nagybetűket.

Főbb különbségek a System.Text.Json és az új JsonPatchDocument<TModel> implementáció között:

• A célobjektum futásidejű típusa, nem a deklarált típus határozza meg, hogy mely tulajdonságokra vonatkoznak a ApplyTo(Object) módosítások.
• System.Text.Json A deszerializálás a deklarált típusra támaszkodik a jogosult tulajdonságok azonosításához.

Példa: JsonPatchDocument alkalmazása hibakezeléssel

A JSON-javítás dokumentumainak alkalmazásakor különböző hibák léphetnek fel. Előfordulhat például, hogy a célobjektum nem rendelkezik a megadott tulajdonsággal, vagy a megadott érték nem kompatibilis a tulajdonságtípussal.

A JSON Patch támogatja a test műveletet, amely ellenőrzi, hogy egy megadott érték megegyezik-e a céltulajdonságokkal. Ha nem, hibát ad vissza.

Az alábbi példa bemutatja, hogyan kezelheti ezeket a hibákat elegánsan.

Important

A metódusnak ApplyTo(Object) átadott objektum a helyén módosul. Ha egy művelet meghiúsul, a hívó felelős a módosítások elvetéséért.

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

Az előző példa a következő kimenetet eredményezi:

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

A biztonsági kockázatok mérséklése

A csomag használatakor Microsoft.AspNetCore.JsonPatch.SystemTextJson kritikus fontosságú a lehetséges biztonsági kockázatok megértése és csökkentése. A következő szakaszok ismertetik a JSON-javításhoz kapcsolódó azonosított biztonsági kockázatokat, és ajánlott megoldásokat nyújtanak a csomag biztonságos használatának biztosítása érdekében.

Important

Ez nem a fenyegetések teljes listája. Az alkalmazásfejlesztőknek saját fenyegetésmodell-felülvizsgálatokat kell végezniük az alkalmazásspecifikus átfogó lista meghatározásához, és szükség szerint megfelelő megoldásokat kell készíteniük. Például azoknak az alkalmazásoknak, amelyek javításműveleteknek teszik ki a gyűjteményeket, figyelembe kell venniük az algoritmikus összetettségi támadások lehetőségét, ha ezek a műveletek elemeket szúrnak be vagy távolítanak el a gyűjtemény elején.

A JSON Patch funkcióinak alkalmazásba való integrálása során felmerülő biztonsági kockázatok minimalizálása érdekében a fejlesztőknek a következőkkel kell rendelkezniük:

• Futtasson átfogó fenyegetésmodelleket saját alkalmazásaikhoz.
• Elhárítja az azonosított fenyegetéseket.
• Kövesse az alábbi szakaszokban javasolt intézkedéseket.

Szolgáltatásmegtagadás (DoS) memóriaerősítéssel

• Forgatókönyv: Egy rosszindulatú ügyfél olyan műveletet küld, copy amely többször duplikálja a nagy objektumdiagramokat, ami túlzott memóriahasználathoz vezet.
• Hatás: Lehetséges kimenőOf-Memory (OOM) feltételek, ami szolgáltatáskimaradásokat okoz.
• Mitigation:
  • Ellenőrizze a bejövő JSON Patch-dokumentumokat a méret és a struktúra szempontjából, mielőtt hívja a ApplyTo(Object)-t.
  • Az érvényesítésnek alkalmazásspecifikusnak kell lennie, de egy példaérvényesítés a következőhöz hasonló lehet:

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

Üzleti logika megváltoztatása

• Forgatókönyv: A javításműveletek implicit invariánsokkal (például belső jelzőkkel, azonosítókkal vagy számított mezőkkel) módosíthatják a mezőket, megsértve az üzleti korlátozásokat.
• Hatás: Adatintegritási problémák és nem szándékos alkalmazás viselkedése.
• Mitigation:
  • Használjon POCOS-objektumokat (egyszerű régi CLR-objektumokat) explicit módon definiált, biztonságosan módosítható tulajdonságokkal.
    • Kerülje a bizalmas vagy biztonsági szempontból kritikus tulajdonságok felfedését a célobjektumban.
    • Ha nem használ POCO-objektumot, ellenőrizze a javított objektumot a műveletek alkalmazása után annak érdekében, hogy az üzleti szabályok és az invariánsok ne sérüljenek.

Hitelesítés és engedélyezés

• Forgatókönyv: A nem hitelesített vagy jogosulatlan ügyfelek rosszindulatú JSON-javításkéréseket küldenek.
• Hatás: Jogosulatlan hozzáférés bizalmas adatok módosításához vagy az alkalmazás viselkedésének megzavarásához.
• Mitigation:
  • A JSON Patch-kéréseket elfogadó végpontok védelme megfelelő hitelesítési és engedélyezési mechanizmusokkal.
  • Korlátozza a hozzáférést a megbízható ügyfelekhez vagy a megfelelő engedélyekkel rendelkező felhasználókhoz.

A kód lekérése

Mintakód megtekintése vagy letöltése. (A letöltés módja).

A minta teszteléséhez futtassa az alkalmazást, és küldjön HTTP-kéréseket a következő beállításokkal:

• URL-cím: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• HTTP-metódus: PATCH
• Fejléc: Content-Type: application/json-patch+json
• Törzs: Másolja és illessze be a JSON-javítás dokumentummintáinak egyikét a JSON projektmappából.

További erőforrások

• IETF RFC 5789 PATCH metódus specifikáció
• IETF RFC 6902 JSON Patch specifikáció
• IETF RFC 6901 JSON mutató
• ASP.NET Core JSON-javítás forráskódja