PHP 프레임워크 – Symfony – 7 – API 개발

작성자 wooah
PHP 프레임워크 - Symfony - 7 - API 개발
PHP 프레임워크 – Symfony – 7 – API 개발

PHP 프레임워크 – Symfony – API 개발

안녕하세요 여러분 😊
이번 시간에는 현대 웹 개발에서 없어서는 안 되는 API(Application Programming Interface) 개발을 Symfony로 어떻게 구현할 수 있는지 알아볼 거예요!

요즘은 모바일 앱, 프론트엔드(Vue, React, Svelte 등), 외부 서비스들이 백엔드와 소통할 때 거의 대부분 RESTful API 방식을 사용하죠.
Symfony는 이런 API를 만들기 아주 좋은 프레임워크입니다. 강력하면서도 유연한 구조 덕분에, 복잡한 데이터 처리와 인증/보안까지 무리 없이 소화할 수 있거든요!

1. API란 무엇인가요?

API는 말 그대로 다른 프로그램들이 사용할 수 있도록 만든 입출력 인터페이스예요.

예를 들어:

  • 앱이 서버에서 게시글 목록을 불러올 때 → GET /api/posts
  • 글을 등록할 때 → POST /api/posts
  • 특정 글을 수정할 때 → PUT /api/posts/123

이런 식으로 HTTP 메서드(GET, POST, PUT, DELETE) 를 조합해서 API가 만들어져요.

마치 음식 주문 앱이 주방과 데이터를 주고받는 통로라고 생각하시면 돼요! 🛎️🍱

2. Symfony에서 API를 만드는 기본 방법

Symfony에서는 API를 만들기 위해 다음 요소들을 주로 사용해요:

  • 라우팅: /api/... 경로로 분리
  • 컨트롤러: JSON 응답 처리
  • Serializer: 객체를 JSON으로 변환
  • Validation: 입력값 유효성 검사
  • API Platform (선택): 완전 자동화된 API 서버 구성

3. JSON 응답 처리하기

가장 기본적인 API는 JSON 데이터를 반환하는 것입니다.

use Symfony\Component\HttpFoundation\JsonResponse;

#[Route('/api/hello', name: 'api_hello')]
public function hello(): JsonResponse
{
    return new JsonResponse([
        'message' => '안녕하세요, Symfony API!',
    ]);
}

결과 예시:

{
  "message": "안녕하세요, Symfony API!"
}

4. 객체를 JSON으로 자동 변환하기 (Serializer)

Symfony에서는 Serializer라는 기능을 사용해서 객체를 JSON으로 바꿀 수 있어요.

설치:

composer require symfony/serializer

사용 예:

use Symfony\Component\Serializer\SerializerInterface;
use App\Entity\Product;

#[Route('/api/product', name: 'api_product')]
public function getProduct(SerializerInterface $serializer): JsonResponse
{
    $product = new Product();
    $product->setName('마법의 물약');
    $product->setPrice(9000);

    $json = $serializer->serialize($product, 'json');

    return new JsonResponse($json, 200, [], true); // true = 이미 JSON 처리됨
}

5. RESTful API 컨트롤러 예제

#[Route('/api/products', name: 'api_products_list', methods: ['GET'])]
public function list(ProductRepository $repo): JsonResponse
{
    $products = $repo->findAll();
    return $this->json($products);
}
  • this->json() 메서드는 Symfony가 제공하는 JSON 변환 단축 함수예요.
  • 객체 배열도 자동 직렬화됩니다.

6. 요청 데이터 받기 (Request)

사용자가 보낸 JSON 데이터를 파싱하려면 Request 객체를 사용하면 됩니다.

use Symfony\Component\HttpFoundation\Request;

#[Route('/api/products', name: 'api_product_create', methods: ['POST'])]
public function create(Request $request): JsonResponse
{
    $data = json_decode($request->getContent(), true);

    $product = new Product();
    $product->setName($data['name'] ?? '');
    $product->setPrice($data['price'] ?? 0);

    // 저장 생략

    return $this->json(['status' => 'created'], 201);
}

7. 유효성 검사 (Validation)

composer require symfony/validator

엔티티에 어노테이션 추가

use Symfony\Component\Validator\Constraints as Assert;

class Product
{
    #[Assert\NotBlank]
    private string $name;

    #[Assert\Positive]
    private float $price;
}

컨트롤러에서 검사:

use Symfony\Component\Validator\Validator\ValidatorInterface;

$errors = $validator->validate($product);

if (count($errors) > 0) {
    return $this->json(['errors' => (string) $errors], 400);
}

8. CORS 설정 (Cross-Origin Resource Sharing)

프론트엔드가 다른 도메인에서 요청하면 CORS 문제가 발생할 수 있어요.

CORS 패키지 설치

composer require nelmio/cors-bundle

설정 추가 (config/packages/nelmio_cors.yaml)

nelmio_cors:
    defaults:
        allow_origin: ['*']
        allow_methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
        allow_headers: ['Content-Type', 'Authorization']
        max_age: 3600
    paths:
        '^/api/':
            allow_origin: ['*']

9. API 보안 처리 (JWT 인증 등)

API는 세션 기반 로그인보다 토큰 기반 인증(JWT) 을 많이 사용해요.

JWT 인증을 위해 필요한 패키지:

composer require lexik/jwt-authentication-bundle

설정 후, API 요청 시 토큰을 헤더에 추가해서 인증할 수 있습니다.

Authorization: Bearer {your_token}

이 부분은 별도로 다룰만큼 방대한 주제이므로 다음 편에서 더 깊이 설명드릴게요 😊

10. API Platform 소개 (자동 API 생성)

Symfony에서는 API Platform이라는 강력한 도구를 제공합니다.
이걸 사용하면 엔티티 하나만 만들어도 CRUD API가 자동 생성돼요!

composer require api

특징

  • 엔티티 기반 자동 API 문서 및 라우팅 생성
  • Swagger UI 자동 생성
  • 데이터 직렬화/역직렬화 자동 처리

주의할 점 ✅

항목 주의사항
JSON 변환 시 순환 참조 주의 @Groups 또는 @Ignore 어노테이션 필요
API는 CSRF 보호 대상 아님 일반 폼과 다르게 동작
API는 세션 사용 최소화 Stateless 원칙 준수
HTTP 상태코드 정확히 반환 200, 201, 400, 404, 500 등 의미에 맞게 사용
입력값 검증 필수 서버에서 반드시 Validation 수행

요약 정리 🎯

기능 방법
JSON 응답 new JsonResponse(), $this->json()
요청 받기 $request->getContent()로 JSON 파싱
객체 변환 Serializer로 serialize()
입력 검증 Validator 컴포넌트 사용
API 인증 JWT 또는 OAuth 사용
자동화 API Platform 도입 시 빠른 구축 가능

마무리하며 😊

Symfony로 API를 개발하면, 가볍게 시작해서 확장성 있게 운영할 수 있는 구조를 갖출 수 있어요.
직접 JSON을 다뤄도 되고, 자동화된 API Platform을 써도 되고요!
또한, 보안과 검증도 함께 고려한 아키텍처 덕분에 유지보수에도 강하답니다 💪

다음 시간에는 Symfony API 개발에 있어 중요한 캐시 처리와 성능 최적화를 알아보겠습니다.
그럼 오늘도 즐거운 Symfony API 개발 되세요~ 🧑‍💻📡💖

답글 남기기