Version: 5.3
소셜 API
스트리밍 에셋

JSON 직렬화

JSON 직렬화는 오브젝트와 JSON 포맷을 상호 변환하는 기능입니다. 이 기능은 웹 서비스와 상호작용할 때 유용하거나 단순히 데이터를 텍스트 기반 포맷으로 간편하게 패킹하고 언패킹하는 데 유용할 수 있습니다.

JsonUtility 클래스에 대한 내용은 Unity ScriptRef JsonUtility 페이지를 참조하십시오.

간단한 사용법

JSON 직렬화 기능은 ‘구조화된’ JSON의 개념을 중심으로 개발되었습니다. 즉, 사용자가 클래스나 구조체를 만들어서 JSON 데이터에 저장할 변수를 기술합니다. 예제:

[Serializable]
public class MyClass
{
    public int level;
    public float timeElapsed;
    public string playerName;
}

위 예에서는 세 개의 변수인 level, timeElapsedplayerName 이 포함된 일반 C# 클래스를 정의하고 시리얼라이저블이라고 표시합니다. 이렇게 해야 JSON 시리얼라이저를 사용하여 작업할 수 있습니다. 다음, 해당 클래스의 인스턴스를 다음과 같이 만들 수 있습니다.

MyClass myObject = new MyClass();
myObject.level = 1;
myObject.timeElapsed = 47.5f;
myObject.playerName = "Dr Charles Francis";

그리고 JsonUtility.ToJson을 사용하여 인스턴스를 JSON 포맷으로 직렬화합니다.

string json = JsonUtility.ToJson(myObject);

그러면 다음 문자열이 포함된 json 변수가 생성됩니다.

{"level":1,"timeElapsed":47.5,"playerName":"Dr Charles Francis"}

JSON을 다시 오브젝트로 변환하려면 JsonUtility.FromJson을 사용합니다.

myObject = JsonUtility.FromJson<MyClass>(json);

그러면 MyClass의 새 인스턴스가 생성되고 JSON 데이터를 사용하여 인스턴스의 값이 설정됩니다. JSON 데이터에 MyClass의 필드와 매핑되지 않는 값이 있으면 무시되고, JSON 데이터에 MyClass 필드의 값이 없는 경우 해당 필드의 값은 반환된 오브젝트의 구성된 값으로 유지됩니다.

JSON 시리얼라이저는 현재 ‘비구조화된’(즉 JSON을 임의의 키-값 쌍 트리로 탐색하고 편집하는) JSON을 지원하지 않습니다. 비구조화된 JSON을 사용해야 하는 경우, 기능이 더 완전한 JSON 라이브러리를 찾아야 합니다.

JSON으로 오브젝트 덮어쓰기

JSON 데이터를 이미 생성된 오브젝트 ‘위’에 역직렬화하여 이미 존재하는 데이터를 덮어쓸 수 있습니다.

JsonUtility.FromJsonOverwrite(json, myObject);

JSON에 값이 없는 오브젝트의 필드는 변경되지 않고 유지됩니다. 이 메서드를 통해 이전에 만든 오브젝트를 재사용하여 할당을 최소한으로 유지하고, 의도적으로 오브젝트를 필드의 작은 부분 집합만 포함된 JSON으로 덮어써서 ‘패치’할 수도 있습니다.

JSON 시리얼라이저 API는 MonoBehaviourScriptableObject 서브클래스뿐만 아니라 일반 구조체/클래스도 지원합니다. 하지만 JSON을 MonoBehaviour 또는 ScriptableObject의 서브클래스로 역직렬화하는 경우 FromJsonOverwrite를 반드시 사용해야 합니다. FromJson은 지원되지 않고 예외를 발생시킵니다.

지원되는 타입

API는 MonoBehaviour 서브클래스, ScriptableObject 서브 클래스, 또는 [Serializable] 속성이 있는 일반 클래스/구조체를 지원합니다. 사용자가 전달하는 오브젝트는 스탠다드 Unity 시리얼라이저에 공급되어 처리되므로, 인스펙터에서 적용되는 규칙과 제한이 동일하게 적용됩니다. 즉 필드만 직렬화되고 Dictionary&lt;&gt; 같은 타입은 지원되지 않습니다.

예를 들어 프리미티브 타입 또는 배열 등 다른 타입을 API에 직접 전달하는 기능은 현재 지원되지 않습니다. 지금은 이러한 타입을 일종의 class 또는 struct에 래핑해야 합니다.

에디터에만 EditorJsonUtility라는 병렬 API가 있습니다. API는 UnityEngine.Object에서 파생된 타입을 JSON과 상호 직렬화하기 위해 사용할 수 있습니다. 그러면 오브젝트의 YAML 표현과 동일한 데이터가 포함된 JSON이 생성됩니다.

성능

벤치마크 테스트에서는 JsonUtility가 인기 .NET JSON 솔루션에 비해(일부 솔루션보다 기능이 더 적기는 하지만) 훨씬 빠른 것으로 나타났습니다.

GC 메모리는 최소한만 사용됩니다.

  • ToJson()은 반환된 문자열에만 GC 메모리를 할당합니다.
  • FromJson()은 반환된 오브젝트와 필요한 하위 오브젝트에만 GC 메모리를 할당합니다. 예를 들어 배열이 포함된 오브젝트를 역직렬화하면 배열을 위한 GC 메모리가 할당됩니다.
  • FromJsonOverwrite()는 문자열 또는 배열 등 작성된 필드에 필요한 GC 메모리만 할당합니다. JSON이 덮어쓰는 모든 필드가 값 타입이면 GC 메모리를 할당하지 않습니다.

백그라운드 스레드에서 JsonUtility API를 사용하는 것은 허용됩니다. 다른 멀티스레드 코드와 마찬가지로, 오브젝트가 스레드에서 직렬화/역직렬화 중인 동안 다른 스레드에서 오브젝트를 수정하거나 액세스하지 않게 주의해야 합니다.

ToJson()의 출력 제어

ToJson은 JSON 출력을 보기 좋게 출력하는 기능을 지원합니다. 이 기능은 기본적으로 꺼져 있지만, true를 두 번째 파라미터로 전달하여 켤 수 있습니다.

[NonSerialized] 속성을 사용하여 필드를 출력에서 생략할 수 있습니다.

타입을 미리 알 수 없는 경우 FromJson() 사용

JSON을 ‘common’ 필드가 포함된 클래스나 구조체로 역직렬화한 다음 해당 필드의 값을 사용하여 원하는 실제 타입을 정한 후 해당 타입으로 다시 역직렬화할 수 있습니다.

소셜 API
스트리밍 에셋