Vapor로 첫 백엔드 만들기 1편: 프로젝트 설정과 기본 라우트
Building My First Vapor Backend in 2026 pt. 1
핵심 요약
- Vapor 대화형 프로젝트 생성 과정에서 Fluent와 Postgres를 선택하고, Leaf는 제외해 JSON API 중심의 LinkVault 기반을 만든다.
- 로컬에서 앱을 실행한 뒤 /health와 /api/welcome 라우트를 추가해 상태 응답과 Content 기반의 타입 지정 JSON 응답을 확인한다.
- LinkPreview 타입과 예시 데이터를 반환하는 /api/links를 구현한다. 다음 편에서는 이 목업 라우트를 Fluent 모델과 데이터베이스 기반 CRUD API로 바꿀 예정이다.
도입
이 연재는 iOS 프런트엔드 개발자가 Swift를 서버 애플리케이션에 적용해 보는 과정으로, 링크 저장 앱 LinkVault를 Vapor로 단계적으로 만든다. 1편에서는 Mac과 Xcode를 기준으로 Vapor 프로젝트를 생성하고 로컬에서 실행한다. 데이터베이스 기능을 위해 Fluent와 Postgres를 선택하며, HTML 템플릿 엔진 Leaf는 사용하지 않는다.
상세 요약
프로젝트 목표와 구성
LinkVault는 링크를 저장하고 컬렉션으로 정리하며, 태그·검색·읽음 상태 관리와 메타데이터 동기화를 제공하는 백엔드 프로젝트다. 1편에서는 기능 구현을 확장하기 전에 Vapor 프로젝트를 만들고 기본 HTTP 라우트를 구성한다. 전제 조건은 Swift가 설치된 Mac 또는 Linux 환경, Homebrew, 터미널, 코드 편집기다. 글의 실습은 Mac과 Xcode를 기준으로 진행한다.
Vapor 프로젝트 생성
Homebrew로 Vapor를 설치하고 vapor --version으로 설치를 확인한다. 이어서 vapor new LinkVault를 실행하면 대화형 설정 화면이 열린다. 글에서는 다음 옵션을 선택한다.
- Fluent: 모델, 마이그레이션, 데이터베이스 쿼리에 사용할 Vapor의 ORM 및 데이터베이스 추상화 계층이다.
- Postgres: 이 백엔드 실습에서 사용할 데이터베이스다.
- Leaf 사용 안 함: Leaf는 동적 HTML 페이지와 렌더링된 이메일 형식 출력을 위한 템플릿 엔진이다. 이 프로젝트는 JSON API에 초점을 맞추므로 제외한다.
vapor new hello -n은 설정 질문에 자동으로 ‘아니오’를 선택하는 기본 템플릿 생성 방식으로도 소개된다. 이 연재에서는 Vapor가 권장하는 프로젝트 설정을 확인하기 위해 대화형 방식을 택한다.
앱 실행과 첫 라우트
프로젝트 디렉터리로 이동해 Xcode에서 연다. Xcode가 설치된 디렉터리에서 xed .을 실행하는 방법도 제시한다. 실행 대상은 My Mac으로 설정하고 앱을 실행한 뒤, 브라우저에서 http://localhost:8080에 접속하면 기본 응답인 It works!를 확인할 수 있다.
routes.swift에 health 경로를 추가하면 http://127.0.0.1:8080/health 요청에 {"status":"ok"}가 반환된다. 이어서 Vapor의 Content 프로토콜을 채택하는 WelcomeResponse 구조체를 정의한다. 이 타입에는 name, message, version 문자열 필드가 들어간다. /api/welcome 라우트는 LinkVault API, 환영 메시지, 버전 0.1.0을 담은 응답을 반환한다. Swift 타입을 라우트의 반환값으로 사용하고 Vapor가 JSON 인코딩을 처리하는 구조다.
목업 링크 응답
마지막으로 id, title, url, isRead 필드를 가진 LinkPreview를 Content 타입으로 정의한다. 예시 데이터로 Vapor 문서 링크와 Swift.org Server 링크를 만들고, 읽음 여부를 각각 false와 true로 설정한다. /api/links는 이 LinkPreview 배열을 JSON으로 반환한다. 이 단계의 링크 데이터는 목업이며, 데이터베이스 모델이나 CRUD 처리는 아직 구현하지 않는다.
다음 편에서는 목업 /api/links를 실제 데이터베이스 기반 API로 바꾼다. Vapor와 Fluent로 LinkVault CRUD 백엔드 만들기에서는 Link 모델, Fluent 마이그레이션, Postgres와 링크 생성·목록·단건 조회·수정·삭제 경로를 다룬다.
결론
1편의 결과물은 데이터베이스에 연결되지 않은 기본 라우트 세 개다. /health는 상태를 반환하고, /api/welcome은 Content를 채택한 Swift 구조체를 JSON으로 돌려주며, /api/links는 목업 링크 배열을 제공한다. 다음 편에서는 링크 모델과 Fluent 마이그레이션, Postgres를 추가하고 생성·조회·수정·삭제 API를 구현할 계획이다.