JSON 모듈

JSON 모듈

JSON 모듈은 JSON 인코딩과 디코딩을 담당해요. 인코더와 디코더 모두 RFC 8259과 ECMA 404 표준을 완전히 따릅니다.

출처: JSON

본문

Elixir의 데이터를 JSON으로 인코딩할 때는 다음 표를 기준으로 매핑돼요.

인코딩

사용자 정의 데이터 구조는 JSON.Encoder 프로토콜을 구현해서 원하는 형태로 인코딩할 수 있어요. 몇몇 내장 데이터 구조는 이미 JSON.Encoder를 파생하고 있는데, 대표적으로 날짜·시간 계열이에요.

디코딩

JSON을 Elixir 타입으로 되돌릴 때는 아래 표처럼 매핑돼요.

주요 타입

@type decode_error_reason() ::
  {:unexpected_end, non_neg_integer()}
  | {:invalid_byte, non_neg_integer(), byte()}
  | {:unexpected_sequence, non_neg_integer(), binary()}

@type encoder() :: (term(), encoder() -> iodata())

디코딩 동작을 사용자 정의하기 위한 decoders() 타입도 제공돼요. 배열·객체의 시작/푸시/마무리 콜백과 float, integer, string, null 처리 함수를 지정할 수 있어요. 모두 선택 사항이고, 지정하지 않으면 decode/1이 쓰는 기본 구현으로 폴백합니다.

decode/1

@spec decode(binary()) :: {:ok, term()} | {:error, decode_error_reason()}

주어진 JSON을 디코딩해요. {:ok, decoded} 또는 {:error, reason}을 돌려줍니다.

iex> JSON.decode("[null,123,\"string\",{\"key\":\"value\"}]")
{:ok, [nil, 123, "string", %{"key" => "value"}]}

에러 튜플은 다음 이유 중 하나를 가져요.

• {:unexpected_end, offset} — binary에 불완전한 JSON 값이 들어 있는 경우
• {:invalid_byte, offset, byte} — 예상 밖의 바이트 또는 잘못된 UTF-8 바이트가 있는 경우
• {:unexpected_sequence, offset, bytes} — 잘못된 UTF-8 이스케이프가 있는 경우

decode/2

@spec decode(binary(), term(), decoders()) ::
  {term(), term(), binary()} | {:error, decode_error_reason()}

주어진 디코더와 함께 JSON을 디코딩해요. {decoded, acc, rest} 또는 {:error, reason}을 돌려줍니다. 스트리밍 디코딩이 필요하면 Erlang의 :json 모듈을 참고하세요.

decode!/1

@spec decode!(binary()) :: term()

주어진 JSON을 디코딩하되, 오류가 있으면 예외를 던져요.

iex> JSON.decode!("[null,123,\"string\",{\"key\":\"value\"}]")
[nil, 123, "string", %{"key" => "value"}]

encode!/2

@spec encode!(term(), encoder()) :: binary()

주어진 term을 JSON 바이너리로 인코딩해요. 두 번째 인자는 term을 재귀적으로 인코딩하기 위해 호출되는 함수예요.

iex> JSON.encode!([123, "string", %{key: "value"}])
"[123,\"string\",{\"key\":\"value\"}]"

💡 네트워크로 보내거나 파일시스템에 저장할 JSON이라면 더 효율적인 encode_to_iodata!/2를 고려해 보세요.

encode_to_iodata!/2

@spec encode_to_iodata!(term(), encoder()) :: iodata()

주어진 term을 JSON iodata로 인코딩해요. IO 목적으로 JSON을 쓸 거라면 가장 효율적인 형식이에요.

iex> data = JSON.encode_to_iodata!([123, "string", %{key: "value"}])
iex> IO.iodata_to_binary(data)
"[123,\"string\",{\"key\":\"value\"}]"

protocol_encode/2

@spec protocol_encode(term(), encoder()) :: iodata()

encode!/1에 전달되는 기본 인코딩 구현이에요. 보통 encode!/2, encode_to_iodata!/2의 두 번째 인자로 넘기며, 기본 구현은 JSON.Encoder 프로토콜로 최적화된 디스패치입니다.

더 알아보기

• JSON.Encoder 프로토콜: 사용자 정의 데이터 구조를 JSON으로 인코딩하는 방법
• JSON.decode!/1: 디코딩 실패 시 던져지는 JSON.DecodeError
• :json 모듈(Erlang): 스트리밍 JSON 디코딩