JSON 응답 최적화와 상태 코드 관리

Slim 프레임워크 기반 API를 구축할 때, 매번 json_encode()를 호출하고 Content-Type 헤더를 수동으로 세팅하는 중복 작업을 줄이는 방법(커스텀 헬퍼 함수 구현)과, 프론트엔드와 원활하게 소통하기 위해 상황별로 올바른 HTTP Status Code를 매핑하는 모범 사례를 알아봅니다.

1. 불편한 기본 JSON 응답 방식

기본적인 Slim의 방식대로라면, PHP 배열을 JSON 문자열로 직렬화하고, 바디 버퍼에 쓰고, application/json 헤더를 붙이는 지루한 코드를 모든 라우트마다 반복해야 합니다.

      
      index.php
    

<?php
$app->get('/users', function ($request, $response) {
    $data = ['id' => 1, 'name' => 'Minstudio'];
    
    // ❌ 매번 반복해야 하는 코드
    $response->getBody()->write(json_encode($data));
    return $response
            ->withHeader('Content-Type', 'application/json')
            ->withStatus(200);
});
?>

2. 최적화: JSON 헬퍼(Helper) 함수 만들기

반복을 피하기 위해 전역(Global) 헬퍼 함수를 하나 만들어두면, 응답 코드를 획기적으로 줄이고 프로젝트 전체에 일관된 API 규격을 강제할 수 있습니다.

      
      helpers.php
    

<?php
// helpers.php 에 선언해두고 전역으로 로드
function jsonResponse($response, array $data, int $status = 200) {
    // JSON_UNESCAPED_UNICODE 옵션으로 한글 깨짐 방지
    $response->getBody()->write(json_encode($data, JSON_UNESCAPED_UNICODE));
    return $response
        ->withHeader('Content-Type', 'application/json')
        ->withStatus($status);
}

// ------------------------------------
// 라우터에서의 활용 (코드가 훨씬 간결해집니다)
// ------------------------------------
$app->post('/users', function ($request, $response) {
    // DB 저장 로직 (Eloquent 등)
    $newUser = ['id' => 3, 'name' => 'Charlie'];
    
    // ✅ 단 한 줄로 JSON 응답 바디 작성 + 상태 코드 설정 완료
    return jsonResponse($response, $newUser, 201);
});
?>

Terminal (curl Response)

$ curl -i -X POST http://localhost:8080/users -d '{"name":"Charlie"}'
HTTP/1.1 201 Created
Host: localhost:8080
Content-Type: application/json
Date: Fri, 22 May 2026 12:45:00 GMT
{
"id": 3,
"name": "Charlie"
}

3. 상황별 HTTP Status Code 모범 사례

프론트엔드 개발자와 원활하게 협업하려면, 단순히 성공(200)과 서버 에러(500)만 내려주어서는 안 됩니다. 실패 원인이나 성공의 종류에 맞게 세분화된 상태 코드를 매핑해야 합니다.

HTTP Status	설명 (주요 사용처)	권장 JSON 응답 형태 (예시)
200 OK	일반적인 요청 성공 (GET 데이터 조회, PUT 성공 등)	`{ "data": [...] }`
201 Created	POST 요청으로 새로운 리소스가 성공적으로 생성됨	`{ "id": 7, "message": "생성 완료" }`
400 Bad Request	클라이언트가 보낸 데이터 형식이 틀림 (유효성 검사 실패)	`{ "error": "Invalid Data", "details": {...} }`
401 Unauthorized	로그인 인증이 누락되었거나 JWT 토큰이 유효하지 않음	`{ "error": "로그인이 필요합니다." }`
403 Forbidden	로그인은 했으나 해당 리소스에 접근할 권한(Role)이 없음	`{ "error": "권한이 없습니다." }`
404 Not Found	요청한 자원(예: 없는 유저 ID)이 DB에 존재하지 않음	`{ "error": "존재하지 않는 회원입니다." }`

JSON 헬퍼 함수 동작 확인

위의 터미널 목업에서는 jsonResponse() 헬퍼 함수를 통해 API 응답이 어떻게 전달되는지 보여줍니다. 단 한 줄의 코드로 JSON 인코딩, Content-Type 헤더 세팅, 그리고 201 Created 와 같은 상태 코드 설정이 한 번에 처리되어 매우 깔끔한 백엔드 구조를 유지할 수 있습니다.

<?php $app->get('/users', function ($request, $response) { $data = ['id' => 1, 'name' => 'Minstudio']; // ❌ 매번 반복해야 하는 코드 $response->getBody()->write(json_encode($data)); return $response ->withHeader('Content-Type', 'application/json') ->withStatus(200); }); ?>

<?php // helpers.php 에 선언해두고 전역으로 로드 function jsonResponse($response, array $data, int $status = 200) { // JSON_UNESCAPED_UNICODE 옵션으로 한글 깨짐 방지 $response->getBody()->write(json_encode($data, JSON_UNESCAPED_UNICODE)); return $response ->withHeader('Content-Type', 'application/json') ->withStatus($status); } // ------------------------------------ // 라우터에서의 활용 (코드가 훨씬 간결해집니다) // ------------------------------------ $app->post('/users', function ($request, $response) { // DB 저장 로직 (Eloquent 등) $newUser = ['id' => 3, 'name' => 'Charlie']; // ✅ 단 한 줄로 JSON 응답 바디 작성 + 상태 코드 설정 완료 return jsonResponse($response, $newUser, 201); }); ?>

HTTP Status

설명 (주요 사용처)

권장 JSON 응답 형태 (예시)

200 OK

일반적인 요청 성공 (GET 데이터 조회, PUT 성공 등)

{ "data": [...] }

201 Created

POST 요청으로 새로운 리소스가 성공적으로 생성됨

{ "id": 7, "message": "생성 완료" }

400 Bad Request

클라이언트가 보낸 데이터 형식이 틀림 (유효성 검사 실패)

{ "error": "Invalid Data", "details": {...} }

401 Unauthorized

로그인 인증이 누락되었거나 JWT 토큰이 유효하지 않음

{ "error": "로그인이 필요합니다." }

403 Forbidden

로그인은 했으나 해당 리소스에 접근할 권한(Role)이 없음

{ "error": "권한이 없습니다." }

404 Not Found

요청한 자원(예: 없는 유저 ID)이 DB에 존재하지 않음

{ "error": "존재하지 않는 회원입니다." }