C++ JSON 파싱: nlohmann/json vs RapidJSON, 커스텀 타입 직렬화, null·타입 에러 처리

들어가며: 필드 접근 한 줄에서 터지는 크래시

HTTP 클라이언트로 API 응답을 받았다면 다음 단계는 문자열을 C++ 값으로 옮기는 일입니다. 이 단계에서 생기는 문제는 대부분 몇 가지 유형으로 묶입니다. API가 "age": 30(숫자)과 "age": "30"(문자열)을 섞어 보내면 get<int>()가 type_error를 던집니다. 비-const json에서 j["optional"]로 없는 키를 읽으면 null이 삽입되고, 이후 get<T>()에서 역시 type_error가 납니다. 쉼표가 빠지거나 따옴표가 닫히지 않은 입력은 parse_error가 되고, 큰 문서를 통째로 DOM으로 만들면 원본 텍스트보다 훨씬 많은 메모리를 씁니다. User, Config 같은 구조체와 JSON 사이를 손으로 변환하는 코드는 번거롭고 실수하기 쉽습니다.

이 글은 nlohmann/json과 RapidJSON으로 REST API 응답과 설정 파일을 파싱하는 예제를 중심으로, contains·value·at을 이용한 안전한 접근, to_json/from_json을 이용한 구조체·enum·optional 직렬화, 파싱 에러와 타입 에러의 구분, 대용량 입력을 위한 SAX 방식, 두 라이브러리의 성능 차이를 다룹니다.


전형적인 실패 패턴과 안전한 파싱 구조

전형적인 실패 패턴

sequenceDiagram
  participant App as 애플리케이션
  participant HTTP as HTTP 클라이언트
  participant API as 외부 API
  App->>HTTP: GET /api/users
  HTTP->>API: 요청
  API-->>HTTP: {"data": [{"id": 1, "name": "Alice"}]}
  HTTP-->>App: body (문자열)
  Note over App: 파싱 필요
  App->>App: json::parse(body)
  Note over App: j[data][0][age] 접근\nage 키 없음 → null
  App->>App: .get<int>() → type_error!

HTTP 응답 본문은 문자열이므로 구조화된 데이터로 바꾸는 단계가 반드시 필요하고, 키 누락·null·타입 불일치는 이 단계에서 런타임 예외로 드러납니다. strstr이나 정규식으로 직접 파싱하는 방법은 이스케이프와 중첩을 제대로 처리하기 어려워 처음부터 고려하지 않는 편이 낫습니다.

API 버전마다 다른 응답 구조

같은 유형의 실패는 여러 모습으로 나타납니다. API v1은 {"user": {"name": "Alice"}}를, v2는 {"user": null}을 반환한다면 j["user"]["name"]은 v2 응답에서 null 값에 문자열 키로 접근하게 되어 type_error가 납니다. 새 버전에서 config.json에 timeout 필드가 추가됐는데 구버전 설정 파일에는 없다면, 비-const json에서 j["timeout"].get<int>()는 null을 삽입한 뒤 type_error를 던집니다. 어떤 엔드포인트는 "count": 100을, 다른 엔드포인트는 "count": "100"을 보내는 경우도 타입 검증 없이 get<int>()만 쓰면 실패합니다.

큰 JSON 로그를 std::string으로 읽어 parse()하면 원본 문자열과 DOM이 동시에 메모리에 올라가고, DOM은 노드마다 별도 할당을 하므로 원본보다 몇 배 커질 수 있습니다. 필요한 필드만 뽑는다면 SAX 방식이 맞습니다. 여러 스레드가 같은 json 객체를 다루는 경우에는, 읽기처럼 보이는 operator[] 호출이 실제로는 삽입을 일으켜 data race가 생길 수 있으므로 파싱 결과를 불변으로 유지하거나 스레드별로 복사해야 합니다.

이 문제들의 공통점은 JSON이 스키마가 없는 포맷이라는 것입니다. C++ 구조체는 컴파일 시점에 필드와 타입이 정해져 있지만, 네트워크에서 온 JSON은 무엇이든 될 수 있습니다. 그래서 JSON 파싱 코드의 본질은 문법 해석보다 “신뢰할 수 없는 입력을 타입이 정해진 C++ 값으로 옮기는 경계 검사”에 있습니다. 이 경계를 한 곳(from_json 함수나 파싱 계층)에 모아 두면, 나머지 코드는 이미 검증된 구조체만 다루면 되므로 contains 검사가 코드 전체에 흩어지지 않습니다.

해결 아키텍처

flowchart TB
  subgraph 입력
    A[HTTP 응답 문자열]
    B[파일 스트림]
    C[소켓 버퍼]
  end
  subgraph 파싱
    D{라이브러리}
    D --> E[nlohmann/json]
    D --> F[RapidJSON]
    E --> G[json 객체]
    F --> G
  end
  subgraph 검증
    G --> H[contains/value 체크]
    H --> I[타입 검증 is_*]
    I --> J[커스텀 타입 변환]
  end
  subgraph 출력
    J --> K[구조체]
    J --> L[비즈니스 로직]
  end
  A --> D
  B --> D
  C --> D

라이브러리 비교: nlohmann vs RapidJSON

항목nlohmann/jsonRapidJSON
헤더 전용OO
API 스타일STL 유사, 직관적명시적, 할당자를 직접 다룸
성능상대적으로 느림빠름
메모리상대적으로 많음적음 (풀 할당자, in-situ 파싱)
커스텀 직렬화to_json/from_json 간편수동 구현
에러 처리예외 기반 (옵션으로 끌 수 있음)반환값 + HasParseError, 접근 오류는 assert
C++ 표준C++11 이상C++03에서도 동작 (C++11 기능은 선택)
추천 용도REST API, 설정, 프로토타입처리량이 중요한 서버, 대용량, 임베디드

개발 속도와 가독성이 우선인 대부분의 웹 API·설정 파싱에는 nlohmann이 맞고, 파싱 처리량이 실제로 문제가 되거나 메모리가 제한된 환경, 로그 파이프라인에는 RapidJSON이 맞습니다.

두 라이브러리의 속도 차이는 설계에서 나옵니다. nlohmann의 json 값은 객체를 std::map(기본), 배열을 std::vector, 문자열을 std::string으로 담으므로 노드마다 힙 할당이 생깁니다. 그 대가로 STL 컨테이너처럼 쓰고, 복사·비교·to_json 확장이 자연스럽습니다. RapidJSON은 Document마다 메모리 풀 할당자를 두고 값을 그 안에 촘촘히 배치하며, 옵션에 따라 입력 버퍼를 제자리에서 수정하는 in-situ 파싱도 지원합니다. 대신 값의 수명이 할당자에 묶이고, 문자열을 추가할 때마다 alloc을 넘겨야 하며, 복사 대신 이동(move) 의미론이 기본이라 실수하기 쉽습니다.

한 가지 더 알아 둘 점은 nlohmann의 기본 객체 타입이 std::map이라 키가 사전순으로 정렬된다는 것입니다. dump() 결과의 키 순서가 입력과 다르다며 당황하는 경우가 많은데, 입력 순서를 유지해야 하면 nlohmann::ordered_json을 쓰면 됩니다(조회는 조금 느려집니다).


nlohmann/json으로 안전하게 파싱하기

설치

# vcpkg
vcpkg install nlohmann-json
# 또는 FetchContent (CMake)
# include(FetchContent)
# FetchContent_Declare(json GIT_REPOSITORY https://github.com/nlohmann/json.git GIT_TAG v3.11.2)
# FetchContent_MakeAvailable(json)

기본 파싱: 문자열·파일

// 복사해 붙여넣은 뒤: g++ -std=c++17 -o json_parse json_parse.cpp -I<경로> && ./json_parse
#include <nlohmann/json.hpp>
#include <fstream>
#include <iostream>
#include <string>
using json = nlohmann::json;
int main() {
    // 1. 문자열 파싱
    std::string str = R"({"name": "Alice", "age": 30, "tags": ["admin", "user"]})";
    json j = json::parse(str);
    std::string name = j["name"].get<std::string>();
    int age = j["age"].get<int>();
    std::cout << name << ", " << age << "\n";  // Alice, 30
    // 2. 배열 순회
    for (auto& tag : j["tags"]) {
        std::cout << tag.get<std::string>() << " ";
    }
    std::cout << "\n";  // admin user
    // 3. 파일 파싱 (config.json)
    std::ifstream f("config.json");
    if (f) {
        json config = json::parse(f);
        int port = config.value("port", 8080);  // 기본값 8080
        std::string host = config.value("host", "localhost");
        std::cout << "port=" << port << ", host=" << host << "\n";
    }
    return 0;
}

안전한 접근 패턴

#include <nlohmann/json.hpp>
#include <iostream>
using json = nlohmann::json;
void safe_access_example(const json& j) {
    // ❌ 위험: 키가 없으면 null 삽입
    // auto v = j["optional_key"];
    // ✅ contains로 존재 확인
    if (j.contains("optional_key")) {
        auto v = j["optional_key"];
        std::cout << v << "\n";
    }
    // ✅ value로 기본값 지정 (키가 없을 때만 default 반환,
    //    키가 있는데 null이나 다른 타입이면 type_error 예외)
    int timeout = j.value("timeout", 30);
    std::string env = j.value("env", "development");
    // ✅ at(): 키 없으면 out_of_range 예외 (검증 필요 시)
    try {
        std::string required = j.at("required_field").get<std::string>();
    } catch (const json::out_of_range& e) {
        std::cerr << "필수 필드 누락: " << e.what() << "\n";
    }
    // ✅ find로 이터레이터 사용
    auto it = j.find("maybe_null");
    if (it != j.end() && !it->is_null()) {
        int val = it->get<int>();
    }
}

네 가지 접근 방식은 “키가 없으면 어떻게 할 것인가”에 대한 서로 다른 답입니다. at()은 없는 것을 버그로 보고 예외를 던지므로 필수 필드에 맞고, value()는 없는 것을 정상으로 보고 기본값을 쓰므로 선택 설정에 맞습니다. find()는 존재 확인과 접근을 한 번의 탐색으로 끝내므로, contains() 후 operator[]로 다시 찾는 방식보다 효율적이고 null 검사까지 함께 할 수 있습니다.

가장 흔한 함정은 value()가 null을 처리해 준다고 믿는 것입니다. 실제로는 키가 없을 때만 기본값을 돌려주고, {"timeout": null}처럼 키가 있고 값이 null이면 int로 변환하다가 [json.exception.type_error.302] type must be number, but is null을 던집니다. 선택 필드를 null로 보내는 API가 의외로 많아서, 처음 외부 API를 붙일 때 이 예외로 서비스가 죽는 경우가 잦습니다. 누락과 null을 똑같이 기본값으로 처리하고 싶다면 find() 결과의 is_null()까지 확인하는 작은 도우미 함수를 만들어 두는 편이 안전합니다.

또 하나, 비-const json에서 j["key"]는 읽기처럼 보여도 쓰기 연산입니다. 키가 없으면 null 값을 삽입하므로, 로그를 찍으려고 j["debug"]를 한 번 읽었을 뿐인데 나중에 dump()한 결과에 "debug": null이 생기는 식의 부작용이 생깁니다. 파싱한 JSON을 const json&로 넘기는 습관을 들이면 이런 실수를 컴파일러가 막아 줍니다(const에서 없는 키를 operator[]로 접근하면 정의되지 않은 동작이므로, const 쪽에서는 at()이나 find()를 씁니다).

중첩 객체·배열 파싱

#include <nlohmann/json.hpp>
#include <iostream>
#include <vector>
using json = nlohmann::json;
struct UserSummary {
    int id;
    std::string name;
};
std::vector<UserSummary> parse_users_response(const std::string& body) {
    json j = json::parse(body);
    std::vector<UserSummary> users;
    // {"data": {"users": [{"id": 1, "name": "Alice"}, ...]}}
    if (!j.contains("data") || !j["data"].contains("users")) {
        return users;
    }
    for (auto& item : j["data"]["users"]) {
        if (!item.contains("id") || !item.contains("name")) continue;
        users.push_back({
            item["id"].get<int>(),
            item["name"].get<std::string>()
        });
    }
    return users;
}
int main() {
    std::string api_response = R"({
        "data": {
            "users": [
                {"id": 1, "name": "Alice"},
                {"id": 2, "name": "Bob"}
            ]
        }
    })";
    auto users = parse_users_response(api_response);
    for (const auto& u : users) {
        std::cout << u.id << ": " << u.name << "\n";
    }
    return 0;
}

에러 처리와 예외

#include <nlohmann/json.hpp>
#include <iostream>
#include <optional>
using json = nlohmann::json;
std::optional<json> safe_parse(const std::string& str) {
    try {
        return json::parse(str);
    } catch (const json::parse_error& e) {
        std::cerr << "JSON 파싱 오류: " << e.what() << "\n";
        std::cerr << "바이트 위치: " << e.byte << "\n";
        return std::nullopt;
    }
}
int main() {
    // 잘못된 JSON: 쉼표 누락
    std::string bad = R"({"a": 1 "b": 2})";
    auto j = safe_parse(bad);
    if (!j) {
        std::cout << "파싱 실패, 폴백 처리\n";
        return 1;
    }
    // 타입 에러 방지: is_* 검증
    json j2 = json::parse(R"({"age": "thirty"})");
    if (j2["age"].is_number_integer()) {
        int age = j2["age"].get<int>();
    } else {
        std::cout << "age가 숫자가 아님\n";
    }
    return 0;
}

nlohmann은 예외를 세 계열로 나눕니다. parse_error(문법 오류, e.byte로 위치 제공), type_error(타입이 맞지 않는 변환), out_of_range(at()에서 없는 키나 인덱스)입니다. 모두 json::exception을 상속하므로, 요청 하나를 처리하는 경계에서 json::exception을 한 번에 잡고 개별 에러는 로그에 남기는 구조가 일반적입니다. e.what() 메시지에는 [json.exception.type_error.302]처럼 에러 번호가 들어 있어 문서에서 원인을 찾기 쉽습니다.

예외 대신 반환값으로 실패를 처리하고 싶다면 json::parse(str, nullptr, false)처럼 세 번째 인자 allow_exceptions를 false로 주면 됩니다. 이 경우 실패 시 예외 대신 is_discarded()가 true인 값을 돌려주므로, 예외를 끈(-fno-exceptions) 빌드나 잘못된 입력이 흔한 경로에서 유용합니다. 다만 이 옵션은 파싱 단계만 해당하고 이후 get<T>()의 type_error는 여전히 예외입니다.

숫자 변환은 조용히 값을 바꿀 수 있다는 점도 기억해야 합니다. {"age": 30.7}에 get<int>()를 호출하면 예외 없이 30이 되고, int 범위를 넘는 정수도 경고 없이 잘립니다. 금액·ID처럼 정확성이 중요한 필드는 is_number_integer()와 범위를 직접 확인하거나 std::int64_t로 받는 편이 안전합니다.


RapidJSON으로 파싱하고 생성하기

설치

# vcpkg
vcpkg install rapidjson
# 또는 헤더만 복사: include/rapidjson 폴더를 프로젝트에

기본 파싱

// g++ -std=c++17 -o rapidjson_parse rapidjson_parse.cpp -I<경로> && ./rapidjson_parse
#include <rapidjson/document.h>
#include <rapidjson/error/en.h>
#include <iostream>
#include <string>
using namespace rapidjson;
int main() {
    const char* json = R"({"name": "Alice", "age": 30, "active": true})";
    Document doc;
    doc.Parse(json);
    if (doc.HasParseError()) {
        std::cerr << "파싱 오류: " << GetParseError_En(doc.GetParseError())
                  << " (offset: " << doc.GetErrorOffset() << ")\n";
        return 1;
    }
    // 객체인지 확인
    if (!doc.IsObject()) {
        std::cerr << "JSON이 객체가 아님\n";
        return 1;
    }
    // HasMember로 키 존재 확인
    if (doc.HasMember("name") && doc["name"].IsString()) {
        std::cout << "name: " << doc["name"].GetString() << "\n";
    }
    if (doc.HasMember("age") && doc["age"].IsInt()) {
        std::cout << "age: " << doc["age"].GetInt() << "\n";
    }
    if (doc.HasMember("active") && doc["active"].IsBool()) {
        std::cout << "active: " << (doc["active"].GetBool() ? "true" : "false") << "\n";
    }
    return 0;
}

RapidJSON 코드가 HasMember와 IsXxx를 매번 짝지어 쓰는 데에는 이유가 있습니다. RapidJSON은 성능을 위해 대부분의 잘못된 접근을 예외가 아니라 RAPIDJSON_ASSERT로 처리합니다. 없는 멤버를 doc["name"]으로 접근하거나 문자열 값에 GetInt()를 호출하면, 디버그 빌드에서는 assert로 프로그램이 즉시 종료됩니다. 릴리스 빌드(NDEBUG)에서는 assert가 사라지므로 없는 멤버 접근은 내부의 정적 null 값을 돌려주고, 타입이 다른 값의 GetInt()는 내부 공용체의 엉뚱한 비트를 그대로 읽어 의미 없는 값을 돌려줍니다. 테스트에서는 잘 죽던 코드가 운영에서는 쓰레기 값을 내는 식이라 추적이 어렵습니다. HasMember 후 doc["name"]은 멤버를 두 번 찾으므로, 많이 반복되는 경로라면 FindMember로 한 번에 찾고 반환된 이터레이터를 쓰는 편이 낫습니다.

숫자 타입 검사도 nlohmann보다 엄격합니다. IsInt()는 값이 32비트 부호 있는 정수 범위일 때만 true이므로, 3000000000 같은 큰 ID는 IsInt()가 false이고 IsInt64()나 IsUint()로 확인해야 합니다. 30.0은 IsDouble()이 true이고 IsInt()는 false입니다.

파일 파싱 (스트림)

#include <rapidjson/document.h>
#include <rapidjson/filereadstream.h>
#include <rapidjson/error/en.h>
#include <cstdio>
#include <iostream>
int main() {
    FILE* fp = fopen("config.json", "rb");
    if (!fp) {
        std::cerr << "파일 열기 실패\n";
        return 1;
    }
    char readBuffer[65536];
    rapidjson::FileReadStream is(fp, readBuffer, sizeof(readBuffer));
    rapidjson::Document doc;
    doc.ParseStream(is);
    fclose(fp);
    if (doc.HasParseError()) {
        std::cerr << "파싱 오류: " << rapidjson::GetParseError_En(doc.GetParseError()) << "\n";
        return 1;
    }
    if (doc.HasMember("port") && doc["port"].IsInt()) {
        std::cout << "port: " << doc["port"].GetInt() << "\n";
    }
    return 0;
}

배열·중첩 객체 파싱

#include <rapidjson/document.h>
#include <rapidjson/error/en.h>
#include <iostream>
#include <vector>
int main() {
    const char* json = R"({
        "users": [
            {"id": 1, "name": "Alice"},
            {"id": 2, "name": "Bob"}
        ]
    })";
    rapidjson::Document doc;
    doc.Parse(json);
    if (doc.HasParseError() || !doc.HasMember("users") || !doc["users"].IsArray()) {
        std::cerr << "파싱 실패 또는 users 배열 없음\n";
        return 1;
    }
    const auto& users = doc["users"].GetArray();
    for (rapidjson::SizeType i = 0; i < users.Size(); ++i) {
        const auto& u = users[i];
        if (!u.IsObject() || !u.HasMember("id") || !u.HasMember("name")) continue;
        int id = u["id"].GetInt();
        const char* name = u["name"].GetString();
        std::cout << id << ": " << name << "\n";
    }
    return 0;
}

RapidJSON으로 JSON 생성

#include <rapidjson/document.h>
#include <rapidjson/stringbuffer.h>
#include <rapidjson/writer.h>
#include <iostream>
int main() {
    rapidjson::Document doc(rapidjson::kObjectType);
    rapidjson::Document::AllocatorType& alloc = doc.GetAllocator();
    doc.AddMember("name", "Bob", alloc);
    doc.AddMember("age", 25, alloc);
    rapidjson::Value tags(rapidjson::kArrayType);
    tags.PushBack("admin", alloc);
    tags.PushBack("user", alloc);
    doc.AddMember("tags", tags, alloc);
    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);
    std::cout << buffer.GetString() << "\n";
    // {"name":"Bob","age":25,"tags":["admin","user"]}
    return 0;
}

doc.AddMember("tags", tags, alloc) 이후 tags는 비어 있는 null 값이 됩니다. RapidJSON의 Value는 대입과 AddMember에서 복사 대신 소유권을 옮기기 때문입니다. 같은 배열을 두 곳에 넣으려고 tags를 재사용하면 두 번째에는 null이 들어가므로, 복사가 필요하면 Value(tags, alloc)처럼 할당자를 넘기는 복사 생성자를 명시적으로 써야 합니다. 문자열 리터럴 "Bob"은 상수 문자열로 참조만 저장하지만, std::string처럼 수명이 짧은 문자열은 아래 커스텀 타입 예제처럼 Value(s.c_str(), alloc)로 복사해 넣어야 합니다. 이를 빠뜨리면 원본 문자열이 사라진 뒤 dangling 포인터를 직렬화하게 됩니다.


to_json/from_json으로 구조체와 enum 직렬화

nlohmann: to_json / from_json

#include <iostream>
#include <nlohmann/json.hpp>
#include <string>
#include <vector>
#include <optional>
using json = nlohmann::json;
struct User {
    std::string name;
    int age;
    std::vector<std::string> tags;
    std::optional<std::string> email;  // 선택적
};
// JSON → User (역직렬화)
void from_json(const json& j, User& u) {
    j.at("name").get_to(u.name);
    j.at("age").get_to(u.age);
    if (j.contains("tags")) {
        j.at("tags").get_to(u.tags);
    }
    if (j.contains("email") && !j["email"].is_null()) {
        u.email = j["email"].get<std::string>();
    }
}
// User → JSON (직렬화)
void to_json(json& j, const User& u) {
    j = json{
        {"name", u.name},
        {"age", u.age},
        {"tags", u.tags}
    };
    if (u.email) {
        j["email"] = *u.email;
    }
}
int main() {
    std::string str = R"({"name": "Alice", "age": 30, "tags": ["admin"], "email": "a@b.com"})";
    json j = json::parse(str);
    User u = j.get<User>();
    std::cout << u.name << ", " << u.age << "\n";
    if (u.email) std::cout << "email: " << *u.email << "\n";
    json j2 = u;  // to_json 자동 호출
    std::cout << j2.dump(2) << "\n";
    return 0;
}

to_json/from_json은 User와 같은 네임스페이스에 정의해야 합니다. nlohmann은 인자 의존 탐색(ADL)으로 이 함수들을 찾기 때문에, 구조체는 myapp 네임스페이스에 있고 함수는 전역에 두면 j.get<User>()에서 수십 줄짜리 템플릿 에러(대개 no matching function for call to 'from_json')가 납니다. 외부 라이브러리 타입처럼 네임스페이스에 함수를 추가할 수 없는 경우에는 nlohmann::adl_serializer를 특수화합니다.

from_json에서 at()과 contains()를 섞어 쓴 것은 의도된 설계입니다. name과 age는 없으면 User를 만들 수 없으므로 at()으로 예외를 내고, tags와 email은 없어도 되는 필드라 존재할 때만 읽습니다. 이렇게 필수/선택의 구분이 from_json 한 곳에 드러나 있으면 API 스펙이 바뀌었을 때 고칠 곳도 한 곳입니다.

NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE (간단한 구조체)

#include <nlohmann/json.hpp>
struct Point {
    double x;
    double y;
};
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(Point, x, y)
// 사용
// Point p{1.0, 2.0};
// json j = p;
// Point p2 = j.get<Point>();

이 매크로는 모든 필드를 필수로 취급합니다. 입력에 y가 없으면 out_of_range 예외가 나므로, 선택 필드가 있는 구조체에는 3.11부터 제공되는 NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT를 쓰면 누락된 필드를 기본 생성된 객체의 값으로 채웁니다. 매크로는 필드를 나열하는 것 외에 검증 로직을 넣을 수 없으므로, 범위 검사나 null 처리 같은 규칙이 필요한 타입은 직접 from_json을 쓰는 편이 낫습니다.

enum 직렬화

#include <nlohmann/json.hpp>
#include <stdexcept>
#include <string>
using json = nlohmann::json;
enum class Status { Pending, Active, Done };
void to_json(json& j, Status s) {
    switch (s) {
        case Status::Pending: j = "pending"; break;
        case Status::Active:  j = "active";  break;
        case Status::Done:    j = "done";    break;
    }
}
void from_json(const json& j, Status& s) {
    std::string v = j.get<std::string>();
    if (v == "pending") s = Status::Pending;
    else if (v == "active") s = Status::Active;
    else if (v == "done") s = Status::Done;
    else throw std::invalid_argument("unknown status: " + v);
}

enum은 숫자로 직렬화하는 것이 가장 쉽지만(아무것도 하지 않으면 nlohmann이 정수로 저장합니다), enum 값 순서를 바꾸거나 중간에 항목을 추가하면 이미 저장된 데이터의 의미가 바뀝니다. 그래서 외부와 주고받는 enum은 위처럼 문자열로 매핑하는 편이 안전합니다. 알 수 없는 문자열을 만났을 때 조용히 한 값(예: Done)으로 떨어뜨리면 서버가 새 상태 값을 추가한 순간 클라이언트가 엉뚱한 상태로 동작하므로, 명시적으로 실패시키거나 Unknown 항목을 따로 두는 것이 좋습니다. nlohmann의 NLOHMANN_JSON_SERIALIZE_ENUM 매크로로도 같은 매핑을 짧게 쓸 수 있는데, 이 매크로는 모르는 값을 목록의 첫 항목으로 매핑하므로 첫 항목을 Unknown으로 두는 관례가 있습니다.

RapidJSON 커스텀 타입 (수동)

#include <rapidjson/document.h>
#include <rapidjson/stringbuffer.h>
#include <rapidjson/writer.h>
#include <string>
#include <vector>
struct User {
    std::string name;
    int age;
    std::vector<std::string> tags;
};
User parse_user(const rapidjson::Value& v) {
    User u;
    if (v.HasMember("name") && v["name"].IsString())
        u.name = v["name"].GetString();
    if (v.HasMember("age") && v["age"].IsInt())
        u.age = v["age"].GetInt();
    if (v.HasMember("tags") && v["tags"].IsArray()) {
        for (auto& t : v["tags"].GetArray()) {
            if (t.IsString()) u.tags.push_back(t.GetString());
        }
    }
    return u;
}
void user_to_json(const User& u, rapidjson::Value& v, rapidjson::Document::AllocatorType& alloc) {
    v.SetObject();
    v.AddMember("name", rapidjson::Value(u.name.c_str(), alloc), alloc);
    v.AddMember("age", u.age, alloc);
    rapidjson::Value tags(rapidjson::kArrayType);
    for (const auto& t : u.tags) {
        tags.PushBack(rapidjson::Value(t.c_str(), alloc), alloc);
    }
    v.AddMember("tags", tags, alloc);
}

type_error, parse_error, null 접근 같은 파싱 에러

nlohmann/json에서 키 사전순 정렬, get<int>()의 조용한 잘림, ordered_json, 잘못된 UTF-8 dump 예외를 재현한 출력

그림: 실제 실행 결과 — 기본 json은 키를 사전순으로 정렬하고 ordered_json은 입력 순서를 유지한다. 30.7은 30으로, 5000000000은 예외 없이 705032704로 바뀌지만 int64_t로 받으면 그대로다. 유효하지 않은 UTF-8 바이트는 dump()에서 type_error.316을 던지고, replace 핸들러를 주면 대체 문자(3바이트)로 바뀐다. (환경: macOS 27.0.1 · Apple clang 21.0.0 · nlohmann/json 3.11.3)

type_error: 타입 불일치

get<int>()를 호출했는데 실제 값이 문자열이나 null, 다른 타입이면 type_error가 납니다. 변환 전에 is_*로 타입을 확인하고, 문자열로 오는 숫자를 허용할지는 명시적으로 결정합니다.

// ❌ 위험: "age"가 "30"(문자열)이면 type_error
int age = j["age"].get<int>();

// ✅ is_* 검증 후 변환
int age2 = 0;
if (j["age"].is_number_integer()) {
    age2 = j["age"].get<int>();
} else if (j["age"].is_string()) {
    age2 = std::stoi(j["age"].get<std::string>());  // 숫자가 아니면 std::invalid_argument
}

// ✅ value로 기본값: 키가 없을 때만 0, 값이 null·문자열이면 여전히 type_error
int age3 = j.value("age", 0);

out_of_range / null 접근

비-const json에서 j[key]로 없는 키에 접근하면 null이 삽입되고, 이후 get<T>()에서 실패합니다. at()으로 접근했다면 키가 없을 때 out_of_range가 납니다.

// ❌ 위험: optional_key가 없으면 null이 삽입되고 get에서 type_error
int x = j["optional_key"].get<int>();

// ✅ find로 존재와 null을 함께 확인
int y = 0;
if (auto it = j.find("optional_key"); it != j.end() && !it->is_null()) {
    y = it->get<int>();
}

parse_error: 잘못된 JSON 문법

쉼표 누락, 닫히지 않은 따옴표, 이스케이프되지 않은 제어 문자 같은 문법 오류는 parse_error로 나타납니다.

// ✅ try-catch로 파싱 실패 처리
try {
    json j = json::parse(response_body);
} catch (const json::parse_error& e) {
    std::cerr << "파싱 오류: " << e.what() << " at byte " << e.byte << "\n";
    // 로깅, 폴백, 재시도 등
}

메모리 과다 사용 (대용량 JSON)

전체 파일을 문자열로 읽은 뒤 parse()하면 원본 문자열과 DOM이 동시에 메모리에 있습니다. 스트림에서 바로 파싱하면 원본 문자열 사본은 없앨 수 있지만, DOM 자체는 여전히 문서 전체만큼 만들어진다는 점을 기억해야 합니다. 메모리 사용을 입력 크기와 무관하게 만들려면 트리를 만들지 않는 SAX 방식이 필요합니다.

// 파일은 스트림으로 파싱: 문자열 사본은 없지만 DOM은 전체가 만들어짐
std::ifstream f("large.json");
json j = json::parse(f);

// 필요한 필드만 뽑는다면 SAX 방식:
// - nlohmann: json::sax_parse(f, &handler) 와 json_sax 인터페이스 구현
// - RapidJSON: Reader::Parse(stream, handler)

인코딩 문제 (UTF-8)

JSON 텍스트는 UTF-8로 주고받는 것이 표준입니다(RFC 8259). Windows에서 CP949 같은 다른 인코딩으로 저장된 파일을 그대로 파싱하면 한글이 깨지거나 파싱 오류가 납니다.

// ✅ 입력을 UTF-8로 보장
// - 파일 저장 시 UTF-8
// - HTTP 응답 Content-Type: application/json; charset=utf-8
// - nlohmann dump()는 기본값(ensure_ascii=false)으로 한글을 그대로 출력,
//   dump(-1, ' ', true)로 주면 \uXXXX 이스케이프로 출력

인코딩 문제는 파싱보다 직렬화할 때 더 자주 터집니다. Windows에서 CP949로 된 파일 경로나 사용자 입력을 std::string에 담아 json에 넣고 dump()하면, 유효하지 않은 UTF-8 바이트 때문에 [json.exception.type_error.316] invalid UTF-8 byte at index ... 예외가 납니다. 로그를 JSON으로 남기는 코드에서 특정 사용자 이름이 들어올 때만 서버가 죽는 문제가 대개 이것입니다. 입력 경계에서 UTF-8로 변환하는 것이 정석이고, 로그처럼 손실이 괜찮은 경우에는 dump(-1, ' ', false, json::error_handler_t::replace)로 잘못된 바이트를 대체 문자로 바꿀 수 있습니다.

Data Race (멀티스레드)

표준 컨테이너와 마찬가지로 json 객체를 여러 스레드가 읽기만 하는 것은 안전합니다. 문제는 읽기처럼 보이는 쓰기입니다. 비-const json에 operator[]로 없는 키를 조회하면 삽입이 일어나므로, “모든 스레드가 설정을 읽기만 한다”고 생각한 코드가 실제로는 동시에 맵을 수정하고 있을 수 있습니다. 공유 설정은 const json으로 만들어 두고 at()/find()/value()만 쓰면 이 문제를 구조적으로 막을 수 있습니다. 스레드마다 수정이 필요하다면 복사본을 넘기거나 파싱을 스레드 안에서 합니다.

// ✅ 파싱 후 스레드별로 복사
json j_global = json::parse(body);
std::thread t1([j_global]() {  // 복사로 전달
    process(j_global);
});
// ✅ 또는 파싱을 스레드 내부에서
std::thread t2([body]() {
    json j = json::parse(body);  // 스레드 로컬
    process(j);
});

필수·선택 필드 구분과 API 응답 래퍼

필수 필드 vs 선택 필드 구분

struct ApiResponse {
    int code;                    // 필수
    std::string message;         // 필수
    std::optional<json> data;    // 선택
};
void from_json(const json& j, ApiResponse& r) {
    r.code = j.at("code").get<int>();
    r.message = j.at("message").get<std::string>();
    if (j.contains("data") && !j["data"].is_null()) {
        r.data = j["data"];
    }
}

API 응답 래퍼

template<typename T>
struct ApiResult {
    bool ok;
    T data;
    std::string error_msg;
};
template<typename T>
ApiResult<T> parse_api_response(const std::string& body) {
    ApiResult<T> result{false, {}, ""};
    try {
        json j = json::parse(body);
        if (j.contains("error")) {
            result.error_msg = j.value("error", "unknown");
            return result;
        }
        result.data = j.get<T>();
        result.ok = true;
    } catch (const json::exception& e) {
        result.error_msg = e.what();
    }
    return result;
}

설정 파일 로드 패턴

struct Config {
    int port = 8080;
    std::string host = "0.0.0.0";
    int timeout = 30;
};
Config load_config(const std::string& path) {
    std::ifstream f(path);
    if (!f) throw std::runtime_error("Cannot open: " + path);
    json j = json::parse(f);
    Config c;
    c.port = j.value("port", 8080);
    c.host = j.value("host", "0.0.0.0");
    c.timeout = j.value("timeout", 30);
    return c;
}

로깅용 한 줄 JSON

// 이벤트·로그 직렬화: 한 줄로 출력 (Kafka, 로그 파일)
json event = {{"ts", timestamp}, {"level", "info"}, {"msg", message}};
std::cout << event.dump() << "\n";  // 압축 형식

nlohmann과 RapidJSON의 성능 비교

무엇이 속도를 가르는가

방식파싱 속도메모리이유
nlohmann/json상대적으로 느림가장 많음노드마다 STL 컨테이너·힙 할당
RapidJSON (DOM)빠름적음풀 할당자에 값을 촘촘히 배치
RapidJSON (SAX)가장 빠름입력 크기와 거의 무관트리를 만들지 않고 이벤트만 전달

공개 벤치마크(예: nativejson-benchmark)에서도 RapidJSON이 nlohmann보다 여러 배 빠른 결과가 흔하지만, 정확한 배수는 JSON 모양(깊은 중첩, 긴 문자열, 숫자 비중), 컴파일러, 할당자에 따라 크게 달라집니다. 더 중요한 것은 파싱이 실제 병목인지입니다. 네트워크 왕복이 밀리초 단위로 걸리는 서비스에서 수 KB 응답의 파싱은 대개 전체 시간의 작은 부분이므로, 라이브러리를 바꾸기 전에 프로파일러로 파싱 비중부터 확인하세요. “JSON이 느리다”는 문제는 라이브러리보다 같은 문서를 여러 번 파싱하거나 json 값을 값으로 넘겨 불필요하게 복사하는 코드에서 나오는 경우가 많습니다.

선택 가이드

flowchart TD
    A[JSON 파싱 필요] --> B{성능·메모리 제약?}
    B -->|아니오| C[nlohmann/json]
    B -->|예| D{대용량 스트리밍?}
    D -->|예| E[RapidJSON SAX]
    D -->|아니오| F[RapidJSON DOM]
    C --> G[개발 편의성 우선]
    F --> H[고성능, 저메모리]
    E --> I[최소 메모리]

type_error, 누락 키, operator[]가 넣는 null: 자주 나는 에러

nlohmann/json의 type_error, out_of_range, operator[]가 삽입하는 null, parse_error를 재현한 출력

그림: 실제 실행 결과 — “30” 문자열을 int로 읽으면 value()로도 같은 type_error.302가 나고, at()은 없는 키에 out_of_range.403을 던진다. j[“optional”]은 읽기만 했는데 객체에 null을 추가했다. 마지막 줄은 trailing comma의 parse_error.101이다.

에러 1: type_error — 타입 불일치

증상: "type must be number, but is string" 같은 메시지가 나옵니다. 원인: JSON 필드가 문자열인데 get<int>()로 읽거나, 숫자인데 get<std::string>()으로 읽은 경우입니다.

// ❌ 잘못된 예: "age"가 "30" (문자열)인 경우
int age = j["age"].get<int>();  // type_error!
// ✅ 해결 1: is_* 로 검증 후 변환
if (j["age"].is_number_integer()) {
    int age = j["age"].get<int>();
} else if (j["age"].is_string()) {
    int age = std::stoi(j["age"].get<std::string>());
}
// ❌ value()는 해결책이 아님: 키가 있고 값이 "30"이면 value("age", 0)도 type_error

에러 2: out_of_range — 누락된 키

증상: j.at("required_key") 호출 시 키가 없으면 out_of_range 예외가 발생합니다. 원인: API 응답에 필드가 없거나, 설정 파일에 키가 누락됩니다.

// ❌ at()은 키 없으면 예외
auto name = j.at("name").get<std::string>();
// ✅ contains로 먼저 확인
if (j.contains("name")) {
    auto name = j["name"].get<std::string>();
}
// ✅ value로 기본값
auto name = j.value("name", std::string("unknown"));

에러 3: j[“key”]가 null을 삽입합니다

증상: 읽기 전용인데 j["nonexistent"]를 호출하면 객체에 null이 추가됩니다. 원인: operator[]는 키가 없으면 null을 삽입한 뒤 반환합니다.

// ❌ 읽기만 할 때도 객체가 수정됨
if (j["optional"] != nullptr) { ... }  // "optional" 키가 생김!
// ✅ contains 또는 find 사용
if (j.contains("optional")) {
    auto v = j["optional"];
}
// 또는
auto it = j.find("optional");
if (it != j.end()) {
    auto v = *it;
}

에러 4: parse_error — 잘못된 JSON 문법

증상: "parse error at line 1, column 10" 같은 메시지가 나옵니다. 원인: trailing comma, 따옴표 누락, 인코딩 문제 등이 원인입니다.

// ❌ 잘못된 JSON
std::string bad = R"({"name": "Alice",})";  // trailing comma
// ✅ try/catch로 처리
try {
    json j = json::parse(bad);
} catch (const json::parse_error& e) {
    std::cerr << "파싱 실패: " << e.what() << "\n";
}

에러 5: 순환 참조

증상: to_json에서 무한 재귀 또는 스택 오버플로가 발생합니다. 원인: 부모·자식이 서로를 가리키는 구조체에서 to_json이 포인터를 따라가며 양쪽을 모두 직렬화하도록 직접 작성했을 때 생깁니다. nlohmann/json이 포인터를 알아서 따라가지는 않으므로, 문제는 항상 사용자 코드의 재귀입니다.

struct Node {
    std::string value;
    Node* parent;  // 순환 참조 가능
};
// ✅ parent는 직렬화에서 제외하거나, ID로 대체
void to_json(json& j, const Node& n) {
    j = {{"value", n.value}};
    // parent 제외
}

에러 6: 숫자 변환이 조용히 값을 바꿉니다

증상: "price": 19.99를 get<int>()로 읽었더니 예외 없이 19가 나오거나, get<float>() 결과가 원래 값과 미세하게 다릅니다. 원인: nlohmann/json은 숫자 타입끼리의 변환을 static_cast처럼 허용합니다. 실수를 정수로 읽으면 소수점이 잘리고, 음수를 unsigned로 읽으면 큰 양수가 됩니다. 예외가 나지 않으므로 테스트에서 드러나지 않다가 실제 데이터에서 값이 틀어집니다. 저장 자체는 double로 정확히 유지되고 dump()도 왕복 가능한 자릿수로 출력하므로, 손실은 대부분 읽는 쪽 타입 선택에서 생깁니다.

// ❌ 소수점이 조용히 잘림
int price = j["price"].get<int>();          // 19.99 → 19
// ✅ 정수가 와야 하는 필드는 타입을 먼저 확인
if (!j["count"].is_number_integer()) throw std::runtime_error("count must be integer");
// ✅ 금액은 double보다 정수(최소 단위, 예: 원·센트)나 문자열 + decimal 라이브러리로 주고받기
std::int64_t price_cents = j["price_cents"].get<std::int64_t>();

큰 정수도 알아 둘 부분입니다. nlohmann/json은 64비트 정수를 정확히 저장하므로 C++ 쪽에서는 문제가 없지만, 같은 JSON을 JavaScript 클라이언트가 읽으면 2^53을 넘는 ID가 반올림됩니다. 트위터 스타일의 64비트 ID를 브라우저와 주고받는다면 서버에서 문자열로 내보내는 것이 안전합니다.

에러 7: UTF-8 BOM 및 인코딩

증상: 파일 파싱 시 "parse error at line 1, column 1"이 나거나 첫 문자가 깨집니다. 원인: nlohmann/json의 parse는 UTF-8 BOM(EF BB BF)을 자동으로 건너뛰므로 UTF-8 BOM 자체는 대개 문제가 되지 않습니다. 문제가 되는 것은 Windows 메모장의 옛 “유니코드” 저장처럼 UTF-16으로 저장된 파일(FF FE로 시작)입니다. nlohmann/json은 UTF-8만 입력으로 받으므로, 이런 파일은 먼저 UTF-8로 변환해야 합니다. 아래 함수는 파서 앞단에서 직접 바이트를 다룰 때(다른 파서로 넘기거나 로그로 남길 때) 쓸 수 있는 BOM 제거 예시입니다.

// ✅ BOM 제거 후 파싱 (구버전 호환)
std::string read_json_file(const std::string& path) {
    std::ifstream f(path, std::ios::binary);
    std::string content((std::istreambuf_iterator<char>(f)),
                         std::istreambuf_iterator<char>());
    if (content.size() >= 3 &&
        static_cast<unsigned char>(content[0]) == 0xEF &&
        static_cast<unsigned char>(content[1]) == 0xBB &&
        static_cast<unsigned char>(content[2]) == 0xBF) {
        content = content.substr(3);
    }
    return content;
}

RapidJSON을 함께 쓰거나 비교 중이라면 동작이 다르다는 점을 알아 두세요. Document::Parse에 BOM이 붙은 문자열을 그대로 넘기면 맨 앞 EF BB BF를 JSON 값으로 읽으려다 kParseErrorValueInvalid 오류가 나는 것이 일반적입니다. 이때는 위처럼 BOM을 직접 잘라 내거나, EncodedInputStream·AutoUTFInputStream으로 입력을 감싸 BOM을 처리하게 합니다. 오류 메시지가 “Invalid value”이고 위치가 offset 0이라면 BOM부터 의심하면 됩니다. 파일 앞 3바이트는 xxd file.json | head -1로 바로 확인할 수 있습니다.

에러 8: 빈 문자열/배열 타입 혼동

증상: 빈 배열에 j["data"][0]로 접근했더니 예외 없이 배열에 null 원소가 생깁니다. 원인: non-const operator[]는 배열에서도 범위를 벗어난 인덱스까지 null로 채워 늘립니다. 객체의 없는 키를 삽입하는 것과 같은 동작이라, 읽기만 하려던 코드가 데이터를 바꿉니다. 범위 검사가 필요하면 at(0)(범위 밖이면 out_of_range)을 쓰거나 empty()를 먼저 확인합니다.

// ❌ 빈 배열일 때 item["id"] 접근 시 문제
for (auto& item : j["data"]) {
    int id = item["id"].get<int>();  // 빈 배열이면 순회 안 함 (OK)
}
// 하지만 j["data"][0] 직접 접근 시
// auto x = j["data"][0]["id"];  // data가 []면 [ {"id": null} ]로 바뀌어 버림
// ✅ size() 확인 후 접근
if (!j["data"].empty()) {
    auto first = j["data"][0];
}

nlohmann/json이 느린 이유와 SAX·json_fwd로 비용 줄이기

nlohmann/json vs 다른 라이브러리

라이브러리특징쓰기(생성)잘 맞는 곳
nlohmann/jsonSTL 같은 API, 커스텀 타입 매핑이 가장 쉬움, 헤더 전용O설정, REST 응답, 도구, 테스트
RapidJSON할당자 제어, in-situ 파싱, 헤더 전용이지만 API가 장황함O게임, 메모리 제약 환경
simdjsonSIMD 파싱, On-Demand API로 필요한 필드만 읽음X (파싱 전용)대용량 로그·고처리량 수신
yyjsonC 라이브러리, 파싱·생성 모두 매우 빠름O성능이 중요한데 쓰기도 필요할 때
Glaze컴파일 타임 리플렉션으로 구조체와 직접 매핑, 최신 C++ 표준 필요O최신 컴파일러에서 속도와 편의 둘 다

nlohmann/json이 느린 주된 이유는 모든 값을 동적 할당되는 트리(DOM)로 만들고 객체를 std::map에 넣기 때문입니다. 다른 라이브러리로 바꾸기 전에 먼저 JSON 처리가 실제로 병목인지 프로파일러로 확인해야 합니다. 요청 처리 시간의 대부분이 네트워크나 DB 대기라면 파서를 바꿔도 체감 차이가 거의 없습니다. 파싱이 병목이더라도 필요한 필드가 몇 개뿐이라면, 전체를 갈아타기보다 그 경로만 simdjson의 On-Demand API로 바꾸는 것으로 충분한 경우가 많습니다.

참고로 json::parse(std::ifstream&)처럼 스트림에서 파싱해도 결과 DOM은 전부 메모리에 올라갑니다. 아끼는 것은 파일 내용을 담을 중간 std::string 하나뿐이므로, 메모리가 문제라면 아래의 SAX 파싱이나 NDJSON 같은 다른 접근이 필요합니다.

컴파일 시간

헤더 전용이라 include하는 순간 컴파일 시간이 늘어납니다. nlohmann/json_fwd.hpp를 사용하면 전방 선언만 하고, 실제 사용하는 .cpp에서만 json.hpp를 include해 컴파일 시간을 줄일 수 있습니다.

// header.h
#include <nlohmann/json_fwd.hpp>
void process(const nlohmann::json& j);
// impl.cpp
#include <nlohmann/json.hpp>  // 여기서만 전체 정의

SAX/이벤트 기반 파싱 (대용량)

수십 MB 이상의 JSON에서 특정 키만 추출할 때는 json::sax_parse와 json_sax 핸들러를 사용해 DOM 전체를 만들지 않고 스트리밍으로 처리할 수 있습니다.

#include <nlohmann/json.hpp>
#include <fstream>
#include <iostream>
#include <string>
#include <vector>
using json = nlohmann::json;
// json_sax<json>의 순수 가상 함수를 모두 구현해야 함
struct KeyExtractor : nlohmann::json_sax<json> {
    std::string target_key;
    std::string current_key;
    std::vector<std::string> values;

    explicit KeyExtractor(std::string k) : target_key(std::move(k)) {}

    bool key(string_t& val) override { current_key = val; return true; }
    bool string(string_t& val) override {
        if (current_key == target_key) values.push_back(val);
        return true;
    }
    bool null() override { return true; }
    bool boolean(bool) override { return true; }
    bool number_integer(number_integer_t) override { return true; }
    bool number_unsigned(number_unsigned_t) override { return true; }
    bool number_float(number_float_t, const string_t&) override { return true; }
    bool binary(binary_t&) override { return true; }
    bool start_object(std::size_t) override { return true; }
    bool end_object() override { return true; }
    bool start_array(std::size_t) override { return true; }
    bool end_array() override { return true; }
    bool parse_error(std::size_t pos, const std::string&, const nlohmann::detail::exception& ex) override {
        std::cerr << "parse error at " << pos << ": " << ex.what() << "\n";
        return false;   // 파싱 중단
    }
};

int main() {
    std::ifstream f("users.json");
    KeyExtractor h("name");
    json::sax_parse(f, &h);           // DOM을 만들지 않고 이벤트만 받음
    for (auto& v : h.values) std::cout << v << "\n";
}

이 예제는 단순화를 위해 중첩 깊이를 추적하지 않아서, 다른 위치에 있는 같은 이름의 키도 함께 잡힙니다. 실제로 쓸 때는 start_object/end_object에서 경로 스택을 관리하세요. 파일 전체를 필드 몇 개 때문에 읽는 경우라면 SAX 대신 NDJSON으로 형식을 바꾸거나 simdjson On-Demand를 쓰는 편이 코드가 훨씬 짧습니다.

직접 측정하기

인터넷의 벤치마크 수치는 JSON 모양(숫자 위주인지 문자열 위주인지, 중첩 깊이), 컴파일러, CPU에 따라 몇 배씩 달라집니다. 실제 서비스에서 받는 JSON 샘플로 파싱 시간을 재 보는 것이 가장 정확합니다.

#include <chrono>
auto t0 = std::chrono::steady_clock::now();
for (int i = 0; i < 1000; ++i) {
    auto j = json::parse(sample);   // 실제 응답 샘플
}
auto ms = std::chrono::duration<double, std::milli>(std::chrono::steady_clock::now() - t0).count();
std::cout << "avg " << ms / 1000 << " ms\n";

반드시 최적화 빌드(-O2, Release)로 재세요. 디버그 빌드에서 nlohmann/json은 템플릿 인라이닝이 안 되어 릴리스보다 훨씬 느리게 나오고, 이 숫자를 보고 라이브러리를 바꾸는 결정을 하면 안 됩니다.

API 응답·설정 파일·NDJSON 로그를 다루는 패턴

API 응답 처리 흐름

sequenceDiagram
    participant Client as C++ 클라이언트
    participant API as REST API
    participant JSON as nlohmann/json
    Client->>API: HTTP GET /users
    API->>Client: {"data":[{"id":1,"name":"Alice"}]}
    Client->>JSON: json::parse(response_body)
    JSON->>Client: json 객체
    Client->>JSON: res["data"].get<vector<User>>()
    JSON->>Client: vector<User>

API 응답 처리

#include <nlohmann/json.hpp>
#include <string>
#include <vector>
using json = nlohmann::json;
struct ApiItem {
    int id;
    std::string name;
};
void from_json(const json& j, ApiItem& item) {
    j.at("id").get_to(item.id);
    j.at("name").get_to(item.name);
}
std::vector<ApiItem> parse_api_response(const std::string& response_body) {
    std::vector<ApiItem> result;
    try {
        json res = json::parse(response_body);
        if (!res.contains("data") || !res["data"].is_array()) {
            return result;
        }
        for (auto& item : res["data"]) {
            result.push_back(item.get<ApiItem>());
        }
    } catch (const json::exception& e) {
        // 로깅 후 빈 결과 반환
        return result;
    }
    return result;
}

설정 파일 로드

#include <nlohmann/json.hpp>
#include <fstream>
#include <optional>
using json = nlohmann::json;
struct AppConfig {
    int port = 8080;
    std::string host = "0.0.0.0";
    std::optional<std::string> log_level;
};
void from_json(const json& j, AppConfig& c) {
    if (j.contains("port")) c.port = j["port"].get<int>();
    if (j.contains("host")) c.host = j["host"].get<std::string>();
    if (j.contains("log_level")) c.log_level = j["log_level"].get<std::string>();
}
AppConfig load_config(const std::string& path) {
    std::ifstream f(path);
    if (!f) {
        return AppConfig{};  // 기본 설정 반환
    }
    try {
        return json::parse(f).get<AppConfig>();
    } catch (const json::exception& e) {
        return AppConfig{};
    }
}

요청 본문 생성

json create_request_body(const std::string& action, const std::vector<int>& ids) {
    return {
        {"action", action},
        {"ids", ids},
        {"timestamp", std::time(nullptr)}
    };
}
// HTTP 클라이언트에 전달
std::string body = create_request_body("delete", {1, 2, 3}).dump();

로그 직렬화

struct LogEntry {
    std::string level;
    std::string message;
    std::time_t timestamp;
};
void to_json(json& j, const LogEntry& e) {
    j = {
        {"level", e.level},
        {"message", e.message},
        {"timestamp", e.timestamp}
    };
}
// 로그를 JSON 한 줄로 출력
LogEntry entry{"INFO", "User logged in", std::time(nullptr)};
std::cout << json(entry).dump() << "\n";

에러 복구 가능한 파싱 래퍼

외부 API나 사용자 입력은 항상 잘못된 JSON일 수 있으므로, 파싱 실패 시 로깅하고 기본값을 반환하는 래퍼를 두는 것이 좋습니다.

#include <nlohmann/json.hpp>
#include <optional>
#include <iostream>
using json = nlohmann::json;
struct ParseResult {
    json data;
    bool ok;
    std::string error_message;
};
ParseResult safe_parse_with_logging(const std::string& input) {
    try {
        return {json::parse(input), true, ""};
    } catch (const json::parse_error& e) {
        std::cerr << "[JSON] 파싱 실패: " << e.what()
                  << " (byte " << e.byte << ")\n";
        return {json::object(), false, e.what()};
    }
}
// 사용
auto result = safe_parse_with_logging(api_response);
if (result.ok) {
    // 정상 처리
} else {
    // 폴백 또는 재시도
}

설정 파일 환경별 오버라이드

환경 변수로 JSON 설정을 오버라이드하는 패턴입니다.

#include <nlohmann/json.hpp>
#include <cstdlib>
#include <fstream>
#include <string>
using json = nlohmann::json;
json load_config_with_env_override(const std::string& path) {
    std::ifstream f(path);
    json j = f ? json::parse(f) : json::object();
    // 환경 변수로 오버라이드
    if (const char* port = std::getenv("APP_PORT")) {
        j["port"] = std::stoi(port);
    }
    if (const char* host = std::getenv("APP_HOST")) {
        j["host"] = host;
    }
    return j;
}

NDJSON(Newline-Delimited JSON) 스트리밍

로그·이벤트 스트림을 한 줄씩 파싱하면 메모리에는 한 줄 분량의 DOM만 올라갑니다. 아래 함수의 auto 매개변수는 C++20 축약 함수 템플릿 문법이므로, C++17이라면 template <class F>로 바꿔 쓰면 됩니다.

void process_ndjson(const std::string& path, auto on_line) {
    std::ifstream f(path);
    std::string line;
    while (std::getline(f, line)) {
        if (line.empty()) continue;
        try { on_line(json::parse(line)); }
        catch (const json::parse_error&) { /* 스킵 */ }
    }
}

숫자/문자열 혼용 필드 처리

API가 "count": 100 또는 "count": "100"을 보낼 때 모두 처리하는 헬퍼입니다.

int get_int_flexible(const json& j, const std::string& key, int d = 0) {
    auto it = j.find(key);            // const json에서는 operator[] 대신 find/at
    if (it == j.end() || it->is_null()) return d;
    if (it->is_number_integer()) return it->get<int>();
    if (it->is_string()) {
        const auto& s = it->get_ref<const std::string&>();
        int out = d;
        auto [p, ec] = std::from_chars(s.data(), s.data() + s.size(), out);   // <charconv>, 예외 없음
        return (ec == std::errc{} && p == s.data() + s.size()) ? out : d;
    }
    return d;
}

HTTP 응답 파싱, 재시도, 스키마 검증

HTTP 응답 + JSON 파싱 통합

#include <nlohmann/json.hpp>
#include <string>
using json = nlohmann::json;
// HTTP 클라이언트로 body 수신 후 (예: #21-1 참고)
bool fetch_and_parse(const std::string& url, json& out) {
    std::string body;
    if (!http_get(url, body)) return false;
    try {
        out = json::parse(body);
        return true;
    } catch (const json::parse_error& e) {
        // 로깅: e.what(), e.byte
        return false;
    }
}

REST API 사용자 목록 조회 통합 예제

// HTTP GET + JSON 파싱 + 커스텀 타입 변환 통합
#include <nlohmann/json.hpp>
#include <string>
#include <vector>
#include <optional>
using json = nlohmann::json;
struct User {
    int id;
    std::string name;
    std::optional<std::string> email;
};
std::optional<std::vector<User>> fetch_users(const std::string& host,
                                              const std::string& path) {
    std::string body;
    if (!http_get(host, path, body)) return std::nullopt;
    try {
        json j = json::parse(body);
        if (!j.contains("data") || !j["data"].is_array()) return std::nullopt;
        std::vector<User> users;
        for (auto& item : j["data"]) {
            if (!item.contains("id") || !item.contains("name")) continue;
            User u;
            u.id = item["id"].get<int>();
            u.name = item["name"].get<std::string>();
            if (item.contains("email") && !item["email"].is_null())
                u.email = item["email"].get<std::string>();
            users.push_back(std::move(u));
        }
        return users;
    } catch (const json::exception&) {
        return std::nullopt;
    }
}

재시도 + 파싱

json fetch_with_retry(const std::string& url, int max_retries = 3) {
    for (int i = 0; i < max_retries; ++i) {
        std::string body;
        if (!http_get(url, body)) {
            std::this_thread::sleep_for(std::chrono::seconds(1 << i));
            continue;
        }
        try {
            return json::parse(body);
        } catch (const json::parse_error&) {
            // 파싱 실패는 재시도해도 소용없음
            throw;
        }
    }
    throw std::runtime_error("HTTP fetch failed after retries");
}

재시도 코드에서 파싱 실패를 다시 던지는 이유는 실패의 종류가 다르기 때문입니다. 네트워크 오류나 5xx는 잠시 뒤 성공할 수 있지만, 서버가 보낸 JSON이 문법적으로 틀렸다면 같은 요청을 몇 번 반복해도 같은 결과가 나옵니다. 다만 예외가 하나 있습니다. 프록시나 로드밸런서가 장애 중에 JSON 대신 HTML 에러 페이지(<html>...)를 돌려주면 parse_error.101 ... unexpected '<'가 나는데, 이 경우는 사실 일시적인 서버 장애입니다. 파싱 전에 HTTP 상태 코드와 Content-Type을 먼저 확인하면 이 둘을 구분할 수 있고, 로그에 본문 앞부분을 조금 남겨 두면 원인을 훨씬 빨리 찾을 수 있습니다.

스키마 검증 (선택)

nlohmann/json 자체에는 스키마 검증이 없습니다. nlohmann 어댑터를 제공하는 valijson이나, nlohmann/json 위에서 동작하는 json-schema-validator(pboettch) 같은 별도 라이브러리로 JSON Schema 검증을 추가할 수 있습니다.


참고 자료