ASP.NET Core Web API의 JSON 패치 지원

이 문서에서는 ASP.NET Core Web API에서 JSON 패치 요청을 처리하는 방법을 설명합니다.

ASP.NET Core Web API에서 JSON 패치 지원은 System.Text.Json 직렬화를 기반으로 하며, Microsoft.AspNetCore.JsonPatch.SystemTextJson NuGet 패키지가 필요합니다.

JSON 패치 표준이란?

JSON 패치 표준:

• JSON 문서에 적용할 변경 내용을 설명하는 표준 형식입니다.

• RFC 6902에 정의되며 JSON 리소스에 대한 부분 업데이트를 수행하기 위해 RESTful API에서 널리 사용됩니다.

• 다음과 같이 JSON 문서를 수정하는 작업 시퀀스를 설명합니다.

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

웹앱에서 JSON 패치는 일반적으로 PATCH 작업에서 리소스의 부분 업데이트를 수행하는 데 사용됩니다. 클라이언트는 업데이트를 위해 전체 리소스를 보내는 대신 변경 내용만 포함하는 JSON 패치 문서를 보낼 수 있습니다. 패치를 사용하면 페이로드 크기가 줄어들고 효율성이 향상됩니다.

JSON 패치 표준에 대한 개요는 jsonpatch.com 참조하세요.

ASP.NET Core Web API의 JSON 패치 지원

ASP.NET Core Web API의 JSON 패치 지원은 .NET 10부터 System.Text.Json 직렬화를 기반으로 Microsoft.AspNetCore.JsonPatch을 구현하며 System.Text.Json 직렬화를 기반으로 합니다. 이 기능은 다음과 같습니다.

• NuGet 패키지가 Microsoft.AspNetCore.JsonPatch.SystemTextJson 필요합니다.
• System.Text.Json 라이브러리를 활용하여 최신 .NET 관행에 부합하며, .NET에 최적화되었습니다.
• 레거시 Newtonsoft.Json기반 구현에 비해 향상된 성능과 메모리 사용량을 제공합니다. 레거시 Newtonsoft.Json기반 구현에 대한 자세한 내용은 이 문서의 .NET 9 버전을 참조하세요.

Note

Microsoft.AspNetCore.JsonPatch 기반 serialization 구현인 System.Text.Json는 레거시 Newtonsoft.Json 기반 구현의 직접적인 대체가 아닙니다. 예를 들어 ExpandoObject동적 형식은 지원하지 않습니다.

Important

JSON 패치 표준에는 고유한 보안 위험이 있습니다. 이러한 위험은 JSON 패치 표준에 내재되어 있으므로 ASP.NET Core 구현은 내재된 보안 위험을 완화하려고 시도하지 않습니다. JSON 패치 문서가 대상 개체에 안전하게 적용되도록 하는 것은 개발자의 책임입니다. 자세한 내용은 보안 위험 완화 섹션을 참조하세요 .

System.Text.Json로 JSON 패치 지원을 활성화하다

JSON 패치 지원을 System.Text.Json 사용하도록 설정하려면 Microsoft.AspNetCore.JsonPatch.SystemTextJson NuGet 패키지를 설치합니다.

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

이 패키지는 JsonPatchDocument<TModel> 형식의 개체에 대한 JSON 패치 문서를 나타내는 클래스와 T를 사용하여 JSON 패치 문서를 직렬화 및 역직렬화하기 위한 사용자 지정 논리를 제공합니다. JsonPatchDocument<TModel> 클래스의 핵심 메서드는 ApplyTo(Object) 형식의 대상 객체에 패치 작업을 적용하는 T입니다.

JSON 패치를 적용하는 작업 메서드 코드

API 컨트롤러에서 JSON 패치의 작업 메서드는 다음과 같습니다.

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

샘플 작업 메서드의 주요 단계는 다음과 같습니다.

• 고객 검색:
  • 메서드는 제공된 ID를 Customer 사용하여 데이터베이스 AppDb 에서 개체를 검색합니다.
  • 개체Customer가 없으면 404 Not Found 응답을 반환합니다.
• JSON 패치 적용:
  • 이 메서드는 ApplyTo(Object) patchDoc의 JSON 패치 작업을 검색된 Customer 개체에 적용합니다.
  • 잘못된 작업 또는 충돌과 같은 패치 애플리케이션 중에 오류가 발생하면 오류 처리 대리자로 캡처됩니다. 이 대리자는 영향을 받는 개체의 형식 이름과 오류 메시지를 사용하여 ModelState에 오류 메시지를 추가합니다.
• ModelState 유효성 검사:
  • 패치를 적용한 후, 메서드는 ModelState의 오류를 확인합니다.
  • ModelState 패치 오류와 같이 잘못된 경우 유효성 검사 오류가 있는 400 Bad Request 응답을 반환합니다.
• 업데이트된 고객을 반환합니다.
  • 패치가 성공적으로 적용되고 ModelState 유효한 경우 메서드는 응답에서 업데이트 Customer 된 개체를 반환합니다.

오류 응답 예제:

다음 예제에서는 지정된 경로가 400 Bad Request 잘못된 경우 JSON 패치 작업에 대한 응답 본문을 보여 줍니다.

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

개체에 JSON 패치 문서 적용

다음 예제에서는 메서드를 사용하여 개체에 ApplyTo(Object) JSON 패치 문서를 적용하는 방법을 보여 줍니다.

예: 개체에 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 큰 개체 그래프를 여러 번 복제하여 과도한 메모리 소비를 초래하는 작업을 제출합니다.
• 영향: OOM(잠재적 아웃-Of-Memory) 조건으로 인해 서비스 중단이 발생합니다.
• 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();
    }
}

비즈니스 논리 전복

• 시나리오: 패치 작업은 내부 플래그, ID, 계산된 필드와 같은 암시적 불변성을 가진 필드를 조작함으로써, 비즈니스 제약 조건을 위반할 수 있습니다.
• 영향: 데이터 무결성 문제 및 의도하지 않은 앱 동작.
• Mitigation:
  • 수정해도 안전한 명시적으로 정의된 속성과 함께 POCO(일반 이전 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 패치 사양
• IETF RFC 6901 JSON 포인터
• ASP.NET Core JSON 패치 소스 코드