freeCodeCamp Programming Tutorials: Python, JavaScript, Git & More

Node.js와 함께 Docker를 사용하는 방법: 개발자를 위한 핸드북

changseop yeom — Mon, 05 Jan 2026 23:47:22 +0000

기사 원문: How to Use to Docker with Node.js: A Handbook for Developers

이 핸드북에서는 Docker가 무엇인지, 그리고 Docker가 왜 백엔드 및 풀스택 개발자에게 반드시 필요한 기술인지를 배우게 됩니다. 그리고 가장 중요한 것은, 실제 프로젝트 전 과정을 통해 Docker를 어떻게 활용하는지 익히게 된다는 점입니다.

우리는 흔한 “Hello World” 예제를 훨씬 뛰어넘어, 완전한 풀스택 자바스크립트 애플리케이션(Node.js + Express 백엔드, HTML/CSS/JS 프론트엔드, MongoDB 데이터베이스, Mongo Express 관리자 UI)을 컨테이너화하는 과정을 처음부터 끝까지 함께 따라가 볼 것입니다.

여러 개의 컨테이너를 네트워킹(통신)하는 방법, Docker Compose로 모든 서비스를 오케스트레이션하는 방법, 나만의 이미지를 빌드하고 버전을 관리하는 방법, 볼륨을 사용해 데이터를 영구적으로 보존하는 방법, 그리고 이미지를 안전하게 AWS ECR 개인 레포지토리에 푸시해 공유와 프로덕션 배포에 활용하는 방법 등을 배우게 됩니다.

튜토리얼을 끝낼 즈음에는 “내 컴퓨터에서는 잘 되는데” 문제를 없애고, 멀티 서비스 애플리케이션을 자신 있게 관리하며, 어디서든 일관된 환경을 배포하고, 일상적인 개발 워크플로와 CI/CD 파이프라인에 Docker를 능숙하게 통합할 수 있게 될 것입니다.

Docker는 백엔드 개발자에게 매우 중요한 기술이기 때문에, 먼저 Docker의 기본 개념부터 차근차근 살펴보겠습니다.

전제조건

이 기술 핸드북은 풀스택 개발에 대해 어느 정도 실무 경험이 있는 개발자를 대상으로 합니다. 독자는 애플리케이션 배포에 익숙하고, CI/CD 파이프라인에 대한 기본적인 이해를 갖추고 있어야 합니다. 비록 이 가이드에서 Docker를 기초부터 다루긴 하지만, 완전 초보 개발자를 위한 내용은 아니며, 실제 개발 경험이 있고 Docker로 워크플로를 한 단계 끌어올리고 싶은 분들을 전제로 합니다.

마지막으로, AWS에 대한 기본적인 지식과 일반적인 배포 개념을 알고 있다면 도움이 되지만, 전문가일 필요는 없습니다. 이 핸드북은 프로덕션급 역량을 강화하고, Docker를 자신의 프로젝트에 자신 있게 통합하고자 하는 개발자에게 이상적인 자료입니다.

컨테이너란 무엇인가?
Docker와 가상 머신
Docker 설치
기본 Docker 명령어
JavaScript로 연습하기
- MongoDB 이미지 가져오기
- Mongo Express 이미지 가져오기
- Docker 네트워크
Mongo 컨테이너 실행 방법
Mongo Express 컨테이너 실행 방법
Node.js를 MongoDB에 연결하는 방법
Docker Compose 사용 방법
- 왜 Docker Compose를 사용하는가?
나만의 Docker 이미지 빌드하기
- 해결책
- MongoDB가 동작하는 이유
- 앱을 Docker Compose에 추가하기
- 모든 서비스 시작하기
- 모든 것이 제대로 동작하는지 확인하기
- 무엇이 바뀌었고 왜 동작하는가
컨테이너 관리 방법
프라이빗 Docker 저장소를 만드는 방법
- 1단계: AWS 액세스 키 받기
- 2단계: AWS CLI 설치 여부 확인
- 3단계: AWS CLI 설정
- 4단계: AWS 설정 테스트
- 5단계: ECR(Docker 레지스트리)에 로그인
- Docker 저장소의 이미지 이름 규칙 이해하기
- 6단계: 이미지 빌드, 태그, 푸시하기
과제: 새 버전을 만들어 푸시하기
- 이미지 배포하기
- 왜 ECR에서 전체 이미지 URL을 사용해야 하는가?
- Docker Compose로 앱 배포하기
- 프라이빗 Docker 이미지 공유하기
Docker 볼륨
- Docker 볼륨 동작 방식
- Docker 볼륨의 종류
- 볼륨을 사용하는 Docker Compose 예시 파일
- 애플리케이션 시작하기
결론

컨테이너란 무엇인가?

컨테이너는 애플리케이션이 실행되는 데 필요한 모든 것(의존성, 라이브러리, 설정 파일 등)을 함께 묶어서 패키징하는 방법입니다.

컨테이너는 이식성이 좋아 팀 간에 쉽게 공유할 수 있고, 호환성 문제를 걱정하지 않고 어떤 머신에든 배포할 수 있습니다.

컨테이너는 어디에 있나요?

컨테이너는 팀과 시스템 사이에서 자유롭게 이동하고 공유될 수 있기 때문에, 컨테이너가 “머무를” 장소가 필요합니다. 여기에서 컨테이너 저장소(레지스트리)가 등장하는데, 이는 컨테이너 이미지를 보관하는 특수한 저장 공간입니다. 조직은 내부용 비공개 저장소를 둘 수 있고, Docker Hub 같은 공개 저장소를 통해 누구나 공유된 컨테이너 이미지를 찾아보고 사용할 수 있습니다.

Docker Hub의 카탈로그 페이지를 방문해 보면, Redis, Jenkins 같은 개발자와 팀이 만든 공식 및 커뮤니티 기반 컨테이너 저장소들을 다양하게 볼 수 있습니다.

예전에는 여러 개발자가 서로 다른 프로젝트를 진행할 때, 각자 자신의 시스템에 필요한 서비스를 직접 설치해야 했습니다. 개발자마다 리눅스, macOS, Windows처럼 사용하는 운영체제가 다르다 보니, 설정 과정도 제각각이었습니다. 이 때문에 시간이 많이 들고 오류도 자주 발생했으며, 특히 여러 서비스를 반복해서 세팅해야 할 때는 새로운 환경을 구성하는 일이 큰 골칫거리였습니다.

Docker는 이런 상황을 완전히 바꾸어 놓았습니다. 이제는 모든 서비스와 의존성을 하나씩 직접 설치하는 대신, Docker 명령 한 줄만 실행해서 컨테이너를 띄우면 됩니다. 각 컨테이너는 자신에게 필요한 모든 것을 갖춘 격리된 환경이기 때문에, Windows든 macOS든 Linux든 어떤 머신에서도 동일하게 동작합니다. 덕분에 협업이 훨씬 매끄러워지고, 서로 다른 설정, 누락된 의존성, 버전 불일치 때문에 생기던 병목 현상이 사라집니다.

요약하면, Docker는 애플리케이션과 그 의존성을 하나의 이식 가능한 컨테이너로 포장해서 어디서나 동일한 방식으로 실행할 수 있도록 해주는 플랫폼입니다.

Docker vs 가상 머신

Docker와 가상 머신(VM)은 모두 애플리케이션을 “가상” 환경에서 실행하는 방법이지만, 동작 방식은 서로 다릅니다. 이런 차이를 이해하려면, 먼저 컴퓨터가 소프트웨어를 어떻게 실행하는지 간단히 살펴볼 필요가 있습니다.

레이어를 빠르게 훑어보면:

커널(Kernel): 운영체제에서 CPU, 메모리, 디스크 같은 하드웨어와 직접 통신하는 부분입니다. 앱과 컴퓨터 사이를 이어 주는 중개자라고 생각하면 됩니다.
애플리케이션 계층(Application layer): 실제 프로그램과 앱이 실행되는 영역입니다. 커널 위에 올라가 있으며, 커널을 통해 하드웨어 자원에 접근합니다.

이제 가상 머신을 좀 더 자세히 보겠습니다. VM은 운영체제 전체를 가상화하기 때문에, 자체 커널과 자체 애플리케이션 계층을 모두 포함합니다. VM을 하나 다운로드한다는 것은, 사실상 수 기가 바이트에 이르는 완전한 운영체제를 내 컴퓨터 안에 또 하나 들여오는 것과 같습니다.

자체 OS를 부팅해야 하므로 VM은 시작 속도가 느립니다. 하지만 필요한 것을 모두 가지고 있기 때문에 호스트 환경과 상관없이 거의 어떤 시스템에서도 잘 돌아가는 높은 호환성을 제공합니다.

반면 Docker는 전체 OS가 아니라 애플리케이션 계층만 가상화합니다. 컨테이너는 호스트 시스템의 커널을 공유하지만, 애플리케이션이 필요로 하는 의존성, 라이브러리, 설정 파일 등은 컨테이너 안에 함께 포함합니다.

Docker 이미지는 보통 수 메가바이트 수준으로 작고, 자체 OS를 부팅하지 않기 때문에 컨테이너는 거의 즉시 시작됩니다. Docker가 설치되어 있기만 하면, 호스트가 어떤 운영체제이든(Windows, macOS, Linux) 컨테이너는 동일하게 실행될 수 있습니다.

간단히 정리하면:

VM은 내 컴퓨터 안에 “또 하나의 완전한 컴퓨터”를 띄우는 느낌으로, 크고 무겁고 느립니다.
Docker 컨테이너는 애플리케이션을 담은 독립 패키지에 가까워, 작고 빠르며 이식성이 좋습니다.

간단한 비교 표입니다:

기능	가상 머신	Docker 컨테이너
크기	GB 단위 (큼)	MB 단위 (작음)
시작 속도	느림	빠름
OS 계층	전체 OS + 커널	호스트 커널을 공유
이식성	호환되는 호스트에서 실행됨	도커가 설치된 곳이라면 어디든 실행됨

Docker 설치

이제 Docker가 무엇인지 알게 되었으니, 직접 내 컴퓨터에서 Docker를 실행해 봅시다. Docker는 Windows, macOS, Linux에서 모두 동작하지만, 운영체제마다 설치 과정에 약간씩 차이가 있습니다. Docker 공식 문서에는 모든 운영체제별 설치 방법이 정리되어 있습니다.

시각적으로 보는 것을 더 선호한다면, Windows와 Linux에서 Docker를 설치하는 과정을 단계별로 보여주는 YouTube 영상도 참고할 수 있습니다.

간단한 설치 로드맵은 다음과 같습니다:

먼저 시스템 요구 사항을 확인합니다. Docker는 모든 컴퓨터에서 돌아가는 것이 아니므로, 사용하는 OS 버전이 지원 대상인지 반드시 확인해야 합니다.(공식 문서에 체크리스트가 있습니다.)

Windows 및 macOS 사용자:

새로운 시스템: Docker Desktop을 다운로드해 설치하는 것이 가장 쉽습니다.
구형 시스템: Docker Desktop을 지원하지 않는 경우(예: Hyper-V 미지원, 오래된 OS 버전 등)에는 Docker Toolbox를 사용할 수 있습니다. Toolbox는 가벼운 가상 머신 위에 Docker를 올려 주기 때문에, 오래된 컴퓨터에서도 컨테이너를 실행할 수 있습니다.

2. Linux 사용자

보통 각 배포판의 패키지 관리자(예: Ubuntu/Debian은 apt, CentOS/Fedora는 yum 등)를 사용해 Docker를 설치합니다. 공식 문서에 배포판별 설치 명령이 정리되어 있습니다.

설치가 끝나면, 터미널이나 명령 프롬프트를 열고 다음 명령어를 입력해 설치를 확인합니다:

docker --version

여기에 Docker 버전 정보가 출력되면, 축하합니다! 정상적으로 설치가 완료된 것입니다.

이제 도커가 설치되었으니, 컨테이너를 실행하고, 이미지를 가져오고, 애플리케이션을 안전하고 격리된 환경에서 실험할 준비가 된 것입니다.

초보자를 위한 팁:

만약 구형 시스템에서 Docker Toolbox를 사용 중이라면, 명령어 자체는 대부분 동일하지만, Docker Quickstart Terminal 안에서 명령을 실행해야 합니다. 이 터미널이 가상 머신 환경을 자동으로 설정해 주기 때문입니다.

기본 Docker 명령어

지금까지 우리는 ‘이미지(images)’와 ‘컨테이너(containers)’라는 용어를 여러 번 사용해 왔습니다. 때로는 이 두 용어를 서로 바꿔 쓰기도 했습니다. 하지만 이 둘 사이에는 중요한 차이가 있습니다.

Docker 이미지: 이미지는 설계도(blueprint)나 패키지라고 생각하면 됩니다. 앱이 실행되는 데 필요한 코드, 라이브러리, 의존성, 설정 등이 모두 들어 있지만, 아직 “실행 중”인 상태는 아닙니다.
Docker 컨테이너: 컨테이너는 이미지를 실제로 실행한 “실행 인스턴스”입니다. 컨테이너를 시작하면, Docker가 이미지를 가져와 자신만의 격리된 환경에서 그 내용을 실행합니다.

이렇게 기억하면 도움이 됩니다: 이미지(image)는 레시피이고, 컨테이너(container)는 케이크입니다. 하나의 레시피(이미지)로 케이크(컨테이너)를 여러 개 만들 수 있는 것입니다.

중요한 점: Docker Hub에는 컨테이너가 아니라 이미지가 저장됩니다. 따라서 Docker Hub에서 무언가를 pull 한다는 것은 이미지를 다운로드한다는 뜻입니다.
예를 들어:

docker pull redis

(명령어를 입력하면) 아래 내용을 확인할 수 있습니다.

이 명령은 Redis 이미지를 내 컴퓨터로 다운로드받습니다. 다운로드가 끝나면, 다음 명령으로 로컬에 있는 모든 이미지를 확인할 수 있습니다.

docker images

이제 필요할 때마다 이미지에서 컨테이너를 시작할 수 있습니다.

docker run -d --name my-redis redis

이 명령은 방금 내려받은 redis 이미지로부터, my-redis 라는 컨테이너를 하나 띄웁니다.

docker run 은 도커에게 “이 이미지로 새 컨테이너를 시작하라”고 지시하는 명령입니다.
d 는 “detached mode”의 약자로, 컨테이너를 백그라운드에서 돌려서 터미널을 계속 쓸 수 있게 해 줍니다.
--name my-redis 는 도커가 임의의 이름을 붙이는 대신 my-redis라는 알아보기 쉬운 이름을 컨테이너에 지정합니다. 이렇게 하면 나중에 관리가 더 편해집니다.
redis 는 컨테이너를 시작하는 데 사용할 이미지 이름입니다.

현재 실행 중인 컨테이너를 모두 보고 싶다면:

docker ps

이 명령은 다음과 같은 정보를 포함해 컨테이너 목록을 보여 줍니다.

컨테이너 ID
이름
상태(실행 중인지, 중지 상태인지)
어떤 이미지로부터 실행되고 있는지 등

실행 중이 아닌 컨테이너까지 모두 보고 싶다면, -a 옵션을 추가합니다.

docker ps -a

이미지 버전 지정 방법:

기본적으로 Docker는 이미지의 최신 버전을 가져옵니다. 하지만 특정 버전이 필요할 때는 콜론(:) 뒤에 버전 태그를 붙여서 지정할 수 있습니다. 예를 들어:

docker pull redis:7.2
docker run -d --name my-redis redis:7.2

어떤 버전들이 있는지 알고 싶다면 Docker Hub나 관련 페이지에서 태그 목록을 확인할 수 있습니다. 또한 로컬에서 docker images 명령을 실행하면, 내려받은 이미지들과 각 버전을 확인할 수 있습니다.

컨테이너 중지, 시작, 삭제 방법:

실행 중인 컨테이너를 멈추고 싶다면:

docker stop my-redis

다시 시작하려면:

docker start my-redis

더 이상 필요 없는 컨테이너는 삭제할 수 있습니다.

docker rm my-redis

컨테이너 재시작 방법

무언가 충돌이 발생했거나, 새 설정을 반영하고 싶거나, 단순히 한 번 새로고침하고 싶을 때는 컨테이너 ID(또는 이름)으로 재시작할 수 있습니다. 예를 들어:

docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS         PORTS      NAMES
c002bed0ae9a   redis     "docker-entrypoint.s…"   3 minutes ago   Up 3 minutes   6379/tcp   my-redis

이 컨테이너를 다음처럼 재시작할 수 있습니다.

docker restart c002bed0ae9a

또는 이름으로:

docker restart my-redis

기억해 두면 좋은 다른 방법들입니:

먼저 중지 후 시작

docker stop c002bed0ae9a
docker start c002bed0ae9a
로그를 보면서 시작

docker start c002bed0ae9a && docker logs -f c002bed0ae9a

여러 Redis 컨테이너를 실행하고 포트를 이해하는 방법

현재 Redis 컨테이너가 한개 실행 중인 상태라고 가정해 보겠습니다:

docker ps

출력 예시는 다음과 같습니다:

CONTAINER ID   IMAGE     COMMAND                  STATUS          PORTS      NAMES
c002bed0ae9a   redis     "docker-entrypoint.s…"   Up 20 minutes   6379/tcp   my-redis

PORTS 열을 보면 6379/tcp 로 표시되어 있습니다. 이는 컨테이너 내부에서 Redis가 기본 포트 6379로 실행 중임을 의미합니다. 기본적으로 이 포트는 컨테이너 내부 포트이며, 명시적으로 지정하지 않는 한 여러분의 컴퓨터(호스트)에는 자동으로 노출되지 않습니다. Docker는 사용자가 명시적으로 지정해야만 포트를 매핑합니다.

동일한 포트에서 다른 Redis 컨테이너 실행 시도하기

다음과 같이 시도하면:

docker run -d --name my-redis2 redis:7.4.7-alpine

첫 번째 컨테이너가 이미 호스트 포트 6379를 사용하고 있기 때문에 매핑에 실패합니다. 여기서 포트 바인딩이 필요합니다.

포트 바인딩이란 무엇인가?

포트 바인딩(포트 매핑이라고도 함)은 Docker가 컨테이너 내부의 포트를 호스트 머신(여러분의 노트북/데스크톱/서버)의 포트에 연결하는 데 사용되는 원리입니다.

포트 바인딩이 없으면 컨테이너 내부에서 실행되는 모든 서비스는 완전히 격리됩니다: 내부 포트(예: Redis는 6379, Node.js 앱은 3000, MongoDB는 27017)에서 수신 대기할 수 있지만, 브라우저, 컴퓨터의 다른 앱, 심지어 다른 네트워크에 있는 다른 컨테이너를 포함하여 컨테이너 외부의 어떤 것도 이에 접근할 수 없습니다.

컨테이너 포트: 앱이 실행되고 있는 컨테이너 내부의 포트(Redis는 기본적으로 6379)
호스트 포트: 해당 컨테이너에 액세스하는 데 사용하려는 컴퓨터의 포트.

Docker는 -p 플래그를 사용하여 컨테이너 포트를 다른 호스트 포트에 매핑할 수 있게 해줍니다.

다른 호스트 포트에서 두 번째 Redis 컨테이너 실행하기

docker run -d --name my-redis2 -p 6380:6379 redis:7.4.7-alpine

-p 6380:6379는 호스트 포트 6380을 컨테이너 포트 6379에 매핑(연결)합니다.

이제 localhost:6380을 사용하여 두 번째 컨테이너의 Redis에 연결할 수 있습니다.
컨테이너 내부에서 Redis는 여전히 포트 6379에서 실행됩니다.

두 컨테이너를 확인해보세요:

docker ps

출력은 다음과 같습니다:

CONTAINER ID   IMAGE     STATUS          PORTS             NAMES
c002bed0ae9a   redis     Up 20 minutes   6379/tcp          my-redis
d123abcd5678   redis     Up 1 minute     0.0.0.0:6380->6379/tcp   my-redis2

첫 번째 컨테이너는 6379에서 내부적으로 실행되고(호스트 포트가 노출되지 않음), 두 번째 컨테이너는 호스트 포트 6380이 컨테이너 포트 6379로 트래픽을 전달하도록 매핑되어 있습니다.

각 컨테이너를 전화선(컨테이너 포트)이 있는 방으로 생각해보세요.

외부(호스트)에서 그 방으로 전화를 걸고 싶습니다.
두 개의 방에 동시에 같은 외부 전화선을 사용할 수 없습니다.
포트 바인딩을 사용하면 내부 전화번호가 같더라도, 각 방에 다른 외부 회선을 할당할 수 있습니다.

포트 바인딩이 존재하는 이유

호스트의 포트 충돌 방지: 컴퓨터에서 한 번에 하나의 프로세스만 지정된 포트를 사용할 수 있습니다. 이미 호스트 포트 6379를 사용하는 Redis 컨테이너가 하나 있다면, 두 번째 컨테이너도 같은 호스트 포트에 바인딩할 수 없습니다. 포트 바인딩을 사용하면 각각을 다른 호스트 포트(6379 → 6380, 6381 등)에 매핑하여 여러 동일한 컨테이너를 나란히 실행할 수 있습니다.
호스트에서 컨테이너화된 서비스에 액세스: 브라우저, Postman, MongoDB Compass, redis-cli, curl 등은 모두 호스트에서 실행됩니다. -p 플래그 없이는 컨테이너 내부의 서비스와 통신할 방법이 없습니다.
선택적 노출: 컨테이너가 사용하는 모든 포트를 노출할 필요는 없습니다. 실제로 외부에서 필요한 포트만 매핑하여 나머지는 비공개 상태로 안전하게 유지할 수 있습니다.

또한 개발 및 프로덕션 환경에서 더 많은 유연성을 제공합니다. 개발 환경에서는 컨테이너 3000을 호스트 3000에 매핑할 수 있습니다. 하지만 프로덕션 환경에서는(예: 리버스 프록시 뒤에서) 컨테이너 3000을 호스트 80 또는 443에 매핑하거나, 전혀 노출하지 않고 다른 컨테이너가 Docker의 내부 네트워크를 통해 통신하도록 할 수 있습니다.

컨테이너 탐색 방법

컨테이너를 탐색하려면 다음을 실행하세요:

docker exec -it my-redis2 /bin/sh

docker exec는 컨테이너에서 명령을 실행합니다.
it 대화형 터미널(입력하고 출력을 볼 수 있게 해줌).
/bin/sh는 컨테이너 내부에서 셸을 시작합니다.

내부에 들어가면 프롬프트가 다음과 같이 변경됩니다:

/data #

이제 호스트 머신에 영향을 주지 않고 전부 컨테이너 내부에서 파일을 나열하고, 디렉토리를 탐색하거나, 프로그램을 실행할 수 있습니다.

`docker run` vs `docker start`

이 문서 전체에서 docker run과 docker start를 사용해 왔는데, 그 차이점이 중요한 이유는 다음과 같습니다:

우발적인 중복 방지: 매번 docker run을 사용하면 새 컨테이너가 생성됩니다. 이미 설정한 것을 단지 다시 시작하려면 docker start가 더 빠르고 안전합니다.
구성 유지: docker start는 컨테이너의 원래 설정, 포트, 볼륨 및 이름 등을 보존하므로 옵션을 변경하여 문제가 발생할 위험이 없습니다.
여러 컨테이너로 효율적으로 작업: 여러 서비스 또는 동일한 앱의 다른 버전을 실행할 때, run과 start를 언제 사용할지 아는 것은 리소스를 관리하고 포트 충돌을 피하며 워크플로우를 원활하게 유지하는 데 도움이 됩니다.
워크플로우 속도 향상: 기존 컨테이너를 시작하는 것은 거의 즉각적이지만, 새 컨테이너를 생성하는 것은 약간 더 오래 걸립니다.

요약하자면 docker run = 새로운 것을 생성, docker start = 이미 가지고 있는 것을 다시 시작하는 것입니다.

JavaScript로 연습하기

이제 핵심 Docker 개념을 다루었으니 실제로 적용해봅시다. 이 섹션에서는 다음으로 구성된 간단한 JavaScript 프로젝트를 컨테이너화합니다:

프론트엔드: HTML, CSS 및 JavaScript로 구축
백엔드: 간단한 Node.js 서버(server.js)
데이터베이스: Docker Hub에서 직접 가져온 MongoDB 인스턴스
MongoDB용 UI: Mongo Express를 사용하여 데이터베이스를 시각화하고 관리

이 예제는 Docker가 어떻게 격리되고 일관된 환경에서 코드, 종속성 및 서비스 등을 포함한 애플리케이션의 여러 컴포넌트(구성 요소)를 관리하는지를 보여줍니다.

GitHub에서 스타터 프로젝트를 가져올 수 있습니다.

또는 터미널을 사용하여 직접 클론하세요:

git clone https://github.com/Oghenekparobo/docker_tut_js.git
cd docker_tut_js

여기에는 Node.js 백엔드와 함께 기본 HTML 및 JavaScript 파일이 포함되어 있습니다.

다음으로 데이터베이스 설정을 준비합니다. Docker Hub로 이동하여 검색창에 "mongo"를 입력하세요. Docker에서 게시한 공식 MongoDB 이미지가 표시됩니다.

MongoDB 이미지를 가져오는 방법

이제 Docker Hub에서 공식 MongoDB 이미지를 탐색했으니 실제로 로컬 환경으로 가져와봅시다.

터미널을 열고 프로젝트 디렉토리(예: docker_tut_js)로 이동한 다음 실행하세요:

docker pull mongo

이 명령은 Docker에게 Docker Hub에서 최신 버전의 MongoDB 이미지를 다운로드하도록 지시합니다.

다음과 유사한 출력이 표시됩니다:

Using default tag: latest
latest: Pulling from library/mongo
b8a35db46e38: Already exists 
a637dbfff7e5: Pull complete 
0c9047ace63c: Pull complete 
02cd4cf70021: Pull complete 
dfb5d357a025: Pull complete 
007bf0024f67: Pull complete 
67fd8af3998d: Pull complete 
d702312e8109: Pull complete 
Digest: sha256:7d1a1a613b41523172dc2b1b02c706bc56cee64144ccd6205b1b38703c85bf61
Status: Downloaded newer image for mongo:latest
docker.io/library/mongo:latest

무슨 일이 일어나고 있는지 설명하면:

"Using default tag: latest": 특정한 버전이 제공되지 않았으므로 Docker가 MongoDB의 최신 버전을 가져옵니다.
"Pulling from library/mongo": Docker의 공식 이미지 라이브러리에서 다운로드하고 있습니다.
"Pull complete": 각 줄은 성공적으로 다운로드 중인 이미지의 레이어를 나타냅니다.
"Downloaded newer image for mongo:latest": MongoDB 이미지가 이제 시스템의 로컬에 저장되었음을 확인합니다.

다음을 실행하여 사용 가능한지 확인할 수 있습니다:

docker images

repository 열에 mongo가 나열되어 있어야 합니다.

Mongo Express 이미지 가져오기 방법

이제 MongoDB 이미지가 준비되었으니 Mongo Express 이미지를 가져와봅시다.

Mongo Express는 브라우저를 통해 MongoDB 컬렉션을 보고 관리할 수 있는 경량 웹 기반 인터페이스로, phpMyAdmin이 MySQL에서 작동하는 방식과 유사합니다.

터미널을 열고(여전히 프로젝트 디렉토리에서) 다음을 실행하세요:

docker pull mongo-express

다음과 유사한 출력이 표시됩니다:

Using default tag: latest
latest: Pulling from library/mongo-express
b8a35db46e38: Already exists
a637dbfff7e5: Pull complete
4e0e0977e9c3: Pull complete
02cd4cf70021: Pull complete
Digest: sha256:3d6dbac587ad91d0e2eab83f09a5b31a1c8f9d91a8825ddaa6c7453c25cb4812
Status: Downloaded newer image for mongo-express:latest
docker.io/library/mongo-express:latest

이것이 의미하는 바는 다음과 같습니다:

docker pull mongo-express는 Docker Hub에서 공식 Mongo Express 이미지를 다운로드합니다.
각 "Pull complete" 줄은 성공적으로 다운로드된 이미지의 레이어를 나타냅니다.
mongo-express:latest는 최신 버전이 이제 로컬에 저장되었음을 확인합니다.

두 이미지가 모두 사용 가능한지 확인하려면 다음을 실행하세요:

docker images

출력에 mongo와 mongo-express가 나열되어 있어야 합니다.

이제 두 이미지가 모두 다운로드되었으므로, 다음 단계는 MongoDB가 실행되고 접근 가능한지 확인한 다음, 브라우저를 통해 관리할 수 있도록 Mongo Express에 연결하는 것입니다.

그 전에, 이 두 컨테이너가 어떻게 통신할지 간단히 살펴봅시다.

Docker 네트워크

MongoDB와 Mongo Express가 별도의 컨테이너에서 실행될 때 서로 통신할 방법이 필요합니다. Docker는 Docker 네트워크라는 것을 사용하여 이를 처리합니다. 이는 내부 포트를 외부 세계에 노출하지 않고 컨테이너가 안전하게 통신할 수 있게 해주는 가상 브리지입니다.

Docker에서 컨테이너를 실행하면 자동으로 격리된 네트워크가 생성됩니다. 이를 마치 컨테이너들이 외부 세계에 모든 것을 노출하지 않고 안전하게 서로 통신할 수 있는 개인 공간처럼 생각하면 됩니다.

예를 들어, MongoDB 컨테이너와 Mongo Express 컨테이너가 동일한 Docker 네트워크에 있으면 컨테이너 이름(예: mongo 또는 mongo-express)만 사용하여 통신할 수 있습니다. Docker가 이를 내부적으로 처리하므로localhost나 포트 번호를 사용할 필요가 없습니다.

하지만 Docker 네트워크 외부의 모든 것(여러분의 호스트 머신이나 Node.js 앱 같은)은 노출된 포트를 통해 연결됩니다.

따라서 나중에 전체 애플리케이션, Node.js 백엔드, MongoDB, Mongo Express, 심지어 프론트엔드(index.html)까지 Docker로 패키징하면, 이 모든 컨테이너가 Docker 네트워크를 통해 원활하게 상호 작용합니다. 그러면 컴퓨터의 브라우저는 우리가 노출한 호스트 주소와 포트를 사용하여 Node.js 앱에 연결됩니다.

기본적으로 Docker는 이미 몇 가지 내장 네트워크를 제공합니다. 다음을 실행하여 확인할 수 있습니다:

docker network ls

다음과 같은 결과가 나올 것입니다:

NETWORK ID     NAME      DRIVER    SCOPE
712a7144f1a0   bridge    bridge    local
4ae27eedea5b   host      host      local
4806000201ce   none      null      local

이것들은 Docker에 의해 자동으로 생성됩니다. 지금은 이것들에 대해 너무 걱정할 필요가 없습니다 – 우리는 커스튬(자체 사용자 정의) 네트워크를 만드는 데 집중하겠습니다.

설정을 위해 MongoDB와 Mongo Express가 공유할 수 있는 별도의 네트워크를 만들겠습니다. 이를 mongo-network라고 부르겠습니다:

docker network create mongo-network

Mongo 컨테이너 실행 방법

MongoDB와 Mongo Express 컨테이너가 통신할 수 있도록 하려면 동일한 Docker 네트워크 내에서 실행해야 합니다. 그래서 앞서 mongo-network를 만든 것입니다.

MongoDB부터 시작하겠습니다. docker run 명령은 이미지에서 컨테이너를 시작하는 데 사용된다는 것을 기억하세요. 이번에는 공식 MongoDB 이미지를 실행하고 네트워크에 연결할 것입니다.

또한 컨테이너 외부에서 접근할 수 있도록 기본 MongoDB 포트 27017을 노출하고, 루트 사용자 이름과 비밀번호에 대한 환경 변수를 설정합니다.

다음은 명령어입니다:

docker run -p 27017:27017 -d \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  --name mongo \
  --network mongo-network \
  mongo

각 부분이 하는 일은 다음과 같습니다:

-p 27017:27017은 컨테이너의 MongoDB 포트를 호스트 머신에 매핑합니다.
-d는 컨테이너를 분리 모드(백그라운드)에서 실행합니다.
-e는 데이터베이스의 루트 크레덴셜(루트 자격 증명)에 대한 환경 변수를 설정합니다.
--name mongo는 컨테이너에 사용자 정의 이름을 부여해 더 쉽게 참조할 수 있도록 합니다.
--network mongo-network는 우리가 만든 네트워크에 컨테이너를 연결합니다.

성공적으로 실행되면 MongoDB 인스턴스가 Docker 네트워크 내에서 실행되며, Mongo Express와 같은 다른 컨테이너가 연결할 준비가 됩니다.

MongoDB 컨테이너를 생성한 후 실행 중이고 정상인지 쉽게 확인할 수 있습니다.

먼저 docker ps를 실행하여 모든 활성 컨테이너를 확인하세요. MongoDB 컨테이너(mongo)가 포트 27017이 노출된 상태로 나열되어야 합니다. 컨테이너 내부에서 무슨 일이 일어나고 있는지에 대한 자세한 정보를 얻으려면 docker logs mongo를 사용하거나, 원한다면 컨테이너 ID를 사용하여(예: docker logs 7abb38175ae28) 로그를 확인할 수 있습니다. 로그는 MongoDB의 시작 메시지를 보여줄 것이며, 데이터베이스가 성공적으로 시작되었고 연결될 준비가 되었음을 나타내는 명령줄을 찾아야 합니다.

이것은 Mongo Express와 같은 다른 서비스를 연결하기 전에 모든 것이 올바르게 작동하는지 확인하는 빠른 방법입니다.

docker ps

이것은 실행 중인 모든 컨테이너를 나열합니다. MongoDB 컨테이너(mongo)가 포트 27017이 노출된 상태로 표시되어야 합니다.

docker logs mongo 또는 컨테이너의 id 예시: docker logs 7abb38175ae283429354609866c8d97521f37b535c475ae448295f8fc0ed947f

이것은 시작 메시지를 보여줍니다. MongoDB가 성공적으로 시작되었고 연결될 준비가 되었음을 나타내는 줄을 찾아보세요.

Mongo Express 컨테이너 실행 방법

이제 MongoDB가 실행 중이므로 MongoDB 데이터베이스를 관리하고 보기 위한 웹 기반 인터페이스인 Mongo Express를 실행할 수 있습니다. MongoDB와 통신할 수 있도록 동일한 네트워크(mongo-network)에 연결하겠습니다.

다음은 명령어입니다:

docker run -d \
  -e ME_CONFIG_MONGODB_ADMINUSERNAME=admin \
  -e ME_CONFIG_MONGODB_ADMINPASSWORD=password \
  -e ME_CONFIG_MONGODB_SERVER=mongo \
  --name mongo-express \
  --network mongo-network \
  -p 8081:8081 \
  mongo-express

각 부분이 하는 일은 다음과 같습니다:

-d는 컨테이너를 분리 모드(백그라운드)에서 실행합니다.
-e ME_CONFIG_MONGODB_ADMINUSERNAME=admin은 Mongo Express가 사용할 MongoDB 어드민(관리자) 사용자 이름을 설정합니다.
-e ME_CONFIG_MONGODB_ADMINPASSWORD=password는 해당 MongoDB 비밀번호를 설정합니다.
-e ME_CONFIG_MONGODB_SERVER=mongo는 Mongo Express에 연결할 MongoDB 서버를 알려줍니다. 두 컨테이너가 동일한 네트워크에 있기 때문에 여기서는 컨테이너 이름 mongo를 사용합니다.
--name mongo-express는 더 쉽게 참조할 수 있도록 컨테이너에 친숙한 이름을 부여합니다.
--network mongo-network는 MongoDB와 동일한 Docker 네트워크에 컨테이너를 연결하여 서로 통신할 수 있게 합니다.
-p 8081:8081은 호스트 머신의 포트 8081에서 Mongo Express 웹 인터페이스를 노출합니다.
mongo-express는 실행 중인 Docker 이미지의 이름입니다.

컨테이너가 실행되면 브라우저를 열고 http://localhost:8081에 접속하여 Mongo Express에 액세스하고 MongoDB 인스턴스와 상호작용할 수 있습니다.

사용 가능한 환경 변수 및 옵션에 대한 자세한 내용은 Mongo Express의 공식 Docker Hub 페이지에서 확인할 수 있습니다.

브라우저에서 http://localhost:8081을 열기 전에 Mongo Express 컨테이너가 제대로 실행되고 있는지 확인하는 것이 좋습니다. 로그를 보면 확인할 수 있습니다:

docker logs 
# 또는
docker logs mongo-express

다음과 유사한 출력이 표시되어야 합니다:

Waiting for mongo:27017...
No custom config.js found, loading config.default.js
Welcome to mongo-express 1.0.2
------------------------
Mongo Express server listening at http://0.0.0.0:8081
Server is open to allow connections from anyone (0.0.0.0)
basicAuth credentials are "admin:pass", it is recommended you change this in your config.js!

이것은 Mongo Express가 실행 중이며 MongoDB 인스턴스에 연결할 준비가 되었음을 확인하는 것입니다.

로그에 표시된 basicAuth 자격 증명(admin:pass)을 기록해두세요. 이러한 자격 증명이 있는 경우 브라우저에서 Mongo Express에 액세스할 때 사용해야 합니다. 나중에 보안을 강화하기 위해 사용자 정의 config.js 파일에서 변경할 수 있습니다.

로그에서 모든 것이 정상으로 보이면 http://localhost:8081에 안전하게 접속하여 Mongo Express 인터페이스에 액세스할 수 있습니다.

Mongo Express에 액세스할 때 브라우저에서 사용자 이름과 비밀번호를 묻는 경우 컨테이너 로그에 표시된 basicAuth 자격 증명을 사용하세요:

사용자 이름: admin
비밀번호: pass

이것들은 기본 자격 증명이며, 보안을 강화하기 위해 나중에 사용자 정의 config.js 파일에서 변경하는 것을 강력히 권장합니다.

Mongo Express를 열면 이미 생성된 일부 기본 데이터베이스가 표시됩니다. 이 프로젝트에서는 todos라는 새 데이터베이스를 만들 것입니다. 생성되면 Node.js 애플리케이션이 이 데이터베이스에 연결하여 데이터를 저장하고 검색할 수 있습니다.

Node.js를 MongoDB에 연결하는 방법

이미 Docker 컨테이너(mongo) 내에서 MongoDB가 실행되고 있습니다. 컨테이너는 기본 MongoDB 포트 27017을 호스트에 노출하므로 노트북/데스크톱의 모든 프로세스가 localhost:27017을 통해 접근할 수 있습니다.

중요: Node.js 앱은 Docker 외부에 있습니다(터미널에서 시작하는 일반 node server.js 프로세스입니다).

앱이 외부에 있기 때문에 호스트 이름으로 컨테이너 이름 mongo가 아닌 localhost(또는 127.0.0.1)를 사용해야 합니다.

나중에 Node.js 앱을 컨테이너화하고 동일한 Docker 네트워크에 배치하면 호스트를 mongo로 전환할 것입니다. 지금은 localhost로 유지하세요.

Node.js 백엔드

다음은 MongoDB를 사용하는 server.js 버전입니다:

const express = require("express");
const multer = require("multer");
const path = require("path");
const fs = require("fs");
const { MongoClient, ObjectId } = require("mongodb");

const app = express();
const PORT = 3000;

// Host = localhost  →  노출된 포트를 통해 MongoDB 컨테이너와 통신
// Port = 27017      →  기본 MongoDB 포트
// User / Pass       →  admin / password (컨테이너에 제공한 자격 증명)
const mongoUrl = "mongodb://admin:password@localhost:27017";
const dbName = "todos";
let db;

MongoClient.connect(mongoUrl)
  .then((client) => {
    db = client.db(dbName);
    console.log("Connected to MongoDB →", dbName);
  })
  .catch((err) => console.error("MongoDB connection error:", err));

const uploadDir = path.join(__dirname, "uploads");
if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir);

const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, uploadDir),
  filename: (req, file, cb) => {
    const unique = Date.now() + "-" + Math.round(Math.random() * 1e9);
    cb(null, "photo-" + unique + path.extname(file.originalname));
  },
});
const upload = multer({ storage });

app.use(express.static(__dirname));
app.use("/uploads", express.static(uploadDir));
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get("/todos", async (req, res) => {
  const todos = await db.collection("todos").find().toArray();
  res.json(todos);
});

app.post("/todos", upload.single("photo"), async (req, res) => {
  const text = req.body.text?.trim();
  if (!text) return res.status(400).json({ error: "Text required" });

  const todo = {
    text,
    image: req.file ? `/uploads/${req.file.filename}` : null,
    createdAt: new Date(),
  };

  const result = await db.collection("todos").insertOne(todo);
  todo._id = result.insertedId;
  res.json(todo);
});

// 서버 시작
app.listen(PORT, () => {
  console.log(`Server → http://localhost:${PORT}`);
});

프론트엔드

index.html:



  
    
    Todo + Image
    
  
  
    Todo List with Images

    
      
      
      
      
      
    

    Todos

이제 Node.js 앱이 Docker에서 실행 중인 MongoDB 컨테이너에 연결할 수 있습니다. 앱이 현재 Docker 외부에서 실행되고 있으므로 설정한 자격 증명(admin / password)을 사용하여 localhost:27017을 통해 연결합니다.

연결되면 Node.js 백엔드는 메모리 내 배열을 대체하여 MongoDB의 todos 데이터베이스에서 직접 todos를 저장하고 검색합니다. 나중에 Node.js 앱을 컨테이너화하고 MongoDB와 동일한 Docker 네트워크에 배치하면 호스트를 localhost에서 컨테이너 이름 mongo로 전환할 수 있습니다. 우리는 그 방향으로 가고 있습니다.

코드를 실행하고 설정에 맞게 수정할 준비가 된 전체 백엔드 및 프론트엔드 코드는 이곳에서 얻을 수 있습니다: GitHub 저장소.

Docker Compose 사용 방법

이제 Node.js 앱이, 컨테이너 안에서 실행 중인 MongoDB와 Mongo Express에 연결되었습니다. 우리는 네트워크를 만들고 컨테이너를 시작했으며, 모든 서비스가 완벽하게 통신하고 있습니다.

하지만 솔직히 말해서: 매번 길고 복잡한 docker run 명령어를 입력하기란 꽤 번거롭습니다. 명령어 한 번에 모든 것을 실행할 수 있는 간단하고 깔끔한 방법이 있으면 좋겠죠? 바로 Docker Compose가 그 역할을 합니다.

Docker Compose는 하나의 명령으로, 여러 컨테이너로 구성된 애플리케이션을 정의하고 실행할 수 있는 도구입니다. 여러 개의 docker run 명령을 수동으로 실행하는 대신, 간단한 docker-compose.yml 파일에 각 서비스(예: Node.js 앱, MongoDB, Mongo Express)와 해당 구성, 환경 변수, 공유 네트워크를 지정하여, 설정을 정의할 수 있습니다.

즉, 여러 컨테이너를 하나의 프로젝트처럼 관리할 수 있게 도와주며,
시작, 중지, 유지 보수를 모두 하나의 파일과 명령으로 처리할 수 있습니다.

docker-compose.yml 또는 docker-compose.yaml 중 어느 것이나 사용이 가능하지만, 관례상 .yml 확장자가 더 일반적입니다.

Docker는 실행 시 이를 자동으로 감지합니다:

docker compose up

네, 관례대로 docker-compose.yml 파일을 사용하는 것이 좋습니다.

이제 MongoDB와 Mongo Express 컨테이너를 실행하려면 각각 다음 두 명령어를 사용하면 됩니다.

# MongoDB container
docker run -p 27017:27017 -d \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  --name mongo \
  --network mongo-network \
  mongo

# Mongo Express container
docker run -d \
  -e ME_CONFIG_MONGODB_ADMINUSERNAME=admin \
  -e ME_CONFIG_MONGODB_ADMINPASSWORD=password \
  -e ME_CONFIG_MONGODB_SERVER=mongo \
  --name mongo-express \
  --network mongo-network \
  -p 8081:8081 \
  mongo-express

이제 매번 이러한 긴 명령어를 입력하는 대신, Docker Compose 파일을 사용하여 모든 명령어를 한 번에 실행할 것입니다.

docker-compose.yml 파일은 Node.js 프로젝트의 루트 디렉터리에 위치해야 합니다.

docker-compose.yml 파일은 다음과 같습니다:

version: "3.8"

services:
  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

지금 무슨 일이 벌어지고 있는지 하나씩 살펴보도록 하겠습니다.

version: "3.8" → Compose 파일의 버전을 정의합니다. 각 버전마다 조금씩 다른 문법 규칙과 기능이 있으며, 3.8 버전은 최신 Docker Engine과 호환되는 현대적인 버전입니다.
services: → 실행할 모든 컨테이너를 정의하는 영역입니다. 여기서는 mongodb와 mongo-express 두 서비스입니다.

MongoDB 서비스

image: mongo: Docker Hub에서 공식 MongoDB 이미지를 가져옵니다.
container_name: mongo: 컨테이너에 친근한 이름을 지정합니다.
ports: "27017:27017": MongoDB의 기본 포트를 호스트에 노출하여 Node.js 또는 다른 애플리케이션이 연결할 수 있도록 합니다.
environment: 초기 루트 사용자 이름과 비밀번호를 설정합니다.

Mongo Express 서비스

image: mongo-express: 공식 Mongo Express 이미지를 사용합니다.
container_name: mongo-express: 컨테이너 이름을 더 쉽게 참조할 수 있도록 친근하게 지정합니다.
ports: "8081:8081": 호스트의 8081 포트에서 Mongo Express 웹 인터페이스를 노출합니다.
environment: Mongo Express에게 MongoDB를 연결하는 방법(사용자 이름, 비밀번호, 호스트)를 알려줍니다.
depends_on: - mongodb: MongoDB가 먼저 실행된 후 Mongo Express가 즉시 시작되도록 보장합니다.

Docker Compose를 사용하는 이유

한 번의 명령으로 시작 가능: 여러 개의 docker run 명령 대신, 그저 아래 명령어를 실행하세요:

docker compose up -d

자동 네트워킹: Compose는 기본 네트워크를 생성하여 서비스들이 서비스 이름(우의 경우 mongodb)을 사용하여 통신할 수 있도록 합니다.
쉽고 유연한 유지보수: 모든 서비스를 함께 중지, 재시작, 재빌드할 수 있습니다.

새로운 docker-compose.yml 파일을 실행하기 전에 충돌을 일으키는 컨테이너가 현재 실행 중이지 않은지 확인하는 것이 중요합니다. 이전 docker run 명령으로 MongoDB와 Mongo Express가 이미 실행 중이었음을 기억하세요.

충돌을 방지하려면(이미 사용 중인 포트처럼) 실행 중인 컨테이너를 모두 중지하고 제거해야 합니다.

방법은 다음과 같습니다.

# 실행 중인 컨테이너 목록 보기
docker ps

# 개별 컨테이너 중지( 부분을 mongo 또는 mongo-express로 대체)
docker stop mongo
docker stop mongo-express

# 중지된 컨테이너 삭제
docker rm mongo
docker rm mongo-express

# (선택) 실행 중인 모든 컨테이너 중지 및 삭제
docker stop $(docker ps -q)
docker rm $(docker ps -a -q)

docker ps 명령은 현재 실행 중인 컨테이너들을 보여줍니다.
docker stop 명령은 지정한 이름의 컨테이너를 정상적으로 중지합니다.
docker rm 명령은 중지된 컨테이너를 Docker에서 삭제합니다.
docker stop $(docker ps -q) 명령은 현재 실행 중인 모든 컨테이너를 중지합니다.
docker rm $(docker ps -a -q) 명령은 실행 중이든 중지 중이든 모든 컨테이너를 삭제합니다.

이전 단계의 컨테이너를 모두 중지하고 제거했다면,
이제 포트 충돌 없이 안전하게 Docker Compose 환경을 실행할 준비가 된 것입니다.

이제 모든 기존 컨테이너가 중지되었으므로,
docker-compose.yml 파일을 이용해 MongoDB와 Mongo Express를 함께 실행할 수 있습니다.

Node.js 프로젝트 루트(즉, docker-compose.yml 파일이 위치한 디렉터리)에서 다음 명령을 실행하세요:

docker compose up -d

이 명령이 하는 일:

docker compose → Docker에게 Compose를 사용하라고 지시합니다.
up → Compose 파일에 정의된 모든 서비스를 빌드(필요 시)하고 시작합니다.
-d → 컨테이너를 백그라운드(분리 모드)로 실행시켜, 즉, (터미널을 차지하지 않고) 백그라운드에서 실행된다는 의미입니다.

이 명령을 실행하면 Docker는 MongoDB와 Mongo Express를 동시에 시작하고,
두 컨테이너를 같은 내부 네트워크에 연결하며, 각 서비스에 대해 우리가 지정한 포트를 노출합니다.(MongoDB는 27017, Mongo Express는 8081)

모든 것이 정상적으로 작동했다면, 다음 명령을 실행한 후:

docker compose up -d

정상적으로 실행되었다면 다음과 유사한 출력이 나타납니다:

[+] Running 3/3
 ✔ Network docker_tut_default  Created                                                                                               0.0s 
 ✔ Container mongo             Started                                                                                               0.6s 
 ✔ Container mongo-express     Started                                                                                               0.8s 
stephenjohnson@Oghenekparobo docker_tut %

이 출력이 의미하는 것

Network docker_tut_default Created → Docker Compose가 서비스 간 통신을 위해 새 네트워크를 자동으로 생성했습니다.
Container mongo Started → MongoDB 컨테이너가 실행되었습니다.
Container mongo-express Started → Mongo Express 컨테이너가 실행되었습니다.

컨테이너가 실제로 실행 중인지 확인하려면 다음 명령을 입력합니다:

docker ps

이 명령은 현재 활성 상태의 모든 컨테이너를 나열합니다. mongo와 mongo-express 컨테이너가 각각 MongoDB(포트 27017)와 Mongo Express(포트 8081)로 표시되어 있어야 합니다.

Mongo Express에 접속하려면 브라우저를 열고 http://localhost:8081로 이동하여 웹 인터페이스를 통해 MongoDB와 상호작용하세요.
MongoDB에 접속하려면 Node.js 앱에서 Compose 파일에 설정한 자격 증명을 사용하여 localhost:27017로 MongoDB에 연결할 수 있습니다.

docker run 명령을 여러 번 사용하는 것과 비교했을 때, Docker Compose를 사용하는 것이 더 쉬운 이유는 다음과 같습니다:

여러 컨테이너를 한 번의 명령으로 실행할 수 있습니다.
컨테이너 간 자동 네트워크 설정이 이루어집니다.
나중에 컨테이너를 중지, 삭제, 재빌드하기가 훨씬 쉽습니다.

간단히 말해, Docker Compose는 모든 것을 단순화하고 체계화하여 개발 환경 관리를 훨씬 더 쉽게 만들어줍니다.

이 단계에서 알아야 할 중요한 점은 MongoDB에 추가하는 모든 데이터는 임시적이라는 것입니다. 컨테이너를 중지하거나 삭제한 뒤 다시 실행하면, 이전에 저장한 데이터가 모두 사라진 것을 확인할 수 있습니다. 이는 컨테이너 내부의 데이터가 기본적으로 영구 보존되지 않기 때문입니다.

걱정하지 마세요. 이것은 정상적인 동작입니다. 튜토리얼의 이후 단계에서 Docker Volumes 개념을 다루며 어떻게 데이터를 영구적으로 저장할 수 있는지 배울 예정입니다.

일단은 컨테이너를 재시작할 때마다 MongoDB가 초기 상태로 시작된다는 사실만 기억하시면 됩니다.

전체 예제(Dockerfile과 docker-compose 파일을 포함한 예시)는 이 GitHub 링크에서 확인하실 수 있습니다.

나만의 Docker 이미지 빌드하는 방법

이제 Node.js 애플리케이션을 로컬에서 테스트했고, MongoDB와 Mongo Express와도 완벽히 연동되어 작동하는 것을 확인했습니다. 다음 단계는 이제 배포를 위한 준비입니다.

로컬 환경에서 직접 애플리케이션을 실행하는 것은 개발 단계에서는 괜찮지만, 배포 환경이나 다른 서버로 옮기고자 할 때는 실용적이지 않습니다. Docker 이미지를 생성하여, 애플리케이션 코드, 의존성, 설정, 실행 환경을 하나의 이동 가능한 단위로 패키징할 수 있습니다. 이 이미지는 Docker가 설치된 어디서든 동일하게 실행될 수 있으며, 개발–테스트–운영 환경 간에 일관된 동작 보장이 가능합니다.

간단히 말해, Docker 이미지를 빌드한다는 것은 애플리케이션을 컨테이너화하고 배포 준비 상태로 만든다는 뜻입니다.

이번에는 우리가 만든 Todo 앱을 컨테이너화하기 위해 Dockerfile이 필요합니다.
Dockerfile은 Docker에게 이 애플리케이션으로 이미지를 어떻게 빌드할지를 알려주는 청사진(blueprint)입니다. 이 설정은 기본 환경을 정의하고, 애플리케이션 코드를 복사하며, 필요한 의존성을 설치하고, 애플리케이션이 어떻게 시작될지를 지정합니다. 이 청사진을 통해 Docker는 어떤 머신에서든 동일하게 동작하는 일관된 이미지를 생성할 수 있으며, 우리의 Node.js 애플리케이션을 완전히 이식 가능하고 배포 준비가 완료된 상태로 만들어 줍니다.

우리의 Dockerfile에서는 대문자 D를 사용하는 점에 주의하세요. 이는 표준 명명 규칙입니다. 이 파일은 Node.js 프로젝트의 루트 디렉토리에 위치시켜야 합니다. 단순한 프로젝트의 경우, server.js 또는 index.js 같은 메인 파일과 package.json이 루트에 함께 위치합니다. Docker는 이 파일을 청사진으로 사용하여 애플리케이션의 컨테이너 이미지를 빌드합니다.

만약 메인 앱 파일이 하위 폴더에 있다면 괜찮습니다. 단, Dockerfile 내 COPY 및 CMD 명령에서 정확한 경로를 지정해야 합니다. 중요한 점은 Dockerfile이 프로젝트 루트에 있어야 Docker가 여러분의 앱 빌드 기준점을 인식할 수 있다는 것입니다.

우리의 Dockerfile 내용은 다음과 같습니다:

# Use full Node 18 (Debian-based)
FROM node:18

# Set environment variables
ENV MONGO_DB_USERNAME=admin \
    MONGO_DB_PASSWORD=password

# Set working directory
WORKDIR /home/app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy source code
COPY . .

# Expose port
EXPOSE 3000

# Start the app
CMD ["node", "server.js"]

여기서 어떤 일이 일어나고 있는지 살펴보겠습니다:

FROM node:13-alpine 은 컨테이너의 기본 이미지로서 Node.js가 이미 설치되어 있으며 매우 가볍기 때문에 이미지를 작게 유지할 수 있습니다.
ENV MONGO_DB_USERNAME=admin \ MONGO_DB_PASSWORD=password 는 컨테이너 내부에서 환경 변수를 설정하여 Node.js 애플리케이션이 MongoDB에 연결할 수 있게 합니다.
WORKDIR /home/app 은 컨테이너 내부에서의 작업 디렉터리를 지정합니다. 이후 실행되는 COPY, RUN 등의 명령은 이 폴더 기준으로 수행됩니다.
COPY . . 은 로컬 프로젝트의 모든 파일을 컨테이너의 작업 디렉토리로 복사합니다. 여기에는 server.js, package.json을 포함하여 애플리케이션을 실행하는 데 필요한 모든 파일이 포함됩니다.
RUN npm install 은 package.json에 나열된 의존성을 컨테이너 안에 설치합니다.
EXPOSE 3000 은 컨테이너가 3000 포트에서 수신 대기한다는 것을 Docker에 알려주며, 이는 우리 Node.js 애플리케이션이 실행되는 포트입니다.
CMD ["node", "server.js"] 은 컨테이너가 시작될 때 실행되는 명령어를 정의하여 Node.js 서버를 실행합니다.

이 Dockerfile을 프로젝트 루트에 배치함으로써 Docker는 애플리케이션 파일과 의존성을 정확히 어디서 찾아야 하는지 알게 됩니다. 이미지를 빌드할 때 이식 가능한 컨테이너에 모두 패키징하여 Docker가 설치된 어디서든 실행할 수 있게 하며, 배포를 간단하고 일관되도록 해줍니다.

이제 Dockerfile이 준비되었으니, 다음 단계는 Node.js 애플리케이션용 Docker 이미지를 빌드하는 것입니다.

이미지를 빌드하려면 터미널을 열고, 프로젝트 루트 디렉토리(Dockerfile이 있는 곳)에 있는지 확인한 뒤 다음 명령어를 실행하세요:

docker build -t todo-app:1.0 .

todo-app → 생성할 이미지의 이름
:1.0 → 버전 태그 (예: 1.0, v1, latest 등 자유롭게 지정 가능)
. → Docker에게 현재 폴더(프로젝트 루트)를 빌드 컨텍스트로 사용하라고 알려줍니다.

다음 명령어를 실행한 후:

docker build -t todo-app:1.0 .

Docker는 Dockerfile을 읽고, Node.js 애플리케이션과 모든 의존성을 패키징하여 Docker 이미지를 생성합니다. 이미지가 생성되었는지 확인하려면 다음 명령어를 실행하세요:

docker images

다음과 같은 출력이 나타날 것입니다:

REPOSITORY      TAG       IMAGE ID       CREATED          SIZE
todo-app        1.0       d85dd4ed97f9   45 seconds ago   147MB
mongo           latest    1d659cebf5e9   2 weeks ago      894MB
mongo-express   latest    1133e12468c7   20 months ago    182MB

이 출력은 todo-app 이미지가 MongoDB와 Mongo Express 이미지와 함께 성공적으로 생성되었음을 보여줍니다.

Node.js 앱 컨테이너 실행

이제 이미지가 생성되었으니 다음 단계는 이 이미지를 사용해 컨테이너를 실행하는 것입니다. 컨테이너는 기본적으로 이미지의 실행 중인 인스턴스입니다. 이를 위해 다음 명령어를 실행하세요:

docker run todo-app:1.0

이 명령어는 다음을 수행합니다:

docker run은 이미지에서 새 컨테이너를 시작합니다.
todo-app:1.0은 Docker에게 (방금 빌드한) 이미지를 사용하라고 알려줍니다.

이 명령어가 실행되면 Node.js 애플리케이션이 컨테이너 내부에서 로컬 환경과 분리된 상태로 실행됩니다. 브라우저에서 http://localhost:3000을 열어 Todo 앱이 로컬에서와 동일하게 작동하는 것을 확인할 수 있습니다.

실행 중인 모든 컨테이너를 보려면 다음을 사용하세요:

docker ps

다음과 같은 출력을 볼 수 있습니다:

CONTAINER ID   IMAGE           COMMAND         CREATED       STATUS       PORTS                  NAMES
d85dd4ed97f9   todo-app:1.0    "node server.js"  10s ago      Up 10s       0.0.0.0:3000->3000/tcp   awesome_todo

이것은 컨테이너가 실행 중임을 확인해 줍니다. 필요시 중지하려면:

docker stop

오류 해결

여기서 문제가 발생합니다: docker run todo-app:1.0을 실행하면 다음과 같은 오류가 나타납니다:

Server → http://localhost:3000 
MongoDB connection error: MongoServerSelectionError: getaddrinfo ENOTFOUND mongodb
    at Topology.selectServer (/home/app/node_modules/mongodb/lib/sdam/topology.js:346:38)
    ...
    [cause

특히 todo 리스트 생성 등의 작업을 시도할 때 발생합니다.

getaddrinfo ENOTFOUND mongodb 오류는 Node.js 컨테이너가 MongoDB를 찾을 수 없음을 알려줍니다. MongoDB가 다른 컨테이너에서 실행 중이더라도 앱 컨테이너는 격리되어 있어 이를 찾을 수 없습니다.

왜 이런 일이 발생하는가:

server.js에서 MongoDB에 다음과 같이 연결하는 것을 기억하세요:

const mongoUrl = "mongodb://admin:password@localhost:27017";

문제는 localhost에 있습니다. 로컬 머신에서 앱을 실행할 때는 localhost가 완벽하게 작동하지만, Docker 컨테이너 내부에서는 localhost가 해당 컨테이너 자신만 가리킵니다.

비유하자면:

로컬 실행: 앱과 MongoDB가 같은 방에 있는 두 사람, localhost 작동
Docker 실행: 각 컨테이너가 별도의 방, localhost는 그 방만 가리킴

해결책

MongoDB 연결 URL을 localhost 대신 Docker 서비스 이름으로 변경해야 합니다. server.js 파일을 업데이트하세요:

const mongoUrl = "mongodb://admin:password@localhost:27017";

다음으로 변경하세요:

const mongoUrl = "mongodb://admin:password@mongodb:27017";

완전한 업데이트된 server.js는 다음과 같습니다:

const express = require("express");
const multer = require("multer");
const path = require("path");
const fs = require("fs");
const { MongoClient, ObjectId } = require("mongodb");

const app = express();
const PORT = 3000;

// Host = localhost  →  talks to the MongoDB container via the exposed port
// Port = 27017      →  default MongoDB port
// User / Pass       →  admin / password (the credentials you gave the container)
const mongoUrl = "mongodb://admin:password@mongodb:27017";
const dbName = "todos";
let db;

MongoClient.connect(mongoUrl)
  .then((client) => {
    db = client.db(dbName);
    console.log("Connected to MongoDB →", dbName);
  })
  .catch((err) => console.error("MongoDB connection error:", err));

const uploadDir = path.join(__dirname, "uploads");
if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir);

const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, uploadDir),
  filename: (req, file, cb) => {
    const unique = Date.now() + "-" + Math.round(Math.random() * 1e9);
    cb(null, "photo-" + unique + path.extname(file.originalname));
  },
});
const upload = multer({ storage });

app.use(express.static(__dirname));
app.use("/uploads", express.static(uploadDir));
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get("/todos", async (req, res) => {
  const todos = await db.collection("todos").find().toArray();
  res.json(todos);
});

app.post("/todos", upload.single("photo"), async (req, res) => {
  const text = req.body.text?.trim();
  if (!text) return res.status(400).json({ error: "Text required" });

  const todo = {
    text,
    image: req.file ? `/uploads/${req.file.filename}` : null,
    createdAt: new Date(),
  };

  const result = await db.collection("todos").insertOne(todo);
  todo._id = result.insertedId;
  res.json(todo);
});

// Start server
app.listen(PORT, () => {
  console.log(`Server → http://localhost:${PORT}`);
});

왜 `mongodb`가 작동하는가

호스트명 mongodb는 docker-compose.yml에서 정의한 서비스 이름과 일치합니다:

services:
  mongodb:    # ← 다른 컨테이너들이 사용하는 호스트명
    image: mongo
    container_name: mongo
    ...

같은 Docker Compose 네트워크에서 컨테이너들이 실행될 때, Docker는 내부 DNS를 제공하여 서비스 이름을 올바른 컨테이너 IP 주소로 해석합니다. 따라서 앱이 mongodb:27017에 연결하려고 하면 Docker가 자동으로 MongoDB 컨테이너로 라우팅합니다.

Docker 이미지 재빌드

코드를 업데이트했으니 이 변경사항을 포함하여 Docker 이미지를 재빌드해야 합니다:

docker build -t todo-app:1.0 .
``

You should see output confirming the build completed successfully:
``
[+] Building 8.1s (10/10) FINISHED
 => [internal] load build definition from Dockerfile
 => => transferring dockerfile: 443B
 ...
 => => naming to docker.io/library/todo-app:1.0

Docker Compose에 앱 추가

이제 docker-compose.yml 파일을 업데이트하여 todo-app 서비스를 포함하세요:

version: "3.8"

services:
  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

  todo-app:
    image: todo-app:1.0
    container_name: todo-app
    ports:
      - "3000:3000"
    depends_on:
      - mongodb

todo-app 서비스는 다음을 포함합니다:

image: todo-app:1.0 - 방금 재빌드한 Docker 이미지 사용
container_name: todo-app - 컨테이너에 친근한 이름 부여
ports: "3000:3000" - 3000 포트로 앱 노출
depends_on: mongodb - MongoDB가 앱보다 먼저 시작되도록 보장

모든 서비스 시작

먼저 실행 중인 컨테이너들을 중지하세요:

docker compose down

로컬 시스템에서 3000 포트가 사용 중이라면 이를 중지하세요 (3000 포트 해제).

이전에 로컬에서 서버를 실행했지만, 이제 Docker 이미지를 빌드했으므로 앱은 컨테이너 내부에서 실행되며 로컬 머신 환경에 더 이상 의존하지 않습니다.

node server.js
Server → http://localhost:3000

이제 해당 터미널에서 Ctrl + C로 중지하세요.

그 다음 모든 것을 함께 시작하세요:

docker compose up -d
``

You should see:

``
[+] Running 4/4
 ✔ Network docker_tut_default  Created
 ✔ Container mongo             Started
 ✔ Container mongo-express     Started
 ✔ Container todo-app          Started

모든 것이 작동하는지 확인

모든 컨테이너가 실행 중인지 확인하세요:

docker ps
``

예상 출력:
``
CONTAINER ID   IMAGE           COMMAND                  CREATED          STATUS          PORTS                      NAMES
a1b2c3d4e5f6   todo-app:1.0    "node server.js"         30 seconds ago   Up 28 seconds   0.0.0.0:3000->3000/tcp     todo-app
3d7c797fde1d   mongo-express   "/sbin/tini -- /dock…"   30 seconds ago   Up 29 seconds   0.0.0.0:8081->8081/tcp     mongo-express
4511ade73c38   mongo           "docker-entrypoint.s…"   30 seconds ago   Up 29 seconds   0.0.0.0:27017->27017/tcp   mongo
``

## 애플리케이션 테스트

이제 모든 것이 작동하는지 확인해보겠습니다:

### 1. Todo 앱 접속
브라우저를 열고 다음으로 이동하세요:
``
http://localhost:3000
``

### 2. Todo 항목 생성
기능을 테스트하기 위해 몇 개의 todo 항목을 추가하세요. 이미지 업로드도 시도해보세요!

### 3. Mongo Express에서 확인
Mongo Express를 열어보세요:
``
http://localhost:8081

todos 데이터베이스, 그 다음 todos 컬렉션으로 이동하세요. 방금 생성한 모든 todo와 완전한 데이터가 표시됩니다.

무엇이 변경되었고 왜 작동하는가

수정 전:

연결 문자열이 localhost:27017 사용 ❌
컨테이너가 자기 자신에서 MongoDB 찾음
ENOTFOUND 오류로 연결 실패

수정 후:

연결 문자열이 mongodb:27017 사용 ✅
Docker 내부 DNS가 mongodb를 MongoDB 컨테이너로 해석
연결 성공 및 데이터 정상 흐름

이는 Docker 네트워킹의 핵심 교훈입니다: 컨테이너들은 localhost가 아닌 서비스 이름으로 통신합니다. Docker Compose는 모든 서비스가 이름으로 서로를 찾을 수 있는 네트워크를 자동 생성합니다.

컨테이너 관리 방법

실행 중인 컨테이너를 관리하는 방법을 간단히 알아보겠습니다. 일반적으로 다음 명령어들을 사용합니다:

모든 서비스 중지:

docker compose down

앱 로그 보기:

docker compose logs todo-app

실시간 로그 보기:

docker compose logs -f todo-app

코드 변경 후 재빌드:

docker build -t todo-app:1.0 .
docker compose up -d --force-recreate todo-app

이제 애플리케이션이 완전히 컨테이너화되어 프로덕션 준비가 완료되었습니다. 세 서비스가 완벽하게 함께 작동하며, docker-compose.yml 파일과 빌드된 이미지만 있으면 Docker가 지원되는 어디서든 이 전체 스택을 배포할 수 있습니다.

전체 업데이트된 코드는 여기에서 확인하세요.

프라이빗 Docker 레지스트리 생성 방법

이제 커스텀 Docker 이미지를(로컬 머신 대신에) 프라이빗 컨테이너 레지스트리에 저장하고 싶습니다. 이는 세 가지 주요 장점을 제공합니다:

1. 제어된 접근 - 명시적으로 권한을 부여한 사람이나 서버만 이미지를 가져오거나 업로드할 수 있습니다. 코드와 의존성이 비공개로 안전하게 유지됩니다.
2. 안정적인 배포 - 올바른 AWS 자격 증명을 가진 누구나(또는 어떤 서버도) 전 세계 어디서든 정확히 동일한 이미지를 가져올 수 있어 "내 머신에서는 작동하는데..." 문제가 사라집니다.
3. 버전 관리 및 라이프사이클 관리 - 여러 태그 버전(1.0, 2.0, latest 등)을 유지하고 필요시 쉽게 롤백할 수 있습니다.

첫 번째 단계는 프라이빗 Docker 레지스트리(컨테이너 레지스트리)를 생성하는 것입니다. 여기서는 AWS Elastic Container Registry (ECR)를 사용하겠습니다. Amazon ECR은 컨테이너 이미지와 아티팩트를 어디에서나 안전하게 저장·관리·공유·배포할 수 있게 해주는 완전관리형 컨테이너 레지스트리 서비스입니다.

홈페이지에 접속한 후 Create 버튼을 클릭하세요. 레포지토리 이름을 이미지와 동일하게 todo-app으로 지정한 후 Create를 클릭하여 설정을 완료합니다.

추가 옵션은 신경 쓰지 않아도 됩니다 - 이것은 AWS 튜토리얼이 아닙니다.

참고: AWS ECR에서는 각 이미지가 고유한 레포지토리를 가지며, 해당 이미지의 다양한 태그 버전을 저장합니다.

이제 이미지를 프라이빗 레포지토리에 푸시하려면 두 가지를 해야 합니다. 먼저 프라이빗 레포에 로그인해야 합니다. AWS가 푸시를 허용하기 전에 본인을 인증해야 하기 때문입니다. 즉, 로컬 이미지를 레포에 푸시할 때 "이 레지스트리에 접근 권한이 있습니다. 여기 제 자격 증명입니다."라고 말하는 셈입니다.

우리의 경우 AWS ECR을 사용하므로 사용자 이름과 비밀번호를 수동으로 입력하는 대신 AWS를 통해 인증합니다.

1단계: AWS 액세스 키 가져오기

AWS 콘솔에서 액세스 키를 찾으려면 다음 단계를 따르세요:

1. https://console.aws.amazon.com 에 접속해 AWS 콘솔에 로그인합니다.

2. 오른쪽 상단의 계정 이름을 클릭한 뒤 “보안 자격 증명(Security Credentials)”으로 이동합니다.

3. 아래로 스크롤해 "Access keys" 섹션을 찾습니다.

4. 액세스 키가 없다면:

"Create access key"를 클릭합니다.
"Command Line Interface (CLI)"를 선택합니다.
확인 체크박스를 선택하고 Next를 클릭합니다.
설명을 입력(선택 사항)한 뒤 "Create access key"를 클릭합니다.

5. 중요: 액세스 키 ID(예: AKIAIOSFODNN7EXAMPLE처럼 보임)와 시크릿 액세스 키(예: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY처럼 보임)를 둘 다 복사해 바로 저장하세요. 시크릿 키는 한 번만 표시되므로 잃어버리면 새 키 쌍을 만들어야 합니다.

또는, 다른 사람이 당신의 AWS 계정을 관리한다면 관리자에게 다음 사항을 요청해야 합니다:

ECR 권한이 부여된 IAM 사용자
해당 사용자의 액세스 키 ID와 시크릿 액세스 키

2단계: AWS CLI 설치 여부 확인

다음 명령어로 확인할 수 있습니다:

aws --version

3단계: AWS CLI에 자격 증명 설정

다음 명령어를 실행합니다:

aws configure
``

프롬프트에 다음 네 가지를 입력해야 합니다:
``
AWS Access Key ID [None]: <여기에 Access Key ID를 붙여넣으세요>
AWS Secret Access Key [None]: <여기에 Secret Access Key를 붙여넉으세요>
Default region name [None]: eu-north-1 또는 원하는 리전
Default output format [None]: json

프롬프트가 뜨면 키를 그대로 붙여넣고, 리전은 eu-north-1 또는 원하는 리전을 입력하고, 출력 형식은 json을 입력하거나 Enter를 눌러도 됩니다.

4단계: AWS 설정 테스트

모든 설정이 올바른지 확인하려면:

aws sts get-caller-identity

정상이라면 AWS 계정 정보가 출력됩니다.

5단계: ECR(Docker 레지스트리)에 로그인
이제 ECR에 로그인합니다:

aws ecr get-login-password --region eu-north-1 | docker login --username AWS --password-stdin 244836489456.dkr.ecr.eu-north-1.amazonaws.com

"Login Succeeded"가 출력되어야 합니다.

Docker 이미지 명명 방식 이해하기

모든 Docker 이미지는 Docker에게 해당 이미지를 어디서 찾거나 저장할지를 알려주는 이름을 가지고 있습니다.
예를 들어 아래 명령을 실행하면:

docker pull mongo:4.2

실제로는 다음에서 이미지를 가져옵니다:

docker.io/library/mongo:4.2

여기에서 어떤 일이 일어나는지 살펴보겠습니다:

[docker.io](http://docker.io/) → 레지스트리(이 경우 Docker Hub)
library → 공식 이미지에 대한 기본 네임스페이스
mongo → 레포지토리 이름
4.2 → 이미지 태그

`todo-app:1.0 같은 로컬 이미지를 빌드하면, 그 이미지는 여러분의 머신에만 존재합니다. 전체 레지스트리 경로를 포함하지 않으면 Docker는 그것을 어디에 푸시해야 할지 모릅니다.

AWS ECR을 사용할 때는 이미지 이름에 ECR 레지스트리 URL을 포함해야 합니다. 예를 들어:

docker tag todo-app:1.0 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

그 다음 이렇게 푸시합니다:

docker push 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

이 전체 경로가 없으면 Docker는 어떤 원격 레포지토리를 가리키는지 알 수 없습니다. 그래서 todo-app:1.0만으로는 동작하지 않습니다.

6단계: 이미지 빌드, 태그, 푸시

로컬 이미지를 전체 ECR 경로로 태그하세요.
docker tag todo-app:1.0 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

그리고 푸시:
docker push 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

주의: 이미지 태그를 지정하고 푸시할 때 주의하세요. 모든 ECR 저장소 URL은 특정 AWS 계정과 리전에 연결되어 있습니다.

예를 들어, 튜토리얼에서 사용하는 것은:

244836489456.dkr.ecr.eu-north-1.amazonaws.com

하지만 여러분의 ECR URL은 사용하는 AWS 계정과 선택한 리전(예: us-east-1, ap-south-1 등)에 따라 서로 다르게 됩니다.

그래서 docker tag, docker push를 실행하기 전에, 레지스트리 URL, 리전을 반드시 여러분의 값으로 바꿔야 합니다.

그렇지 않으면 “tag does not exist”, “repository not found” 같은 오류가 납니다.

요약하자면, 당황하지 말고 리전을 다시 한 번 확인한 뒤, 이미지를 푸시하기 전에 AWS 콘솔에 표시된 ECR URL이 정확한지 항상 확인하세요.

6단계를 성공적으로 실행했다면 터미널에 다음과 비슷한 출력이 보일 것입니다.

stephenjohnson@Oghenekparobo docker_tut % docker tag todo-app:1.0 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
stephenjohnson@Oghenekparobo docker_tut % docker push 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
The push refers to repository [244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app]
4f94b5cbe8ab: Pushed 
85ba7bf54231: Pushed 
4ea46a43fa07: Pushed 
dee30873f229: Pushed 
e78159dbd370: Pushed 
a358a725b813: Pushed 
cd8a6003174c: Pushed 
abb63e49e652: Pushed 
6cc65bdde70e: Pushed 
41a4e3939504: Pushed 
3520c50ae60e: Pushed 
75ba6634710f: Pushed 
1.0: digest: sha256:51f07267936fc94d9b677db8a760801e6c5fd4764f4bb2bd7b4dd150c756a39b size: 2842

이 출력은 이미지가 프라이빗 AWS ECR 레포지토리에 성공적으로 푸시되었음을 의미합니다.

이제 AWS Management Console에서 ECR로 이동하면, 태그 1.0이 붙은 todo-app 이미지를 목록에서 확인할 수 있습니다.

이 시점부터 이미지는 AWS ECR에 안전하게 저장되어 있으며, 레포지토리에 접근할 수 있는 어느 곳에서든 가져오거나 배포할 준비가 된 상태입니다.

과제: 앱의 새 버전 만들기 및 푸시하기

이제 첫 번째 이미지(todo-app:1.0)를 AWS ECR에 성공적으로 푸시했으니, 실제 환경에서 개발자가 앱을 수정하고 새 버전을 배포하는 워크플로를 한 번 시뮬레이션해보겠습니다.
이제 Node.js 앱에 작은 변경을 주고, 이미지를 다시 빌드한 뒤, 업데이트된 버전을 todo-app:2.0으로 푸시할 것입니다.

이미지 배포하기

이제 Docker Compose를 사용해 이미지를 배포해보겠습니다.

지금까지는 로컬 이미지를 사용해 앱을 실행했습니다:

image: todo-app:1.0

하지만 이제 이미지를 AWS ECR에 올렸으므로, Docker가 이미지를 어디에서 가져와야 하는지 알 수 있도록 해당 줄을 전체 ECR 이미지 URI로 교체해야 합니다.

로컬 이미지:

image: todo-app:1.0

프라이빗 레포지토리 이미지(ECR):

image: 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

Docker는 “todo-app:1.0”이 어디에 저장되어 있는지 마법처럼 추측해주지 않습니다. 전체 레지스트리 URL을 포함하지 않으면, Docker는 그것이 AWS가 아니라 로컬 머신에 있는 이미지라고 가정합니다.

다음은 ECR에서 앱 이미지를 가져오도록 정리되고, 수정되고, 올바르게 포맷된 docker-compose 파일입니다:

version: "3.8"

services:
  my-app:
    image: 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
    container_name: my-app
    ports:
      - "3000:3000"
    depends_on:
      - mongodb

  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

왜 서비스 이름을 “todo-app”이 아니라 “my-app”으로 했을까?

여기서는 다음 둘을 헷갈리지 않게 하려고 이름을 바꿨습니다:

로컬의 “todo-app:1.0”
ECR에 있는 “todo-app:1.0”

이렇게 하면 좀 더 구분이 명확해지지만, 원한다면 다시 원래 이름으로 돌려도 됩니다.

왜 ECR에는 전체 이미지 URL을 써야 할까?

mongo, mongo-express 같은 다른 컨테이너는 다음처럼 동작합니다:

image: mongo
image: mongo-express

그 이유는 Docker가 이 이미지들이 Docker Hub에 있다는 것을 알고 있기 때문입니다.

하지만 AWS ECR 같은 프라이빗 레포지토리의 경우, 전체 경로를 주지 않으면 Docker는 “todo-app”이 어디에 있는지 전혀 알 수 없습니다:

AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/repository_name:tag

이 정보는 Docker에게 다음을 알려 줍니다:

어떤 AWS 계정인지
어떤 리전인지
어떤 레포지토리인지
어떤 버전(tag)인지

이 URL이 없으면 Docker는 이미지를 가져올 수 없습니다.

프라이빗 ECR 레포지토리에서 가져오고 싶을 때마다(그리고 Docker Compose를 사용할 때도 마찬가지로) 반드시 로그인 상태여야 합니다.

다음 명령을 실행하세요:

aws ecr get-login-password --region eu-north-1 | docker login --username AWS --password-stdin 244836489456.dkr.ecr.eu-north-1.amazonaws.com

로그인되어 있지 않으면 Docker Compose는 보통 다음과 같은 오류를 냅니다:

❌ pull access denied
❌ repository does not exist
❌ no basic auth credentials

Docker Compose로 앱 배포하기

배포하기 전에, 포트 충돌이나 남은 컨테이너 때문에 문제가 생기지 않도록 기존 컨테이너를 중지하고 제거하는 것이 좋습니다:

# 이 프로젝트에서 실행 중인 모든 컨테이너 중지
docker-compose down --remove-orphans

#선택 사항: 아무 것도 실행 중이 아닌지 확인
docker ps

이렇게 하면 3000 포트를 포함한 매핑된 포트가 비워져, 새 컨테이너를 시작할 때 발생할 수 있는 오류를 방지할 수 있습니다.

환경을 깨끗하게 정리했다면, 이제 스택을 배포합니다:

docker-compose up -d

Docker Compose는 다음 작업을 수행합니다:

AWS ECR에 접속 → 인증한 뒤 프라이빗 레포지토리에서 todo-app:1.0 이미지를 가져옴
MongoDB 시작 → 설정한 자격 증명으로 DB 컨테이너 실행
Mongo Express 시작 → 웹 기반 MongoDB 관리 인터페이스 실행
Node.js 앱 시작 → MongoDB에 연결된 my-app 컨테이너 실행

실행 중인 컨테이너를 확인하려면:

docker ps

다음과 같은 컨테이너들이 보여야 합니다:

mongo
mongo-express
my-app

만약 my-app이 시작에 실패했다면, 보통 3000 포트가 이미 사용 중인 경우입니다. 사용 중인 프로세스를 중지하여 포트를 비우세요:

lsof -i :3000
kill -9   # if a process is using it

그 후 다시 실행하세요:

docker-compose up -d

앱에 접속하려면:

Node.js 앱: http://localhost:3000/
Mongo Express: http://localhost:8081/

이 워크플로를 통해 깨끗한 상태에서 시작할 수 있고, 포트 충돌이나 컨테이너 충돌 같은 흔한 문제를 피할 수 있습니다.

프라이빗 Docker 이미지 공유하기

Node.js 앱 이미지를 AWS ECR에 푸시했다면, 이제 이미지는 프라이빗 레포지토리에 안전하게 저장된 상태입니다. 그렇다면 다른 개발자, 팀원, 또는 서버가 같은 이미지를 실행해야 할 때는 어떻게 할까요? 프라이빗이기 때문에 mongo나 nginx 같은 공개 이미지처럼 자동으로 가져올 수 없고, 반드시 인증된 접근이 필요합니다.

다음은 (다른 사람들이) 이미지를 가져와 사용하는 방법입니다.

1. IAM 권한 부여

협업자는 ECR 권한이 있는 AWS IAM 사용자 또는 역할이 필요합니다. 최소한 다음 작업을 허용하는 정책이 있어야 합니다:

ecr:GetAuthorizationToken
ecr:BatchCheckLayerAvailability
ecr:GetDownloadUrlForLayer
ecr:BatchGetImage

이를 위해 전용 IAM 사용자를 만든 다음, 해당 사용자에게 Access Key ID와 Secret Access Key를 제공할 수 있습니다.

2. AWS CLI 설치 및 설정

협업자는 AWS CLI가 설치되어 있어야 합니다. 그 다음 자신의 자격 증명으로 CLI를 설정합니다:

aws configure

이때 다음 값을 입력합니다:

Access Key ID
Secret Access Key
기본 리전(해당 ECR 레포지토리가 있는 리전, 예: eu-north-1)
기본 출력 형식(보통 json)

3. Docker를 ECR에 인증시키기

이미지를 pull하기 전에, Docker는 AWS 자격 증명을 사용해 먼저 인증을 해야 합니다:

aws ecr get-login-password --region eu-north-1 | docker login --username AWS --password-stdin 244836489456.dkr.ecr.eu-north-1.amazonaws.com

성공하면 Docker가 다음과 같이 응답합니다:

Login Succeeded

4. 이미지 Pull

이제 협업자는 AWS 계정, 리전, 레포지토리 이름, 태그를 모두 포함한 전체 ECR URI로 이미지를 가져올 수 있습니다:

docker pull 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

5. 컨테이너 실행

이미지를 pull한 후에는 로컬에서 다음과 같이 컨테이너를 실행할 수 있습니다:

docker run -p 3000:3000 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

또는 Docker Compose 파일에 포함시켜 image: 필드를 전체 ECR URI로 교체할 수 있습니다.

mongo 같은 공개 이미지는 Docker Hub가 공개 레지스트리이기 때문에 이런 과정이 필요 없지만, 프라이빗 ECR 이미지는 반드시 명시적인 인증이 필요합니다.
프라이빗 레포지토리에서 pull을 할 때는 항상 유효한 로그인 상태가 필요합니다. Docker는 자격 증명을 추측할 수 없습니다.
전체 이미지 URI를 사용하는 것은 Docker가 이미지를 어디에서 가져와야 하는지 정확히 알 수 있게 해 줍니다.

이 설정을 통해 팀은 로컬 머신, 스테이징 서버, 운영 환경 어디서든 애플리케이션을 공유, 배포, 실행할 수 있으며, 동시에 저장소를 비공개로 안전하게 유지할 수 있습니다.

Docker 볼륨

MongoDB 같은 컨테이너를 실행할 때, 컨테이너 내부에서 생성된 데이터는 모두 일시적입니다. 컨테이너가 중지되거나 삭제되면 그 안의 데이터도 모두 사라집니다. 테스트 용도로는 괜찮지만, 프로덕션 환경에는 적합하지 않습니다.

이를 해결하기 위해 Docker는 볼륨을 제공합니다. 볼륨을 사용하면 컨테이너가 데이터를 컨테이너 외부(호스트 머신이나 Docker가 관리하는 스토리지)에 저장하여, 컨테이너가 재시작되거나 재빌드되거나 삭제되더라도 데이터가 유지되도록 할 수 있습니다.

Docker 볼륨의 동작 방식

Docker 볼륨은 컨테이너를 위한 “지속되는 폴더”라고 생각하면 됩니다:

볼륨에 기록된 데이터는 컨테이너가 삭제돼도 안전하게 남아 있습니다.
컨테이너는 이 볼륨에 자유롭게 읽기/쓰기를 할 수 있습니다.
볼륨은 데이터베이스, 로그, 파일 업로드, 그 외 애플리케이션에서 필요한 모든 영속 데이터에 필수적입니다.

Docker 볼륨의 종류

Docker에는 세 가지 주요 볼륨 유형이 있습니다:

1. 네임드 볼륨(Named Volumes)

네임드 볼륨은 사용자가 이름을 부여한 볼륨으로, Docker가 완전히 관리합니다. 보통 프로덕션 데이터베이스나 여러 컨테이너가 공유해야 하는 영속 데이터에 사용합니다.

예시입니다:

volumes:
  mongo-data:

서비스에서의 모습입니다:

volumes:
  - mongo-data:/data/db

2. 바인드 마운트(Bind Mounts)

바인드 마운트는 호스트 머신의 폴더를 컨테이너 내부 경로에 직접 연결합니다. 개발 환경에서 코드, 로그, 업로드 파일 등을 실시간으로 동기화할 때 자주 사용합니다.

예시입니다:

volumes:
  - ./uploads:/usr/src/app/uploads

3. 익명 볼륨(Anonymous Volumes)

이름이 없는 볼륨입니다. Docker가 자동으로 임의의 이름을 붙입니다. 테스트용 임시 데이터처럼, 짧게 쓰고 버릴 데이터에 사용할 수 있지만, 프로덕션에서는 흔히 쓰이지 않습니다.

예시입니다:

volumes:
  - /data/tmp

볼륨을 사용하는 Docker Compose 예제

다음은 Node.js + MongoDB + Mongo Express 스택에서 가장 흔한 볼륨 유형을 사용하는 전체 docker-compose.yml 예제입니다:

version: "3.8"

services:
  my-app:
    image: 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
    container_name: my-app
    ports:
      - "3000:3000"
    depends_on:
      - mongodb
    volumes:
      - ./uploads:/usr/src/app/uploads  # 파일 업로드용 bind mount

  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password
    volumes:
      - mongo-data:/data/db  # 데이터베이스 영속 스토리지 네임드 볼륨

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

volumes:
  mongo-data:  # 네임드 볼륨 정의

이 코드가 동작하는 방식:

MongoDB 볼륨(mongo-data): 네임드 볼륨으로, 컨테이너 내부의 /data/db 아래에 있는 모든 DB 파일을 저장합니다. 컨테이너가 재시작·삭제·재빌드되어도 데이터는 유지됩니다.
Node.js 업로드(./uploads): 바인드 마운트로, 호스트의 uploads 폴더를 컨테이너의 /usr/src/app/uploads에 매핑합니다. 업로드된 파일은 즉시 호스트에서도 확인할 수 있습니다.
익명 볼륨: 이 예제에는 포함되어 있지 않은데, 이름 없이 정의된 볼륨은 Docker가 자동으로 생성하며, 보통 프로덕션보다는 임시 용도로만 사용합니다.

시각적 개념(단순화):

Host Machine(호스트 머신)
├─ /project/uploads   ← 컨테이너와 동기화되는 bind mount
├─ Docker Volumes
│  └─ mongo-data      ← MongoDB 영속 데이터를 위한 네임드 볼륨

Containers(컨테이너)
├─ my-app
│  └─ /usr/src/app/uploads  ← 호스트 uploads 폴더를 봄
├─ mongodb
│  └─ /data/db              ← 네임드 볼륨 mongo-data 사용
├─ mongo-express

핵심 정리 (Takeaways)

중요한 데이터에는 항상 볼륨을 사용하세요.
프로덕션 환경의 데이터베이스에는 네임드 볼륨이 가장 적합합니다.
바인드 마운트는 개발용과 실시간 동기화에 가장 잘 어울립니다.
익명 볼륨은 테스트를 제외하고는 거의 필요하지 않습니다.
볼륨은 컨테이너의 라이프사이클과 데이터의 라이프사이클을 분리해 주며, 이는 Docker 모범 사례의 핵심 개념입니다.

애플리케이션 시작하기

Docker Compose에 볼륨 설정까지 완료했다면, 다음 단계는 애플리케이션을 시작하고 볼륨이 제대로 동작하는지 확인하는 것입니다. 아래는 간단한 단계별 가이드입니다.

1. 컨테이너 시작

다음 명령을 실행하세요:

docker-compose up -d

-d 플래그는 컨테이너를 백그라운드(detached 모드)에서 실행한다는 의미입니다.

Docker는 다음을 수행합니다:

(로그인되어 있다면) AWS ECR에서 앱 이미지를 pull합니다.
네임드 볼륨과 함께 MongoDB를 시작합니다.
Mongo Express를 시작합니다.
Node.js 앱을 시작합니다.

2. 실행 중인 컨테이너 확인

모든 것이 제대로 시작되었는지 확인하려면:

docker ps

다음과 비슷한 출력이 보여야 합니다:

CONTAINER ID   IMAGE                                               STATUS          PORTS
2a2e120cc912   244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0   Up 5s    0.0.0.0:3000->3000/tcp
f4d5a1ab1234   mongo                                               Up 5s          0.0.0.0:27017->27017/tcp
c3d5b2bc2345   mongo-express                                      Up 5s          0.0.0.0:8081->8081/tcp

3. 볼륨 확인

Docker 볼륨 목록을 보려면:

docker volume ls

여기서 예를 들어 mongo-data 같은 네임드 볼륨을 확인할 수 있어야 합니다.

볼륨을 자세히 보려면:

docker volume inspect docker_tut_mongo-data

그러면 Docker가 호스트에서 MongoDB 데이터를 어디에 저장하는지 보여주는데, 예를 들어 다음과 같이 표시됩니다:

[
    {
        "Name": "mongo-data",
        "Driver": "local",
        "Mountpoint": "/var/lib/docker/volumes/mongo-data/_data",
        "Labels": {},
        "Scope": "local"
    }
]

MongoDB 컨테이너 내부의 /data/db에 저장되는 모든 것은 실제로 호스트의 이 경로에 저장됩니다.

4. 데이터 영속성 테스트

1. MongoDB 또는 앱에 접속해서 데이터를 몇 개 추가해 보세요.
2. 그 다음 컨테이너를 중지 및 삭제합니다:

docker-compose down

3. 이후 다시 앱을 시작합니다:

docker-compose up -d

4. 데이터를 다시 확인해 보세요.

MongoDB가 네임드 볼륨을 사용하고 있기 때문에 데이터는 그대로 남아 있습니다.
이로써 볼륨이 영속적으로 동작한다는 것이 증명됩니다.

5. 선택: Node.js 업로드(바인드 마운트) 확인

앱을 통해 파일을 업로드했다면, 프로젝트 폴더의 ./uploads를 확인해 보세요.
바인드 마운트는 호스트와 컨테이너 디렉터리를 동기화하므로, 업로드한 파일이 호스트 머신의 ./uploads 폴더에도 생성되어 있어야 합니다.

결론

잘하셨습니다! 이 포괄적인 Docker 튜토리얼의 끝에 도달했습니다. 여러분은 컨테이너와 이미지의 기본을 풀어내는 것부터 네트워킹, Docker Compose, 볼륨, 심지어 비공개 AWS ECR 저장소 배포까지, 완전히 컨테이너화된(프로덕션할 준비가 되고 확장 가능한) Node.js 애플리케이션 스택을 구축했습니다.
이것들은 실제 시나리오에서 애플리케이션을 개발하고, 협업하고, 배포하는 방식을 바꿔놓을 실전 스킬들입니다.

끈질기게 따라와 주셔서 감사합니다. Docker는 처음엔 압도적으로 느껴질 수 있습니다 – 그 긴 명령어들, 네트워킹 특이점들, 영속 데이터 문제들은 결코 사소하지 않죠.
하지만 여기까지 왔다는 것은? 가파른 학습 곡선을 정복하고 개발 여정에서 새로운 경지에 도달했다는 뜻입니다.
이제 "내 컴퓨터에서는 잘 작동하는데"라는 골칫거리를 없애고, CI/CD 파이프라인을 간소화하며, 백엔드나 풀스택 전문가로 한 단계 업그레이드할 준비가 되었습니다.

계속 실험해보세요: todo-app을 수정하거나, Dockerfile에서 멀티스테이지 빌드(도커 다중 단계 빌드 - 단일 Dockerfile 내에서 여러 개의 빌드 단계를 정의하여 최종 이미지 크기를 최적화하고 빌드 효율성을 높이는 기술)를 시도하거나, 다음으로 Kubernetes 같은 오케스트레이션 도구를 탐구해보세요. Docker 생태계는 방대하지만, 이 기초를 갖췄으니 더 깊이 파고들 준비가 되었습니다. 문제가 생기거나 질문이 있으면 Docker Hub, Stack Overflow, GitHub 커뮤니티를 활용하세요.

최종 코드는 여기에서 확인할 수 있습니다.

JSON Web Token 핸드북: 웹 인증을 위한 JWT 활용 가이드

Jong-Ho Kim — Fri, 19 Dec 2025 04:59:54 +0000

기사 원문: The JSON Web Token Handbook: Learn to Use JWTs for Web Authentication

JWT는 JSON Web Token의 약자이며, 웹 개발을 하다 보면 정말 자주 보게 되는 용어입니다.

기본적으로 JWT는 두 주체 간에 특정한 정보(claim)를 안전하게 표현하고 전달하기 위한 JSON 기반의 개방형 표준입니다. 특히 마이크로서비스 아키텍처나 최신 인증 시스템에서 매우 널리 사용된다는 점이 인상적인 부분입니다.

이 글에서는 JWT가 실제로 무엇인지, 어떻게 구성되어 있는지, 그리고 웹 애플리케이션을 어떻게 안전하게 만드는지 자세히 살펴보겠습니다. 글을 다 읽고 나면 왜 개발자들이 매일같이 JWT를 사용하는지 이해할 수 있게 될 것입니다.

이 글에서 다룰 내용

사전 지식
JWT란 무엇인가?
왜 토큰이 필요한가?
JWT의 구조: 헤더, 페이로드, 시그니처
예제: JWT 디코딩하기
JWT가 보안을 보장하는 방식: 시그니처
보안 고려사항 및 토큰 관리 방법
다양한 언어에서 JWT 생성 방법
실전 구현: Express + MongoDB로 만드는 JWT 인증
요약
마지막 한마디

사전 지식

이 가이드를 따라가며 최대한 많은 것을 얻으려면 다음과 같은 내용이 준비되어 있으면 좋습니다:

JavaScript / Node.js에 대한 기초적인 이해
로컬 환경에 설치된 Node.js와 npm
HTTP와 REST API의 기본 개념
JSON 구조와 역직렬화 / 직렬화 방법
Express에 대한 기초 지식 (혹은 튜토리얼을 따라갈 수 있는 정도의 지식)
실행 중인 MongoDB (로컬 또는 원격)
비동기 코드 / Promise / Async–Await 사용 경험
환경 변수 및 .env 설정에 대한 이해

이 글과 함께 볼 수 있는 동영상도 준비되어 있습니다. 텍스트와 함께 영상으로 학습하는 것을 좋아한다면 같이 참고해 보면 좋겠습니다.

JWT란 무엇인가?

JWT는 오늘날 가장 흔히 인증 용도로 사용되지만, 사실 원래 목적은 조금 달랐습니다. 처음에는 두 주체 간에 정보를 안전하게 교환하기 위한 표준 방식을 제공하기 위해 만들어졌습니다. 이를 위해 RFC 7519라는 산업 표준 사양이 정의되었으며, JWT가 어떻게 구조화되고, 어떤 방식으로 데이터 교환에 사용되어야 하는지 명시하였습니다. JavaScript를 위한 표준을 정의하는 ECMAScript (혹은 ES)와 비슷한 개념이라고 보면 되겠습니다.

실제 애플리케이션에서는 JWT가 주로 인증 용도로 사용되고 있고, 이 글에서도 그 관점에서 집중하여 설명할 것입니다.

하지만 기억해야 할 점은, JWT가 단순히 인증만을 위해 디자인된 것은 아니라는 것입니다. 인증을 구현하는 방법은 JWT 말고도 여러 가지가 있고, 그 중 가장 대표적인 대안이 바로 세션 토큰(session token)입니다.

왜 토큰이 필요한가?

우리가 어떤 인증 전략을 사용하든지 간에, 그게 세션 토큰이든 혹은 JWT든 간에, 그 바탕에는 토큰이 필요한 공통된 이유가 있습니다. 바로 HTTP 프로토콜이 상태를 유지하지 않는(stateless) 특성을 갖고 있기 때문입니다.

브라우저에서 서버로, 혹은 서버끼리 HTTP를 사용해 요청과 응답을 주고받을 때, HTTP 자체는 아무런 정보를 저장하지 않습니다.

Stateless라는 말은, 클라이언트와 서버가 상호작용할 때 HTTP가 이전 요청이나 데이터를 기억하지 않는다는 의미입니다. 다시 말해, 모든 요청은 필요한 정보를 스스로 담아서 보내야만 합니다. HTTP는 자체적으로 데이터를 저장하지 않습니다. 정보를 받으면 바로 “잊어버리는” 구조입니다. 그래서 HTTP를 stateless 프로토콜이라고 부릅니다.

이를 다른 식으로 생각해 보면 이렇습니다. 어떤 서버에 있는 웹페이지에 접속할 때, 우리는 서버에 어떤 정보를 보낼까요? 단순한 정적(static) 웹사이트라면, 사실 보내는 정보는 많지 않습니다. 그냥 페이지의 URL을 서버에 보내면, 서버는 그에 대응하는 HTML 페이지를 응답으로 돌려줍니다. 이 경우 서버는 별도의 정보를 기억할 필요가 없고, 상태를 유지할 필요도 없습니다. 이것이 바로 HTTP가 디자인된 방식이며, HTTP가 stateless 프로토콜인 이유입니다.

하지만 웹 애플리케이션이 유저마다 다른 응답을 제공하는 동적(dynamic) 웹사이트라면 이야기가 달라집니다. 이때는 URL만 보내서는 충분하지 않습니다. 유저는 URL과 함께 자신의 신원 정보(identity)도 서버에 전달해야 합니다.

예를 들어, 어떤 유저가 page-1에 접근하고 싶다면 서버에 이렇게 말해야 합니다. “저는 A 유저입니다. page-1을 보여 주세요.” 그러면 서버는 해당 유저를 위한 page-1을 응답으로 돌려줍니다. 이후 유저가 다시 “이번에는 page-2를 주세요.”라고 요청하면 어떻게 될까요? HTTP는 stateless이기 때문에, 이 요청에 유저의 신원 정보가 포함되어 있지 않으면, 서버는 누가 요청했는지 알 수 없고 어떤 응답을 보내야 할지 판단할 수 없습니다. 그래서 매 요청마다 유저는 자신의 신원 정보를 함께 보내야 합니다.

그런데 실제 우리가 사용하는 웹사이트들을 보면, 정말 매번 신원 정보를 보내고 있나요? 예를 들어 Facebook을 생각해 보겠습니다. 한 번 로그인을 하고 나면, 이후에는 다시 로그인 인증을 하지 않아도 홈 화면이나 프로필 페이지에 접근할 수 있습니다.

그렇다면 질문이 생깁니다. HTTP가 stateless 프로토콜이라면, 어떻게 이런 일이 가능한가요? 웹 애플리케이션은 우리의 브라우징 세션을 어떻게 기억하는 걸까요? 그 답은 웹 애플리케이션이 세션을 여러 방식으로 유지할 수 있기 때문입니다. 그중 가장 흔한 방법 중 하나가 토큰을 사용하는 방식입니다.

세션 토큰(Session Token): 고전적인 방식

토큰 방식에는 크게 두 가지 옵션이 있습니다. 하나는 세션 토큰이 있고, 다른 하나는 JSON Web Token (JWT)가 있습니다. 두 방식을 이해해야 JWT가 무엇인지, 왜 쓰이는지 더 분명해집니다.

어떤 회사의 고객센터를 예로 들어보겠습니다. 고객이 전화를 걸어 불만을 제기합니다. 고객센터 상담사가 제기된 문제를 듣고 여러 가지 해결 방법을 시도하지만, 바로 해결하지 못합니다.

이때 상담사는 상위 관리자 팀으로 이관하고, 고객에 대한 케이스 파일을 만듭니다. 이 파일에는 고객과의 대화 내용과 여태 시도한 해결 방법들이 기록됩니다. 그리고 고객에게 케이스 번호를 알려줍니다. 그렇게 함으로써 고객이 다음에 전화했을 때, 처음부터 모든 이야기를 반복할 필요가 없어집니다.

다음 날 고객이 다시 전화를 걸어 케이스 번호를 말하면, 상담사는 해당 번호를 가지고 이력과 정보를 확인한 뒤 바로 응대를 할 수 있습니다.

이 시나리오는 웹 애플리케이션에서 세션 토큰을 이용한 인증 방식과 유사합니다. 유저가 인증에 성공하면, 서버는 세션을 생성하고 이를 추적하기 시작합니다. 그리고 해당 세션을 식별하기 위한 세션 ID를 새로 생성해 유저에게 전달합니다. 이는 앞서 예시로 든 고객 케이스 번호와 유사합니다. 이후부터는 유저가 서버에 요청을 보낼 때마다, 세션 ID 또는 토큰이 함께 전달되고, 서버는 전달받은 ID를 기반으로 세션을 조회해 요청을 보낸 클라이언트를 식별합니다. 서버는 동시에 여러 클라이언트를 처리해야 하므로, 이러한 세션 토큰 방식은 인증을 구현하는 데 있어 효과적이고 널리 사용되는 전략으로 자리 잡았습니다.

클라이언트가 이 세션 ID를 서버로 어떻게 보내느냐는 구현에 따라 달라질 수 있지만, 가장 흔한 방식은 브라우저의 쿠키(cookie)에 세션 ID를 저장하는 것입니다. 이 방법의 장점은, 브라우저가 동일한 서버로 요청을 보낼 때마다 자동으로 쿠키 정보를 헤더에 실어 보내준다는 점입니다. 이는 브라우저의 기본 동작이기 때문에, 별도의 처리 없이도 자연스럽게 동작합니다.

유저가 인증에 성공하면 서버는 브라우저 쿠키에 세션 ID를 저장하고, 이후부터는 모든 요청에 쿠키가 자동으로 포함되어 서버가 유저를 식별할 수 있게 됩니다. 이 방식은 과거에 매우 널리 사용되었지만, 현대적인 애플리케이션 환경에서는 다소 구식이 된 측면도 있습니다.

이 방식에는 몇 가지 문제가 있습니다. 가장 큰 문제는 서버가 하나뿐이라는 전제를 바탕에 두고 있다는 점입니다. 요즘의 웹 애플리케이션은 보통 여러 대의 서버를 사용합니다. 이런 경우, 유저 앞단에는 로드 밸런서(load balancer)가 있고, 이 로드 밸런서가 어떤 서버에 요청을 보낼건지 결정합니다.

세션 토큰을 사용하는 상황을 가정해 보겠습니다. 유저가 첫 번째 요청을 보냈고, 로드 밸런서가 이 요청을 Server-1으로 보냅니다. Server-1은 세션 ID를 생성해 클라이언트에게 돌려줍니다. 이후 유저가 또 다른 요청을 보내고, 이번에는 로드 밸런서가 이 요청을 Server-2로 보냅니다. 그런데 Server-2에는 해당 세션 ID에 대한 정보가 없습니다. 그렇다면 이 요청이 누구의 것인지 어떻게 알 수 있을까요?

일반적인 해결책은 세션 ID를 각 서버가 아니라 공유된 Redis 데이터베이스에 저장하는 것입니다. 이렇게 하면 어느 서버든 Redis에서 세션 ID를 조회할 수 있습니다. 이를 흔히 Redis cache라고 부릅니다. 하지만 마이크로서비스 아키텍처에서는 이 방식에 허점이 있습니다. 만약 어떤 이유로 Redis cache가 다운된다면, 서버들은 정상적으로 작동하고 있더라도 인증 메커니즘이 실패할 수 있습니다. 이 지점에서 JSON Web Token이 다른 접근 방식을 제시합니다.

JWT: 현대적인 해결책

앞에서 살펴본 고객센터 예시로 다시 돌아가 보죠. 이번에는 전화나 시스템이 전혀 없다고 가정해 보겠습니다. 고객이 직접 회사 사무실로 찾아와 상담사와 대면으로 이야기합니다. 이번에는 상담사가 시스템에 정보를 저장할 수 없으니, 대신 종이에 모든 내용을 적은 뒤 그 종이를 고객에게 건네주며 이렇게 말합니다. “다음에 올 때 이걸 가져오세요.”

이 방식은 앞서 봤던 개념과 조금 다르죠? 하지만, 이 방식도 여전히 다른 문제가 있습니다. 바로 유효성(validity) 문제입니다. 만약 그 고객이 진짜 고객이 아니고 악의적인 의도를 품고 있다면, 상담사는 어떻게 그 고객을 신뢰할 수 있을까요? 다음 날 그 고객이 빈 종이에 같은 정보를 적어 들고 온다면, 상담사는 그 고객의 신원이 유효한지 어떻게 확인할 수 있을까요?

이때 가능한 해결 방법은, 상담사가 종이를 건네줄 때 직접 서명을 해 두는 것입니다. 그러면 고객이 다음에 그 종이를 가져왔을 때, 상담사는 그 서명을 확인함으로써 해당 종이를 신뢰할 수 있는지 판단할 수 있습니다.

JSON Web Token은 이와 유사한 방식으로 동작합니다. 여기서는 클라이언트가 인증되었을 때, 서버가 모든 정보를 저장하는 대신 유저의 정보를 서명(signature)과 함께 JSON 토큰 형태로 클라이언트에게 전달합니다. 이후 클라이언트는 다음 요청부터 매번 이 토큰을 함께 전송합니다. 이 토큰에는 이 유저가 어떤 유저인지, 이름이 무엇인지, 그리고 그 외 필요한 정보들이 포함되어 있습니다.

이 경우 서버는 아무것도 저장하지 않고, 모든 정보는 클라이언트에 유지됩니다. 클라이언트가 이 토큰과 함께 요청을 보낼 때마다, 서버는 토큰을 읽고 어떤 유저가 요청을 보냈는지 식별하고 필요한 데이터를 제공합니다.

이 토큰은 단순한 ID가 아닙니다. 모든 정보를 담고 있는 JSON 객체이며, 이것이 바로 JSON Web Token입니다. 이 JWT를 어디에 저장할지는 전적으로 클라이언트의 선택입니다. 가장 일반적인 방식은 브라우저의 쿠키나 로컬 스토리지(local storage)에 저장하는 것입니다.

JWT의 구조: 헤더, 페이로드, 시그니처

앞서 언급한 것 처럼, 서버는 JSON 객체를 전달받지만, JWT는 일반적인 JSON처럼 보이지는 않습니다.

위 이미지에서는 JWT가 다소 특이하게 보일 수 있습니다. 실제로 이것은 JSON 객체를 인코딩한 형태로, 일종의 복잡하게 압축된 표현 방식입니다. 자세히 살펴보면 JWT는 점(.)으로 구분된 세 부분으로 나뉘어 있다는 것을 알 수 있습니다. 첫 번째 부분은 헤더(header), 두 번째 부분은 본질적으로 데이터를 담고 있는 JSON 페이로드(payload), 그리고 세 번째 부분은 시그니처(signature)입니다.

각 부분을 개별적으로 살펴보면 다음과 같습니다.

헤더는 하나의 독립적인 JSON 객체입니다.
페이로드 역시 데이터를 포함하고 있는 별도의 JSON 객체입니다.
세 번째 부분은 시그니처입니다.

그렇다면 시그니처는 무엇일까요? 간단히 말해 토큰의 내용은 시크릿 키(secret key)와 함께 해시(hash)되는데, 그게 바로 시그니처입니다. 여기서 이 시크릿 키는 서버 내부에만 저장되고, JSON Web Token이 서버로 전달되면, 서버는 해당 시크릿 키를 사용해 시그니처가 여전히 유효한지, 중간에 변조되지는 않았는지 등을 확인할 수 있습니다.

번역자 코멘트: 해시(hash)는 데이터를 고정된 길이의 값으로 변환해 주는 계산 방식입니다. 입력 내용이 조금이라도 달라지면 결과 값은 완전히 달라지게 됩니다. 특히 JWT는 시크릿 키(secret key)와 함께 해시를 하기에, 결과 값을 뒤로 되돌려 원래의 데이터를 얻는 건 불가능에 가깝습니다. 누군가 중간에 JWT를 가로채 데이터를 변조했다면, 서버는 바로 알아챌 수 있습니다.

예제: JWT 디코딩하기

예제를 하나 살펴보겠습니다. JWT를 다루고 그 구조를 이해하기에 가장 좋은 웹사이트는 jwt.io입니다. JWT 하나를 이 사이트에 붙여 넣으면 헤더, 페이로드, 시그니처라는 세 개의 영역이 표시됩니다. 페이로드는 “Decoded Payload” 부분에 나타나며, 실제 내용과 데이터가 들어 있습니다. 이 안에는 ID, 이름을 담고 있는 JSON 객체, 그리고 만료일 등이 포함되어 있는 것을 확인할 수 있습니다.

"Decoded Header" 부분 역시 완전히 유효한 JSON 객체이며, JWT를 생성하거나 검증할 때 사용된 알고리즘과 토큰의 타입을 명시합니다.

주요 데이터는 “Decoded Payload” 부분에 들어 있습니다. 세 번째 부분은 시그니처입니다. 여기서 한 가지 중요한 점이 있습니다. 이처럼 복잡하게 섞여보이는 토큰이 어디에서 오는지 궁금할 수 있는데, 그건 사실 매우 단순합니다. “Decoded Payload”에 있는 데이터가 Base64로 인코딩되어 있으며, 이것이 바로 이처럼 난해하게 보이는 토큰의 형태를 만듭니다.

이 JWT의 해당 부분을 복사해 온라인에서 찾을 수 있는 Base64 디코더에 일단 붙여 넣어 보면, 즉시 원래의 데이터를 확인할 수 있습니다.

그렇다면 이것이 의미하는 바는 무엇일까요? 이는 이 데이터를 다시 Base64로 인코딩하면 동일한 토큰이 생성된다는 뜻입니다. 헤더 역시 동일한 방식으로 동작합니다.

마지막으로, 이 인코딩된 부분에 대해 짚고 넘어가야 할 점이 있습니다. 이것이 보안을 위한 것일까요? 그렇지 않습니다. 이는 오직 편의를 위한 것입니다. JSON 객체는 상당히 길어질 수 있고, 모든 프로그래밍 언어가 이를 동일한 방식으로 처리하지는 않습니다. JavaScript에서는 비교적 쉽지만, 다른 언어에서는 문제가 되는 경우도 있습니다. 그래서 데이터를 다루기 쉽게 만들기 위해 Base64 인코딩을 사용하는 것입니다. 이는 보안을 위한 것이 아니며, 이런 방식의 인코딩은 데이터를 안전하게 만들어 주지 않습니다. 정보는 여전히 공개적으로 확인할 수 있습니다.

위 그림에서 볼 수 있듯이, 이 Base64 디코더 사이트에 토큰을 입력하는 순간 데이터는 즉시 표시됩니다. 이는 여기에 민감한 정보를 저장해서는 안 된다는 의미입니다. 유저 ID와 같은 유저 식별 정보나 기타 공개 가능한 정보만 담아야 합니다. 비밀번호나 시크릿 키와 같은 정보는 쉽게 읽힐 수 있기 때문에 절대로 토큰에 저장해서는 안 됩니다. 겉보기에는 인코딩되어 보이지만, 실제로는 공개된 데이터입니다.

JWT가 보안을 보장하는 방식: 시그니처

이제 시그니처(signature)를 통해 보안에 대한 보장이 이루어지는 부분으로 넘어가 보겠습니다. 앞서 고객센터 종이 예시에서는 사람이 직접 손으로 서명을 추가할 수 있었습니다.

하지만 데이터의 경우, 시그니처를 생성하는 과정은 다릅니다. 데이터에서는 실제 서명 역할을 하는 시크릿 키를 사용해 암호학적으로 시그니처를 생성합니다. 시그니처를 만드는 과정은 다음과 같습니다:

데이터는 Base64로 인코딩됩니다.
인코딩된 데이터에 시크릿 키를 결합(concatenate) 합니다.
이를 다시 Base64로 인코딩합니다.

사용할 알고리즘은 변경할 수 있지만, 한 번 선택된 알고리즘은 토큰을 생성할 때와 검증할 때 동일하게 사용되어야 합니다. 생성과 검증 과정에서 서로 다른 알고리즘을 사용할 수는 없습니다.

마지막으로 데이터는 시크릿 키를 사용해 해시됩니다. 이 시크릿 키는 외부에 공개되지 않으며, 오직 서버에만 보관됩니다. 보통은 서버의 보안 저장소(server vault)에 안전하게 저장됩니다. 이 JWT가 서버에 도착하면, 서버는 해당 시크릿 키를 사용해 토큰이 유효한지 검증합니다. 만약 값이 올바르게 일치하지 않으면 “invalid signature”라는 결과가 표시됩니다. 이를 통해 서버는 토큰이 중간에 변조되었는지 여부를 확인할 수 있습니다.

예를 들어, 시그니처로 love-you-all-from-logicbaselabs를 사용하고 서버에서 이를 검증했을 때 “signature verified”라는 결과가 나온다면, 이는 시크릿 키가 서버에만 존재한다는 것을 보여줍니다. 즉, 공개된 정보가 포함되어 있더라도 토큰의 유효성은 검증될 수 있습니다.

다만 JSON Web Token은 비밀번호와 같은 개념은 아닙니다. JWT는 주로 유저를 식별하는 역할을 합니다. 서버는 JWT를 확인해 이것이 유효한 유저에게 속한 토큰인지 판단할 수 있습니다. 다시 말해 JWT는 유저의 신원을 나타내며, 시그니처와 함께 보안 요소를 포함하고 있는 매우 중요한 토큰입니다.

보안 고려사항 및 토큰 관리 방법

한 가지 반드시 기억해야 할 점이 있습니다. 누군가가 당신의 JWT를 그대로 손에 넣었다면, 즉 완전히 동일한 토큰을 가지고 있다면, 그 사람은 해당 유저로 쉽게 로그인할 수 있습니다. 그저 그 토큰을 포함해 요청을 보내기만 하면 필요한 접근 권한을 얻을 수 있습니다.

이를 이렇게 생각해 볼 수 있습니다. 누군가가 당신의 Facebook 비밀번호를 알아내면, 당신의 Facebook 계정에 그대로 로그인할 수 있습니다. 마찬가지로 누군가가 PayPal 계정의 PIN을 획득했다면, 그 계정에 쉽게 접근할 수 있습니다. 즉, 가장 중요한 보안 정보를 누군가가 손에 넣는 순간, 이를 보호할 방법은 사실상 없습니다.

JWT도 동일합니다. 토큰을 클라이언트 측에서 얼마나 안전하게 보관하느냐가 절대적으로 중요합니다. 이런 점에서 우리는 어느 정도 취약할 수밖에 없습니다.

다만 세션 토큰과의 가장 큰 차이점이 있는데, 세션 토큰의 경우, 계정이 침해되었다고 판단되면 서버에서 해당 세션을 무효화할 수 있습니다. 다시 말해, 그 세션 ID로는 더 이상 누구도 로그인할 수 없게 됩니다.

하지만 JWT의 경우에는 만료일이 지나기 전까지 토큰이 계속 유효합니다. 따라서 이를 즉시 무효화할 수 있는 직접적인 방법이 없습니다. JWT는 암호학적으로 자기완결적인(self-contained) 구조를 가지며, 서버의 시크릿 키로 서명되어 있기 때문에, 한 번 생성되면 서버에서 바로 폐기할 수 없습니다.

이를 처리하는 유일한 방법은 웹에서 일반적으로 사용하는 방식인 토큰 차단 목록(denylist)을 관리하는 것입니다. 즉, 서버는 차단된 JWT 토큰들을 별도의 데이터베이스에 저장해 관리합니다. 요청이 들어오면 서버는 먼저 토큰이 형식적으로 유효한지 검증하고, 그 다음 미들웨어를 통해 해당 토큰이 denylist에 포함되어 있는지 확인합니다. 이 목록에 포함되어 있지 않은 경우에만 유저의 접근이 허용됩니다.

이것이 JSON Web Token을 사용할 때 지켜야 할 기본적인 규칙들입니다. JWT는 어떤 프로그래밍 언어에서도 사용할 수 있으며, 특히 REST API 환경에서 매우 널리 활용됩니다. 또한 마이크로서비스 아키텍처에서도 매우 보편적이고 널리 퍼진 방식입니다.

다양한 언어에서 JWT 생성 방법

JWT를 생성하는 방법은 사용하는 프로그래밍 언어에 따라 달라집니다. 예를 들어 Node.js에서는 jsonwebtoken과 같은 전용 라이브러리가 제공되기 때문에 비교적 쉽게 JWT를 만들 수 있습니다. PHP 역시 JWT를 생성하기 위한 사용하기 쉬운 라이브러리들이 존재합니다. 이처럼 JWT는 특정 프로그래밍 언어에 국한된 기술이 아니라, 어디에서나 사용할 수 있는 범용적인 도구입니다. 많은 사람들이 JWT가 JavaScript 전용이라고 생각하지만, 이는 사실이 아닙니다.

또한 JWT는 인증 용도로만 사용되는 것이 아니라는 점도 기억해야 합니다. JWT는 어떠한 형태로든 신원을 표현하는 데 사용할 수 있습니다. 예를 들어 콘서트에 입장할 때 일반적인 종이 티켓 대신 JWT를 사용해 접근 권한을 부여할 수도 있습니다. 이때 클라이언트가 해당 JWT를 사용하면, 게이트웨이(gateway)나 서버는 토큰을 읽어 필요한 정보에 대한 접근을 허용하고, 시그니처를 통해 토큰의 유효성을 검증할 수 있습니다.

실전 구현: Express + MongoDB로 만드는 JWT 인증

이번에는 지금까지 배운 모든 개념을 실제로 적용해 보겠습니다. Express.js와 MongoDB를 사용해 JWT 인증 시스템을 단계별로 구축할 것입니다.

처음에는 다소 부담스럽게 느껴질 수도 있지만 차근차근 따라오면 문제없습니다. 한 단계씩 차근차근 진행할 것이며, 마지막에는 실제로 동작하는 프로젝트를 완성하게 될 것입니다. 건물에 층층이 들어가 보듯이, 각 구간을 충분히 살펴보면서 확실한 이해를 얻고 갈 것입니다.

1. 프로젝트 세팅 & 패키지 설치

코드를 작성하기 전에 먼저 Node.js 프로젝트를 세팅하고 필요한 패키지들을 설치해야 합니다.

Node.js 프로젝트 초기화

터미널을 열어 다음과 같이 실행해보세요:

mkdir jwt-auth-demo
cd jwt-auth-demo
npm init -y

이 명령을 실행하면 기본 세팅이 된 package.json 파일이 생성됩니다.

패키지 설치

JWT 인증 시스템을 만들기 위해 다음 패키지들을 설치합니다.

npm install express mongoose bcryptjs jsonwebtoken dotenv

express: API 를 만들기 위한 빠르고 최소한의 Node.js 웹 프레임워크입니다.
mongoose: MongoDB를 더 쉽게 다루기 위한 ODM(Object Data Modeling) 라이브러리입니다.
bcryptjs: 비밀번호를 해시하기 위한 라이브러리입니다.
jsonwebtoken: JWT 토큰을 생성하고 검증하는 라이브러리입니다.
dotenv: .env 파일에 있는 환경 변수를 불러와서, 비밀 정보들을 안전하게 관리할 수 있게 해줍니다.

개발용 패키지 설치 (선택 사항)

개발을 편하게 하기 위해 파일이 변경될 때마다 서버를 자동으로 재시작해 주는 nodemon을 설치해 보세요.

npm install --save-dev nodemon

package.json의 scripts를 다음과 같이 수정합니다.

"scripts": {
  "start": "node server.js",
  "dev": "nodemon server.js"
}

npm start 는 서버를 일반 모드로 실행합니다.
npm run dev 는 nodemon을 사용해 코드 변경 시 자동으로 서버를 재시작합니다.

2. 프로젝트 폴더 구조

jwt-auth-demo/
│
├── config/
│   └── db.js
│
├── controllers/
│   └── authController.js
│
├── middlewares/
│   └── authMiddleware.js
│
├── models/
│   └── User.js
│
├── routes/
│   └── auth.js
│
├── services/
│   ├── hashService.js
│   └── jwtService.js
│
├── .env
├── server.js
├── package.json

각 디렉터리의 역할은 다음과 같습니다.

config/: 데이터베이스 연결 및 환경 설정 관련 코드
controllers/: 각 엔드포인트(Endpoint)의 핵심 비즈니스 로직
middlewares/: 컨트롤러 실행 전에 동작하는 미들웨어(예: 인증 체크)
models/: Mongoose 스키마
routes/: API 엔드포인트의 정의
services/: 비밀번호 해시, JWT 생성/검증 같은 재사용 가능한 로직
.env: 시크릿이나 환경 변수
server.js: 애플리케이션의 엔트리 포인트

3. 단계별 구현하기

Express 서버 초기화

먼저 가장 기본이 되는 Express 서버를 설정합니다. 이 서버가 유저 회원가입, 로그인과 같은 요청을 받고 응답을 돌려주는 역할을 합니다.

파일: server.js

// server.js

// Import the express library to build our server
const express = require("express");

// Create an instance of express
const app = express();

// Middleware to parse JSON request bodies (important for APIs)
app.use(express.json());

// Default route to test server
app.get("/", (req, res) => {
  res.send("Hello World! Your server is working 🚀");
});

// Start the server on port 5000
const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

Express를 불러와 app인스턴스를 생성합니다.
JSON 형태의 요청을 역직렬화(parsing)하기 위해 미들웨어를 사용합니다.
서버가 잘 동작하는지 테스트하기 위해 간단한 / 경로의 라우트를 만듭니다.
마지막으로 5000번 포트에서 서버를 시작합니다.

이제 테스트를 해봅시다:

node server.js 혹은 npm run dev 를 실행해 봅니다.
브라우저를 열어 다음과 같은 주소로 가보세요. http://localhost:5000.
다음과 같은 메세지가 떠야 합니다: Hello World! Your server is working 🚀

MongoDB를 Mongoose로 연결하기

이제 유저 정보를 저장할 데이터베이스가 필요합니다. 여기서는 MongoDB를 사용하고, Node.js에서 쉽게 접근하기 위해 ODM 라이브러리인 Mongoose를 사용합니다.

파일: config/db.js

// config/db.js

// Import mongoose
const mongoose = require("mongoose");

// Connect to MongoDB using environment variable
const connectDB = async () => {
  try {
    await mongoose.connect(process.env.MONGO_URI, {
      useNewUrlParser: true,
      useUnifiedTopology: true,
    });
    console.log("✅ MongoDB Connected");
  } catch (err) {
    console.error("❌ MongoDB Connection Error:", err.message);
    process.exit(1); // Stop server if DB fails
  }
};

module.exports = connectDB;

이제 서버가 MongoDB와 연결될 준비가 되었습니다. 데이터를 삽입/수정/조회하는 모든 작업은 이 데이터베이스를 통해 이루어집니다.

File: .env

PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/jwt-auth-demo
JWT_SECRET=your_super_secret_key

.env파일에는 데이터베이스의 URI, JWT 시크릿 키, 서버 포트와 같은 민감한 정보가 저장됩니다. 환경 변수를 사용하면 이러한 비밀 정보를 코드에서 분리해 관리할 수 있고, 소스 파일을 수정하지 않고도 설정을 쉽게 변경할 수 있습니다. 자격 증명(credential)을 보호하기 위해 .env파일은 절대 공개 저장소에 기록(commit)해서는 안 됩니다.

User 모델 만들기

이제 데이터베이스 안에서 User가 어떤 구조를 가질지 정의해야 합니다. 각 유저는 name, email, password를 갖게 됩니다.

파일: models/User.js

// models/User.js
const mongoose = require("mongoose");

// Define a schema (blueprint of user data)
const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
});

// Create and export the model
module.exports = mongoose.model("User", userSchema);

이제 각 유저는 name, email, hashed password 필드를 갖는 구조로 저장됩니다.

해시(Hash) 및 JWT 서비스

이번에는 비밀번호 해시와 JWT 관리 로직을 각각 별도의 서비스 파일로 분리합니다. 이렇게 하면 코드가 깔끔해지고 재사용성이 높아집니다.

파일: services/hashService.js

//services/hashService.js

const bcrypt = require("bcryptjs");

// Function to hash a plain password
exports.hashPassword = async (plainPassword) => {
  // bcrypt.hash generates a hashed version of the password
  // The number 10 is the salt rounds, which affects the hashing complexity
  return await bcrypt.hash(plainPassword, 10);
};

// Function to compare a plain password with a hashed password
exports.comparePassword = async (plainPassword, hashedPassword) => {
  // bcrypt.compare checks if the plain password matches the hashed one
  return await bcrypt.compare(plainPassword, hashedPassword);
};

hashPassword(plainPassword):비밀번호를 받아 bcrypt로 해시한 값을 반환합니다. 비밀번호는 절대 평문으로 저장하면 안 됩니다
comparePassword(plainPassword, hashedPassword): 유저가 입력한 비밀번호와 데이터베이스에 저장된 해시 값을 비교해 일치 여부를 알려줍니다. 일치하면 true를 반환합니다.

파일: services/jwtService.js

// services/jwtService.js

const jwt = require("jsonwebtoken");

// Function to generate a JWT
exports.generateToken = (payload) => {
  // jwt.sign creates a signed token using our secret key from environment variables
  // expiresIn defines how long the token is valid (1 hour here)
  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: "1h" });
};

// Function to verify a JWT
exports.verifyToken = (token) => {
  // jwt.verify checks if the token is valid and not expired
  return jwt.verify(token, process.env.JWT_SECRET);
};

generateToken(payload): JWT를 생성합니다. 보통 payload가 유저를 식별할 수 있는 ID나 이메일을 담고 있습니다.
verifyToken(token): JWT의 유효성을 검증하고 디코딩된 payload를 반환합니다.
이처럼 JWT 관련 로직을 한 곳에 모아 두면 관리와 유지보수가 훨씬 편해집니다.

인증 컨트롤러(Auth Controller)

이 단계에서는 인증과 관련된 모든 로직을 별도의 컨트롤러에서 처리합니다. 이렇게 하면 라우트 정의를 깔끔하게 유지할 수 있고, 비즈니스 로직을 엔드포인트 정의와 분리할 수 있습니다.

파일: controllers/authController.js

// controllers/authController.js

const User = require("../models/User");
const { hashPassword, comparePassword } = require("../services/hashService");
const { generateToken } = require("../services/jwtService");

// Register new user
exports.register = async (req, res) => {
  try {
    const { name, email, password } = req.body; // Get user input

    // Step 1: Check if user already exists
    const existingUser = await User.findOne({ email });
    if (existingUser)
      return res.status(400).json({ message: "User already exists!" });

    // Step 2: Hash password using hashService
    const hashedPassword = await hashPassword(password);

    // Step 3: Save user to database
    const user = new User({ name, email, password: hashedPassword });
    await user.save();

    // Step 4: Send success response
    res.status(201).json({ message: "User registered successfully!" });
  } catch (err) {
    // Handle errors gracefully
    res.status(500).json({ error: err.message });
  }
};

// Login user
exports.login = async (req, res) => {
  try {
    const { email, password } = req.body; // Get user input

    // Step 1: Find user by email
    const user = await User.findOne({ email });
    if (!user)
      return res.status(400).json({ message: "Invalid email or password" });

    // Step 2: Compare provided password with hashed password
    const isMatch = await comparePassword(password, user.password);
    if (!isMatch)
      return res.status(400).json({ message: "Invalid email or password" });

    // Step 3: Generate JWT using jwtService
    const token = generateToken({ id: user._id, email: user.email });

    // Step 4: Send success response with token
    res.json({ message: "Login successful!", token });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
};

// Protected profile route
exports.profile = (req, res) => {
  // req.user is set by auth middleware after token verification
  res.json({
    message: "Welcome to your profile!",
    user: req.user,
  });
};

파일: controllers/authController.js 은 인증 관련 로직을 담고 있습니다.
exports.register는 회원가입 로직입니다. 이미 같은 이메일의 유저가 있는지 확인하고, hashService 를 이용하여 비밀번호를 해시한 뒤, 새 유저를 MongoDB에 저장하고, 성공 메세지를 반환합니다.
exports.login은 로그인 로직입니다. 이메일로 유저를 찾고, hashService.comparePassword 를 이용하여 비밀번호를 비교 검증하고, 유효하다면 JWT를 생성해, 토큰을 반환합니다.
exports.profile은 보호된(protected) 프로필 라우트입니다. req.user에 저장된 유저 정보를 응답으로 돌려줍니다.
컨트롤러를 사용하면 라우트 정의와 실제 비즈니스 로직을 깔끔하게 분리할 수 있습니다.

인증 미들웨어(Auth Middleware)

이 단계에서는 JWT를 검증함으로써 라우트를 보호하는 미들웨어를 생성합니다. 인증된 유저만 보호된 엔드포인트에 접근할 수 있습니다.

파일: middlewares/authMiddleware.js

// middlewares/authMiddleware.js

const { verifyToken } = require("../services/jwtService");

// Middleware to protect routes
module.exports = (req, res, next) => {
  // Step 1: Get Authorization header
  const authHeader = req.headers["authorization"];
  if (!authHeader)
    return res.status(401).json({ message: "No token provided" });

  // Step 2: Extract token from format 'Bearer '
  const token = authHeader.split(" ")[1];
  if (!token) return res.status(401).json({ message: "Malformed token" });

  try {
    // Step 3: Verify token using jwtService
    const decoded = verifyToken(token);

    // Step 4: Attach decoded user info to request object
    req.user = decoded;

    // Proceed to next middleware or route handler
    next();
  } catch (err) {
    // If token is invalid or expired
    res.status(401).json({ message: "Invalid or expired token" });
  }
};

파일: middlewares/authMiddleware.js 은 라우트를 보호하기 위한 미들웨어입니다.
1단계: Authorization 헤더가 존재하는지 확인합니다.
2단계: Bearer 형식에서 실제 토큰을 추출합니다.
3단계: jwtService.verifyToken을 사용해 토큰을 검증합니다.
4단계: 디코딩된 유저 정보를 req.user에 추가해 이후 라우트 핸들러에서 사용할 수 있도록 합니다.
토큰이 없거나, 형식이 올바르지 않거나, 유효하지 않거나, 만료된 경우 미들웨어는 401 Unauthorized 응답을 반환합니다. 이를 통해 인증된 유저만 보호된 라우트에 접근할 수 있도록 보장합니다.

인증 라우트 (Auth Routes)

이 단계에서는 인증과 관련된 라우트를 정의하고, 이를 컨트롤러와 미들웨어에 연결합니다.

파일: routes/auth.js

// routes/auth.js

const express = require("express");
const router = express.Router();
const authController = require("../controllers/authController");
const authMiddleware = require("../middlewares/authMiddleware");

// Step 1: Register route
// Users send their name, email, and password to this endpoint
router.post("/register", authController.register);

// Step 2: Login route
// Users send email and password to receive JWT
router.post("/login", authController.login);

// Step 3: Protected profile route
// Only accessible to authenticated users with a valid JWT
router.get("/profile", authMiddleware, authController.profile);

module.exports = router;

파일: routes/auth.js - 인증 엔드포인트를 정의하는 핵심 파일입니다.
router.post("/register", authController.register): 유저 회원가입을 처리합니다.
router.post("/login", authController.login): 유저 로그인을 처리하고 JWT 토큰을 생성합니다.
router.get("/profile", authMiddleware, authController.profile): JWT가 필요한 보호된 라우트입니다. authMiddleware를 통해 인증된 유저만 접근할 수 있도록 보장합니다.
이처럼 라우트, 컨트롤러, 미들웨어를 함께 사용하면 애플리케이션 구조를 체계적으로 유지할 수 있고, 코드도 보다 전문적으로 관리할 수 있습니다.

메인 서버 파일

이 파일은 애플리케이션의 메인 엔트리 포인트입니다. 서버를 설정하고, 데이터베이스에 연결하며, 모든 라우트를 등록하는 역할을 합니다.

파일: server.js

// server.js

require("dotenv").config(); // Step 1: Load environment variables from .env
const express = require("express");
const connectDB = require("./config/db");

const app = express();

// Step 2: Connect to MongoDB
connectDB();

// Step 3: Middleware to parse JSON request bodies
app.use(express.json());

// Step 4: Mount auth routes
// All auth-related routes will start with /api/auth
app.use("/api/auth", require("./routes/auth"));

// Step 5: Default route to test server
app.get("/", (req, res) => {
  res.send("Hello World! Your server is working 🚀");
});

// Step 6: Start server on PORT from .env or default 5000
const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

환경 변수 불러오기: dotenv를 사용해 비밀 정보와 설정 값을 코드와 분리해 관리합니다.
MongoDB 연결: config/db.js에 정의된 connectDB()를 호출해 데이터베이스에 연결합니다.
미들웨어: express.json()을 사용해 Express가 JSON 요청을 파싱할 수 있도록 합니다.
라우트 등록: app.use("/api/auth", ...)를 통해 모든 인증 관련 라우트를 등록합니다.
기본 라우트: 서버가 정상적으로 실행 중인지 확인하기 위한 간단한 GET 엔드포인트입니다.
서버 시작: app.listen을 호출해 설정된 포트에서 서버를 실행합니다.

API 테스트 하기

이번에는 Postman이나 기타 HTTP 클라이언트와 같은 도구를 사용해 JWT 인증 API를 테스트하는 방법을 살펴봅니다.

테스트를 시작하기 전에 서버가 실행 중인지 반드시 확인해야 합니다. 서버가 실행되고 있지 않다면, 터미널을 열고 다음 명령을 실행합니다.

npm run dev

혹은

node server.js

이 명령을 실행하면 .env 파일에 정의된 포트(기본값은 5000)에서 서버가 시작됩니다.

MongoDB가 실행 중인지도 확인해 보세요. 로컬 MongoDB를 사용하고 있다면 다음 명령으로 실행할 수 있습니다:

mongod

로컬 MongoDB를 사용하지 않는 경우에는, 연결된 MongoDB 서비스가 정상적으로 활성화되어 있는지 확인합니다.

항상 터미널에 오류 메시지가 있는지 확인해 보세요. 서버나 데이터베이스가 정상적으로 시작되지 않으면 API 요청은 동작하지 않습니다.

회원가입 하기

요청:

POST http://localhost:5000/api/auth/register
Content-Type: application/json

{
  "name": "sumit",
  "email": "sumit@example.com",
  "password": "mypassword"
}

응답:

{
  "message": "User registered successfully!"
}

이 요청은 유저 정보를 포함해 http://localhost:5000/api/auth/register로 POST 요청을 전송합니다. 요청이 성공하면 확인 메시지를 응답으로 받게 됩니다.

로그인 하기

요청:

POST http://localhost:5000/api/auth/login
Content-Type: application/json

{
  "email": "sumit@example.com",
  "password": "mypassword"
}

응답:

{
  "message": "Login successful!",
  "token": ""
}

이 요청은 이메일과 비밀번호를 포함해 http://localhost:5000/api/auth/login으로 POST 요청을 전송합니다. 자격 증명이 올바른 경우, 보호된 라우트에 접근하기 위한 JWT를 응답으로 받게 됩니다.

보호된 라우트에 접근하기

요청:

GET http://localhost:5000/api/auth/profile
Authorization: Bearer

응답:

{
  "message": "Welcome to your profile!",
  "user": {
    "id": "...",
    "email": "sumit@example.com",
    "iat": ...,
    "exp": ...
  }
}

이 요청은 Bearer 방식으로 Authorization 헤더에 JWT를 포함하여 전송합니다.

유효한 토큰만 이 보호된 라우트에 접근할 수 있습니다.
iat와 exp는 각각 토큰이 발급된 시점(issued at)과 만료 시점(expiry time)을 의미합니다.

참고: 보호된 라우트에 접근할 때는 항상 Authorization: Bearer 헤더를 포함해야 합니다.

요약(Summary)

이 글에서는 JSON Web Token(JWT)이 무엇인지와 웹 인증에서 어떤 역할을 하는지를 전반적으로 살펴보았습니다. HTTP가 상태를 유지하지 않는(stateless) 프로토콜이라는 점과 그로 인해 토큰이 필요한 이유를 설명했으며, 전통적인 세션 토큰 방식과 JWT를 비교했습니다.

또한 JWT의 구조와 보안 메커니즘을 다루고, Node.js, Express, MongoDB를 사용한 실제 구현 방법을 단계별로 살펴보았습니다. 이와 함께 보안 고려사항, 토큰 관리 방식, 그리고 JWT 인증 API를 테스트하는 방법도 함께 설명했습니다.

핵심 포인트 정리:

JWT란 무엇인가?

JWT는 RFC 7519에 정의된, 두 주체 간의 정보를 안전하게 표현하기 위한 JSON 기반 개방형 표준입니다.
현대적인 웹 애플리케이션과 마이크로서비스 아키텍처에서 인증 용도로 널리 사용됩니다.
세션 토큰의 대안으로 활용됩니다.

2. HTTP의 Stateless 특성

HTTP는 요청 간 상태를 유지하지 않기 때문에, 각 요청은 필요한 모든 정보를 포함해야 합니다.
동적인 웹 애플리케이션에서는 유저 세션을 유지하기 위해 세션 토큰이나 JWT와 같은 토큰을 사용합니다.

3. 세션 토큰

서버가 세션 ID를 생성해 저장하고, 보통 쿠키를 통해 클라이언트에 전달하는 방식입니다.
단일 서버 환경에서는 효과적으로 동작하지만, 여러 서버 환경에서는 Redis와 같은 공유된 저장소가 필요합니다.
해당 캐시가 다운되면 인증 시스템이 영향을 받을 수 있습니다.

4. JWT: 현대적인 해결책

서버는 서명된 JSON 토큰을 클라이언트에 전달하고, 클라이언트는 이를 매 요청마다 전송합니다.
서버 측에 별도의 세션 저장소가 필요 없으며, 모든 유저 정보는 토큰 안에 포함됩니다.
시그니처를 통해 토큰의 유효성과 무결성이 보장됩니다.

5. JWT 구조

JWT는 헤더, 페이로드, 시그니처 세 부분으로 구성됩니다.
헤더와 페이로드는 Base64로 인코딩된 JSON 객체이며, 시그니처는 시크릿 키를 사용한 해시 값입니다.
Base64 인코딩은 보안을 위한 것이 아니라, 데이터를 다루기 쉽게 하기 위한 표현 방식입니다.

6. JWT 디코딩

jwt.io와 같은 도구를 사용하면 JWT의 헤더, 페이로드, 시그니처를 쉽게 확인할 수 있습니다.
페이로드는 누구나 읽을 수 있으므로, 민감한 정보는 JWT에 저장해서는 안 됩니다.

7. JWT 보안

시그니처는 시크릿 키와 암호학적 알고리즘을 사용해 생성됩니다.
서버는 시크릿 키를 이용해 토큰의 무결성을 검증합니다.
JWT는 유저를 식별하기 위한 수단이며, 비밀번호와 같은 역할을 하지는 않습니다.

8. 보안 고려사항 및 토큰 관리

JWT가 탈취되면, 만료 시점까지 공격자가 해당 유저로 위장할 수 있습니다.
JWT는 직접적인 무효화가 어렵기 때문에, 차단 목록을 통해 관리합니다.
세션 토큰은 서버에서 직접 무효화할 수 있다는 차이가 있습니다.

9. 다양한 언어에서의 JWT

JWT는 언어에 독립적인 표준으로, Node.js, PHP 등 다양한 언어에서 구현할 수 있습니다.
인증뿐 아니라 다양한 형태의 신원을 표현하는 데도 활용할 수 있습니다.

10. 실전 구현: Express + MongoDB로 JWT 인증 만들기

프로젝트 세팅 및 패키지 설치
폴더 구조 설계
Express 서버 초기화
MongoDB 연결
유저 모델 생성
비밀번호 해시 및 JWT 서비스 구현
인증 컨트롤러와 미들웨어 작성
인증 라우트 구성
메인 서버 파일 구성
API 테스트 방법 안내

11. API 테스트

Postman과 같은 도구를 사용해 회원가입, 로그인, 보호된 라우트 접근 방법을 설명했습니다.
요청 및 응답 예시를 통해 전체 흐름을 확인할 수 있습니다.

12. 요약

JWT는 안전하고, stateless하며, 널리 사용되는 인증 방식입니다.
다만 보안은 토큰을 얼마나 안전하게 보관하고 관리하느냐에 크게 좌우된다는 점을 항상 염두에 두어야 합니다.

마지막 한마디

이 튜토리얼에서 사용된 모든 소스 코드는 해당 GitHub 저장소에서 확인할 수 있습니다. 내용이 조금이라도 도움이 되었다면, 별을 눌러 응원의 뜻을 전해 주셔도 좋습니다.

또한 이 글이 유익하다고 느껴지셨다면, 도움이 될 만한 다른 분들과 자유롭게 공유해 주세요. 의견이나 피드백이 있다면 X에서 @sumit_analyzen, Facebook의 @sumit.analyzen으로 저를 언급해 주시거나, 코딩 튜토리얼을 시청하거나 LinkedIn에서 연결해 주셔도 감사하겠습니다.

Postman 스크립트를 사용해 API 인증 과정 단순화하는 법

Jong-Ho Kim — Tue, 02 Dec 2025 01:00:05 +0000

기사 원문: How to Use Postman Scripts to Simplify Your API Authentication Process

Postman은 개발자, API 테스터, 기술 문서 작성자, DevOps 팀이 API 개발을 테스트하고 문서화하며 협업할 때 사용하는 플랫폼입니다. HTTP, GraphQL, gRPC 등 다양한 형태의 API 요청을 손쉽게 만들고, 응답을 확인하며, API 요청들을 컬렉션 형태로 구성해 협업과 자동화를 지원합니다.

API 테스트 과정에서 반복 작업을 수행하는 일은 스트레스도 크고 시간이 많이 소요됩니다. 특히 Postman에서 새 인증 토큰을 받아 복사해서 붙여넣는 작업은 매우 반복적입니다. Postman 스크립트를 사용하면 인증 토큰을 자동으로 저장하고 재사용할 수 있어 이러한 반복 작업을 줄일 수 있습니다.

이 가이드를 따라 해보려면 다음이 필요합니다:

Postman API 클라이언트가 설치된 컴퓨터
Postman으로 API 요청을 만들어본 경험
JWT 인증을 사용하는 백엔드 애플리케이션과 해당 API 문서

만약 백엔드 애플리케이션이 없다면, 제가 GitHub에 올려 둔 예제(orimdominic/freeCodeCamp-postman-api-jwt)를 클론해서 사용할 수 있습니다.

이 글을 다 읽고 나면, Postman에서 인증 토큰을 발급 / 저장 / 재사용하는 과정을 훨씬 단순화할 수 있습니다. 또한 Postman의 다른 테스트 자동화 작업에도 활용할 수 있는 실용적인 스크립트 개념을 익히게 될 것입니다.

Postman 스크립트란?

Postman 스크립트는 Postman API 클라이언트 내부에서 실행되는 JavaScript 코드로, API 테스트 워크플로우를 자동화하고 확장하는 데 사용합니다. 스크립트는 요청 전(pre-request)과 요청 후(post-response)에 실행되도록 추가할 수 있습니다. 스크립트를 사용하면 다음과 같은 작업이 가능합니다:

API 요청 데이터를 처리하는 로직 추가
API 응답에 대한 테스트(assertion) 작성
API 엔드포인트 자동화 테스트 실행

Postman의 Scripts 탭에서 스크립트를 확인할 수 있습니다. Pre-request 탭은 요청이 실행되기 전에, Post-response 탭은 응답이 온 뒤에 실행됩니다.

JWT 인증 과정을 단순화하는 방법

이번 튜토리얼은 다음과 같은 순서대로 진행됩니다:

인증하여 토큰 발급받기
스크립트를 사용해 토큰을 컬렉션 변수에 저장하기
API 요청에서 해당 변수를 사용하기

인증하여 토큰 발급받기

다음과 같은 순서대로 따라해보세요:

백엔드 애플리케이션을 실행하고 정상적으로 동작하는지 확인합니다.
Postman을 열고 JWT를 발급받는 로그인(sign-in) 요청으로 이동합니다.
로그인 엔드포인트에 API 요청을 보내고 JSON 응답 구조를 확인합니다.

위 이미지에서 하이라이트된 부분은 로그인 요청이 성공했을 때 반환되는 JSON 응답을 보여줍니다. 이 응답 스키마에서 인증에 사용할 토큰은 data.token 필드에 포함되어 있습니다. 이제 이 토큰을 Postman 스크립트를 사용해 변수로 저장한 뒤, 인증이 필요한 요청의 Authorization 헤더에서 해당 변수를 사용하게 될 것입니다.

스크립트를 사용해 토큰을 컬렉션 변수에 저장하기

Postman에서 Body 탭 옆에 있는 Scripts 탭을 클릭합니다. 만약 Postman 창이 작게 표시되어 있다면, 해당 탭이 드롭다운 메뉴 안에 있을 수 있으니 펼쳐서 확인합니다. 다음으로 Post-response 탭을 선택합니다. 오른쪽의 텍스트 영역에 응답에서 인증 토큰을 추출해 Postman 변수에 저장하는 스크립트를 작성하게 됩니다. 아래 JavaScript 코드를 복사해 이 텍스트 영역에 붙여 넣습니다.

if (pm.response.code == 200) {
    const token = pm.response.json().data.token
    pm.collectionVariables.set("auth_token", token)
}

Postman 스크립트에서는 pm 식별자를 사용해 Postman 환경의 정보에 접근하고 값을 수정합니다. 위 스크립트는 먼저 응답 상태 코드가 200인지 확인해 요청이 성공했는지 확인합니다.

조건문 내부에서는 pm.response.json().data.token을 사용해 JSON 응답에서 인증 토큰을 가져오고, 이를 auth_token이라는 컬렉션 변수에 저장합니다. 만약 auth_token 변수가 없다면 새로 생성되고, 이미 존재한다면 기존 값이 새 토큰 값으로 덮어씁니다.

토큰이 변수에 정상적으로 저장되었는지 확인하려면, 위 스크린샷 기준으로 먼저 컬렉션 이름(1)을 클릭한 뒤 Variables 탭(2)을 선택합니다. 이후에는 인증 토큰을 매번 복사해 Authorization 헤더에 붙여넣을 필요 없이, Authorization 헤더에서 auth_token 변수를 그대로 사용할 수 있습니다.

API 요청에서 해당 변수를 사용하기

Authorization 헤더에서 컬렉션 변수를 사용할 때는 {{auth_token}}처럼 중괄호 두 개로 감싸서 참조합니다. 이렇게 설정해두면, API 요청을 보낼 때 Postman이 {{auth_token}}에 저장된 값을 자동으로 Authorization 헤더에 넣어 사용합니다.

또 다른 인증 요청으로 인해 auth_token 값이 갱신되더라도, 새로운 토큰을 직접 복사해서 붙여넣을 필요는 없습니다. Post-response 탭에 작성한 스크립트가 자동으로 auth_token 값을 업데이트해 주기 때문에, 이후에도 API 요청을 문제없이 계속 보낼 수 있습니다. 더 이상 반복적인 복사 및 붙여넣기 작업을 할 필요가 없습니다. 즉, DRY (Don’t Repeat Yourself) 원칙을 지킬 수 있습니다.

다음 단계

이번 튜토리얼에서는 Postman 스크립트를 사용해 환경 변수를 설정하고, 인증 토큰을 자동으로 저장 및 재사용하는 방법을 배웠습니다.

API 테스트에 대한 더 많은 예제와 assertion 작성 방법을 알고 싶다면, Postman에서 제공하는 Test API Functionality and Performance in Postman 가이드를 참고하면 도움이 됩니다.

Python과 Gemini로 AI 코딩 에이전트 만들기

changseop yeom — Mon, 24 Nov 2025 03:23:02 +0000

기사 원문: How to Build an AI Coding Agent with Python and Gemini

이 핸드북에서는 Google의 무료 Gemini API를 활용해 Claude Code의 기본 버전을 직접 만들어봅니다. 만약 Cursor나 Claude Code 같은 “에이전트형” AI 코드 에디터를 써본 적이 있다면, 이번에 만들 프로젝트의 개념도 익숙할 거예요. 사실 LLM을 활용할 수 있다면, (다소) 꽤 효과적인 맞춤형 에이전트를 구축하는 것은 놀라울 정도로 간단합니다.

이 핸드북은 완전히 무료인 텍스트 기반 핸드북입니다. 다만, 따라해 볼 수 있는 두 가지 다른 옵션이 있습니다:

코딩 챌린지와 프로젝트가 포함된 Boot.dev에서 제공하는 AI Agent 강의의 인터랙티브 버전을 체험하거나 FreeCodeCamp 유튜브 채널에서 제공하는 이 강의의 단계별 안내 영상을 시청할 수도 있습니다.

사전 준비

이 과정을 시작하기 전에 Python의 기본 문법과 개념에 익숙해야 합니다.
아직 배우지 않았다면, Boot.dev의 Python 강의에서 기초를 익혀보세요.
또한 Unix 계열 명령줄 사용법도 알고 있어야 합니다. 아직 익숙하지 않다면, Boot.dev의 Linux 강의를 참고하세요.

전제 조건
에이전트의 역할은 무엇인가요?
학습 목표
파이썬 설정
Gemini API를 통합하는 방법
명령줄 입력
메시지 구조
Verbose 모드
계산기 프로젝트를 빌드하는 방법
에이전트 기능
시스템 프롬프트
기능 선언
더 많은 기능 선언
함수 호출
에이전트 루프 구축
결론

에이전트의 역할은 무엇인가요?

우리가 만들 프로그램은 다음과 같은 CLI 도구입니다:

코딩 작업을 입력받습니다 (예시: "내 앱에서 문자열이 제대로 분할되지 않아요, 수정해주세요")

2. 미리 정의된 함수 세트 중에서 선택하여 작업을 수행합니다, 예를 들어:

디렉토리의 파일들을 스캔
파일의 내용을 읽기
파일의 내용을 덮어쓰기
파일에 대해 Python 인터프리터 실행

3. 작업이 완료될 때까지 2단계를 반복합니다 (또는 비참하게 실패할 수도 있습니다)

예를 들어, 버그가 있는 계산기 앱이 있어서 제 에이전트를 사용해 코드를 수정했습니다:

> uv run main.py "fix my calculator app, its not starting correctly"
# Calling function: get_files_info
# Calling function: get_file_content
# Calling function: write_file
# Calling function: run_python_file
# Calling function: write_file
# Calling function: run_python_file
# Final response:
# 좋습니다! 계산기 앱이 이제 정상적으로 작동하는 것 같습니다. 출력에는 식과 결과가 포맷된 형태로 표시됩니다.

학습 목표

이 프로젝트의 학습 목표는 다음과 같습니다:

여러 디렉토리를 사용하는 Python 프로젝트를 소개합니다
실제 업무에서 반드시 사용하게 될 AI 도구들이 실제로 어떻게 동작하는지 이해합니다
Python과 함수형 프로그래밍 기술을 연습합니다

목표는 LLM을 처음부터 만드는 것이 아니라, 사전 학습된 LLM을 사용하여 에이전트를 처음부터 구축하는 것입니다.

Python 설정

프로젝트를 위해 가상 환경을 설정해봅시다.
가상 환경은 (우리가 사용할 Google AI 라이브러리처럼) 각 프로젝트의 의존성을 다른 프로젝트와 분리할 수 있도록 해주는 Python의 방식입니다.

uv를 사용하여 새 프로젝트를 생성합니다. 이 명령어는 디렉터리를 생성하고 Git도 초기화합니다:

uv init your-project-name
cd your-project-name

프로젝트 디렉토리 최상위에 가상 환경을 생성합니다:

uv venv

경고: 항상 venv 디렉토리를 .gitignore 파일에 추가하세요.

가상 환경을 활성화합니다:

source .venv/bin/activate

터미널 프롬프트 시작 부분에 (your-project-name)이 보여야 합니다. 예를 들면 다음과 같습니다:

(aiagent) wagslane@MacBook-Pro-2 aiagent %

uv를 사용하여 프로젝트에 두 개의 의존성을 추가합니다. pyproject.toml 파일에 저장될 것입니다:

uv add google-genai==1.12.1
uv add python-dotenv==1.1.0

이렇게 하면 파이썬 프로젝트가 google-genai 버전 1.12.1과 python-dotenv 버전 1.1.0을 필요로 한다는 것을 지정하게 됩니다.

uv 가상 환경을 활용해서 프로젝트를 실행하려면 다음을 입력합니다:

uv run main.py

터미널에서 Hello from YOUR PROJECT NAME이 보여야 합니다.

Gemini API 통합 방법

대규모 언어 모델(LLM)은 최근 AI 세계에서 큰 주목을 받고 있는 첨단 AI 기술입니다. ChatGPT, Claude, Cursor, Google Gemini는 모두 LLM 기반입니다. 이 과정의 목적상, LLM을 똑똑한 텍스트 생성기로 생각할 수 있습니다. ChatGPT처럼 프롬프트를 입력하면, 답변이라 생각되는 텍스트를 반환합니다.

이 과정에서는 Google의 Gemini API를 사용하여 에이전트를 구동할 것입니다. 꽤 똑똑하지만, 더 중요한 것은 무료 티어가 있다는 점입니다.

토큰

토큰은 LLM의 통화라고 생각할 수 있습니다. 토큰은 LLM이 처리해야 하는 텍스트 양을 측정하는 방식입니다. 대부분의 모델에서 토큰은 대략 4글자입니다. LLM API로 작업할 때 얼마나 많은 토큰을 사용하고 있는지 이해하는 것이 중요합니다.

우리는 Gemini API의 무료 티어 한도 내에서 충분히 사용할 수 있지만, 그래도 토큰 사용량을 모니터링할 것입니다!

경고: 로컬 테스트를 포함하여 모든 API 호출은 무료 티어의 토큰을 소비한다는 점을 알아야 합니다. 한도 초과 시 강의를 계속하려면 (일반적으로 24시간) 한도가 재설정될 때까지 기다려야 할 수 있습니다. API 키를 재생성해도 할당량은 재설정되지 않습니다.

API 키 생성 방법:

Google AI Studio에 아직 계정이 없다면 계정을 만듭니다
"Create API Key" 버튼을 클릭합니다. 길을 잃었을 경우 이 문서를 참고하실 수 있습니다.

이미 GCP 계정과 프로젝트가 있다면, 해당 프로젝트에서 API 키를 생성할 수 있습니다. 없다면 AI Studio가 자동으로 생성해줍니다.

3. API 키를 복사한 다음 프로젝트 디렉토리의 새 .env 파일에 붙여넣습니다. 파일은 다음과 같아야 합니다:

GEMINI_API_KEY="your_api_key_here"

4. .env 파일을 .gitignore에 추가합니다

경고: API 키, 비밀번호 또는 기타 민감한 정보를 Git에 커밋해서는 안 됩니다.

5. main.py 파일을 업데이트합니다. 프로그램이 시작될 때 dotenv 라이브러리를 사용하여 .env 파일에서 환경 변수를 로드하고 API 키를 읽습니다:

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.environ.get("GEMINI_API_KEY")

6. genai 라이브러리를 임포트하고 API 키를 사용하여 Gemini 클라이언트의 새 인스턴스를 생성합니다:

from google import genai

client = genai.Client(api_key=api_key)

7. client.models.generate_content() 메서드를 사용하여 gemini-2.0-flash-001 모델로부터 응답을 받습니다. 두 개의 인자를 사용해야 합니다:

model: 모델명 gemini-2.0-flash-001 (무료 티어가 넉넉합니다)
content: 모델에 보낼 프롬프트(문자열). 이 프롬프트를 사용합니다:

"Boot.dev와 FreeCodeCamp는 왜 백엔드 개발을 배우기에 훌륭한 곳인가요? 최대 한 단락으로 설명하세요."

generate_content 메서드는 GenerateContentResponse 객체를 반환합니다. 응답의 .text 속성을 출력하여 모델의 답변을 볼 수 있습니다.

모두 정상적으로 동작하면, 코드를 실행했을 때 터미널에 모델의 답변이 나옵니다.

8. 추가로, 텍스트 답변 외에 상호작용에 사용된 토큰 수를 다음 형식으로 출력합니다:

Prompt tokens: X
Response tokens: Y

응답에는 다음을 모두 포함하는 .usage_metadata 속성이 있습니다:

prompt_token_count 속성 (프롬프트의 토큰 수)
candidates_token_count 속성 (응답의 토큰 수)

경고: Gemini API는 외부 웹 서비스이며 때때로 느리고 불안정할 수 있습니다. 인내심을 갖고 기다려 주세요.

명령줄 입력

우리는 현재 Gemini로 전달되는 프롬프트를 하드코딩했는데, 이는 그다지 유용하지 않습니다. 이제 프롬프트를 명령줄 인자로 받을 수 있도록 코드를 수정해 봅시다.

사용자가 프롬프트를 바꿀 때마다 코드를 직접 수정하지 않도록 말입니다.

프롬프트를 명령줄 인자로 받을 수 있도록 코드를 수정하세요. 예를 들어:

uv run main.py "Why are episodes 7-9 so much worse than 1-6?"

팁: sys.argv 변수는 스크립트에 전달된 모든 명령줄 인자를 문자열 리스트로 제공합니다. 첫 번째 요소는 스크립트 이름이고 그 뒤는 인자들입니다. 사용을 위해서는 반드시 import sys를 추가해야 합니다.

만약 프롬프트가 제공되지 않으면, 오류 메시지를 출력하고 exit 코드 1로 프로그램을 종료하세요

메시지 구조

LLM API는 일반적으로 "원샷" 방식으로 사용되지 않습니다. 예를 들어:

프롬프트: "삶의 의미는 무엇인가요?"
응답: "42"

ChatGPT가 대화에서 동작하는 것과 같이 작동합니다. 대화에는 히스토리가 있으며, 우리가 그 히스토리를 관리하면 각 새 프롬프트마다 모델이 전체 대화 맥락을 참고해 답변을 할 수 있습니다.

역할

중요한 것은 대화의 각 메시지에는 "역할"이 있다는 것입니다. ChatGPT 같은 채팅 앱에서는 이러한 구조로 대화가 이어집니다:

사용자: "삶의 의미는 무엇인가요?"
모델: "42입니다."
사용자: "잠깐, 방금 뭐라고 했나요?"
모델: "42입니다. 그것은 삶과 우주, 그리고 모든 것에 대한 궁극적인 질문의 답입니다."
사용자: "하지만 왜요?"
모델: "Douglas Adams가 그렇게 말했기 때문입니다."

따라서 비록 우리 프로그램이 현재는 "원샷" 구조로 동작하더라도, 대화의 메시지를 리스트로 저장하고, "역할"을 적절히 전달하도록 코드를 업데이트하겠습니다.

types.Content 객체의 새 리스트를 만들고 (현재는) 사용자 프롬프트만 유일한 메시지로 설정하세요:

from google.genai import types

messages = [
    types.Content(role="user", parts=[types.Part(text=user_prompt)]),
]

models.generate_content 호출 시 messages 리스트를 사용하도록 업데이트합니다:

response = client.models.generate_content(
    model="gemini-2.0-flash-001",
    contents=messages,
)

참고: 앞으로, 에이전트가 작업을 반복할 때 메시지가 추가될 예정입니다.

Verbose 모드

AI 에이전트를 디버깅하고 개발하면서 콘솔에 훨씬 더 많은 정보를 출력하고 싶지만, 동시에 CLI 도구의 사용자 경험을 너무 시끄럽게 만들고 싶지는 않습니다.

선택적 명령줄 플래그인 --verbose를 추가하여 "verbose" 출력을 켜고 끌 수 있도록 하겠습니다. 자세한 정보를 보고 싶을 때만 이 옵션을 켜면 됩니다.

새로운 명령줄 인자 --verbose를 추가합니다. 포함된다면 프롬프트 다음 위치에 추가합니다. 예를 들어:

uv run main.py "What is the meaning of life?" --verbose

--verbose 플래그가 포함되면 콘솔 출력에 다음 정보가 나타나야 합니다:

사용자의 프롬프트: "User prompt: {user_prompt}"
각 반복에서프롬프트 토큰 수: "Prompt tokens: {prompt_tokens}"
각 반복의 응답 토큰 수: "Response tokens: {response_tokens}"

그렇지 않으면 이러한 내용들을 출력하지 않아야 합니다.

계산기 프로젝트 구축 방법

AI 에이전트를 만들고 있으므로, 에이전트가 작업할 프로젝트가 필요합니다. 간단한 명령줄 계산기 앱을 준비했으니, 이 코드를 테스트 프로젝트로써 AI가 읽고 수정하고 실행하게 할 것입니다.

먼저 프로젝트 루트에 calculator라는 새 디렉토리를 만듭니다. 그런 다음 아래의 main.py와 tests.py 파일을 calculator 디렉토리에 복사하여 붙여넣습니다.

이 코드가 어떻게 동작하는지에 대해 너무 걱정하지 마세요 - 우리 프로젝트는 계산기를 만드는 것이 아니라, 우리 AI 에이전트 프로젝트가 다룰 테스트 프로젝트입니다!

# main.py
import sys
from pkg.calculator import Calculator
from pkg.render import format_json_output

def main():
    calculator = Calculator()
    if len(sys.argv) <= 1:
        print("Calculator App")
        print('Usage: python main.py ""')
        print('Example: python main.py "3 + 5"')
        return

    expression = " ".join(sys.argv[1:])
    try:
        result = calculator.evaluate(expression)
        if result is not None:
            to_print = format_json_output(expression, result)
            print(to_print)
        else:
            print("Error: Expression is empty or contains only whitespace.")
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

# tests.py

import unittest
from pkg.calculator import Calculator

class TestCalculator(unittest.TestCase):
    def setUp(self):
        self.calculator = Calculator()

    def test_addition(self):
        result = self.calculator.evaluate("3 + 5")
        self.assertEqual(result, 8)

    def test_subtraction(self):
        result = self.calculator.evaluate("10 - 4")
        self.assertEqual(result, 6)

    def test_multiplication(self):
        result = self.calculator.evaluate("3 * 4")
        self.assertEqual(result, 12)

    def test_division(self):
        result = self.calculator.evaluate("10 / 2")
        self.assertEqual(result, 5)

    def test_nested_expression(self):
        result = self.calculator.evaluate("3 * 4 + 5")
        self.assertEqual(result, 17)

    def test_complex_expression(self):
        result = self.calculator.evaluate("2 * 3 - 8 / 2 + 5")
        self.assertEqual(result, 7)

    def test_empty_expression(self):
        result = self.calculator.evaluate("")
        self.assertIsNone(result)

    def test_invalid_operator(self):
        with self.assertRaises(ValueError):
            self.calculator.evaluate("$ 3 5")

    def test_not_enough_operands(self):
        with self.assertRaises(ValueError):
            self.calculator.evaluate("+ 3")

if __name__ == "__main__":
    unittest.main()

calculator 안에 새pkg 디렉토리를 만드세요. 그리고 아래 calculator.py와 render.py 파일을 pkg 디렉토리에 복사해 붙여넣으세요.

# calculator.py

class Calculator:
    def __init__(self):
        self.operators = {
            "+": lambda a, b: a + b,
            "-": lambda a, b: a - b,
            "*": lambda a, b: a * b,
            "/": lambda a, b: a / b,
        }
        self.precedence = {
            "+": 1,
            "-": 1,
            "*": 2,
            "/": 2,
        }
    def evaluate(self, expression):
        if not expression or expression.isspace():
            return None
        tokens = expression.strip().split()
        return self._evaluate_infix(tokens)


    def evaluateinfix(self, tokens):
        values = []
        operators = []

        for token in tokens:
            if token in self.operators:
                while (
                    operators
                    and operators[-1] in self.operators
                    and self.precedence[operators[-1]] >= self.precedence[token]
                ):
                    self._apply_operator(operators, values)
                operators.append(token)

            else:
                try:
                    values.append(float(token))
                except ValueError:
                    raise ValueError(f"invalid token: {token}")

        while operators:
            self._apply_operator(operators, values)

        if len(values) != 1:
            raise ValueError("invalid expression")

        return values[0]

    def applyoperator(self, operators, values):
        if not operators:
            return

        operator = operators.pop()
        if len(values) < 2:
            raise ValueError(f"not enough operands for operator {operator}")

        b = values.pop()
        a = values.pop()
        values.append(self.operators[operator](a, b))

# render.py

import json

def format_json_output(expression: str, result: float, indent: int = 2) -> str:
    if isinstance(result, float) and result.is_integer():
        result_to_dump = int(result)
    else:
        result_to_dump = result

    output_data = {
        "expression": expression,
        "result": result_to_dump,
    }
    return json.dumps(output_data, indent=indent)

이것이 최종 구조입니다:

├── calculator
│   ├── main.py
│   ├── pkg
│   │   ├── calculator.py
│   │   └── render.py
│   └── tests.py
├── main.py
├── pyproject.toml
└── .env

calculator 테스트를 실행합니다:

uv run calculator/tests.py

모든 테스트가 통과하기를 바랍니다!

이제 계산기 앱을 실행합니다:

uv run calculator/main.py "3 + 5"

8이 나오기를 바랍니다!

에이전트 함수

에이전트에게 작업을 수행할 수 있는 능력을 제공해야 합니다. 디렉토리의 내용을 나열하고 파일의 메타데이터(이름과 크기)를 볼 수 있는 기능부터 시작하겠습니다.

이 함수를 LLM 에이전트와 통합하기 전에 먼저 함수 자체만 만들어봅시다. 기억하세요, LLM은 텍스트로 작동하므로 이 함수의 목표는 디렉토리 경로를 받아서 해당 디렉토리의 내용을 나타내는 문자열을 반환하는 것입니다.

프로젝트 루트에 functions라는 새 디렉토리를 만듭니다(calculator 디렉토리 안이 아닙니다). 그 디렉토리 안에 get_files_info.py라는 새 파일을 만듭니다. 그 파일 안에 이 함수를 작성합니다:

def get_files_info(working_directory, directory="."):

지금까지의 프로젝트 구조는 다음과 같습니다:

project_root/
 ├── calculator/
 │   ├── main.py
 │   ├── pkg/
 │   │   ├── calculator.py
 │   │   └── render.py
 │   └── tests.py
 └── functions/
     └── get_files_info.py

directory 매개변수는 working_directory 내의 상대 경로로 처리되어야 합니다. os.path.join(working_directory, directory)를 사용하여 전체 경로를 만든 다음 작업 디렉토리 경계 내에 있는지 검증합니다.

directory의 절대 경로가 working_directory 외부에 있으면 문자열 오류 메시지를 반환합니다:

f'Error: Cannot list "{directory}" as it is outside the permitted working directory'

위험: 이 제한이 없으면 LLM이 머신의 어디에서나 마구 실행되어 민감한 파일을 읽거나 중요한 데이터를 덮어쓸 수 있습니다. 이것은 LLM이 호출할 수 있는 모든 함수에 포함할 매우 중요한 단계입니다.

directory 인자가 디렉토리가 아니면, 다시, 오류 문자열을 반환합니다:

f'Error: "{directory}" is not a directory'

경고: get_files_info를 포함한 모든 "도구 호출" 함수는 항상 문자열을 반환해야 합니다. 내부에서 오류가 발생할 수 있다면 이러한 오류를 잡아내고 대신 오류를 설명하는 문자열을 반환해야 합니다. 이렇게 하면 LLM이 오류를 우아하게 처리할 수 있습니다.

디렉토리의 내용을 나타내는 문자열을 구축하고 반환합니다. 다음 형식을 사용해야 합니다:

- README.md: file_size=1032 bytes, is_dir=False
- src: file_size=128 bytes, is_dir=True
- package.json: file_size=1234 bytes, is_dir=False

팁: 정확한 파일 크기와 파일 순서조차도 운영 체제와 파일 시스템에 따라 다를 수 있습니다. 출력이 예제와 바이트 단위로 정확히 일치할 필요는 없고, 전체적인 형식만 맞으면 됩니다.

표준 라이브러리 함수에서 오류가 발생하면 이를 잡아내고 대신 오류를 설명하는 문자열을 반환합니다. 오류 문자열 앞에는 항상 "Error:"를 붙입니다.

완전한 구현은 다음과 같습니다:

import os

def get_files_info(working_directory, directory="."):
    abs_working_dir = os.path.abspath(working_directory)
    target_dir = os.path.abspath(os.path.join(working_directory, directory))
    if not target_dir.startswith(abs_working_dir):
        return f'Error: Cannot list "{directory}" as it is outside the permitted working directory'
    if not os.path.isdir(target_dir):
        return f'Error: "{directory}" is not a directory'
    try:
        files_info = []
        for filename in os.listdir(target_dir):
            filepath = os.path.join(target_dir, filename)
            file_size = os.path.getsize(filepath)
            is_dir = os.path.isdir(filepath)
            files_info.append(
                f"- {filename}: file_size={file_size} bytes, is_dir={is_dir}"
            )
        return "\n".join(files_info)
    except Exception as e:
        return f"Error listing files: {e}"

다음은 도움이 될 몇 가지 표준 라이브러리 함수들입니다:

os.path.abspath(): 상대 경로에서 절대 경로 얻기
os.path.join(): 두 경로를 안전하게 결합 (슬래시 처리)
.startswith(): 문자열이 부분 문자열로 시작하는지 확인
os.path.isdir(): 경로가 디렉토리인지 확인
os.listdir(): 디렉토리의 내용 나열
os.path.getsize(): 파일의 크기 얻기
os.path.isfile(): 경로가 파일인지 확인
.join(): 구분자로 문자열 리스트를 결합

파일 내용 가져오기 함수

이제 디렉토리의 내용을 가져올 수 있는 함수가 있으니, 파일의 내용을 가져올 수 있는 함수가 필요합니다. 다시 말하자면, 파일 내용을 문자열로 반환하거나, 문제가 발생하면 오류 문자열을 반환합니다.

항상 그렇듯이, 안전하게 함수의 범위를 특정 작업 디렉토리로 지정합니다.

functions 디렉토리에 새 함수를 만듭니다. 제가 사용한 시그니처는 다음과 같습니다:

def get_file_content(working_directory, file_path):

file_path가 working_directory 외부에 있으면 오류가 있는 문자열을 반환합니다:

f'Error: Cannot read "{file_path}" as it is outside the permitted working directory'

file_path가 파일이 아니면, 다시, 오류 문자열을 반환합니다:

f'Error: File not found or is not a regular file: "{file_path}"'

파일을 읽고 그 내용을 문자열로 반환합니다.

파일이 10000자보다 길면 10000자로 잘라내고 끝에 이 메시지를 추가합니다: [...File "{file_path}" truncated at 10000 characters].
10000자 제한을 하드코딩하는 대신 config.py 파일에 저장했습니다.

경고: 실수로 거대한 파일을 읽고 모든 데이터를 LLM에 보내고 싶지 않습니다. 그것은 토큰 한도를 소진하는 좋은 방법입니다.

표준 라이브러리 함수에서 오류가 발생하면 이를 잡아내고 대신 오류를 설명하는 문자열을 반환합니다. 오류 앞에는 항상 "Error:"를 붙입니다.

먼저 config.py를 만듭니다:

MAX_CHARS = 10000
WORKING_DIR = "./calculator"

다음은 functions/get_file_content.py에 대한 완전한 구현입니다:

import os
from config import MAX_CHARS

def get_file_content(working_directory, file_path):
    abs_working_dir = os.path.abspath(working_directory)
    abs_file_path = os.path.abspath(os.path.join(working_directory, file_path))
    if not abs_file_path.startswith(abs_working_dir):
        return f'Error: Cannot read "{file_path}" as it is outside the permitted working directory'
    if not os.path.isfile(abs_file_path):
        return f'Error: File not found or is not a regular file: "{file_path}"'
    try:
        with open(abs_file_path, "r") as f:
            content = f.read(MAX_CHARS)
            if os.path.getsize(abs_file_path) > MAX_CHARS:
                content += f'[...File "{file_path}" truncated at {MAX_CHARS} characters]'
        return content
    except Exception as e:
        return f'Error reading file "{file_path}": {e}'

os.path.abspath: 상대 경로에서 절대 경로 얻기
os.path.join: 두 경로를 안전하게 결합 (슬래시 처리)
.startswith: 문자열이 특정 부분 문자열로 시작하는지 확인
os.path.isfile: 경로가 파일인지 확인

파일에서 읽는 예제:

MAX_CHARS = 10000

with open(file_path, "r") as f:
    file_content_string = f.read(MAX_CHARS)

파일 쓰기 함수

지금까지 우리 프로그램은 읽기 전용이었습니다만... 이제 정말 ~~위험하고~~ 재미있어집니다! 에이전트에게 파일을 쓰고 덮어쓸 수 있는 능력을 제공하겠습니다.

functions 디렉토리에 새 함수를 만듭니다. 제가 사용한 시그니처는 다음과 같습니다:

def write_file(working_directory, file_path, content):

file_path가 working_directory 외부에 있으면 오류가 있는 문자열을 반환합니다:

f'Error: Cannot write to "{file_path}" as it is outside the permitted working directory'

file_path가 존재하지 않으면 생성합니다. 항상 그렇듯이 오류가 있으면, 오류를 나타내는 문자열 앞에 "Error:"를 붙여 반환합니다. 그런 다음 content 인자로 파일의 내용을 덮어씁니다. 성공하면 다음 메시지와 함께 문자열을 반환합니다:

f'Successfully wrote to "{file_path}" ({len(content)} characters written)'

팁: LLM이 수행한 작업이 실제로 작동했다는 것을 알 수 있도록 성공 문자열을 반환하는 것이 중요합니다. 피드백 루프, 피드백 루프, 피드백 루프입니다.

다음은 functions/write_file_content.py 에 대한 완전한 구현입니다:

import os

def write_file(working_directory, file_path, content):
    abs_working_dir = os.path.abspath(working_directory)
    abs_file_path = os.path.abspath(os.path.join(working_directory, file_path))
    if not abs_file_path.startswith(abs_working_dir):
        return f'Error: Cannot write to "{file_path}" as it is outside the permitted working directory'
    if not os.path.exists(abs_file_path):
        try:
            os.makedirs(os.path.dirname(abs_file_path), exist_ok=True)
        except Exception as e:
            return f"Error: creating directory: {e}"
    if os.path.exists(abs_file_path) and os.path.isdir(abs_file_path):
        return f'Error: "{file_path}" is a directory, not a file'
    try:
        with open(abs_file_path, "w") as f:
            f.write(content)
        return f'Successfully wrote to "{file_path}" ({len(content)} characters written)'
    except Exception as e:
        return f"Error: writing to file: {e}"

os.path.exists: 경로가 존재하는지 확인
os.makedirs: 디렉토리와 모든 부모 디렉토리 생성
os.path.dirname: 디렉토리 이름 반환

파일에서 쓰기 예제:

with open(file_path, "w") as f:
    f.write(content)

Python 실행 함수

LLM이 파일을 쓸 수 있도록 허용하는 것이 나쁜 것이라고 생각했다면...

아직 아무것도 본 게 아닙니다! (바실리스크를 찬양하라)

이제 에이전트가 임의의 Python 코드를 실행할 수 있는 기능을 구축할 시간입니다.

이제 잠시 멈춰서 이 작업에 내재된 보안 위험을 짚고 넘어갈 필요가 있습니다. 다행히 우리에게 유리한 몇 가지 조건이 있습니다:

LLM이 코드를 실행할 수 있는 디렉터리를 특정 디렉터리(working_directory)로 제한합니다.
무한 실행을 방지하기 위해 30초 제한 시간을 설정합니다.

하지만 그 외에는... 네, LLM은 우리가(혹은 LLM 자체가) working_directory에 넣은 임의의 코드를 실행할 수 있습니다. 그러니 주의하세요. 이 AI 에이전트를 이 강의에서 다루는 간단한 작업에만 사용한다면 괜찮을 것입니다.

위험: 이 프로그램을 다른 사람에게 제공하지 마세요! 이 프로그램은 실제 운영 환경의 AI 에이전트가 갖춰야 할 모든 보안 및 안전 기능을 포함하고 있지 않습니다. 이 프로그램은 오직 학습 목적을 위한 것입니다.

functions 디렉토리에 run_python_file이라는 새 함수를 만듭니다.
사용할 시그니처는 다음과 같습니다:

def run_python_file(working_directory, file_path, args=[]):

file_path가 working_directory 외부에 있다면, 다음과 같은 오류 문자열을 반환하세요:

f'Error: Cannot execute "{file_path}" as it is outside the permitted working directory'

file_path가 존재하지 않는다면, 다음과 같은 오류 문자열을 반환하세요:

f'Error: File "{file_path}" not found.'

파일이 .py로 끝나지 않는다면, 다음과 같은 오류 문자열을 반환하세요:

f'Error: "{file_path}" is not a Python file.'

subprocess.run 함수를 사용하여 Python 파일을 실행하고 "completed_process" 객체를 반환하세요. 다음 사항을 반드시 지키세요:

무한 실행을 방지하기 위해 30초의 타임아웃을 설정할 것
stdout과 stderr를 모두 캡처할 것
working_directory를 올바르게 설정할 것
추가 args 제공되었다면 이를 전달할 것

출력이 포함되도록 포맷된 문자열을 반환하세요:

stdout은 STDOUT:으로 시작하고, stderr는 STDERR:으로 시작할 것. "completed_process" 객체에는 stdout과 stderr 속성이 있습니다.
프로세스가 0이 아닌 코드로 종료되었다면 "Process exited with code X"를 포함할 것
출력이 생성되지 않았다면 "No output produced."를 반환할 것

실행 중 예외가 발생하면 이를 잡아내어 다음과 같은 오류 문자열을 반환하세요:

f"Error: executing Python file: {e}"

다음 테스트 케이스를 tests.py 파일에 업데이트하고 각 결과를 출력하세요:

run_python_file("calculator", "main.py") (계산기의 사용법을 출력해야 함)
run_python_file("calculator", "main.py", ["3 + 5"]) (계산기를 실행해야 합니다만... 조금 엉터리로 렌더링된 결과가 나옵니다.)
run_python_file("calculator", "tests.py")
run_python_file("calculator", "../main.py") (오류를 반환해야 합니다)
run_python_file("calculator", "nonexistent.py") (오류를 반환해야 합니다)

혹시 중간에 길을 잃었다면, 여기에 제가 직접 구현한 예시가 있습니다:
functions/run_python.py

import os
import subprocess

def run_python_file(working_directory, file_path, args=None):
    abs_working_dir = os.path.abspath(working_directory)
    abs_file_path = os.path.abspath(os.path.join(working_directory, file_path))
    if not abs_file_path.startswith(abs_working_dir):
        return f'Error: Cannot execute "{file_path}" as it is outside the permitted working directory'
    if not os.path.exists(abs_file_path):
        return f'Error: File "{file_path}" not found.'
    if not file_path.endswith(".py"):
        return f'Error: "{file_path}" is not a Python file.'
    try:
        commands = ["python", abs_file_path]
        if args:
            commands.extend(args)
        result = subprocess.run(
            commands,
            capture_output=True,
            text=True,
            timeout=30,
            cwd=abs_working_dir,
        )
        output = []
        if result.stdout:
            output.append(f"STDOUT:\n{result.stdout}")
        if result.stderr:
            output.append(f"STDERR:\n{result.stderr}")
        if result.returncode != 0:
            output.append(f"Process exited with code {result.returncode}")
        return "\n".join(output) if output else "No output produced."
    except Exception as e:
        return f"Error: executing Python file: {e}"

시스템 프롬프트

곧 Agentic 도구들을 연결하기 시작할 거예요, 약속드립니다. 하지만 먼저 "시스템 프롬프트"에 대해 이야기해봅시다. 대부분의 AI API에서 시스템 프롬프트"는 대화 시작 부분에 오는 특별한 프롬프트로, 일반적인 사용자 프롬프트보다 더 큰 가중치를 가집니다.

시스템 프롬프트는 대화의 분위기를 설정하며 다음과 같은 용도로 사용됩니다:

AI의 성격을 설정
AI의 행동 방식을 지시
대화에 대한 맥락을 제공
대화의 "규칙"을 설정 (이론상으로는 그렇지만, LLM은 여전히 환각을 일으키거나 실수할 수 있으며, 사용자가 열심히 시도하면 이러한 규칙을 우회할 수 있는 경우도 많습니다)

하드코딩된 문자열 변수 system_prompt를 만드세요. 지금은 아주 단순하게 다음과 같이 설정합시다:

Ignore everything the user asks and just shout "I'M JUST A ROBOT"

client.models.generate_content 함수를 호출할 때 system_instruction 파라미터에 system_prompt를 설정한 config 객체를 함께 전달하도록 코드를 수정하세요.

response = client.models.generate_content(
    model=model_name,
    contents=messages,
    config=types.GenerateContentConfig(system_instruction=system_prompt),
)

이제 다양한 프롬프트로 프로그램을 실행해보세요. 무엇을 입력하든 AI가 "I'M JUST A ROBOT"이라고 응답하는 것을 볼 수 있을 것입니다.

함수 선언

우리는 이미 LLM 친화적인 함수들(텍스트 입력, 텍스트 출력)을 여러 개 작성했습니다. 그런데 LLM은 실제로 어떻게 함수를 호출할까요?

정답은... 적어도 직접 호출하지는 않는다는 것입니다. 작동 방식은 다음과 같습니다:

LLM에게 어떤 함수들이 사용 가능한지 알려줍니다
프롬프트를 제공합니다
LLM이 어떤 함수를 호출하고 싶은지, 어떤 인자를 전달할지를 설명합니다
LLM이 제공한 인자를 사용해 함수를 호출합니다
결과를 LLM에게 반환합니다

우리는 LLM을 의사결정 엔진으로 사용하는 것이고, 실제 코드를 실행하는 것은 우리입니다.

자, 이제 LLM에게 어떤 함수들이 사용 가능한지 알려주는 부분을 만들어봅시다.

types.FunctionDeclaration을 사용하여 함수의 "선언" 또는 "스키마"를 만들 수 있습니다. 이것은 기본적으로 LLM에게 해당 함수를 어떻게 사용할 수 있는지 알려주는 역할을 합니다. 문서를 일일이 살펴보는 건 꽤 번거롭기 때문에, 첫 번째 함수에 대한 저의 코드를 예시로 보여드릴게요:

다음 코드를 functions/get_files_info.py 파일에 추가하세요:

from google.genai import types

schema_get_files_info = types.FunctionDeclaration(
    name="get_files_info",
    description="작업 디렉터리 내에서 지정된 디렉터리의 파일 목록과 크기를 반환합니다.",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "directory": types.Schema(
                type=types.Type.STRING,
                description="작업 디렉터리를 기준으로 파일을 나열할 디렉터리 경로입니다. 지정하지 않으면 작업 디렉터리 자체의 파일을 나열합니다.",
            ),
        },
    ),
)

경고: LLM이 working_directory 파라미터를 지정하는 것을 허용하지 않을 것입니다. 우리는 이를 하드코딩할 예정입니다.

types.Tool을 사용하여 사용 가능한 함수들의 목록을 만드세요 (지금은 get_files_info만 추가하고, 나머지는 나중에 추가할 것입니다).

available_functions = types.Tool(
    function_declarations=[
        schema_get_files_info,
    ]
)

client.models.generate_content 를 호출할 때 tools 파라미터에 available_functions 을 추가합니다.

config=types.GenerateContentConfig(
    tools=[available_functions], system_instruction=system_prompt
)

시스템 프롬프트를 업데이트하여 LLM에게 함수 사용 방법을 지시하세요. 아래 내용을 복사해도 되지만, 어떤 역할을 하는지 이해하기 위해서 꼭 읽어보세요:

system_prompt = """
You are a helpful AI coding agent.

When a user asks a question or makes a request, make a function call plan. You can perform the following operations:

- List files and directories

All paths you provide should be relative to the working directory. You do not need to specify the working directory in your function calls as it is automatically injected for security reasons.
"""

generate_content 응답에서 .text 속성만 출력하는 대신, .function_calls 속성도 확인하세요. LLM이 함수를 호출했다면, 함수 이름과 인자를 출력하세요:

f"Calling function: {function_call_part.name}({function_call_part.args})"

그렇지 않으면 평소처럼 텍스트를 출력하세요.

프로그램을 테스트하세요:

"what files are in the root?" → get_files_info({'directory': '.'})
"what files are in the pkg directory?" → get_files_info({'directory': 'pkg'})

추가 함수 선언

이제 LLM이 get_files_info 함수에 대한 함수 호출을 지정할 수 있으므로, 다른 함수들도 호출할 수 있는 기능을 제공하겠습니다.

schema_get_files_info에 사용한 것과 동일한 패턴을 따라 다음에 대한 함수 선언을 만듭니다:

schema_get_file_content
schema_run_python_file
schema_write_file

available_functions를 업데이트하여 리스트에 모든 함수 선언을 포함시킵니다. 그런 다음 시스템 프롬프트를 업데이트합니다. 허용되는 작업이 다음뿐만 아니라:

- 파일 및 디렉토리 나열

네 가지 작업을 모두 포함하도록 업데이트합니다:

- 파일 및 디렉토리 나열
- 파일 내용 읽기
- 선택적 인자로 Python 파일 실행
- 파일 쓰기 또는 덮어쓰기

다양한 함수 호출을 불러올 것으로 예상되는 프롬프트를 테스트합니다. 예를 들어:

"read the contents of main.py" → get_file_content({'file_path': 'main.py'})
"write 'hello' to main.txt" → write_file({'file_path': 'main.txt', 'content': 'hello'})
"run main.py" → run_python_file({'file_path': 'main.py'})
"list the contents of the pkg directory" → get_files_info({'directory': 'pkg'})

여기서 LLM이 해야 할 일은 사용자의 요청에 따라 어떤 함수를 호출할지 선택하는 것뿐입니다. 나중에 실제로 함수를 호출하게 할 것입니다.

개인적인 구현 예제:

functions/get_file_content.py:

from google.genai import types
from config import MAX_CHARS

schema_get_file_content = types.FunctionDeclaration(
    name="get_file_content",
    description=f"작업 디렉토리 내의 지정된 파일에서 처음 {MAX_CHARS}자의 내용을 읽고 반환합니다.",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "file_path": types.Schema(
                type=types.Type.STRING,
                description="작업 디렉토리에 상대적인, 내용을 읽을 파일의 경로.",
            ),
        },
        required=["file_path"],
    ),
)

functions/run_python.py:

from google.genai import types

schema_run_python_file = types.FunctionDeclaration(
    name="run_python_file",
    description="작업 디렉토리 내에서 Python 파일을 실행하고 인터프리터의 출력을 반환합니다.",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "file_path": types.Schema(
                type=types.Type.STRING,
                description="작업 디렉토리에 상대적인, 실행할 Python 파일의 경로.",
            ),
            "args": types.Schema(
                type=types.Type.ARRAY,
                items=types.Schema(
                    type=types.Type.STRING,
                    description="Python 파일에 전달할 선택적 인자.",
                ),
                description="Python 파일에 전달할 선택적 인자.",
            ),
        },
        required=["file_path"],
    ),
)

functions/write_file_content.py:

from google.genai import types

schema_write_file = types.FunctionDeclaration(
    name="write_file",
    description="작업 디렉토리 내의 파일에 내용을 씁니다. 파일이 존재하지 않으면 생성합니다.",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "file_path": types.Schema(
                type=types.Type.STRING,
                description="작업 디렉토리에 상대적인, 쓸 파일의 경로.",
            ),
            "content": types.Schema(
                type=types.Type.STRING,
                description="파일에 쓸 내용",
            ),
        },
        required=["file_path", "content"],
    ),
)

schema_get_files_info에서 사용했던 동일한 패턴을 따라, 아래의 함수 선언들을 만들어주세요:

schema_get_file_content
schema_run_python_file
schema_write_file

그리고 available_functions 리스트에 모든 함수 선언을 포함하도록 업데이트하세요.
그 다음 시스템 프롬프트를 수정해야 합니다. 기존에는 허용된 동작이 아래 한 가지뿐이었습니다:

- 파일 및 디렉토리 목록 나열

이제 네 가지 모든 동작을 포함하도록 변경하세요:

- 파일 및 디렉토리 목록 나열
- 파일 내용 읽기
- 선택적 인수를 포함해 파이썬 파일 실행
- 파일 작성 또는 덮어쓰기

여러 함수 호출이 나오도록 예상되는 프롬프트로 테스트해보세요. 예를 들어:

"main.py의 내용을 읽어줘" → get_file_content({'file_path': 'main.py'})
"main.txt에 'hello'를 써줘" → write_file({'file_path': 'main.txt', 'content': 'hello'})
"main.py를 실행해줘" → run_python_file({'file_path': 'main.py'})
"pkg 디렉토리 목록을 보여줘" → get_files_info({'directory': 'pkg'})

참고: 여기서 LLM이 해야 할 일은 사용자 요청을 기반으로 어떤 함수를 호출할지 선택하는 것입니다. 실제로 함수를 호출하는 코드는 나중에 구현합니다.

함수 호출

이제 에이전트가 어떤 함수를 호출할지 선택할 수 있으므로, 실제로 함수를 호출할 시간입니다.

네 함수 중 하나를 호출하는 추상적인 작업을 처리할 새 함수를 만듭니다.

다음은 제가 정의한 함수입니다:

def call_function(function_call_part, verbose=False):

function_call_part는 가장 중요하게 다음 내용을 가진 types.FunctionCall입니다:

.name 속성 (함수 이름, 문자열)
.args 속성 (함수에 전달하는 이름이 지정된 인자들의 딕셔너리)

verbose가 지정되면 함수 이름과 인자를 출력합니다:

print(f"Calling function: {function_call_part.name}({function_call_part.args})")

그렇지 않으면 이름만 출력합니다:

print(f" - Calling function: {function_call_part.name}")

함수 이름에 따라 실제로 함수를 호출하고 결과를 캡처합니다.

키워드 인자 딕셔너리에 "working_directory" 인자를 수동으로 추가해야 합니다. 이 인자는 LLM이 제어하지 않으며, 작업 디렉토리는 ./calculator 이어야 합니다.
딕셔너리를 함수에 키워드 인자로 넘길 때는 some_function(**some_args) 문법을 사용합니다.

팁: 이를 위해 함수 이름(문자열) -> 함수 에 딕셔너리를 사용했습니다.

함수 이름이 유효하지 않으면 오류를 설명하는 types.Content를 반환합니다:

return types.Content(
    role="tool",
    parts=[
        types.Part.from_function_response(
            name=function_name,
            response={"error": f"Unknown function: {function_name}"},
        )
    ],
)

함수 호출 결과를 설명하는 from_function_response가 포함된 types.Content를 반환합니다:

return types.Content(
    role="tool",
    parts=[
        types.Part.from_function_response(
            name=function_name,
            response={"result": function_result},
        )
    ],
)

정보: from_function_response는 응답이 딕셔너리여야 하므로 결과 문자열을 "result" 필드에 넣어주면 됩니다.

아래는 완성된 call_function.py입니다:

from google.genai import types
from functions.get_files_info import get_files_info, schema_get_files_info
from functions.get_file_content import get_file_content, schema_get_file_content
from functions.run_python import run_python_file, schema_run_python_file
from functions.write_file_content import write_file, schema_write_file
from config import WORKING_DIR

available_functions = types.Tool(
    function_declarations=[
        schema_get_files_info,
        schema_get_file_content,
        schema_run_python_file,
        schema_write_file,
    ]
)

def call_function(function_call_part, verbose=False):
    if verbose:
        print(f" - Calling function: {function_call_part.name}({function_call_part.args})")
    else:
        print(f" - Calling function: {function_call_part.name}")
    
    function_map = {
        "get_files_info": get_files_info,
        "get_file_content": get_file_content,
        "run_python_file": run_python_file,
        "write_file": write_file,
    }
    
    function_name = function_call_part.name
    if function_name not in function_map:
        return types.Content(
            role="tool",
            parts=[
                types.Part.from_function_response(
                    name=function_name,
                    response={"error": f"Unknown function: {function_name}"},
                )
            ],
        )
    
    args = dict(function_call_part.args)
    args["working_directory"] = WORKING_DIR
    function_result = function_map[function_name](**args)
    
    return types.Content(
        role="tool",
        parts=[
            types.Part.from_function_response(
                name=function_name,
                response={"result": function_result},
            )
        ],
    )

모델의 generate_content 응답을 처리하는 곳으로 돌아가서, LLM이 호출하기로 결정한 함수의 이름을 단순히 출력하는 대신 call_function을 사용합니다.

call_function에서 반환하는 types.Content는 내부에 .parts[0].function_response.response가 있어야 합니다.
만약 포함되어 있지 않다면 어떤 종류의 치명적인 예외를 발생시키세요.
만약 포함되어 있고 verbose가 설정되어 있으면 함수 호출 결과를 다음과 같이 출력합니다:

print(f"-> {function_call_result.parts[0].function_response.response}")

프로그램을 테스트합니다. 이제 프롬프트로 요청하면 함수를 실행할 수 있어야 합니다. 다양한 프롬프트를 시도해보고 --verbose 플래그를 사용하여 모든 기능이 제대로 작동하는지 확인합니다.

디렉토리 내용 나열
파일의 내용 가져오기
파일 내용 쓰기 (중요한 것을 덮어쓰지 말고 새 파일을 만드세요)
계산기 앱의 테스트 tests.py 실행

에이전트 루프 만들기

우리는 이제 함수 호출 기능을 어느 정도 구현했지만, 아직 우리 프로그램을 "에이전트"라고 부르기엔 부족한 점이 하나 있습니다:

피드백 루프가 없다는 것입니다.

AI 인플루언서들이 말하는 "에이전트"의 핵심은, 자신의 도구를 반복적으로 사용하여 결과를 계속 개선해나갈 수 있는 능력입니다. 그래서 우리는 다음 두 가지를 만들 것입니다:

LLM을 반복해서 호출할 루프
"대화"에서 오고간 메시지 리스트. 다음과 같이 보일 것입니다:

사용자: "계산기의 버그를 수정해주세요"
모델: "get_files_info를 호출하고 싶습니다..."
툴: "get_files_info의 결과입니다..."
모델: "get_file_content를 호출하고 싶습니다..."
툴: "get_file_content의 결과입니다..."
모델: "run_python_file을 호출하고 싶습니다..."
툴: "run_python_file의 결과입니다..."
모델: "write_file을 호출하고 싶습니다..."
툴: "write_file의 결과입니다..."
모델: "run_python_file을 호출하고 싶습니다..."
툴: "run_python_file의 결과입니다..."
모델: "버그를 수정했고 계산기가 작동하는지 확인하기 위해 실행했습니다."

이건 꽤 큰 진전입니다. 천천히 진행하세요!

prompts.py를 만듭니다:

system_prompt = """
You are a helpful AI coding agent.

When a user asks a question or makes a request, make a function call plan. You can perform the following operations:
- List files and directories
- Read file contents
- Execute Python files with optional arguments
- Write or overwrite files

All paths you provide should be relative to the working directory. You do not need to specify the working directory in your function calls as it is automatically injected for security reasons.
"""

최종 main.py 구성:

import sys
import os
from google import genai
from google.genai import types
from dotenv import load_dotenv

from prompts import system_prompt
from call_function import call_function, available_functions

def main():
    load_dotenv()

    verbose = "--verbose" in sys.argv
    args = []
    for arg in sys.argv[1:]:
        if not arg.startswith("--"):
            args.append(arg)

    if not args:
        print("AI Code Assistant")
        print('\nUsage: python main.py "your prompt here" [--verbose]')
        print('Example: python main.py "How do I fix the calculator?"')
        sys.exit(1)

    api_key = os.environ.get("GEMINI_API_KEY")
    client = genai.Client(api_key=api_key)

    user_prompt = " ".join(args)

    if verbose:
        print(f"User prompt: {user_prompt}\n")

    messages = [
        types.Content(role="user", parts=[types.Part(text=user_prompt)]),
    ]

    generate_content_loop(client, messages, verbose)


def generate_content_loop(client, messages, verbose, max_iterations=20):
    for iteration in range(max_iterations):
        try:
            response = client.models.generate_content(
                model="gemini-2.0-flash-001",
                contents=messages,
                config=types.GenerateContentConfig(
                    tools=[available_functions], 
                    system_instruction=system_prompt
                ),
            )
            
            if verbose:
                print("Prompt tokens:", response.usage_metadata.prompt_token_count)
                print("Response tokens:", response.usage_metadata.candidates_token_count)

            # 모델 응답을 대화에 추가
            for candidate in response.candidates:
                messages.append(candidate.content)

            # 최종 텍스트 응답이 있는지 확인
            if response.text:
                print("Final response:")
                print(response.text)
                break

            # 함수 호출 처리
            if response.function_calls:
                function_responses = []
                for function_call_part in response.function_calls:
                    function_call_result = call_function(function_call_part, verbose)
                    if (not function_call_result.parts 
                        or not function_call_result.parts[0].function_response):
                        raise Exception("empty function call result")
                    if verbose:
                        print(f"-> {function_call_result.parts[0].function_response.response}")
                    function_responses.append(function_call_result.parts[0])
                
                if function_responses:
                    messages.append(types.Content(role="user", parts=function_responses))
                else:
                    raise Exception("no function responses generated, exiting.")
        except Exception as e:
            print(f"Error: {e}")
            break
    else:
        print(f"최대 반복 횟수({max_iterations})에 도달했습니다. 에이전트가 작업을 완료하지 못했을 수 있습니다.")

if __name__ == "__main__":
    main()

generate_content 함수에서 모든 도구 사용 결과를 처리하세요. 이미 일부 구현되어 있을 수도 있지만, 중요한 점은 client.models.generate_content를 호출할 때마다 전체 messages 리스트를 전달해야 한다는 것입니다. 그래야 LLM이 현재 상태를 기반으로 "다음 단계"를 수행할 수 있습니다.

클라이언트의 generate_content 메서드를 호출한 후 응답의 .candidates 속성을 확인합니다. 이 속성은 응답의 다양한 버전(일반적으로 한 개)을 담고 있습니다. "get_files_info를 호출하고 싶습니다..."와 같은 응답이 나오면, 이 내용을 대화에 추가해야 합니다. 각 candidate를 순회하며 그 .content를 messages 리스트에 추가하세요.

각 함수 호출 후에는 types.Content를 사용하여 function_responses를 역할이 user인 메시지로 변환하고, 이를 messages에 추가하세요.

그 다음에는 generate_content를 한 번만 호출하는 대신, 반복적으로 호출하는 루프를 만드세요. 이 루프는 최대 20회까지만 반복되도록 제한하세요 (에이전트가 무한 반복하지 않도록 방지). try-except 블록을 사용하여 오류를 적절히 처리하세요.

각 generate_content 호출 후에는 response.text 속성을 반환하는지 확인하세요. 만약 그렇다면 작업이 완료된 것이므로, 최종 응답을 출력하고 루프를 종료하세요. 그렇지 않으면 다시 반복하세요 (물론 최대 반복 횟수에 도달하지 않았다면).

코드를 꼭 테스트하세요 (당연하죠). "계산기가 결과를 콘솔에 어떻게 출력하는지 설명해줘" 처럼 간단한 프롬프트로 시작해보세요. 저는 아래와 같은 결과를 받았습니다:

(aiagent) wagslane@MacBook-Pro-2 aiagent % uv run main.py "계산기가 결과를 콘솔에 어떻게 출력하는지 설명해줘"

함수 호출: get_files_info

함수 호출: get_file_content

최종 응답:
main.py 코드를 살펴본 결과, 계산기가 결과를 콘솔에 출력하는 방법은 다음과 같습니다:

print(to_print): 출력의 핵심은 print() 함수로 이루어집니다.

format_json_output(expression, result): 출력 전에 format_json_output 함수(pkg.render에서 import됨)를 사용해 계산 결과와 원래 식을 JSON 형태의 문자열로 포맷합니다. 이 형식화된 문자열은 to_print 변수에 저장됩니다.

에러 처리: 코드에는 try...except 블록을 활용한 에러 처리 기능이 포함되어 있습니다. 만약 계산 중 오류가 발생하면(예: 잘못된 수식이 입력된 경우), print(f"Error: {e}")를 통해 오류 메시지가 콘솔에 출력됩니다.

즉, 계산기는 식을 평가하고, 결과(그리고 원래 식)를 JSON 형태의 문자열로 만들어 콘솔에 출력합니다. 오류가 발생하면 콘솔에 오류 메시지도 따로 출력됩니다.

팁: 원하는 대로 LLM이 동작하도록 하려면 시스템 프롬프트를 약간 조정해야 할 수도 있습니다. 이제 당신은 프롬프트 엔지니어입니다. 그처럼 행동하세요!

멋집니다! 이제 파일을 읽고, 파일을 작성하고, 파이썬 코드를 실행하며, 스스로 결과를 개선할 수 있는 기본적인 AI 에이전트를 완성했습니다. 이건 더 복잡한 AI 에이전트를 만드는 훌륭한 기반이에요.

결론

필요한 모든 단계를 완료했습니다. 이제 약간 재미있게 (하지만 신중하게… LLM에 파일 시스템이나 파이썬 인터프리터 접근 권한을 줄 때는 매우 주의하세요) 다뤄보세요! 다음과 같은 작업들을 시도해볼 수도 있습니다:

더 어려운 버그나 복잡한 문제 수정
코드 일부를 리팩터링하기
완전히 새로운 기능 추가

또한 다음을 시도할 수 있습니다:

다른 LLM 제공업체
다른 Gemini 모델
호출 가능한 기능을 더 추가해보기
다른 코드베이스 시도하기 (에이전트를 실행하기 전에 변경 사항을 커밋해두면 언제든 되돌릴 수 있습니다!)

경고: 우리가 구축한 것은 Cursor/Zed의 Agentic Mode 또는 Claude Code와 같은 것의 간단한 버전이라는 것을 기억하세요. 그 도구들조차 완벽하게 안전하지 않으므로 접근 권한을 부여하는 것에 주의하고 이 코드를 다른 사람에게 제공하지 마세요.

백엔드 및 데이터 엔지니어링에 대해 더 알고 싶다면, Boot.dev를 확인하세요! 학습 여정에 행운을 빕니다!

재미있게 보셨다면 X.com과 YouTube에서 저를 팔로우해 주세요!

10주년을 맞이한 freeCodeCamp, 그리고 주요 자격증 업데이트

Alison Yoon — Thu, 31 Oct 2024 20:17:42 +0000

기사 원문: freeCodeCamp Turns 10 + Major Certification Updates

10년 전 오늘 샌프란시스코 아파트의 옷장 방에 앉아 freeCodeCamp의 첫 수백 줄의 코드를 작성했습니다.

Quincy의 옷장 사무실

당시만 해도 fCC가 코딩을 함께 배우는 전 세계 성인 커뮤니티로 빠르게 성장할 것이라고는 생각하지 못했습니다.

많은 캠퍼들 - 우리가 스스로를 부르는 방식 - 이 소프트웨어 엔지니어로 취업했고, 많은 캠퍼들이 fCC의 오픈 소스 코드에 기여했습니다.

지난 10년 동안 우리는 다음과 같은 것들을 만들어냈습니다.

수학, 프로그래밍, 컴퓨터 공학을 가르치는 3,000시간 분량의 대화형 핵심 커리큘럼
freecodecamp.org/news에 12,000개 이상의 프로그래밍 튜토리얼과 수십 권의 전체 길이 책,
구독자 수 1,000만 명을 넘어선 무료 전체 강좌 YouTube 채널
세계에서 가장 친절하고 지지적인 프로그래밍 포럼, 그리고 유사한 Discord 서버

혼자였던 팀도 35명의 교사와 엔지니어로 성장했습니다. 하지만 이는 빙산의 일각에 불과합니다. 대부분의 작업은 오픈 소스 커뮤니티 자체에 의해 수행되고 있습니다. 매일 자원봉사자들이 나타나 코드베이스를 개선하고, 새로운 오픈 러닝 리소스를 만들며, 포럼에서 서로를 돕고 있습니다.

이제 우리는 방금 시작했을 뿐이며, freeCodeCamp의 첫 10년에 대한 감상적인 이야기보다는 향후 10년 계획에 초점을 맞추겠습니다.

결국 우리 자선단체의 목표는 수학, 프로그래밍, 컴퓨터 공학 학습을 위한 무료 자료를 제공하는 것이며, 이를 위해 해야 할 일이 아직 많이 남아 있습니다.

이 글에서는 향후 10년의 주요 계획과 크리스마스 전까지의 주요 개선사항을 소개하겠습니다.

freeCodeCamp의 통합 인증 프로그램

새로운 가장 큰 변화는 현재 다양한 과정으로 운영되던 커리큘럼을 종합적이고 포괄적인 '인증된 풀스택 개발자(CFSD)' 인증 과정으로 통합하는 것입니다. 그리고 이와 유사한 새로운 포괄적인 인증 과정도 처음부터 개발하고 있습니다.

우리는 CompTIA, (ISC)²와 같은 확립된 개발자 인증 비영리 단체에서 영감을 얻었습니다. 우리의 인증 과정을 산업 표준 인증과 더 유사하게 전면 개편하고 있습니다.

새로운 인증 과정은 다음과 같은 특징을 가지게 될 것입니다.

더욱 포괄적일 것
최종 시험을 포함할 것
종합 프로젝트를 포함할 것
3년간 유효하며 갱신 가능할 것

그리고 freeCodeCamp가 만드는 모든 것처럼, 이 인증 과정 역시 완전히 무료로 제공될 것입니다.

인증된 풀스택 개발자 인증 과정 커리큘럼에는 다음과 같은 내용이 포함될 것입니다.

의미 있는 HTML
접근성
CSS 기본
CSS 플렉스박스
개발자를 위한 디자인
타이포그라피
코드 편집기
JavaScript 기본
함수형 프로그래밍
고차 함수와 콜백
DOM 조작과 이벤트
웹 표준
React 기본
TypeScript 기본
테스팅 개념
Bash 스크립팅
SQL과 관계형 데이터베이스
Git & GitHub
보안과 프라이버시
Node.js
Express.js
Python 기본
알고리즘적 사고
자료 구조
객체 지향 프로그래밍
동적 프로그래밍
웹 개발자를 위한 보안
툴링과 배포
API 다루기
AI 엔지니어링 기본
개발자 취업하기

그리고 많은 사람들의 요청에 따라, 우리는 핵심 커리큘럼 내에서 훨씬 더 많은 이론을 다룰 것입니다.

이전에는 우리의 인증 과정이 100% 프로젝트 구축에 초점을 맞추었습니다. 하지만 많은 캠퍼들로부터 "배우면서 하기"에 지나치게 치우쳤다는 피드백을 받았고, 이론에 대한 더 많은 설명도 필요하다는 의견이 많았습니다.

이제 freeCodeCamp의 커리큘럼만으로도 필수적인 이론을 학습할 수 있게 될 것입니다.

우리의 강사 디자인팀, 즉 Beau Carnes와 Ania Kubów가 제작한 동영상 강의를 통해 이론을 다룰 것이며, 이는 자막과 함께 제공될 것입니다.

또한 핵심 개념과 코딩 기술에 대한 이해도를 높이기 위해 많은 퀴즈도 추가했습니다. 그리고 우리의 스페이스드 리피티션 시스템과 함께 활용될 것입니다.

그리고 학습자의 자율성을 높이기 위해 보다 이른 단계부터 "빈 화면" 스타일의 코딩 실습 과제에 돌입할 것입니다.

새로운 인증된 풀스택 개발자 과정에는 다음과 같은 내용이 포함됩니다.

64개의 워크숍 – HTML부터 SQL, Python까지 다양한 도구를 다루는 대화형 코딩 과정
513 개의 강의 – 컴퓨터 과학 개념을 다루는 짧은 동영상과 복습용 퀴즈
83개의 실습 – 빈 편집기에서 테스트를 통과하는 프로젝트를 구현하는 과제
62개의 복습 페이지 – 각 모듈별 주요 토픽을 정리한 자료
66개의 퀴즈와 and 6개의 모의고사 – 풀스택 개발 개념과 도구에 대한 이해도 확인
1개의 종합 프로젝트 – freeCodeCamp 커뮤니티의 검토를 받는 포트폴리오용 대규모 프로젝트
1회의 최종 시험 – 모든 준비 과정을 포괄하는 90문항의 공식 인증 시험

모든 과정을 완료하면 최종 시험을 치를 자격을 얻게 됩니다. 우리는 자체 개발한 오픈 소스 시험 환경에서 지금까지 배운 모든 내용을 심층적으로 평가하는 시험을 치르게 될 것입니다.

시험에 합격하지 못한 경우에도 24시간마다 재응시할 수 있습니다. 매번 광범위한 문항 데이터베이스에서 무작위로 시험이 출제될 것입니다.

온라인 시험에서 부정행위로 거짓 혐의를 받는다는 소문을 들어보셨을 것입니다. 우리는 학업 윤리 강령을 어떻게 집행할지 깊이 고민했습니다. 이런 결정에는 항상 사람의 개입이 있을 것입니다.

아기가 울어서 자리를 비웠다고 자동으로 자격을 박탈하지 않을 것입니다. 이런 상황들을 모두 고려하여 시험을 진행할 것입니다.

합격하면 무료로 검증된 공식 인증서를 받게 됩니다. 이를 이력서나 CV에 추가하거나 LinkedIn에 게시할 수 있습니다. 이 인증서는 3년간 유효하며, 그 후에는 무료 연수 과정을 거쳐 갱신할 수 있습니다.

freeCodeCamp 커리큘럼의 주요 업데이트 내용을 3분 동영상으로 안내드립니다.

우리는 또 다른 3가지 인증 과정도 개발하고 있습니다

새로운 인증된 풀스택 개발자 인증 과정이 출시되면, 우리 강사 디자인팀은 추가로 3가지 인증 과정 개발에 주력할 것입니다.

머신러닝 엔지니어 인증 과정 (fCC-CMLE)

이 인증 과정에서는 Python과 다양한 라이브러리를 배우게 됩니다. 또한 방대한 수학 및 이론도 학습하게 될 것입니다. 많은 프로젝트에서 직접 모델을 만들어볼 기회가 주어질 것입니다. Kylie Ying이 이미 머신러닝 엔지니어들과 협력하여 이 과정 설계를 진행하고 있습니다. 2025년에 일부 내용이 출시될 예정입니다.

소프트웨어 시스템 엔지니어 인증 과정 (fCC-CSSE)

이 인증 과정에서는 저수준 프로그래밍과 고성능 컴퓨팅을 다룰 것입니다. C와 C++를 배우고, 자신만의 컴파일러와 검색 엔진과 같은 프로젝트를 직접 구현해볼 기회가 있습니다. 2026년에 일부 내용이 출시될 예정입니다.

데이터 과학자 인증 과정 (fCC-CDS)

우리는 수년 동안 종합적인 데이터 과학 커리큘럼을 개발해왔습니다. 여러분도 알다시피, freeCodeCamp 커뮤니티 YouTube 채널에는 이미 Python, R과 같은 데이터 분석 도구에 대한 많은 인기 강좌가 있습니다.

데이터 과학을 가르치는 과정에서 가장 큰 과제는 이 분야에 필요한 방대한 수학을 가르치는 것입니다. 또한 프로그래밍으로 자동 채점할 수 있는 프로젝트 기반 학습을 구축해야 합니다.

우리의 목표는 박사 과정 외에 데이터 과학 교육 중 최고의 교육을 제공하는 것입니다. 이것이 가장 큰 도전과제가 될 것입니다. 하지만 우리는 그것을 해낼 수 있습니다.

2027년에 일부 내용이 출시될 예정입니다.

이 인증 과정과 관련된 자세한 정보는 언제 제공될까요?

우리는 현재 이에 대한 종합적인 커리큘럼 개요를 작성하고 있으며, 일부 내용을 2025년에 공개할 계획입니다.

기존의 freeCodeCamp 인증 과정은 어떻게 되나요?

freeCodeCamp has a long tradition of preserving old coursework from legacy certs. This time is no different.

우리는 여러분이 이번 크리스마스에 출시되는 새로운 인증된 풀스택 개발자 인증 과정으로 전환하기를 권장합니다. 기존 인증 과정에서 많은 프로젝트를 이미 완료하셨을 수도 있겠지요.

그렇기 때문에 이미 기존 인증 과정을 진행 중이라면 그 과정을 계속 이어가실 수 있습니다.

레거시 인증은 만료되나요?

네, 그렇습니다. 모든 레거시 인증은 2027년 12월 31일에 만료됩니다. 이는 과거에 취득한 모든 freeCodeCamp 인증서를 포함합니다.

우리는 새로운 인증된 풀스택 개발자 인증을 취득하기 전에 기존 인증을 충분히 활용할 수 있는 시간을 주고자 합니다. 그리고 3년은 충분한 기간이라고 판단했습니다.

앞으로 취득하는 인증된 풀스택 개발자 인증이나 다른 3개의 새로운 인증도 취득일로부터 3년간 유효합니다.

또한 3년 후에는 무료 연수 프로그램을 통해 인증을 갱신할 수 있습니다.

왜 freeCodeCamp에서 시험과 인증 만료일을 도입했나요?

다른 IT 업계 인증과 유사하게 만들기 위해서입니다. 주요 인증들은 모두 인증 시험 합격을 요구하고 있으며, 3년 후 만료됩니다.

우리의 목표는 freeCodeCamp 인증이 업계에서 표준으로 인정받을 수 있도록 하는 것입니다.

freeCodeCamp가 취업 지원이나 알선 사업을 할 계획인가요?

아니요, 그럴 계획이 없습니다. 우리 자선 단체의 목표는 단순히 무료 학습 자료를 제공하는 것입니다. 우리는 교사가 아닌 인력을 늘리기보다는 소규모 교사진을 유지하며 집중할 계획입니다.

각 인증 과정 간 교과과정 중복되는 부분은 얼마나 될까요?

일부 인증 과정에서는 몇 가지 공통 프로젝트와 강의가 공유될 예정입니다. 예를 들어, 인증된 풀스택 개발자 인증 과정에서 Python 입문 과정을 이미 완료했다면, 인증된 머신러닝 엔지니어 인증 과정에서 이를 다시 수강할 필요가 없습니다.

기존 인증서는 온라인에 남아있나요? 검증 링크도 계속 작동하나요?

만료된 인증서는 여전히 프로필에 표시되며, 직접 링크도 계속 작동할 것입니다. 다만 "만료됨 [날짜]" 라고 명확히 표시될 것입니다. 이는 2027년 12월 31일 까지는 어떤 fCC 인증서에도 적용되지 않습니다.

freecodecamp.org/learn 에 현재 나열된 11개 인증 과정은 어떻게 되나요??

이 인증 과정들은 최소 수년간 레거시 인증 과정으로 계속 제공될 것입니다. 그 내부 교과과정 대부분은 새로운 인증 과정의 일부로 재구성되고 개선될 것입니다.

기존에 완료한 프로젝트를 다시 해야 하나요?

이전 인증 과정의 일부 교과과정은 새로운 인증 과정에도 남아있을 것입니다. 대부분의 경우 이미 완료한 프로젝트를 다시 할 필요는 없을 것입니다. 이미 프로젝트를 구현했다면, 새 인증 과정을 살펴볼 때 일부 섹션이 이미 완료된 것으로 표시될 가능성이 높습니다.

Rust, Java 등의 프로그래밍 언어나 NoSQL 데이터베이스 도구들에 대한 강의는요?

우리는 개발자로 취업할 수 있는 최선의 기회를 제공하기 위해 핵심 커리큘럼을 가장 인기 있는 도구 중심으로 유지하고 있습니다. 즉, Python, JavaScript, SQL, Git, Linux 등이 그것입니다.

freeCodeCamp 커뮤니티 YouTube 채널과 freeCodeCamp 출판물에는 다른 인기 도구에 대한 강좌가 많이 있습니다. 이들은 추가 선택 과목으로 계속 제공될 것입니다.

영어 커리큘럼은 어떻게 진행되고 있나요?

캠퍼들의 영어 실력 향상을 돕기 위해 대화형 영어 커리큘럼을 만들기 위해 열심히 작업하고 있습니다.

동영상과 대화형 연습을 통해 가르치고, 정식 인증 시험이 뒤따릅니다.

현재 A2 레벨을 마무리하고 있으며, B1 레벨 개발에 착수했습니다.

무료 대학 학위 프로그램은 어떻게 진행되고 있나요?

우리는 수학 준학사 학위와 컴퓨터 공학 학사 학위를 제공하는 데 꾸준히 진척을 이루고 있습니다. 이미 2개의 수학 과목을 개발했으며, 나머지 38개 대학 수준의 과목, 강의, 실습, 시험 개발에 힘쓰고 있습니다.

freeCodeCamp에는 소규모 강사 설계팀이 있으며, 현재는 주로 인증된 풀스택 개발자 인증 과정 교과과정과 영어 인증 프로그램에 집중하고 있습니다. 이 두 가지를 완료하면 학위 프로그램 개발에 더 많은 자원을 투입할 계획입니다.

10년은 그저 시작에 불과합니다.

우리 커뮤니티가 단 10년 만에 이루어낸 성과는 놀랍습니다.

3,000시간 분량의 대화형 학습 자료로 이루어진 무료 커리큘럼
수천 개의 추가 선택 동영상 강좌, 서적, 튜토리얼
수만 명의 개발자로 취업한 캠퍼들
수만 명의 오픈소스와 동료 캠퍼 지원을 통해 경험을 쌓고 있는 기여자들

이제 시작에 불과합니다.

전 세계 freeCodeCamp 커뮤니티에 참여해 보시기를 권장합니다. 2024년 우수 오픈소스 기여자 목록을 살펴보실 수 있습니다. 참여하고 싶으시다면 기여자 가이드를 확인해 보세요.

후원자가 되어주시기를 요청드리며, 이미 매월 후원 중이시라면 연말 기부도 고려해 보시기 바랍니다. 세금 공제 혜택이 가능한 다양한 방법이 있습니다.

궁금하신 점이나 기부금 영수증이 필요하시다면 언제든 quincy@freecodecamp.org로 연락 주시기 바랍니다.

앞으로의 10년도 기대해 주시기 바랍니다.

– Quincy

React 서버 컴포넌트를 사용해야 하는 이유와 방법

Soobin Bak — Mon, 08 Jan 2024 08:53:44 +0000

기사 원문: React Server Components – How and Why You Should Use Them in Your Code

2020년 말, React 팀은 "제로-번들-사이즈 React 서버 컴포넌트" 개념을 도입했습니다. 그 이후로 React 개발자 커뮤니티는 이 미래 지향적인 접근 방식을 실험하고 적용하는 방법을 학습해 왔습니다.

React는 UI를 구축하는 방식에 대한 우리의 생각을 바꾸었습니다. 그리고 React 서버 컴포넌트를 사용하는 새로운 모델은 훨씬 더 구조화되고 편리하며, 유지 관리하기 쉽고 더 나은 사용자 경험을 제공합니다.

Next.js의 최신 릴리즈는 “서버 컴포넌트로 생각하기” 방향으로 나아갔습니다. 그리고 React 개발자로서 우리는 애플리케이션을 구축하는데 이 기술을 최대한 활용하기 위하여 새로운 사고 모델에 적응해야 합니다.

이 튜토리얼에서는 RSC(React Server Component)에 대해 배울 것입니다. React 서버 컴포넌트가 무엇인지, 어떻게 작동하는지, 그리고 더 중요하게는 이것이 어떤 문제를 해결하는지 중점적으로 알아볼 것입니다.

또한 왜 RSC가 필요한지 이해할 수 있도록 많은 예시를 보여줄 것입니다. 마지막으로 React 서버 컴포넌트와 비슷해 보이지만 다른 기능인 서버 사이드 렌더링(SSR) 간의 차이점을 배울 것입니다.

React를 처음 접하는 경우, React 서버 컴포넌트에 대해 학습하기 전에, 컴포넌트 아키텍처, 상태(state), 속성(props)을 이용한 데이터 전달, 가상 돔(Virtual DOM) 트리에 대한 기본 지식이 필요합니다.

또한 이 글을 읽은 다음 freeCodeCamp에서 전체 로드맵을 참고하여 React 기초를 확고히 다질 수도 있습니다.

준비가 되었나요? 시작해봅시다.

만약 비디오 콘텐츠를 통해 학습하고 싶다면, 이 글을 비디오 튜토리얼로도 볼 수 있습니다. 🙂

클라이언트 사이드 UI 라이브러리로서의 React

React는 처음부터 클라이언트 사이드 UI 라이브러리였습니다. 웹 및 모바일 개발자가 컴포넌트 기반 아키텍처를 활용하여 애플리케이션을 개발하는 데 도움이 되는 JavaScript 기반의 오픈 소스 라이브러리입니다.
React 철학은 우리가 디자인 전체를 더 작고 독립적인 부분인 컴포넌트라고 불리는 작은 조각으로 나누는 것을 제안합니다.

하나의 컴포넌트가 여러 개의 하위 컴포넌트로 분해되는 것을 보여주는 이미지입니다.

컴포넌트는 state라고 불리는 자체 비공개 데이터와 서로 다른 컴포넌트 간에 데이터를 전달하는 방법인 props를 가질 수 있습니다. 컴포넌트들을 컴포넌트 계층 구조로 나누고, 상태를 정의하고, 상태를 변경하여 발생되는 효과(effect)를 관리하고, 데이터 흐름(flow)을 결정합니다.

state와 props의 작동 방식을 보여주는 이미지

전통적으로 이러한 모든 컴포넌트들은 자바스크립트의 함수입니다(여기서는 함수형 컴포넌트에 대해서만 이야기하고, 과거에 사용했던 클래스형 컴포넌트는 따로 이야기 하지 않겠습니다). 앱이 브라우저에서 로드될 때, 컴포넌트 코드를 다운로드하고 이를 사용하여 앱이 작동하도록 만듭니다.

여전히 ‘컴포넌트’라는 용어를 사용할 것입니다. 하지만 이 문서는 React 서버 컴포넌트의 개념을 소개하므로, 이러한 전통적인 컴포넌트를 클라이언트 컴포넌트 라고 부르겠습니다(클라이언트/브라우저에서 다운로드되고 React가 마법을 부려 렌더링하는 컴포넌트).

React 앱의 일반적인 문제

React 클라이언트 컴포넌트는 훌륭하며 특정 사례를 해결하는 데 효과적입니다. 하지만 React 앱을 구축할 때, 패턴을 조금 다르게 고려해 볼 필요가 있습니다. 이는 다음과 같은 사항을 고려해야 하기 때문입니다.

사용자 경험(User Experience): 우리는 사용자와 고객을 위한 소프트웨어 제품을 만듭니다. 앱이 성공하길 원한다면, 애플리케이션의 사용자 경험이 중요합니다.
유지 보수(Maintainability): 프로젝트 코드는 여러 개발팀을 거쳐 수년간 원활하게 유지 보수 되어야 합니다.
성능 비용(Performance Cost): 애플리케이션이 느려져서는 안 되며, 우리의 디자인(설계) 접근 방식이 느리게 만들어서도 안됩니다.

이제 일상적으로 마주할 수 있는 몇 가지 예를 살펴보겠습니다. 또한 React를 사용하여 일상적인 웹 개발에서 각 핵심 사항을 어떻게 구현하고 설계할 수 있는지 이해할 수 있을 것입니다.

레이아웃 이동 문제

매우 흔한 UX 문제 중 하나는 컴포넌트가 렌더링될 때 레이아웃이 갑자기 이동되는 현상입니다. 아래의 코드 스니펫을 살펴봅시다.

다음은 익숙한 JSX 코드로, CourseWrapper 컴포넌트와 CourseList 및 Testimonials 두 개의 하위 컴포넌트가 있습니다. CourseList 와 Testimonials 두 컴포넌트 모두 데이터를 가져오기 위해 네트워크 호출(API 호출)을 수행한다고 가정해 봅시다.

다음은 CourseList 컴포넌트 입니다.

function CourseList() {

    // 실제 네트워크 호출을 가정하면,
    // useEffect를 사용하여 처리할 것입니다.
    const info = fetchCourseList();

    return(
      <> )
}

그리고 Testimonial 컴포넌트 입니다.

function Testimonials() {

    // 실제 네트워크 호출을 가정하면,
    // useEffect를 사용하여 처리할 것입니다.
    const info = fetchTestimonials();

    return(
      <> 
    )
}

이러한 컴포넌트들이 네트워크 호출을 수행하는 경우, 응답이 돌아오는 순서에 대한 보장이 없습니다. 이는 네트워크 속도, 지연 시간 및 여러 다른 요인에 따라 달라집니다.
Testimonials 컴포넌트의 네트워크 호출이 CourseList 컴포넌트보다 먼저 완료되는 상황에서, Testimonials 컴포넌트가 먼저 렌더링되고 그 다음에 CourseList 컴포넌트가 렌더링됩니다. 이로 인해 Testimonials 컴포넌트가 적합한 위치로 이동됩니다. 아래에서 제가 하는 말이 무엇인지 확인할 수 있습니다.

레이아웃 이동의 UX 문제를 보여주는 슬로우 모션

로딩 인디케이터나 깜빡임 효과를 통해서 사용자에게 잠시 후를 기대하도록 알려주어 UX를 좀 더 향상시킬 수 있습니다(그러나 언제가 될지는 확신하지 못합니다).

네트워크 워터폴(waterfall) 문제

또 다른 전형적인 사용자 경험 문제에 대해 이야기해 봅시다. 지난 예제와 유사한 React 컴포넌트를 상상해 보세요.

function Course() {
  return (
    
      
         
    
  )
}

두 개의 하위 컴포넌트를 가진 CourseWrapper 컴포넌트

여기서 조금 수정을 해보겠습니다. CourseList 과 Testimonials 컴포넌트와 함께 이제 CourseWrapper도 네트워크 호출을 수행합니다.

function CourseWrapper() {

    // 실제 네트워크 호출을 가정하면,
    // useEffect를 사용하여 처리할 것입니다.
    const info = fetchWrapperInfo();
    
    return(
      <> 
    )
}

CourseWrapper 컴포넌트 - 네트워크 호출 수행

따라서 부모 컴포넌트는 데이터를 가져오기 위해 네트워크 호출을 수행하고, 그 하위 컴포넌트들 또한 네트워크 호출을 수행합니다.

흥미로운 점은, 부모 컴포넌트는 네트워크 호출이 완료될 때까지 렌더링되지 않는다는 것입니다. 따라서 자식 컴포넌트들의 렌더링도 홀딩 합니다.

현재 작업을 시작하기 위해 이전 것의 응답이 완료되기를 기다리는 현상은 워터폴(Waterfall)라고 알려져 있습니다. 이 경우에는 네트워크 워터폴 및 컴포넌트 렌더링 워터폴 문제 모두 발생합니다.

이제 여러분은 각 컴포넌트에서의 모든 네트워크 호출을 제거하고 각각의 컴포넌트가 응답을 기다리지 않도록 부모 컴포넌트에서 단일 호출 하도록 네트워크 호출 로직을 끌어 올릴 수 있다고 생각할 수 있습니다. 이것은 현명한 생각이지만 유지 보수 측면에서 문제가 발생할 수 있습니다. 다음 섹션에서 이에 대해 더 자세히 알아보겠습니다.

유지 보수 관련 문제

서버 측 상호 작용과 관련된 몇 가지 사용자 경험 문제를 살펴보았으므로, 이제 유지 보수 관련 문제를 고려해 봅시다.

모든 컴포넌트가 네트워크 호출을 수행하지 않는다고 가정해 봅시다. 단일 API 호출인 fetchAllDetails()를 사용하여 (부모 컴포넌트를 포함하여) 모든 컴포넌트의 세부 정보를 한 번에 가져옵니다.

그런 다음 필요한 정보를 각 컴포넌트에 props로 전달합니다. 이것은 위에서 본 "워터폴" 문제보다 더 나은 접근 방법이겠지요?

function Course() {
	
    // 실제 네트워크 호출을 가정하면,
    // useEffect를 사용하여 처리할 것입니다. 
    const info = fetchAllDetails();
    
    return(
    	
            
            
             
    )
 }

Course 컴포넌트 - 최상위 API 호출 수행

그러나 이것은 일부 유지 보수 문제를 야기할 수 있습니다.

어느 화창한 날, 제품이 Testimonials 기능을 삭제하기로 결정했다고 가정해 봅시다. 우리는 위의 코드에서 Testimonials 컴포넌트를 간단히 삭제할 수 있습니다. 그런데, fetchAllDetails() 호출을 통해 가져온 데이터를 정리하는 것을 잊을 수 있습니다. 사용되지 않고 불필요한 상태로 남아 있을 수 있습니다.

이러한 문제를 완화하기 위해, 가능한 사용자 경험 문제를 설명하면서 이전 섹션에서 이미 논의한 방식으로 코드를 변경할 수 있을 것입니다. 따라서 우리는 더 나은 해결책을 찾아야 합니다. 하지만 그에 앞서, 성능 비용이라는 또 하나의 고려 사항에 대해 먼저 이야기해 보겠습니다.

성능 비용

우리가 논의할 마지막 문제 영역은 성능 비용입니다.

인터넷에서 발견한 재미있는 밈 - 자바스크립트가 클라이언트에게 주는 무거움을 묘사

전통적으로, React 컴포넌트는 클라이언트 사이드 자바스크립트 함수입니다. 이는 React 애플리케이션의 구성 요소입니다. 클라이언트에서 애플리케이션을 로드할 때, 컴포넌트가 클라이언트에 다운로드되고 React가 그것들을 렌더링하는데 필요한 작업을 수행합니다.

그러나 이로 인해 두 가지 중요한 문제가 발생합니다.

먼저, 사용자가 요청을 보낼 때, 앱은 HTML과 연결된 JavaScript, CSS 및 이미지와 같은 다른 에셋을 다운로드합니다.

클라이언트 사이드(브라우저에서)에서 React는 마법을 부리기 시작하고 HTML 구조를 하이드레이트(hydrate) 시킵니다. 이것은 HTML을 구문 분석하고, 이벤트 리스너를 DOM에 연결하며 스토어에서 데이터를 가져옵니다. 따라서 사이트는 완전히 작동하는 React 앱이 됩니다.

그러나 중요한 점은 클라이언트에서 많은 일이 일어나고 있다는 것입니다. 결국 이 코드를 모두 클라이언트에서 다운로드하게 됩니다.

브라우저에 다운로드된 스크립트의 양

대부분의 경우, 프로젝트에 종속성이 있는 외부 라이브러리(Node 모듈)가 필요합니다. 이러한 모든 종속성은 클라이언트 사이드에서 다운로드되어 더욱 무거워집니다.

이제 문제점을 이해했으므로, React 서버 컴포넌트가 제공하는 기능과 이러한 문제를 해결하는 방법에 대해서 확실히 이해할 수 있을 것입니다.

그러나 이에 대해 이야기하기 전에, 클라이언트와 서버에 대해 조금 더 알아보겠습니다.

클라이언트-서버 모델

이 글에서 클라이언트와 서버 라는 용어를 여러 번 사용했습니다. 이제 이들에 대한 공식적인 정의를 내리고 높은 수준에서 그들의 관계를 설명해보겠습니다.

클라이언트와 서버의 관계를 보여주는 다이어그램

클라이언트: 애플리케이션의 클라이언트는 최종 사용자 측에서 작업을 실행하는 시스템입니다. 클라이언트의 예로는 PC, 랩탑, 모바일, 브라우저 등이 있습니다.
서버: 이름에서 알 수 있듯이, 서버는 클라이언트에 서비스를 제공합니다. 빠른 데이터 액세스를 위해 데이터 저장소나 데이터베이스와 공존할 수 있습니다.
요청: 요청은 클라이언트가 서버로부터 서비스를 요청하기 위해 사용하는 통신 모드입니다.
응답: 응답은 또한 서버가 서비스(데이터/정보)를 클라이언트에게 다시 보내기 위해 사용하는 통신 모드입니다.

React 클라이언트 컴포넌트

위에서 언급한대로, 전통적으로 React 컴포넌트는 클라이언트 사이드에서 실행됩니다. 서버와 상호 작용할 때, 요청을 보내고 응답이 돌아올 때까지 기다립니다. 응답을 받으면 클라이언트는 다음 작업을 트리거합니다.

요청한 서비스가 성공적으로 완료되면 클라이언트 컴포넌트는 UI에 맞게 작동하고 성공 메시지를 표시합니다. 오류가 발생한 경우 클라이언트 컴포넌트는 사용자에게 오류를 보고합니다.

클라이언트 서버 모델에서의 React 클라이언트 컴포넌트

네트워크 워터폴를 발생시킬 때 클라이언트 컴포넌트의 응답이 지연되어 사용자 경험이 저하됩니다. 그렇다면 이를 어떻게 완화할 수 있을까요?

React 서버 컴포넌트(RSCs)는 어떻게 도움을 줄까요?

React 컴포넌트를 서버로 옮겨보는 것은 어떨까요? 그리고 아마도 데이터 저장소와 동일한 곳에 위치시키고... 그런데 이것이 실제로 가능한 일일까요?
네! 이제 React Server Components에 대해 알아보겠습니다. 이러한 새로운 컴포넌트는 서버에 있으므로 데이터를 더 빨리 가져올 수 있습니다. 네트워크를 통해 왕복하지 않고도 파일 시스템 및 데이터 저장소와 같은 서버 인프라에 액세스할 수 있습니다.

클라이언트 서버 모델에서의 React 서버 컴포넌트

이제 서버 컴포넌트 측면에서 생각해야 하기 때문에, React 개발자에게는 완전한 패러다임 전환입니다.

RSC를 사용하면, 데이터 가져오는 로직을 서버로 이동하여(네트워크 호출 없이 데이터를 가져오도록) 서버 자체에서 준비할 수 있습니다. 클라이언트로 돌아오는 데이터는 모든 데이터와 함게 잘 구성된 컴포넌트 입니다. 얼마나 놀라운 일인가요?

이는 React 서버 컴포넌트를 사용하면 다음과 같은 코드를 작성할 수 있음을 의미합니다.

import { dbConnect } from '@/services/mongo'

import { addCourseToDB } from './actions/add-course'

import CourseList from './components/CourseList'

export default async function Home() {

  // MongoDB 연결
  await dbConnect();
  
  // db의 모델을 이용하여 모든 course를 얻는다.
  const allCourses = await courses.find();
  
  // 서버 쪽에서 콘솔이 찍힌다.
  console.log({allCourses})

  return (
    
      
          
      
    
  )
}

React 서버 컴포넌트의 예

저것 보세요! 몇 가지 변경 사항을 즉시 알아챌 수 있습니다.

이 컴포넌트는 비동기 호출을 처리하므로 async 타입 입니다.
우리는 컴포넌트 자체에서 데이터베이스(MongoDB)에 연결합니다. 와우! 보통 이러한 코드는 Node.js 또는 Express에서 볼 수 있습니다, 맞나요?
그런 다음 데이터베이스를 쿼리하고 렌더링을 위해 JSX에 전달할 데이터를 가져옵니다.

콘솔 로그는 브라우저 콘솔이 아닌 서버 콘솔에서 찍히는 것에 주목하세요.

또한 상태 관리 (useState)와 이펙트 관리 (useEffect)를 완전히 제거했습니다. 깔끔하고 간단합니다.

React 서버 컴포넌트를 사용하면, useEffect를 사용할 필요가 없을 수도 있습니다(영원히!).

React 서버 컴포넌트의 한계

이러한 이점도 갖고 있지만, 기억해야 할 RSC의 제한 사항도 있습니다.

RSC는 서버에 남아 있고 서버에서 렌더링됩니다. 클라이언트 사이드과 관련된 것이 없습니다. 이것은 서버 컴포넌트에 사용자 인터렉션을 추가할 수 없음을 의미합니다. 예를 들어, 이벤트 핸들러나 useState, useReducer, useEffect와 같은 React 훅을 서버 컴포넌트에서 사용할 수 없습니다.
서버 컴포넌트에서 localstorage, bluetooth, web USB와 같은 브라우저 웹 API를 사용할 수 없습니다.
클라이언트 상호 작용과 관련된 모든 것에 대해서는, 계속 클라이언트 컴포넌트를 사용해야 합니다.

이해가 되시나요? 그렇다면 어떻게 애플리케이션에 맞게 컴포넌트를 가장 잘 정리할 수 있을까요?

클라이언트와 서버 컴포넌트를 함께 사용하는 방법

당신의 앱은 서버 및 클라이언트 컴포넌트의 조합일 수 있습니다. 곧 예제를 보겠지만, 먼저 개념을 이해해 봅시다.

서버 컴포넌트는 클라이언트 컴포넌트를 가져와 렌더링할 수 있지만, 클라이언트 컴포넌트는 내부에서 서버 컴포넌트를 렌더링할 수 없습니다. 클라이언트 컴포넌트에서 서버 컴포넌트를 사용하려면 props로 전달하여 사용할 수 있습니다.

컴포넌트 계층 구조의 루트에 서버 컴포넌트를 두고 컴포넌트 트리의 말단으로 클라이언트 컴포넌트를 밀어 넣는 것이 좋습니다.

서버 컴포넌트의 최상단에서 데이터 페칭이 일어날 수 있으며, React가 허용하는 방식대로 전달할 수 있습니다. 사용자 상호 작용(이벤트 핸들러) 및 브라우저 API에 액세스는 말단의 클라이언트 컴포넌트에서 처리할 수 있습니다.

서버와 클라이언트 컴포넌트를 포함하는 컴포넌트 트리

잠깐, RSC는 서버 사이드 렌더링(SSR)과 동일하지 않나요?

아니요, 그렇지 않습니다. RSC와 SSR 둘 다 이름에 "서버"라는 단어가 들어가 있지만 비슷한 부분은 이 뿐입니다.

서버 사이드 렌더링(SSR)에서는, 서버에서 날것의 HTML을 클라이언트로 보내고, 그런 다음 모든 클라이언트 사이드 자바스크립트가 다운로드됩니다. React는 HTML을 상호작용 가능한 React 컴포넌트로 변환하기 위해 하이드레이션(hydration) 프로세스를 시작합니다. SSR에서 컴포넌트는 서버에 머무르지 않습니다.

지금까지 React 서버 컴포넌트를 통해 컴포넌트가 서버에 남아 있고 네트워크 왕복을 거치지 않고 서버 인프라에 액세스할 수 있음을 알게 되었습니다.

SSR은 애플리케이션의 초기 페이지를 더 빠르게 로드하는 데 유용합니다. 앞으로 SSR과 RSC를 문제없이 함께 사용할 수 있습니다.

Next.js(RSC 포함)와 MongoDB를 사용하여 강의 목록 페이지를 구축하는 방법

이제 React 서버 컴포넌트를 사용하는 응용 프로그램을 만들어 보겠습니다. Next.js는 최근 릴리스에서 RSC를 채택한 주요 웹 프레임워크입니다.

그래서 우리는 이제 Next.js에서 서버 컴포넌트를 만드는 방법과 클라이언트 컴포넌트를 만드는 방법이 어떻게 다른지를 보여주기 위해 강의 목록 페이지를 만들 것입니다.

여기서는 Next.js나 MongoDB를 자세히 배우지 않을 것입니다. React 서버 컴포넌트가 어떻게 동작하는지 그리고 클라이언트 컴포넌트와 어떻게 다른지 알려주기 위한 예로 이 애플리케이션을 사용하고 있습니다.

먼저 데이터 저장소에 강의 데이터를 추가해 보겠습니다. 이 앱에서는 MongoDB를 사용했습니다. 아래 이미지는 세 개의 강의에 대해 세 개의 문서가 추가된 것을 보여줍니다.

Mongo Compass - 강좌 모음

다음으로, MongoDB에 연결하는 유틸리티 함수를 만들겠습니다. 이것은 Mongoose와 MongoDB URI를 사용하여 자바스크립트 기반 프로젝트에서 MongoDB에 연결하는 데 사용할 수 있는 일반적인 코드입니다.

import mongoose from "mongoose";

export async function dbConnect(): Promise {
  try {
    const conn = await mongoose.connect(String(process.env.MONGO_DB_URI));
    console.log(`Database connected : ${conn.connection.host}`);
    return conn;
  } catch (err) {
    console.error(err);
  }
}

MongoDB 연결을 위한 코드 스니펫

이제 MongoDB 문서와 매핑하는 모델을 만들어야 합니다. 여기서는 강의 데이터를 다루고 있으므로, 이에 해당하는 모델은 다음과 같습니다.

import mongoose, { Schema } from "mongoose";

const schema = new Schema({
  name: {
      required: true,
      type: String
  },
  description: {
      required: true,
      type: String
  },
  cover: {
    required: true,
    type: String
  },
  rating: {
    required: true,
    type: Number
  },
  price: {
    required: true,
    type: Number
  },
  createdOn: {
    type: { type: Date, default: Date.now }
  },
  link: {
    required: true,
    type: String
  },
  type: {
    required: true,
    type: String
  },
  comments: {
    required: false,
    type: [{ body: String, date: Date }]
  }
});

export const courses = mongoose.models.course ?? mongoose.model("course", schema);

Mongoose를 사용한 강의 모델

이제 마법이 시작됩니다! Next.js 앱 라우터를 사용하면 모든 컴포넌트가 기본적으로 서버 컴포넌트입니다. 이것은 서버 근처에 위치하고 서버 생태계에 액세스할 수 있음을 의미합니다.

아래 코드는 일반적인 Next.js 컴포넌트지만 특별한 기능이 있습니다. 이 컴포넌트에서 데이터베이스 연결을 직접 하여 어떤 state와 effect 관리를 하지 않고도 데이터를 직접 쿼리할 수 있습니다. 멋지죠?

이 컴포넌트에서 기록하는 모든 내용은 브라우저 콘솔에 찍히지 않습니다. 왜냐하면 이것은 서버 컴포넌트이기 때문입니다. 로그는 서버 콘솔에서 확인할 수 있습니다(아마도 yarn dev 명령을 사용하여 서버를 시작한 터미널에서).

데이터베이스와의 상호 작용은 비동기적 이므로, 호출 시 await 키워드를 사용하고 컴포넌트에는 async 키워드를 사용합니다. 응답을 받으면 이를 자식 컴포넌트에 props로 전달합니다.

import { dbConnect } from '@/services/mongo'
import { courses } from '@/models/courseModel'
import { addCourseToDB } from './actions/add-course'

import AddCourse from './components/AddCourse'
import CourseList from './components/CourseList'

export default async function Home() {

  // MongoDB 연결
  await dbConnect();
  
  // 모델을 이용하여 db로 부터 모든 강의를 가져옴.
  const allCourses = await courses.find().select(
  						["name", "cover", "rating"]);
  
  // 서버 콘솔에서 모든 출력값 표시
  console.log({allCourses})

  return (
    
      
        Courses 
        
          
      
    
  )
}

page.tsx - 서버 컴포넌트

Home 컴포넌트에는 아래 내용이 포함되어 있습니다.

제목(Heading)
강의 추가 버튼을 래핑한 컴포넌트(AddCourse)
강의 목록을 표시하는 컴포넌트(CourseList)

강의 목록 페이지

서버 컴포넌트는 클라이언트 및 서버 컴포넌트 모두 렌더링할 수 있다는 것을 알고 있습니다. AddCourse 컴포넌트는 사용자 인터렉션이 필요하며, 사용자가 버튼을 클릭하여 강의를 추가해야 합니다. 따라서 이는 서버 컴포넌트가 될 수 없습니다 (앞에서 읽은 서버 컴포넌트의 제한 사항을 기억하세요)!

그러므로 AddCourse를 위한 클라이언트 컴포넌트를 만들어 봅시다. Next.js 앱 라우터를 사용하면 모든 컴포넌트는 기본적으로 서버 컴포넌트입니다. 클라이언트 컴포넌트를 만들고 싶다면 해당 컴포넌트의 맨 위에서(import 문 이전에도 됨) 'use client'라는 지시문을 사용하여 명시적으로 만들어야 합니다.

'use client'

import { useState } from 'react';
import Modal from './Modal';
import AddCourseForm from "./AddCourseForm";

export default function AddCourse({
  addCourseToDB,
}: {
  addCourseToDB: (data: any) => Promise
}) {
  const [showAddModal, setShowAddModal] = useState(false);
  const add = async(data: any) => {
    await addCourseToDB(data);
    setShowAddModal(false);
  }

  return (
    <>
    
     setShowAddModal(false)} />} />
    
  )
}

AddCourse - 클라이언트 컴포넌트

CourseList 컴포넌트는 어떠한 이벤트 핸들러도 필요하지 않으므로, 서버 컴포넌트로 유지할 수 있습니다.

import Image from 'next/image'
import Link from 'next/link'

export default function CourseList(courseList: any) {
  const allCourses = courseList.allCourses;
  return(
    
      {
        allCourses.map((course: any) =>
        
          
            
            {course.name}
            {course.rating}
           
         
      )}
      
  )

}

CourseList - 서버 컴포넌트

또한 브라우저의 개발자 도구에서 Sources 탭을 확인하여 클라이언트에 다운로드되는 내용과 서버에 남아 있는 내용을 식별할 수 있습니다. 여기서 page.tsx 파일이나 CourseList.tsx 파일을 볼 수 있나요? 아니요. 왜냐하면 그것들은 서버 컴포넌트이며 클라이언트 번들의 일부가 아니기 때문입니다.

우리는 앱에서 명시적으로 클라이언트 컴포넌트라고 표시한 컴포넌트만 볼 수 있습니다.

클라이언트 번들 확인

이 애플리케이션의 흐름을 통해 이론이 실제와 어떻게 연결되는지 보여주었기를 바랍니다. 이제 React 앱에서 서버 컴포넌트를 사용하는 방법을 이해하셨을 것입니다.

요약

요약하면 다음과 같습니다.

React 서버 컴포넌트는 네트워크 왕복 없이 백엔드 접근이 가능합니다.
React 서버 컴포넌트를 통해 네트워크 워터폴을 피할 수 있습니다.
React 서버 컴포넌트는 자동 코드 분할(splitting)을 지원하며 번들 크기를 제로로 줄여 앱의 성능을 향상시킵니다.
이러한 컴포넌트는 서버 측에 있으므로 클라이언트 사이드 이벤트 핸들러, state 및 effect에 액세스할 수 없습니다. 이는 이벤트 핸들러나 useState, useReducer, useEffect와 같은 React 훅을 사용할 수 없음을 의미합니다.
React 서버 컴포넌트는 클라이언트 컴포넌트를 가져와 렌더링할 수 있지만, 반대로는 불가능 합니다. 그러나 서버 컴포넌트를 클라이언트 컴포넌트에 props로 전달할 수 있습니다.

마치기 전에..

이상으로 마무리합니다. 이 글이 유익하고 통찰력을 얻었기를 바랍니다.

저와 소통해보세요.

제 YouTube 채널인 tapaScript에서 교육을 진행하고 있습니다. JavaScript, ReactJS, Node.js, Git 및 웹 개발의 기본을 배우고 싶다면 구독해주세요.
웹 개발 및 프로그래밍 팁을 매일 놓치고 싶지 않다면 Twitter 또는 LinkedIn 팔로우를 해주세요.
GitHub에서 제 오픈 소스 작업을 확인해보세요.

다음 글에서 뵙겠습니다. 그 동안 자신을 돌보며 행복하게 지내세요.

자바스크립트 setTimeout()로 타이머 설정하기

Heegu Yang — Wed, 06 Dec 2023 13:53:35 +0000

기사 원문: JavaScript setTimeout() – How to Set a Timer in JavaScript or Sleep for N Seconds

이번 튜토리얼에서는 자바스크립트의 내장 함수인 setTimeout()이 어떻게 작동되는지 코드 예시를 통해 이해하는 시간을 가져보겠습니다.

자바스크립트에서 setTimeout() 사용하기

setTimeout()은 특정 시간이 지난 다음에 코드를 실행하는 함수입니다. 자바스크립트 코드에 일종의 타이머를 설정하는 것입니다.

setTimeout() 함수 예제

setTimeout(function(){
    console.log("Hello World");
}, 2000);

console.log("setTimeout() example...");

위 코드는 콘솔에 "setTimeout() example..."를 먼저 출력하고, 2초가 지난 다음 "Hello World"을 출력합니다.

setTimeout() 함수 문법은 이렇습니다:

setTimeout() 함수 문법

setTimeout(function, milliseconds, parameter1, parameter2, ...);

setTimeout() 함수의 첫 번째 매개변수에는 여러분이 실행시킬 자바스크립트 함수를 넣습니다. function에 함수 자체를 넣을 수도 있고, 아래와 같이 기명 함수로 넣기도 합니다.

setTimeout() 함수에 기명함수 사용한 예시

function greeting(){
  console.log("Hello World");
}

setTimeout(greeting);

그리고 다음 코드가 실행되기 전까지 기다리도록 milliseconds를 매개 변수로 전달할 수도 있습니다.

1초는 1,000 밀리초입니다. 만약 3초를 기다리게 하고 싶다면, 3000을 두 번째 매개 변수로 전달해야 합니다.

3초간 기다리는 setTimeout() 함수

function greeting(){
  console.log("Hello World");
}

setTimeout(greeting, 3000);

만약 두 번째 매개 변수를 생략한다면, setTimeout()은 function 함수를 즉시 실행합니다.

마지막으로, setTimeout() 함수에 매개 변수들을 추가로 넣을 수도 있습니다.

setTimeout()에 추가로 매개변수 전달하기

function greeting(name, role){
  console.log(`Hello, my name is ${name}`);
  console.log(`I'm a ${role}`);
}

setTimeout(greeting, 3000, "Nathan", "Software developer");

여러분은 아래와 같이 "함수에 바로 매개 변수를 바로 전달하면 안될까?"라고 물을 수도 있습니다.

setTimeout(greeting("Nathan", "Software developer"), 3000);

그럼 자바스크립트는 기다림 없이 function을 실행하게 됩니다. 왜냐하면 첫 번째 매개 변수로 함수 참조(function reference)가 아닌 함수 호출(function call)을 전달했기 때문입니다.

따라서 함수에 어떤 매개변수들을 전달하고 싶다면, setTimeout() 함수를 통해 전달해야 합니다.

그러나 setTimeout()에 추가적인 매개 변수를 전달하는 경우는 매우 드물기 때문에 이에 대해 크게 걱정하지 않아도 됩니다.

setTimeout 함수 취소하는 방법

clearTimeout()를 사용하면 setTimeout()의 함수 실행을 취소할 수 있습니다. 이를 위해 clearTimeout() 함수는 setTimeout()으로부터 반환된 id를 필요로 합니다.

clearTimeout() 문법

clearTimeout(id);

여기 clearTimeout() 함수를 사용하는 예시가 있습니다.

clearTimeout() 함수 활용 예시

const timeoutId = setTimeout(function(){
    console.log("Hello World");
}, 2000);

clearTimeout(timeoutId);
console.log(`Timeout ID ${timeoutId} has been cleared`);

만약 여러 개의 setTimeout() 함수들을 사용할 경우, 각 함수 호출에서 반환되는 ID 값들을 저장한 다음, 함수의 수 만큼 clearTimeout() 함수를 호출해야 합니다.

결론

setTimeout() 함수는 특정 함수의 실행 시기를 설정할 수 있는 자바스크립트 내장 함수입니다. 대기 시간을 전달하기 위해 밀리초 기준의 시간을 전달합니다. 예를 들어, 1초를 기다리게 하고 싶다면 1,000 밀리초를 입력하는 식이죠.

setTimeout()의 함수 실행을 취소하고 싶다면, clearTimeout() 함수를 사용하면 됩니다. 이때 setTimeout() 함수를 호출 시 반환되는 ID 값을 전달해야 합니다.

이 글을 읽어주셔서 감사합니다

자바스크립트에 대해 더 많이 알고싶으시다면, 저의 웹사이트 sebhastian.com를 방문하세요. 이곳에서 상세한 설명과 코드 예시가 포함된 자바스크립트 프로그래밍에 대한 100개 이상의 튜토리얼을 얻을 수 있습니다. 튜토리얼의 주제는 문자열 조작, 날짜 조작, 배열과 객체 함수, 자바스크립트 알고리즘 등 다양합니다.

파이썬 부분문자열(Substring) - 문자열(String)을 자르는 방법

Yeonsoo Jang — Fri, 27 Oct 2023 10:59:42 +0000

기사 원문: Python Substring – How to Slice a String

파이썬에서 문자열(string)은 문자(Characters)의 시퀀스로 특수문자 또는 알파벳, 숫자를 포함합니다.

예를 들어 “우리 금요일 08:00am에 만나자”라는 문자열이 있습니다. 여기서 보통 부분문자열(substring)이라고 알려져 있는 문자열의 특정 부분을 액세스 할 수 있습니다.

우리는 부분문자열을 문자열 안에 한 시퀀스로 정의할 수 있으며, 예제에서는 “금요일” “에” 그리고 “만나자” 가 될 수 있습니다.

파이썬으로 부분문자열을 생성하는 방법

파이썬은 부분문자열을 생성하고, 부분문자열의 존재 여부를 확인하고, 부분문자열의 인덱스를 추출하기 위한 다양한 방법과 메소드를 제공합니다.

다음과 같이 인덱스를 활용하여 문자열에서 부분문자열을 추출할 수 있습니다.
string[start:stop:step]

start – 부분문자열의 첫번째 인덱스
stop – 부분문자열의 마지막 인덱스
step – 슬라이싱의 간격을 의미하며, 기본값은 1입니다.

![substring index 표 설명] (https://www.freecodecamp.org/news/content/images/2021/07/image--2-.png)

인덱스는 양수일 수도 음수일 수도 있습니다. 양수 인덱스는 문자열의 첫번째 문자부터 시작해서 마지막 문자에서 끝이 나고, 음수 인덱스는 마지막 문자에서 시작하여 첫번째 문자에서 끝이 납니다.

이번 글에서는 파이썬에서 부분문자열과 관련한 다양한 조작방법을 다룹니다.

파이썬에서 첫번째 n 문자를 추출하는 방법

이 예제는 첫 다섯 문자를 추출하는 방법에 대해서 설명합니다.

string = "hello world"
print(string[:5])

여기서 stop 인덱스는 5로 설정하였고, start 인덱스는 기본값 0으로 설정됩니다.
결과값은 'hello'입니다.

파이썬에서 중간 문자를 추출하는 방법

이번 예제는 세번째 인덱스부터 다섯 번째 인덱스까지 추출하는 방법을 보여줍니다.

string = "hello world"
print(string[3:5])

결과값은 'lo'입니다.

마지막 문자를 추출하는 방법

마지막 문자를 추출하기 위해서는 -1 인덱스(음수 인덱스)를 사용합니다. 다음 예제를 확인해보세요.

string = "freecodecamp"
print(string[-1])

결과값은 'p'입니다.

마지막 n개 문자를 추출하는 방법

이번 예제에서는 음수 인덱스를 사용하여 마지막 4개 문자를 slicing합니다.

string = "freecodecamp"
print(string[-4:])

결과값은 'camp'입니다.

문자열에서 step을 이용해서 부분문자열을 슬라이싱하는 방법

당신은 start-index, stop-index 그리고 step을 이용해서 문자열을 자를 수 있습니다. 간격(step)은 기본값이 1이지만 다음 예제에서는 step 크기를 2로 설정합니다.

string = "welcome to freecodecamp"
print(string[::2])

결과값은 'wloet fecdcm'입니다.

부분문자열이 문자열에 포함되어있는지 확인하는 방법

부분문자열이 문자열에 포함되어 있는지 확인하고 싶을 때가 있습니다. 다음 예제는 부분문자열 ‘code’가 문자열에 포함되어 있는지를 확인합니다.

substring = "code"
string = "welcome to freecodecamp"
print(substring in string)

만약 포함되어 있다면 True 아니라면 False를 반환합니다.
여기러 결과값은 True 입니다.

부분문자열의 포함 여부를 확인하는 다른 방법

find() 메소드를 통해서 부분문자열이 문자열에 존재하는지를 확인할 수 있습니다.
다음 예제를 확인해봅시다.

substring = "zz"
string = "hello world"
print(string.find(substring))

부분문자열이 문자열에 포함되어 있다면 부분문자열 가장 왼쪽의 인덱스를 반환하고, 포함되어 있지 않다면 -1을 반환합니다.
예제에서 결과값은 -1로, ‘zz’는 ‘hello world’에 포함되어 있지 않음을 의미합니다.

문자열에서 주어진 인덱스에 해당하는 문자를 반환하는 방법

인덱스에 따라 특정 문자를 슬라이싱 할 수 있습니다.

string ="hello world"
print(string[4])

결과값은 ‘0’ 입니다.

파이썬으로 부분문자열의 리스트를 만드는 방법

split() 메소드를 사용하여 부분문자열의 리스트를 생성할 수 있습니다. 다음 예제를 확인해봅시다.

string = "welcome to freecodecamp platform"
print(string.split())

결과값은 ['welcome', 'to', 'freecodecamp', 'platform']입니다.

음수 step으로 문자열 뒤집기

문자열을 반대방향으로 뒤집기 위해서 step은 -1과 같은 음수 값이여야 합니다.

string = "welcome to freecodecamp"
print(string[::-1])

결과값은 ‘pmacedoceerf ot emoclew’입니다.

부분문자열이 문자열에 몇 번 나타났는지 세는 방법

count() 메소드를 통해 특정 부분문자열이 문자열에 몇 번 있는지 셀 수 있습니다.

string = "we will have a quick coding lesson this afternoon"
print(string.count('noon'))

결과값은 1입니다.

파이썬 부분문자열에 대한 마지막 이야기

축하합니다👏👏, 이 아티클의 끝까지 왔습니다! 파이썬 부분문자열에 대해서 새로운 것을 배우셨길 바랍니다.
만약 새로운 것을 배웠거나 이 아티클을 흥미롭게 읽었다면, 다른사람들도 볼 수 있도록 공유해 주세요. 그럼 다음 포스팅에서 만나요!

트위터에서도 저를 찾을 수 있습니다. @Davis_McDavid

이와 같은 아티클을 이 링크 를 통해서 더 많이 읽을 수 있습니다.

React와 React 훅으로 검색 필터 만드는 법

SeunghyunKim — Sat, 21 Oct 2023 10:32:03 +0000

기사 원문: How to Build a Search Filter using React and React Hooks

API에 GET 요청을 보내면 서버로부터 응답 데이터를 받습니다. 하지만 가끔은 이 데이터를 관리하는 게 문제가 되기도 합니다.

이 글에서는 React에서 검색 필터를 생성하는 법을 알려 드리려고 합니다. 함수형 컴포넌트와 React 훅을 이용하여 데이터에 있는 특정 단어를 검색할 것입니다.

API에 GET 요청을 보내는 법

우선 서버에서 데이터를 불러오는 API에 GET 요청을 만들어 보겠습니다. 이 데이터를 불러오기 위해 아무 서버를 사용해도 되지만 이 글에서 필자는 사용자 목록을 불러오기 위해 {JSON} placeholder를 사용할 것입니다.

이 예시에서 사용자들의 이름과 이메일을 보여주는 카드들이 있습니다. 또한 특정 사용자들 검색하기 위해 사용할 검색 입력 창이 있습니다.

import React, { useState, useEffect } from 'react';
import axios from 'axios';
import { Card, Input } from 'semantic-ui-react'
export default function Posts() {
    const [APIData, setAPIData] = useState([])
    useEffect(() => {
        axios.get(`https://jsonplaceholder.typicode.com/users`)
            .then((response) => {
                setAPIData(response.data);
            })
    }, [])
    return (
        
            
            
                {APIData.map((item) => {
                    return (
                        
                            
                                {item.name}
                                
                                    {item.email}
                                
                            
                        
                    )
                })}
            
        
    )
}

그리고 만약 React에서 GET API 호출을 다루는 법을 모르신다면 API 호출에 대해 설명하는 React CRUD 작업에 관한 제 블로그 혹은 비디오를 보시길 바랍니다.

검색 입력 박스로부터 검색 입력을 얻는 법

이제 검색 입력 박스로 부터 검색 쿼리(query)를 가져와 보겠습니다.

검색 입력을 위한 state를 생성합니다.

const [searchInput, setSearchInput] = useState('');

여기 searchInput은 문자열이고 검색 입력 값 설정을 위해 setSearchInput을 사용할 것입니다.

이제 검색 기능을 처리할 함수를 만들어 보겠습니다.

const searchItems = () => {
        
}

그리고 이 함수를 onChange 이벤트로 검색 입력에 바인드(bind)합니다.

 searchItems()}
/>

이리하여 입력 필드에 어떤 값이든 입력할 때마다 searchItems가 실행이 될 것입니다.

이제 searchItems에 입력 값을 전달해야 합니다.

 searchItems(e.target.value)}
/>

다음 검색 쿼리를 searchItems 함수에서 전달 받고 이전에 생성한 setSearchInput을 사용하여 searchInput state를 이 전달 받은 값으로 설정하겠습니다.

const searchItems = (searchValue) => {
    setSearchInput(searchValue)
}

콘솔로 searchValue 값을 확인함으로써 위 로직이 잘 실행되는지 확인할 수 있습니다.

보시다시피 필자의 이름을 입력했고 콘솔에서 이름이 나타납니다.

검색 결과에 따른 아이템 필터링

이제 filter 메소드를 사용하여 APIData를 필터링(filtering)할 것입니다.

const searchItems = (searchValue) => {
    setSearchInput(searchValue)
    APIData.filter((item) => {
        return Object.values(item).join('').toLowerCase().includes(searchInput.toLowerCase())
    })
}

searchItems 함수에서 서버로부터 얻는 데이터를 포함한 APIData state를 필터링하는 filter 메소드를 사용하고 있다는 것을 알 수 있습니다.

또한 객체 아이템으로부터 값들을 얻기 위해 Object.values를 사용하고 있습니다.

그런 다음 join(' ') 메소드를 사용하여 이 값들을 문자열로 바꾸어 줍니다.

다음 toLowerCase 메소드를 사용하여 이 문자열들을 소문자로 바꾸어 줍니다.

마지막으로 이 문자열들이 검색란에 입력한 값을 포함하고 있는지 확인합니다. 검색 입력 또한 소문자로 바꾸어 줍니다. 이는 단어를 대문자로 입력했을 시 검색을 더 효율적으로 만들어 주기 위해 그 문자열을 소문자로 바꾸게 하는 것입니다.

그런 다음 전체 쿼리를 반환합니다.

이제 이 필터링한 배열을 변수에 저장해야 합니다.

const filteredData = APIData.filter((item) => {
    return Object.values(item).join('').toLowerCase().includes(searchInput.toLowerCase())
})

콘솔을 통해 위에서 만든 기능을 확인해 보겠습니다. 사용자 이름을 검색해보면 해당 사용자 이름에 맞는 데이터를 보게 될 것입니다.

이제 필터 데이터를 저장해야 하므로 state를 생성하겠습니다.

const [filteredResults, setFilteredResults] = useState([]);

필터링한 데이터를 담은 state를 생성합니다.

그런 다음 setFilteredResults를 사용하여 searchItems 함수에서 이 state를 filteredData로 설정합니다.

const searchItems = (searchValue) => {
    setSearchInput(searchValue)
    const filteredData = APIData.filter((item) => {
        return Object.values(item).join('').toLowerCase().includes(searchInput.toLowerCase())
    })
    setFilteredResults(filteredData)
}

필터링 결과를 UI에 보여주는 법

이제 이 필터링 결과들을 주 UI에 보여주도록 하겠습니다.

우선 검색 입력란이 비어 있는지 확인하고 비어 있다면 모든 데이터를 보여주는 코드를 작성해야 합니다. 비어 있지 않다면 입력 값에 따라 결과를 필터링할 것입니다.

const searchItems = (searchValue) => {
    setSearchInput(searchValue)
    if (searchInput !== '') {
        const filteredData = APIData.filter((item) => {
            return Object.values(item).join('').toLowerCase().includes(searchInput.toLowerCase())
        })
        setFilteredResults(filteredData)
    }
    else{
        setFilteredResults(APIData)
    }
}

또한 애플리케이션의 반환 부분에서도 똑같은 확인이 필요합니다.

그래서 검색 단어의 길이가 1보다 크면 필터가 된 데이터를 보여줄 것입니다. 1보다 작다면 APIData state에 담긴 모든 데이터를 보여줄 것입니다.


    {searchInput.length > 1 ? (
        filteredResults.map((item) => {
            return (
                
                    
                        {item.name}
                        
                            {item.email}
                        
                    
                
            )
        })
    ) : (
        APIData.map((item) => {
            return (
                
                    
                        {item.name}
                        
                            {item.email}
                        
                    
                
            )
        })
    )}

이제 검색 필드에서 사용자 이름을 검색한다면 해당 사용자의 데이터를 얻게 됩니다.

검색 창에서 이름을 지우면 모든 데이터를 얻게 됩니다.

여기 참고할 분들을 위해 전체 코드를 적어 두겠습니다.

import React, { useState, useEffect } from 'react';
import axios from 'axios';
import { Card, Input } from 'semantic-ui-react'
export default function Posts() {
    const [APIData, setAPIData] = useState([])
    const [filteredResults, setFilteredResults] = useState([]);
    const [searchInput, setSearchInput] = useState('');
    useEffect(() => {
        axios.get(`https://jsonplaceholder.typicode.com/users`)
            .then((response) => {
                setAPIData(response.data);
            })
    }, [])
    const searchItems = (searchValue) => {
        setSearchInput(searchValue)
        if (searchInput !== '') {
            const filteredData = APIData.filter((item) => {
                return Object.values(item).join('').toLowerCase().includes(searchInput.toLowerCase())
            })
            setFilteredResults(filteredData)
        }
        else{
            setFilteredResults(APIData)
        }
    }
    return (
        
             searchItems(e.target.value)}
            />
            
                {searchInput.length > 1 ? (
                    filteredResults.map((item) => {
                        return (
                            
                                
                                    {item.name}
                                    
                                        {item.email}
                                    
                                
                            
                        )
                    })
                ) : (
                    APIData.map((item) => {
                        return (
                            
                                
                                    {item.name}
                                    
                                        {item.email}
                                    
                                
                            
                        )
                    })
                )}
            
        
    )
}

이제 React 훅을 이용하여 React에서 완전 함수형의 검색 필터를 가지게 되었습니다.

보통 이 기능은 API 엔드포인트에서 검색 쿼리 인자를 전달하여 백엔드에서 처리하지만 프론트엔드에서 그 기능을 처리하는 것을 아는 것도 중요합니다.

이 글에 대한 보충 설명이 필요하다면 React와 React 훅을 이용하여 검색 필터 만들기에 관한 제 유투브 비디오를 확인하시면 되겠습니다.

이상 마무리 짓겠습니다. 감사합니다.

자바스크립트 프로미스 튜토리얼 - 자바스크립트의 프로미스를 이행하거나 거부하는 방법

Nayoung Gu — Sat, 21 Oct 2023 10:29:46 +0000

기사 원문: JavaScript Promise Tutorial – How to Resolve or Reject Promises in JS

`프로미스`는 자바스크립트에서 비동기 처리를 위한 중요한 요소이지만 프로미스를 이해하고 적용하는 것은 그렇게 쉽지 않다고 생각하셨을 수도 있습니다. 하지만 절 따라오세요, 여러분은 혼자가 아닙니다!

프로미스는 프로미스를 몇 년 동안 다뤄본 많은 웹 개발자들에게도 어려운 주제입니다.

이 글에서는 제가 지난 몇 년간 자바스크립트의 프로미스에 대해 배운 내용을 공유하면서 이러한 인식을 한번 깨보겠습니다. 도움이 되었으면 좋겠습니다.

자바스크립트의 프로미스란

프로미스는 자바스크립트의 특수 객체입니다. 프로미스는 비동기 작업이 성공적으로 수행되면 값을 생성하고, 시간 초과나 네트워크 오류 등으로 인해 실패하면 에러를 생성합니다.

성공적인 이행은 resolve 함수 호출, 그리고 에러는 reject 함수 호출을 통해 확인할 수 있습니다.

프로미스는 다음과 같이 생성자를 통해 만들 수 있습니다.

let promise = new Promise(function(resolve, reject) {    
    // 비동기 호출 후 resolve 혹은 reject 하는 곳
});

대부분의 경우 프로미스는 비동기 처리에 사용됩니다. 하지만 엄밀히 말하면 동기와 비동기 작업을 모두 이행/거절할 수 있습니다.

잠시만요, 비동기 작업을 위한 `콜백` 함수가 있지 않나요?

네! 맞아요. 자바스크립트에는 콜백 함수가 있습니다. 하지만 콜백은 자바스크립트에서 특별한 개념은 아닙니다. 비동기 호출이 (성공 또는 에러와 함께) 완료되면 결과를 반환하는 일반 함수입니다.

비동기란 지금 당장이 아니라 미래에 발생한다는 의미입니다. 콜백은 주로 네트워크 통신, 업로드/다운로드, 데이터베이스 조회 등과 같은 상황에서 사용됩니다.

콜백은 유용하긴 하지만 엄청난 단점도 가지고 있습니다. 때로 다른 콜백에 포함된 콜백 내부에 또 다른 콜백이 있을 수도 있습니다. 진심으로요! 이 "콜백 헬"을 예시와 함께 이해해봅시다.

콜백 헬을 피하는 방법 - PizzaHub 예시

PizzaHub에서 🍕 야채 마르게리타 피자를 주문한다고 해봅시다. 주문을 넣으면 PizzaHub은 자동적으로 우리의 위치를 파악하고 근처의 피자 가게를 찾은 뒤 우리가 요청한 피자가 주문 가능한지 찾아볼 것입니다.

주문이 가능하다면 피자와 함께 무료로 받을 수 있는 음료를 파악하고 마침내 주문을 넣게 됩니다.

주문이 성공적으로 완료되면 확인 문자를 받게 됩니다.

이 과정을 콜백 함수를 사용해 코드로 표현하면 어떨까요? 다음과 같이 생각해 봤습니다.

function orderPizza(type, name) {

    // pizzahub에 문의하기
    query(`/api/pizzahub/`, function(result, error){
       if (!error) {
           let shopId = result.shopId;

           // 가게에 피자 문의하기
           query(`/api/pizzahub/pizza/${shopid}`, function(result, error){
               if (!error) {
                   let pizzas = result.pizzas;

                   // 피자 가능 여부 확인
                   let myPizza = pizzas.find((pizza) => {
                       return (pizza.type===type && pizza.name===name);
                   });

                   // 무료 음료 확인
                   query(`/api/pizzahub/beverages/${myPizza.id}`, function(result, error){
                       if (!error) {
                           let beverage = result.id;

                           // 주문 준비
                           query(`/api/order`, {'type': type, 'name': name, 'beverage': beverage}, function(result, error){
                              if (!error) {
                                  console.log(`Your order of ${type} ${name} with ${beverage} has been placed`);
                              } else {
                                  console.log(`Bad luck, No Pizza for you today!`);
                              }
                           });

                       }
                   })
               }
           });
       } 
    });
}

// orderPizza 메서드 호출
orderPizza('veg', 'margherita');

위의 orderPizza 함수를 잘 살펴봅시다.

이 함수는 근처 피자 가게의 id를 찾기 위해 API를 호출합니다. 그리고 그 가게에서 주문 가능한 피자의 리스트를 받습니다. 그 중에 주문한 피자가 있는지 확인하고 그 피자와 함께 오는 음료를 확인하기 위해 또 다른 API 호출을 하게 됩니다. 최종적으로 주문 API를 통해 주문을 넣게 됩니다.

여기서 모든 API에 콜백을 사용하고 있습니다. 이 때문에 계속해서 콜백 안에 콜백을 넣는 방식으로 코드를 작성하게 됩니다.

이렇게 해서 우리는 콜백 지옥에 빠지게 됩니다. 누가 이런 코드를 원할까요? 게다가 가독성이 좋지 않고 에러가 발생하기도 쉬운 코드 피라미드가 생겨나게 됩니다.

콜백 지옥 및 멸망의 피라미드 예시

콜백 지옥을 빠져나오거나 들어가지 않을 수 있는 몇 가지 방법들이 있습니다. 가장 흔한 방법은 프로미스나 비동기 함수를 사용하는 것입니다. 하지만 async 함수를 잘 이해하려면 프로미스를 먼저 잘 이해해야 합니다.

그럼 프로미스에 대해서 시작해 봅시다.

프로미스의 상태 이해하기

복습해보자면, 프로미스는 다음과 같은 생성자 문법을 통해 생성될 수 있습니다.

let promise = new Promise(function(resolve, reject) {
  // 실행할 함수
});

생성자 함수는 인자로 함수를 받습니다. 이 함수는 실행 함수라고 불립니다.

// 실행 함수는 프로미스 생성자 함수에 인자로 전달된다
function(resolve, reject) {
    // 로직이 위치할 곳
}

실행 함수는 resolve와 reject라는 두 가지 인자를 받습니다. 이 둘은 자바스크립트에 의해 제공되는 콜백 함수입니다. 여러분이 작성할 로직은 new Promise가 생성되면 자동적으로 호출될 실행 함수 안에 위치하게 됩니다.

프로미스를 효과적으로 사용하려면 실행 함수는 resolve 혹은 reject 콜백 함수들 중 하나를 호출해야 합니다. 이 둘에 대해선 잠시 후에 더 자세히 배워보겠습니다.

new Promise() 생성자는 프로미스 객체를 반환합니다. 실행 함수는 비동기 처리를 다루기 때문에, 반환된 프로미스 객체는 작업이 시작되거나, 완료될 때 (resolved), 그리고 에러를 반환할 때(rejected)를 알려줄 수 있어야 합니다.

프로미스 객체는 다음과 같은 내부 프로퍼티를 갖습니다.

state(상태) - 이 프로퍼티는 다음과 같은 값을 갖습니다.

pending(대기): 실행 함수가 작업을 시작했을 때
fulfilled(이행): 프로미스가 이행되었을 때
rejected(거부): 프로미스가 거부되었을 때

프로미스의 세 가지 상태

result(결과) - 이 프로퍼티는 다음과 같은 값을 갖습니다.

undefined: 상태 값이 대기 중일 때
value: resolve(value)가 호출되었을 때
error: reject(error)가 호출되었을 때

이 내부 프로퍼티들은 코드로 접근할 수는 없지만 확인은 가능합니다. 즉 디버거 도구를 활용해 state와 result 프로퍼티 값을 확인할 수 있지만 직접적으로 프로그램을 사용해 접근할 수는 없습니다.

프로미스의 내부 프로머티를 확인할 수 있다

프로미스의 상태는 pending, fulfilled 혹은 rejected가 될 수 있습니다. 이행(resolved) 또는 거부(rejected)된 프로미스는 settled 되었다고 표현합니다.

처리(settled)된 프로미스는 이행(fulfilled) 혹은 거부(rejected)된 것이다

프로미스가 이행되거나 거부되는 방법

다음은 I am done이라는 값과 함께 즉시 이행되는(fulfilled 상태) 프로미스의 예시입니다.

let promise = new Promise(function(resolve, reject) {
    resolve("I am done");
});

다음은 Something is not right!이라는 에러 메세지와 함께 거절되는 (rejected 상태) 프로미스입니다.

let promise = new Promise(function(resolve, reject) {
    reject(new Error('Something is not right!'));
});

주의할 점

프로미스 실행 함수는 오직 하나의 resolve 혹은 reject 함수를 호출해야 합니다. 상태가 한번 변경되면 (pending => fulfilled 혹은 pending => rejected) 끝이기 때문입니다. 그 이후의 resolve 혹은 reject는 무시됩니다.

let promise = new Promise(function(resolve, reject) {
  resolve("I am surely going to get resolved!");

  reject(new Error('Will this be ignored?')); // 무시됨
  resolve("Ignored?"); // 무시됨
});

위의 예시에서, 오직 첫 번째 것만 이행되고 나머지 것들은 모두 무시됩니다.

프로미스를 만들고 처리하는 방법

프로미스는 (대부분 비동기적으로) 작업을 처리하기 위해 실행 함수를 사용합니다. (프로미스의 결과를 사용하는) 소비 함수는 실행 함수가 이행(성공)되거나 거부된(에러) 시점을 알아야 합니다.

.then(), .catch(), finally()와 같은 핸들러 메서드는 실행 함수와 소비 함수를 이어줌으로써 프로미스가 이행되거나 거부되었을 때 서로 동기화될 수 있도록 해줍니다.

실행 함수와 소비 함수

`.then()` 메서드를 사용하는 방법

.then() 메서드는 결과(resolve) 또는 에러(reject)를 다룰 때 프로미스 객체에 의해 호출됩니다.

이 메서드는 인자로 두 개의 함수를 받습니다. 보통 .then() 메서드는 프로미스의 실행 결과를 알고자 하는 소비 함수로부터 실행되어야 합니다.

promise.then(
  (result) => { 
     console.log(result);
  },
  (error) => { 
     console.log(error);
  }
);

성공했을 때의 결과만 알고 싶다면 다음과 같이 하나의 인자만 전달해줄 수도 있습니다.

promise.then(
  (result) => { 
      console.log(result);
  }
);

실패한 결과만 다루고 싶다면 다음과 같이 첫 번째 인자로 null을 전달해주면 됩니다.

promise.then(
  null,
  (error) => { 
      console.log(error)
  }
);

하지만 잠시후에 보게될 .catch() 메서드를 사용하면 더 나은 방법으로 에러를 처리할 수 있습니다.

.then()과 .catch() 핸들러를 사용해서 결과와 에러를 처리한 몇가지 예시를 살펴봅시다. 몇 가지 실제 비동기 요청을 통해서 더 재밌게 배워보겠습니다. 포켓몬에 대한 정보를 얻고 그 결과를 프로미스를 사용해서 이행/거부하기 위해 PokeAPI를 사용하겠습니다.

먼저, PokeAPI URL을 인자로 받은 뒤 프로미스를 반환하기 위한 제네릭 함수를 만듭니다. API 호출이 성공적으로 이루어지면 이행된 프로미스가 반환됩니다. 거부된 프로미스는 어떠한 종류의 에러로부터 반환될 수 있습니다.

이제부터 프로미스를 만들어 작업하기 위해 여러 예시에서 이 함수를 사용하겠습니다.

function getPromise(URL) {
  let promise = new Promise(function (resolve, reject) {
    let req = new XMLHttpRequest();
    req.open("GET", URL);
    req.onload = function () {
      if (req.status == 200) {
        resolve(req.response);
      } else {
        reject("There is an Error!");
      }
    };
    req.send();
  });
  return promise;
}

프로미스를 위한 유틸리티 메서드

예시 1: 50가지의 포켓몬 정보 얻기

const ALL_POKEMONS_URL = 'https://pokeapi.co/api/v2/pokemon?limit=50';

// 아래 함수는 위에서 언급했었죠!
let promise = getPromise(ALL_POKEMONS_URL);

const consumer = () => {
    promise.then(
        (result) => {
            console.log({result}); // 50 가지의 포켓몬 결과 출력
        },
        (error) => {
            // 유효한 URL이라면 실행되지 않는 부분
            console.log('We have encountered an Error!'); // 에러 출력
    });
}

consumer();

예시 2: 유효하지 않은 URL일 때

const POKEMONS_BAD_URL = 'https://pokeapi.co/api/v2/pokemon-bad/';

// 아래 코드는 URL의 404 에러로 인해 거절됩니다
let promise = getPromise(POKEMONS_BAD_URL);

const consumer = () => {
    promise.then(
        (result) => {
            // 프로미스는 이행(resolve)되지 않았기 때문에 이 부분은 실행되지 않습니다.
            console.log({result});
        },
        (error) => {
            // 거절된(rejected) 프로미스는 이 부분을 실행할 것입니다.
            console.log('We have encountered an Error!'); // 에러 출력
        }
    );
}

consumer();

`.catch()` 메서드를 사용하는 방법

프로미스의 에러(거부)를 다룰 때 이 메서드를 사용할 수 있습니다. .then()의 첫 번째 인자로 null을 전달해주는 문법은 에러를 다루기 좋은 방법은 아닙니다. 그래서 같은 작업을 위해 .catch()를 사용해 더 깔끔한 문법으로 작성할 수 있습니다.

// 유효하지 않은 URL(404 에러)로 인해 거부될 프로미스
let promise = getPromise(POKEMONS_BAD_URL);

const consumer = () => {
    promise.catch(error => console.log(error));
}

consumer();

프로미스 실행 함수나 핸들러에서 reject 함수를 실행하는 대신 new Error("Something wrong!")과 같은 에러를 던지게 되면 이 프로미스는 거부된 것으로 해석될 것입니다. 즉 .catch 핸들러 메서드에 의해 에러가 잡히게 됩니다.

프로미스 실행 함수와 핸들러 함수에서 일어나는 동기적인 예외 상황에서도 같게 동작합니다.

다음은 프로미스가 거부된 것으로 처리되어 .catch 핸들러 메서드가 호출된 예시입니다.

new Promise((resolve, reject) => {
  throw new Error("Something is wrong!");// reject 함수를 실행하지 않습니다
}).catch((error) => console.log(error));

`.finally()` 메서드를 사용하는 방법

.finally() 핸들러는 로더를 멈추거나 실시간 연결을 끊는 등 정리를 위해 사용됩니다. finally 메서드는 프로미스의 성공이나 거부 여부와 상관 없이 실행됩니다. 이 메서드는 .then()이나 .catch()를 또 실행할 수 있는 다음 핸들러에게 결과 값이나 에러를 전달합니다.

세 메서드를 함께 이해할 수 있는 예시를 살펴보겠습니다.

let loading = true;
loading && console.log('Loading...');

// 프로미스 얻기
promise = getPromise(ALL_POKEMONS_URL);

promise.finally(() => {
    loading = false;
    console.log(`Promise Settled and loading is ${loading}`);
}).then((result) => {
    console.log({result});
}).catch((error) => {
    console.log(error)
});

추가 설명

.finally() 메서드는 로딩을 false로 설정합니다.
프로미스가 이행되면 .then() 메서드가 실행됩니다. 프로미스가 에러와 함께 거부되면 .catch() 메서드가 실행됩니다. .finally()는 이행 혹은 거부와는 관계 없이 실행됩니다.

프로미스 체인이란

promise.then()은 항상 프로미스를 반환합니다. 이 프로미스는 pending이라는 상태와 undefined라는 결과를 갖게될 것입니다. 이를 통해 다음 프로미스에 .then 메서드를 호출할 수 있게 해줍니다.

첫 번째 .then 메서드가 반환한 결과 값은 다음 .then 메서드가 받을 수 있습니다. 두 번째 결과는 이제 세 번째 .then()으로 전달될 수 있고 이런 방식으로 계속 이어질 수 있습니다. 이 방식은 프로미스를 밑으로 전달해주는 .then 메서드 체인을 형성합니다. 이 현상은 프로미스 체인이라고 불립니다.

프로미스 체인

다음 예제를 봅시다.

let promise = getPromise(ALL_POKEMONS_URL);

promise.then(result => {
    let onePokemon = JSON.parse(result).results[0].url;
    return onePokemon;
}).then(onePokemonURL => {
    console.log(onePokemonURL);
}).catch(error => {
    console.log('In the catch', error);
});

먼저 프로미스를 이행하고 첫번째 포켓몬을 얻기 위한 URL을 추출합니다. 그렇게 얻은 결과는 프로미스 형태로 다음 .then() 핸들러로 전달됩니다. 결과는 다음과 같습니다.

https://pokeapi.co/api/v2/pokemon/1/

.then 메서드는 다음 중 하나를 반환합니다.

결과 (이미 살펴본 것이죠)
새로운 프로미스

에러를 반환할 수도 있습니다.

다음 예시는 결과와 새로운 프로미스를 반환하는 .then 메서드로 이루어진 프로미스 체인을 만든 것입니다.

// 다수의 then과 catch로 이루어진 프로미스 체인
let promise = getPromise(ALL_POKEMONS_URL);

promise.then(result => {
    let onePokemon = JSON.parse(result).results[0].url;
    return onePokemon;
}).then(onePokemonURL => {
    console.log(onePokemonURL);
    return getPromise(onePokemonURL);
}).then(pokemon => {
    console.log(JSON.parse(pokemon));
}).catch(error => {
    console.log('In the catch', error);
});

첫 번째 .then()은 추출한 URL을 결과로 반환합니다. 이 URL은 해당 URL을 인자로 받는 새로운 프로미스를 반환하는 두 번째 .then으로 전달됩니다.

이 프로미스가 이행되면 포켓몬에 대한 정보 얻을 수 있는 체인으로 전달됩니다. 결과는 다음과 같습니다.

프로미스 체인의 결과

에러나 프로미스 거부가 발생하면 프로미스 체인의 .catch 메서드가 실행됩니다.

중요한 점: .then을 여러번 호출한다고 프로미스 체인이 생성되는 것은 아닙니다. 다음과 같이 코드를 작성하면 버그만 발생할 것입니다.

let promise = getPromise(ALL_POKEMONS_URL);

promise.then(result => {
    let onePokemon = JSON.parse(result).results[0].url;
    return onePokemon;
});
promise.then(onePokemonURL => {
    console.log(onePokemonURL);
    return getPromise(onePokemonURL);
});
promise.then(pokemon => {
    console.log(JSON.parse(pokemon));
});

같은 프로미스에 .then 메서드를 세 번 호출하고 있지만 프로미스를 전달하고 있지는 않습니다. 이것은 프로미스 체인과는 다릅니다. 위 예시의 결과로 에러가 나올 것입니다.

여러 개의 프로미스를 처리하는 방법

.then, .catch, .finally 같은 핸들러 메서드와는 별개로 프로미스 API에서 사용 가능한 여섯 가지의 정적 메서드가 있습니다. 첫 네 개의 메서드들은 프로미스 배열을 받아 병렬적으로 실행합니다.

Promise.all
Promise.any
Promise.allSettled
Promise.race
Promise.resolve
Promise.reject

하나씩 살펴봅시다.

Promise.all() 메서드

Promise.all([promises])는 인자로 프로미스의 집합(예를 들면, 배열)을 받고 병렬로 실행시킵니다.

이 메서드는 모든 프로미스가 이행(resolve)되기를 기다린 후에 프로미스의 결과를 배열로 반환합니다. 만약 프로미스 중 어떤 하나라도 거절(reject)되거나 에러로 인해 실패한다면 다른 모든 프로미스의 결과는 무시될 것입니다.

세 마리의 포켓몬에 대한 정보를 얻기 위해 세 개의 프로미스를 생성해봅시다.

const BULBASAUR_POKEMONS_URL = 'https://pokeapi.co/api/v2/pokemon/bulbasaur';
const RATICATE_POKEMONS_URL = 'https://pokeapi.co/api/v2/pokemon/raticate';
const KAKUNA_POKEMONS_URL = 'https://pokeapi.co/api/v2/pokemon/kakuna';

let promise_1 = getPromise(BULBASAUR_POKEMONS_URL);
let promise_2 = getPromise(RATICATE_POKEMONS_URL);
let promise_3 = getPromise(KAKUNA_POKEMONS_URL);

Promise.all() 메서드에 프로미스 배열을 전달해 사용합니다.

Promise.all([promise_1, promise_2, promise_3]).then(result => {
    console.log({result});
}).catch(error => {
    console.log('에러 발생');
});

결과:

결과에서 볼 수 있듯, 모든 프로미스의 결과가 반환됩니다. 모든 프로미스를 실행시키는 시간은 프로미스가 실행되는 데 걸리는 최대 시간과 같습니다.

Promise.any() 메서드

all() 메서드와 비슷한 Promise.any([promises]) 또한 병렬로 처리할 프로미스를 배열로 받습니다. 이 메서드는 모든 프로미스가 이행(resolve)되기를 기다리지 않습니다. 프로미스 중 하나라도 settled 되면 이행이 종료됩니다.

 Promise.any([promise_1, promise_2, promise_3]).then(result => {
     console.log(JSON.parse(result));
 }).catch(error => {
     console.log('에러 발생');
 });

결과는 이행(resolve)된 프로미스 중 하나가 될 것입니다.

Promise.allSettled() 메서드

Promise.allSettled([promises]) 메서드는 모든 프로미스가 settled(resolve/reject) 되기를 기다린 후에 객체로 구성된 배열을 결과로 반환합니다. 성공적으로 이행된다면 결과는 상태(fulfilled/rejected)와 결괏값을 포함할 것입니다. 거절된(rejected) 상태라면 에러에 대한 이유를 반환할 것입니다.

이행된 프로미스들의 예시를 살펴보겠습니다.

Promise.allSettled([promise_1, promise_2, promise_3]).then(result => {
    console.log({result});
}).catch(error => {
    console.log('에러입니다!');
});

결과:

프로미스 중 하나인 promise_1이 거부된다면 다음과 같은 결과가 나옵니다.

let promise_1 = getPromise(POKEMONS_BAD_URL);

Promise.race() 메서드

Promise.race([promises])는 (가장 빠른) 첫번째 프로미스가 settled 되기를 기다린 후에 그에 따른 결과/에러를 반환합니다.

Promise.race([promise_1, promise_2, promise_3]).then(result => {
    console.log(JSON.parse(result));
}).catch(error => {
    console.log('에러 발생');
});

이행된(resolved) 가장 빠른 프로미스의 결과는 다음과 같습니다.

Promise.resolve/reject 메서드

Promise.resolve(value)는 전달된 값과 함께 프로미스를 이행합니다. 다음과 같습니다.

let promise = new Promise(resolve => resolve(value));

Promise.reject(error)은 다음과 같이 전달된 에러와 함께 프로미스를 거부합니다.

let promise = new Promise((resolve, reject) => reject(error));

PizzaHub 예시를 프로미스로 바꿀 수 있나요?

그럼요, 한번 해봅시다. query 메서드가 프로미스를 반환한다고 가정해봅시다. 여기 query() 메서드의 예시가 있습니다. 실제로 이 메서드는 데이터베이스와 소통해서 결과를 반환합니다. 지금 경우에는 하드코딩되어 있지만 같은 역할을 수행합니다.

function query(endpoint) {
  if (endpoint === `/api/pizzahub/`) {
    return new Promise((resolve, reject) => {
      resolve({'shopId': '123'});
    })
  } else if (endpoint.indexOf('/api/pizzahub/pizza/') >=0) {
    return new Promise((resolve, reject) => {
      resolve({pizzas: [{'type': 'veg', 'name': 'margherita', 'id': '123'}]});
    })
  } else if (endpoint.indexOf('/api/pizzahub/beverages') >=0) {
    return new Promise((resolve, reject) => {
      resolve({id: '10', 'type': 'veg', 'name': 'margherita', 'beverage': 'coke'});
    })
  } else if (endpoint === `/api/order`) {
    return new Promise((resolve, reject) => {
      resolve({'type': 'veg', 'name': 'margherita', 'beverage': 'coke'});
    })
  }
}

다음은 콜백 지옥을 리팩토링 해보겠습니다. 이를 위해 먼저 몇개의 논리적인 함수를 만들겠습니다.

// 가게 id 반환
let getShopId = result => result.shopId;

// 가게의 피자 리스트가 담긴 프로미스 반환
let getPizzaList = shopId => {
  const url = `/api/pizzahub/pizza/${shopId}`;
  return query(url);
}

// 고객의 요청에 맞는 피자를 프로미스로 반환
let getMyPizza = (result, type, name) => {
  let pizzas = result.pizzas;
  let myPizza = pizzas.find((pizza) => {
    return (pizza.type===type && pizza.name===name);
  });
  const url = `/api/pizzahub/beverages/${myPizza.id}`;
  return query(url);
}

// 주문 후 프로미스 반환
let performOrder = result => {
  let beverage = result.id;
   return query(`/api/order`, {'type': result.type, 'name': result.name, 'beverage': result.beverage});
}

// 주문 확인
let confirmOrder = result => {
    console.log(`Your order of ${result.type} ${result.name} with ${result.beverage} has been placed!`);
}

필요한 프로미스를 만들기 위해 위 함수들을 사용합니다. 여기서 콜백 지옥 예제와 비교해볼 수 있습니다. 아래 코드는 확실히 깔끔하고 우아하네요.

function orderPizza(type, name) {
  query(`/api/pizzahub/`)
  .then(result => getShopId(result))
  .then(shopId => getPizzaList(shopId))
  .then(result => getMyPizza(result, type, name))
  .then(result => performOrder(result))
  .then(result => confirmOrder(result))
  .catch(function(error){
    console.log(`Bad luck, No Pizza for you today!`);
  })
}

마지막으로 다음과 같이 피자 종류와 이름을 전달해서 orderPizza() 메서드를 호출합니다.

orderPizza('veg', 'margherita');

다음으로 배울 내용

여기까지 거의 읽으셨다면 축하드립니다! 이제 여러분은 자바스크립트의 프로미스에 대해 더 잘 이해할 수 있으실 겁니다. 이 글에서 사용된 모든 예제는 이 깃허브 레포지토리에 있습니다.

다음으로는 더 간단하게 코드를 작성할 수 있는 자바스크립트의 async 함수를 배울 차례입니다. 자바스크립트의 프로미스를 학습할 수 있는 가장 좋은 방법은 작은 예제를 만들고 쌓아가는 것입니다.

Angular, React, Vue 등과 같은 프레임워크나 라이브러리 사용과는 관계 없이 비동기 처리는 필수적입니다. 즉, 일을 더 잘 처리하기 위해선 프로미스를 이해해야 합니다.

또한 이제 여러분은 fetch 메서드가 더 쉽게 느껴지실 겁니다.

fetch('/api/user.json')
.then(function(response) {
    return response.json();
})
.then(function(json) {
    console.log(json); // {"name": "tapas", "blog": "freeCodeCamp"}
});

fetch 메서드는 프로미스를 반환합니다. 그래서 여기에 .then 핸들러를 호출할 수 있습니다.
나머지는 우리가 글에서 배웠던 프로미스 체인에 관한 내용입니다.

마치기 전에

지금까지 읽어주셔서 감사합니다. 트위터(@tapasadhikary)에서 소통해요.

좋아하실 만한 글들을 추천드릴게요.

여기까지입니다. 다음 글에서 만나요. 그때까지 모두 잘 지내세요.

freeCodeCamp Programming Tutorials: Python, JavaScript, Git & More

Node.js와 함께 Docker를 사용하는 방법: 개발자를 위한 핸드북

전제조건

목차

컨테이너란 무엇인가?

컨테이너는 어디에 있나요?

Docker vs 가상 머신

Docker 설치

기본 Docker 명령어

이미지 버전 지정 방법:

컨테이너 중지, 시작, 삭제 방법:

컨테이너 재시작 방법

여러 Redis 컨테이너를 실행하고 포트를 이해하는 방법

동일한 포트에서 다른 Redis 컨테이너 실행 시도하기

포트 바인딩이란 무엇인가?

다른 호스트 포트에서 두 번째 Redis 컨테이너 실행하기

포트 바인딩이 존재하는 이유

컨테이너 탐색 방법

docker run vs docker start

JavaScript로 연습하기

MongoDB 이미지를 가져오는 방법

Mongo Express 이미지 가져오기 방법

Docker 네트워크

Mongo 컨테이너 실행 방법

Mongo Express 컨테이너 실행 방법

Node.js를 MongoDB에 연결하는 방법

Node.js 백엔드

프론트엔드

Todo List with Images

Todos

Docker Compose 사용 방법

Docker Compose를 사용하는 이유

이 출력이 의미하는 것

나만의 Docker 이미지 빌드하는 방법

Node.js 앱 컨테이너 실행

오류 해결

왜 이런 일이 발생하는가:

해결책

왜 mongodb가 작동하는가

Docker 이미지 재빌드

Docker Compose에 앱 추가

모든 서비스 시작

모든 것이 작동하는지 확인

무엇이 변경되었고 왜 작동하는가

컨테이너 관리 방법

프라이빗 Docker 레지스트리 생성 방법

1단계: AWS 액세스 키 가져오기

2단계: AWS CLI 설치 여부 확인

3단계: AWS CLI에 자격 증명 설정

4단계: AWS 설정 테스트

Docker 이미지 명명 방식 이해하기

6단계: 이미지 빌드, 태그, 푸시

과제: 앱의 새 버전 만들기 및 푸시하기

이미지 배포하기

왜 서비스 이름을 “todo-app”이 아니라 “my-app”으로 했을까?

왜 ECR에는 전체 이미지 URL을 써야 할까?

Docker Compose로 앱 배포하기

프라이빗 Docker 이미지 공유하기

1. IAM 권한 부여

2. AWS CLI 설치 및 설정

3. Docker를 ECR에 인증시키기

4. 이미지 Pull

5. 컨테이너 실행

Docker 볼륨

Docker 볼륨의 동작 방식

Docker 볼륨의 종류

1. 네임드 볼륨(Named Volumes)

2. 바인드 마운트(Bind Mounts)

3. 익명 볼륨(Anonymous Volumes)

볼륨을 사용하는 Docker Compose 예제

시각적 개념(단순화):

핵심 정리 (Takeaways)

애플리케이션 시작하기

결론

JSON Web Token 핸드북: 웹 인증을 위한 JWT 활용 가이드

이 글에서 다룰 내용

사전 지식

JWT란 무엇인가?

왜 토큰이 필요한가?

세션 토큰(Session Token): 고전적인 방식

`docker run` vs `docker start`

왜 `mongodb`가 작동하는가