애플리케이션 개발 시 API 키와 같은 민감한 정보는 소스 코드에 직접 작성하지 않고 안전하게 관리하는 것이 매우 중요합니다. VS Code에서 Python을 사용할 때, API 키를 관리하는 가장 일반적인 두 가지 방법인 시스템 환경 변수와 .env 파일에 대해 단계별로 상세히 정리합니다.
[ 방법 1: 시스템 환경 변수에 API 키 저장 및 사용 ]
시스템 환경 변수는 운영 체제 전체에서 접근할 수 있는 전역 변수입니다. 이 방법을 사용하면 한 번만 설정하면 해당 컴퓨터의 모든 프로그램에서 API 키를 사용할 수 있습니다.
단계 1: 시스템 환경 변수에 API 키 설정하기
a) Windows (PowerShell 사용)
PowerShell을 관리자 권한으로 실행합니다.시작 메뉴에서 powershell을 검색한 후, Windows PowerShell을 마우스 오른쪽 버튼으로 클릭하고 관리자 권한으로 실행을 선택합니다.
다음 명령어를 입력하여 사용자 환경 변수에 API 키를 설정합니다. 'your_api_key' 부분에 실제 OpenAI API 키를 붙여넣기 합니다. [System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY','your_api_key','User')
PowerShell 창을 닫고 다시 새로 엽니다. 환경 변수는 새로운 세션에서부터 적용됩니다.
b) macOS 또는 Linux (Bash/Zsh 터미널 사용)
터미널을 엽니다.
다음 명령어를 입력하여 .bash_profile 또는 .zshrc 파일을 편집합니다.
Bash 사용자: nano ~/.bash_profile
Zsh 사용자: nano ~/.zshrc
파일의 맨 아래에 다음 줄을 추가합니다. 'your_api_key' 부분에 실제 API 키를 넣습니다. export OPENAI_API_KEY='your_api_key'
파일을 저장하고 종료합니다. (Ctrl + X, Y, Enter)
다음 명령어를 입력하여 변경 사항을 적용합니다.
Bash 사용자: source ~/.bash_profile
Zsh 사용자: source ~/.zshrc
단계 2: 환경 변수 설정 확인하기
설정이 올바르게 되었는지 확인하기 위해 새로운 터미널을 열고 다음 명령어를 실행합니다.
Windows (PowerShell): echo $env:OPENAI_API_KEY
macOS / Linux: echo $OPENAI_API_KEY
입력한 API 키가 출력되면 성공적으로 설정된 것입니다.
단계 3: VS Code에서 Python 코드로 API 키 불러오기
이제 VS Code에서 파이썬 스크립트를 작성하여 시스템 환경 변수를 불러올 수 있습니다. os 모듈을 사용합니다.
import os
# 시스템 환경 변수에서 API 키 불러오기
openai_api_key = os.getenv("OPENAI_API_KEY")
# 키가 제대로 불러와졌는지 확인
if openai_api_key:
print("API 키가 성공적으로 불러와졌습니다.")
else:
print("API 키를 찾을 수 없습니다.")
# 이후에 openai_api_key 변수를 사용하여 API 호출
# ...
[ 방법 2: .env 파일에 API 키 저장 및 사용 ]
.env 파일은 프로젝트 루트 디렉토리에 위치하는 숨김 파일로, 주로 로컬 개발 환경에서 사용됩니다. 이 방법은 프로젝트별로 다른 환경 변수를 관리할 수 있어 편리합니다.
단계 1: python-dotenv 라이브러리 설치
터미널을 열고 다음 명령어를 입력하여 필요한 라이브러리를 설치합니다.
pip install python-dotenv
단계 2: .env 파일 생성 및 API 키 저장
VS Code에서 프로젝트 폴더를 엽니다.
탐색기 패널에서 프로젝트 루트 디렉토리에 **.env**라는 이름의 파일을 생성합니다. 파일 이름 앞에 점(.)을 붙이는 것이 중요합니다.
.env 파일 안에 다음 형식으로 API 키를 저장합니다. OPENAI_API_KEY='your_api_key'
'your_api_key' 부분에 실제 API 키를 입력합니다.
주석(#)을 사용하여 설명을 추가할 수도 있습니다.
단계 3: VS Code에서 Python 코드로 API 키 불러오기
.env 파일에 저장된 환경 변수는 os 모듈이 자동으로 읽어오지 못합니다. dotenv 라이브러리의 load_dotenv() 함수를 호출하여 .env 파일을 로드해야 합니다.
import os
from dotenv import load_dotenv
# .env 파일에 저장된 환경 변수들을 로드
load_dotenv()
# 환경 변수에서 API 키 불러오기
openai_api_key = os.getenv("OPENAI_API_KEY")
# 키가 제대로 불러와졌는지 확인
if openai_api_key:
print("API 키가 성공적으로 불러와졌습니다.")
else:
print("API 키를 찾을 수 없습니다.")
# 이후에 openai_api_key 변수를 사용하여 API 호출
# ...
단계 4 (필수): .gitignore 파일에 .env 추가하기
.env 파일은 민감한 정보를 담고 있으므로, 실수로 Git 저장소에 업로드되지 않도록 해야 합니다.
프로젝트 루트 디렉토리에 .gitignore 파일을 엽니다. (없으면 새로 생성)
파일의 맨 아래에 다음 줄을 추가합니다. # 환경 변수 파일 제외 .env
이렇게 하면 Git이 .env 파일을 무시하게 되어 안전하게 관리할 수 있습니다.
[ 두 가지 방법 비교 및 권장 사항 ]
구분
시스템 환경 변수
.env파일
장점
한 번 설정하면 모든 프로젝트에서 사용 가능<br>프로젝트에 키를 저장할 필요 없음
프로젝트별로 다른 키를 편리하게 관리 가능<br>협업 시 환경 변수 목록 공유가 쉬움
단점
프로젝트별로 다른 키를 사용하기 번거로움<br>민감한 정보가 컴퓨터에 영구적으로 저장됨
Git에 업로드되지 않도록 주의해야 함<br>(.gitignore 사용 필수)<br>.gitignore 파일에 .env 추가하는 것을 잊지 말아야 함
권장
개인 프로젝트에서 주로 하나의 API 키를 사용하는 경우
팀 프로젝트나 여러 개의 API 키를 사용하는 경우
두 가지 방법 중 본인의 작업 환경과 프로젝트 성격에 맞는 방법을 선택하여 사용하시면 됩니다. .env 파일 방법은 Git을 사용하는 협업 환경에서 특히 유용합니다.
Amazon CodeWhisperer는 머신러닝 기반의 코드 생성 AI 도구로, 개발자가 코드를 작성하는 동안 실시간으로 코드 제안을 제공합니다. 주석이나 기존 코드에 기반하여 함수, 클래스, 코드 블록 등을 추천해 주기 때문에 개발 생산성을 크게 향상시킬 수 있습니다. 현재 VS Code, IntelliJ IDEA, PyCharm 등 다양한 IDE에서 사용할 수 있습니다.
이 문서에서는 VS Code에서 CodeWhisperer를 설정하고 사용하는 방법을 단계별로 상세히 설명합니다.
2. 시작하기 전에 준비할 것들
Visual Studio Code (VS Code): 최신 버전이 설치되어 있어야 합니다.
AWS Builder ID: CodeWhisperer를 사용하려면 개인 AWS Builder ID가 필요합니다. AWS 계정과는 별개로 개인 이메일 주소로 생성할 수 있습니다. (설정 과정에서 안내에 따라 생성할 수 있습니다.)
3. 단계별 설치 및 설정 방법
단계 1: AWS Toolkit 확장 프로그램 설치
VS Code를 엽니다.
왼쪽 사이드바에서 Extensions (확장) 아이콘 (네 개의 사각형 모양)을 클릭합니다.
검색창에 AWS Toolkit을 입력합니다.
AWS Toolkit 확장 프로그램을 찾아 Install (설치) 버튼을 클릭합니다.
단계 2: AWS Toolkit에 연결
설치가 완료되면, 왼쪽 사이드바에 AWS 아이콘이 새로 생깁니다. 이 아이콘을 클릭하여 AWS Toolkit 패널을 엽니다.
패널 상단에 CodeWhisperer 섹션이 보일 것입니다.
Start 버튼을 클릭합니다.
단계 3: AWS Builder ID로 로그인
Start 버튼을 클릭하면, AWS Builder ID로 로그인하라는 메시지가 뜹니다.
Use a personal email to sign in with AWS Builder ID 버튼을 클릭합니다.
VS Code가 기본 웹 브라우저를 열어 인증 페이지로 리디렉션합니다.
단계 4: AWS Builder ID 생성 또는 로그인
브라우저에서 AWS Builder ID 로그인 페이지가 열리면, 이미 계정이 있다면 로그인하고, 없다면 Create an AWS Builder ID를 선택하여 계정을 만듭니다.
계정 생성 시에는 이메일 주소와 이름 등을 입력하면 됩니다.
입력한 이메일로 전송된 확인 코드를 브라우저에 입력하여 계정 생성을 완료합니다.
로그인 또는 계정 생성이 완료되면, VS Code로 돌아가라는 안내 메시지가 브라우저에 표시됩니다.
단계 5: VS Code로 돌아가기
브라우저에서 Visual Studio Code 열기와 같은 팝업 창이 나타나면, 이를 허용하여 VS Code로 돌아갑니다.
VS Code 하단 상태 표시줄에 CodeWhisperer가 성공적으로 연결되었다는 메시지가 표시됩니다.
이제 모든 설정이 완료되었습니다.
4. Amazon CodeWhisperer 사용 방법
이제 CodeWhisperer를 직접 사용해 볼 시간입니다.
지원되는 파일 열기: Python(.py), JavaScript(.js), Java(.java), C++(.cpp) 등 CodeWhisperer가 지원하는 언어의 파일을 엽니다.
코드 작성 시작: 코드를 작성하기 시작하면 CodeWhisperer가 자동으로 맥락을 파악하여 실시간으로 코드 제안을 표시합니다.
제안 수락하기:
CodeWhisperer의 제안이 마음에 든다면 Tab 키를 눌러 코드를 삽입합니다.
여러 개의 제안이 있는 경우, 방향키(위/아래)를 사용하여 제안 목록을 탐색할 수 있습니다.
수동으로 제안 받기:
때로는 자동 제안이 나오지 않을 때가 있습니다. 이럴 때는 Option + C (macOS) 또는 Alt + C (Windows) 단축키를 눌러 수동으로 제안을 받을 수 있습니다.
예시: Python 파일에서 CodeWhisperer 사용
example.py 파일을 열고 아래와 같이 주석을 작성합니다.
# Function to calculate the factorial of a number
위 주석을 입력하면 CodeWhisperer가 아래와 같은 코드를 자동으로 제안합니다.
def factorial(n):
if n == 0:
return 1
else:
return n * factorial(n-1)
```Tab` 키를 눌러 이 제안을 수락할 수 있습니다.
5. VS Code에서 확장 프로그램 비활성화하기
CodeWhisperer와 같은 다른 확장 프로그램을 사용하기 위해 GitHub Copilot을 비활성화하는 방법은 다음과 같습니다.
확장 프로그램 탭 열기 VS Code의 왼쪽 사이드바에서 Extensions (확장) 아이콘 (네 개의 사각형 모양)을 클릭합니다.
GitHub Copilot 검색 확장 프로그램 검색창에 GitHub Copilot을 입력합니다.
확장 프로그램 비활성화 검색 결과로 나타난 GitHub Copilot 확장 프로그램을 클릭합니다.
전역적으로 비활성화: 확장 프로그램 페이지 상단에 있는 Disable (비활성화) 버튼을 클릭하면, 모든 작업 영역(Workspace)에서 Copilot이 비활성화됩니다.
특정 작업 영역에서만 비활성화:Disable (Workspace) 버튼을 클릭하면, 현재 열려 있는 프로젝트에서만 Copilot이 비활성화되고 다른 프로젝트에서는 계속 사용할 수 있습니다.
6. CodeWhisperer 사용 시 설정 확인
GitHub Copilot을 비활성화한 후, CodeWhisperer가 제대로 작동하는지 확인하려면 AWS Toolkit 설정에서 CodeWhisperer가 활성화되어 있는지 다시 한번 확인해 보세요.
VS Code 왼쪽 사이드바의 AWS 아이콘을 클릭합니다.
CodeWhisperer 섹션에서 상태가 Active로 표시되어 있는지 확인합니다.
이렇게 하면 두 개의 AI가 동시에 코드 제안을 하는 충돌을 피하고, CodeWhisperer의 제안을 방해 없이 받을 수 있습니다.
이 단계에서는 Qdrant, Flask, serve 관련 프로세스가 현재 백그라운드에서 실행 중인지 확인하고 모두 종료합니다. 그래야 깨끗한 상태에서 다시 시작할 수 있습니다.
Qdrant Docker 컨테이너 확인 및 중지: Bash sudo docker ps -a
결과 확인: qdrant/qdrant 이미지를 사용하는 컨테이너가 Up (실행 중) 상태이거나 Exited (종료됨) 상태로 보일 수 있습니다.
중지 명령어: 만약 Up 상태인 Qdrant 컨테이너가 있다면, 해당 CONTAINER ID 또는 NAMES를 사용하여 중지합니다. Bash sudo docker stop [QDRANT_CONTAINER_ID_OR_NAME] (예: sudo docker stop 5f7287e6328c 또는 sudo docker stop xenodochial_mendeleev)
삭제 (선택 사항): 완전히 제거하고 새로 시작하려면 중지 후 삭제합니다. 삭제해도 데이터 볼륨은 남습니다. Bash sudo docker rm [QDRANT_CONTAINER_ID_OR_NAME]
Flask 백엔드 프로세스 확인 및 중지: Bash ps -ef | grep python | grep "chapter5-1-3_from_4-2_from_3-7_copy.py"
결과 확인: 이전에 nohup으로 실행한 Flask 앱 프로세스가 보일 수 있습니다. (예시: ec2-user 12345 1 0 10:00 ? 00:00:00 python3 chapter5-1-3_from_4-2_from_3-7_copy.py) 여기서 12345가 PID입니다.
중지 명령어: 해당 PID를 사용하여 프로세스를 종료합니다. Bash sudo kill [FLASK_APP_PID] (예: sudo kill 12345) 만약 종료되지 않으면 sudo kill -9 [FLASK_APP_PID] (강제 종료)를 시도합니다.
프론트엔드 serve 프로세스 확인 및 중지: Bash ps -ef | grep serve
결과 확인: serve 명령어를 사용하여 구동한 프론트엔드 앱 프로세스가 보일 수 있습니다. (예시: ec2-user 67890 1 0 10:00 ? 00:00:00 /usr/bin/node /usr/bin/serve ...) 여기서 67890이 PID입니다.
중지 명령어: 해당 PID를 사용하여 프로세스를 종료합니다. Bash sudo kill [SERVE_PID] (예: sudo kill 67890) 만약 종료되지 않으면 sudo kill -9 [SERVE_PID] (강제 종료)를 시도합니다.
2단계: Qdrant Docker 컨테이너 구동
Qdrant는 벡터 데이터베이스로, 백엔드 Flask 앱이 의존하므로 가장 먼저 실행해야 합니다.
Qdrant 데이터 저장소 디렉토리로 이동 (또는 확인): Flask 앱이 있는 디렉토리(/home/ec2-user/flask)에 qdrant_storage 폴더가 위치하는 것이 일반적입니다. 해당 디렉토리로 이동합니다. Bash cd /home/ec2-user/flask
중요: 만약 qdrant_storage 폴더가 손상되었거나, 잘못된 컬렉션 차원 문제(OutputTooSmall 에러)가 계속 발생한다면, 이 폴더의 내용을 완전히 비우거나 삭제한 후 Qdrant를 재실행하세요. Bash sudo rm -rf qdrant_storage/* # 폴더 안의 내용만 삭제 # 또는 sudo rm -rf qdrant_storage # 폴더 자체를 삭제 (docker run 시 다시 생성됨)
Flask 앱 실행 확인: Bash ps -ef | grep python | grep "chapter5-1-3_from_4-2_from_3-7_copy.py" Flask 앱 프로세스가 백그라운드에서 잘 실행되고 있는지 확인합니다.
로그 확인: Flask 앱의 초기 구동 로그는 nohup.out 파일에 기록됩니다. Bash tail -f nohup.out 이 명령어로 Qdrant 연결 성공 메시지(Qdrant 클라이언트 연결 및 컬렉션 정보 가져오기 성공: ...)가 뜨는지 확인합니다. (Ctrl+C로 종료)
데이터 재삽입 (필수): 만약 2단계에서 qdrant_storage를 초기화했다면, Qdrant test3 컬렉션에 데이터가 없습니다. Flask 앱의 /upsertPoint 엔드포인트를 호출하여 데이터를 다시 삽입해야 합니다. (예: Postman 또는 프론트엔드를 통해)
4단계: React 프론트엔드 애플리케이션 구동
이제 백엔드와 Qdrant가 모두 실행 중이므로, 사용자 인터페이스를 제공하는 React 프론트엔드 앱을 구동합니다.
프론트엔드 build 디렉토리로 이동: Bash cd /home/ec2-user/front/build
중요: build 디렉토리 안에 .html, .js, .css 파일들이 있는지 ls -l로 다시 한번 확인하세요. 빌드가 제대로 안 되었다면 내용이 비어있을 수 있습니다.
serve 백그라운드 실행: Bash nohup serve -s . -l 3000 &
nohup: 터미널 세션이 끊어져도 serve 프로세스가 계속 실행됩니다.
-s .: 현재 디렉토리(build)의 정적 파일들을 서빙합니다.
-l 3000: 3000번 포트에서 리스닝합니다. (Flask 앱의 5500번과 충돌하지 않도록 다른 포트 사용)
&: 명령어를 백그라운드로 실행합니다.
serve 프로세스 실행 확인: Bash ps -ef | grep serve ```serve` 프로세스가 백그라운드에서 잘 실행되고 있는지 확인합니다.
5단계: 최종 확인 및 AWS 보안 그룹 점검 (매우 중요)
모든 서비스가 EC2 인스턴스 내에서 실행 중이지만, 외부에서 접근하려면 AWS 보안 그룹 설정이 올바른지 확인해야 합니다.
웹 브라우저에서 프론트엔드 접속 시도: http://[YOUR_EC2_PUBLIC_IP]:3000
[YOUR_EC2_PUBLIC_IP]는 당신의 AWS EC2 인스턴스의 퍼블릭 IP 주소입니다.
AWS 보안 그룹 인바운드 규칙 최종 점검:
3000번 포트 (프론트엔드 serve): 당신의 로컬 PC IP 또는 0.0.0.0/0에서 3000번 포트로의 TCP 접근이 허용되어 있는지 확인.
5500번 포트 (Flask 백엔드): 당신의 로컬 PC IP 또는 0.0.0.0/0에서 5500번 포트로의 TCP 접근이 허용되어 있는지 확인.
6333번 포트 (Qdrant gRPC): 당신의 Flask 앱이 Qdrant와 같은 EC2 인스턴스에 있으므로 이 포트는 외부에서 직접 접근할 필요는 없지만, 만약 외부에서 Qdrant에 직접 연결하는 경우가 있다면 (예: Qdrant GUI) 이 포트도 열어야 합니다. 현재 구성에서는 Flask 앱이 localhost로 Qdrant에 접속하므로 보안 그룹과 무관합니다.
이 순서대로 진행하시면 모든 컴포넌트가 올바르게 구동되고 서로 통신하여 챗봇 서비스가 웹에서 정상적으로 작동할 것입니다.
이 에러 메시지는 "Address already in use" (이미 사용 중인 주소) 문제로, Flask 애플리케이션을 실행하려는 5500번 포트가 이미 다른 프로그램에 의해 사용되고 있기 때문에 발생합니다.
Port 5500 is in use by another program. Either identify and stop that program, or start the server with a different port.
이 메시지처럼, 5500번 포트를 사용 중인 프로그램을 찾아 중지시키거나, Flask 서버를 다른 포트에서 시작해야 합니다.
해결 방법:
옵션 1: 5500번 포트를 사용 중인 프로그램 찾아서 중지시키기 (권장)
이 방법은 가장 일반적이며, 기존에 백그라운드로 실행해 둔 Flask 앱이나 다른 웹 서버 프로세스가 아직 살아있는 경우에 해당합니다.
5500번 포트를 사용 중인 프로세스 확인: AWS EC2 인스턴스 터미널에서 다음 명령어를 입력합니다. Bash sudo netstat -tulnp | grep 5500
sudo: 관리자 권한으로 실행합니다.
netstat -tulnp: 현재 활성화된 네트워크 연결 및 리스닝 중인 포트 정보를 표시합니다.
-t: TCP 연결
-u: UDP 연결
-l: 리스닝 중인 소켓만 표시
-n: 주소와 포트 번호를 숫자로 표시 (이름으로 변환하지 않음)
-p: 해당 포트를 사용 중인 프로그램의 PID(Process ID)와 이름 표시
grep 5500: netstat 결과에서 5500을 포함하는 라인만 필터링합니다.
이 명령어를 실행하면 다음과 유사한 결과가 나올 수 있습니다:
tcp 0 0 0.0.0.0:5500 0.0.0.0:* LISTEN 12345/python3 여기서 12345가 프로세스 ID (PID)이고, python3가 해당 프로세스의 이름입니다. (PID는 매번 다를 수 있습니다.)
해당 프로세스 중지시키기 (kill): 위에서 확인한 PID를 사용하여 프로세스를 강제로 종료합니다. Bash sudo kill 12345 (여기서 12345는 netstat 명령어로 찾은 실제 PID로 바꿔야 합니다.) 만약 kill 명령어로 종료되지 않는다면, kill -9 (강제 종료)를 시도할 수 있습니다. Bash sudo kill -9 12345
다시 Flask 애플리케이션 실행: 프로세스를 종료한 후, 다시 Flask 애플리케이션을 실행해 보세요. Bash python3 test5-3-from-4-2.py 또는 백그라운드로 실행하려면: Bash nohup python3 test5-3-from-4-2.py &
옵션 2: Flask 애플리케이션을 다른 포트에서 실행하기
만약 5500번 포트를 사용 중인 프로그램을 중지시키기 어렵거나, 다른 이유로 다른 포트를 사용하고 싶다면, Flask 앱의 포트를 변경할 수 있습니다.
Flask 코드 수정: Flask 애플리케이션 코드의 app.run() 부분을 수정합니다. 예를 들어, 5501번 포트를 사용하도록 변경합니다. Python if __name__ == "__main__": app.run(debug=True, port=5501) # 5500을 5501로 변경
저장 및 실행: 코드를 저장한 후, Flask 애플리케이션을 다시 실행합니다. Bash python3 test5-3-from-4-2.py 이제 Flask 앱은 http://127.0.0.1:5501에서 실행될 것입니다.
AWS 보안 그룹 업데이트 (필수): 만약 Flask 앱이 외부에서 접근해야 한다면, AWS EC2 인스턴스의 보안 그룹에서 새로 변경한 포트(예: 5501번)에 대한 인바운드 규칙을 추가하거나 기존 규칙을 수정해야 합니다. (이전에 설명해 드린 보안 그룹 설정 방법을 참고하세요.)
이 두 가지 옵션 중 하나를 선택하여 문제를 해결하실 수 있습니다. 일반적으로는 옵션 1을 통해 기존 프로세스를 정리하고 원하는 포트를 사용하는 것이 선호됩니다.
코드는 React를 사용하여 간단한 웹 챗봇 인터페이스를 구현한 것입니다. 사용자가 메시지를 입력하고 전송하면, 해당 메시지가 화면에 표시되고 백엔드 API(http://localhost:5500/searchChat)와 통신하여 챗봇의 응답을 받아 다시 화면에 표시하는 기능을 합니다.
import React, {useState} from "react" // React 라이브러리와 React 훅인 useState를 가져옵니다.
// useState: 컴포넌트 내에서 상태(데이터)를 관리할 수 있게 해주는 훅입니다.
import "./ChatPage.css" // ChatPage 컴포넌트의 스타일을 정의하는 CSS 파일을 가져옵니다.
const ChatPage =() => { // ChatPage라는 이름의 함수형 컴포넌트를 정의합니다. React 컴포넌트 이름은 대문자로 시작해야 합니다.
// --- 1. 상태(State) 변수 정의 ---
// React 컴포넌트의 UI나 동작에 영향을 미치는 데이터는 '상태'로 관리해야 합니다.
// input: 사용자가 입력 필드에 타이핑하는 현재 텍스트를 저장하는 상태 변수입니다.
// setInput: input 상태를 업데이트하는 함수입니다.
const [input, setInput] = useState("") // input의 초기값은 빈 문자열("")입니다.
// messages: 채팅창에 표시될 메시지들의 배열을 저장하는 상태 변수입니다.
// 각 메시지는 {sender: "user" | "bot", text: "메시지 내용"} 형태의 객체입니다.
// setMessages: messages 상태를 업데이트하는 함수입니다.
const [messages, setMessages] = useState([{sender:"bot", text:"안녕하세요, 무엇을 도와드릴까요?"}])
// messages의 초기값으로 챗봇의 환영 메시지를 포함합니다.
// --- 2. 이벤트 핸들러 함수 정의 ---
// handleSend: 메시지 전송 버튼 클릭 또는 Enter 키 입력 시 실행될 비동기 함수입니다.
const handleSend = async() => { // async 키워드는 이 함수 내에서 await를 사용하여 비동기 작업을 기다릴 수 있게 합니다.
// 1. 사용자 메시지 생성 및 화면에 즉시 추가
const userMessage = {sender: "user", text: input} // 현재 input 상태의 텍스트로 사용자 메시지 객체를 생성합니다.
setMessages(prev => [...prev, userMessage]) // setMessages를 사용하여 messages 상태를 업데이트합니다.
// prev: 이전 messages 상태를 참조합니다.
// [...prev, userMessage]: 이전 메시지들(prev)을 모두 복사하고, 그 뒤에 새로운 userMessage를 추가하여 새로운 배열을 만듭니다.
// 이렇게 해야 React의 불변성(immutability) 원칙을 지키면서 상태를 업데이트할 수 있습니다.
// 2. 입력 필드 초기화
setInput("") // 메시지를 보낸 후 input 필드를 비웁니다.
// 3. 백엔드 API 호출 (비동기 통신)
try{ // 네트워크 요청은 실패할 수 있으므로 try-catch 블록으로 에러를 처리합니다.
const response = await fetch("http://localhost:5500/searchChat",{ // fetch API를 사용하여 백엔드(Flask 앱)의 /searchChat 엔드포인트로 POST 요청을 보냅니다.
method: "POST", // HTTP 요청 메서드를 POST로 지정합니다.
headers : { // 요청 헤더를 설정합니다.
"Content-Type": "application/json", // 보내는 데이터가 JSON 형식임을 서버에 알립니다.
},
body: JSON.stringify({inputText : input}) // input 상태의 텍스트를 JSON 문자열로 변환하여 요청 본문에 담아 보냅니다.
// 주의: 여기서 input은 handleSend 함수가 호출될 당시의 input 값입니다.
// setInput("")으로 input이 초기화되기 전의 값입니다.
})
// 4. 백엔드 응답 처리
const data = await response.text() // 서버로부터 받은 응답을 텍스트 형태로 파싱합니다. (서버가 JSON이 아닌 일반 텍스트를 반환할 경우)
const chatBotMessage = {sender: "bot", text:data} // 파싱된 텍스트로 챗봇 메시지 객체를 생성합니다.
// 5. 챗봇 메시지를 messages 상태에 추가
setMessages(prev => [...prev, chatBotMessage]) // 이전 메시지들 뒤에 챗봇 메시지를 추가하여 상태를 업데이트합니다.
}catch(error){ // fetch 요청 또는 응답 처리 중 에러가 발생하면 이 블록이 실행됩니다.
console.error("메시지 전송 중 오류 발생:", error) // 콘솔에 에러를 출력합니다. (사용자에게는 다른 방식으로 보여줄 수 있음)
setMessages(prev => [...prev, {sender: "bot", text: "오류가 발생했습니다. 다시 시도해주세요."}]); // 오류 메시지를 챗봇 메시지로 표시
}
}
// handleKeyDown: 입력 필드에서 키보드 이벤트 발생 시 실행될 함수입니다.
const handleKeyDown = (e) => {
if(e.key === "Enter") { // 눌린 키가 "Enter" 키인지 확인합니다.
handleSend(); // Enter 키가 눌렸으면 메시지 전송 함수를 호출합니다.
}
}
// --- 3. 컴포넌트 UI (JSX) 렌더링 ---
return( // 컴포넌트가 화면에 렌더링할 JSX를 반환합니다.
<div className = "chat-fullscreen"> {/* 전체 채팅 페이지를 감싸는 컨테이너. CSS 클래스 적용. */}
<div className = "chat-header"> {/* 채팅 헤더 영역 */}
챗봇 만들기
</div>
<div className = "chat-window"> {/* 메시지들이 표시될 채팅창 영역 */}
{
// messages 배열을 순회하며 각 메시지에 대해 <div> 요소를 생성합니다.
messages.map((msg, i) => (
// key={i}: React에서 리스트를 렌더링할 때 각 요소에 고유한 'key' prop을 부여해야 합니다.
// 여기서는 인덱스(i)를 사용했지만, 실제 앱에서는 메시지 ID와 같은 고유한 값을 사용하는 것이 좋습니다.
// className={`chat-bubble ${msg.sender}`}: 각 메시지에 'chat-bubble' 클래스와 함께
// 'user' 또는 'bot' 클래스를 동적으로 적용하여 스타일을 다르게 합니다.
<div key={i} className={`chat-bubble ${msg.sender}`}>
{msg.text} {/* 메시지 내용을 표시합니다. */}
</div>
))
}
</div>
<div className="chat-input-bar"> {/* 메시지 입력 및 전송 영역 */}
<input
type="text" // 입력 필드 타입
value={input} // input 상태 변수와 입력 필드의 값을 바인딩합니다. (제어 컴포넌트)
onChange={e => setInput(e.target.value)} // 입력 필드 내용이 변경될 때마다 input 상태를 업데이트합니다.
placeholder="메시지를 입력하세요" // 입력 필드에 표시될 안내 텍스트
onKeyDown = {handleKeyDown} // 키보드 눌림 이벤트 발생 시 handleKeyDown 함수 호출
></input>
{/* 전송 버튼을 추가할 수도 있습니다. */}
{/* <button onClick={handleSend}>전송</button> */}
</div>
</div>
)
}
export default ChatPage; // ChatPage 컴포넌트를 외부에서 가져다 사용할 수 있도록 내보냅니다.
React ChatPage 컴포넌트 코딩 순서 및 사고 과정
이 챗봇 페이지를 처음부터 코딩해 나간다고 가정하고, 어떤 순서로 어떤 부분을 추가하며 생각해야 하는지 단계별로 설명해 드리겠습니다.
1단계: 기본 React 컴포넌트 구조 잡기
가장 먼저, React 컴포넌트의 기본적인 틀을 만듭니다.
파일 생성:ChatPage.jsx (또는 ChatPage.js) 파일과 ChatPage.css 파일을 만듭니다.
기본 임포트 및 컴포넌트 정의:
사고 과정: "일단 화면에 챗봇 레이아웃을 보여줘야 하니, 헤더, 메시지 창, 입력 바 이렇게 세 부분으로 나눌 수 있겠다. 각 부분에 CSS 클래스를 미리 지정해두면 나중에 스타일링하기 편하겠지?"
import React from "react"; // React를 사용하기 위해 필수 import "./ChatPage.css"; // 스타일 시트 임포트 const ChatPage = () => { // 컴포넌트 로직이 들어갈 곳 return ( // JSX (UI)가 들어갈 곳 <div className="chat-fullscreen"> <div className="chat-header">챗봇 만들기</div> <div className="chat-window"></div> <div className="chat-input-bar"></div> </div> ); }; export default ChatPage; // 외부에서 이 컴포넌트를 사용할 수 있도록 내보내기
2단계: 사용자 입력 필드 구현 (상태 관리 시작)
사용자가 메시지를 입력할 수 있는 <input> 요소를 추가하고, 그 값을 React 상태로 관리합니다.
useState 임포트:import React, { useState } from "react"로 변경합니다.
input 상태 정의:
const [input, setInput] = useState(""); // 사용자가 입력할 텍스트 상태
<input> 요소에 바인딩:
사고 과정: "사용자가 입력하는 텍스트는 계속 변하니 React의 상태로 관리해야 해. useState를 써서 input 변수에 현재 값을 저장하고, setInput 함수로 업데이트해야지. <input> 태그의 value와 onChange를 연결하면 사용자가 입력할 때마다 input 상태가 자동으로 업데이트될 거야."
// ... (return 문 내부) ... <div className="chat-input-bar"> <input type="text" value={input} // input 상태와 연결 onChange={e => setInput(e.target.value)} // 입력값 변경 시 상태 업데이트 placeholder="메시지를 입력하세요" /> </div>
3단계: 메시지 목록 표시 및 초기 메시지 설정
채팅 메시지들을 저장할 상태를 만들고, 이를 화면에 렌더링합니다.
messages 상태 정의:
const [messages, setMessages] = useState([{sender:"bot", text:"안녕하세요, 무엇을 도와드릴까요?"}]); // 메시지 목록 상태
chat-window에 메시지 렌더링:
사고 과정: "챗봇 대화는 여러 메시지가 순서대로 쌓이는 형태이니 배열로 관리하는 게 좋겠어. 초기에는 챗봇의 환영 메시지가 있어야겠지? map 함수를 써서 배열의 각 요소를 div로 만들고, sender에 따라 다른 스타일을 적용할 수 있도록 className을 동적으로 바꿔줘야겠다. 리스트 렌더링 시 key prop은 필수니까 i라도 넣어두자 (나중에 고유 ID로 바꾸는 게 좋겠지만)."
const handleSend = () => { const userMessage = {sender: "user", text: input}; setMessages(prev => [...prev, userMessage]); // 사용자 메시지 추가 setInput(""); // 입력 필드 초기화 };
Enter 키 이벤트 핸들러:
사고 과정: "메시지를 보내려면 버튼 클릭이나 Enter 키 입력이 필요해. handleSend 함수를 만들어서 현재 input 값을 사용자 메시지로 만들고 messages 배열에 추가해야지. 그리고 input 필드는 비워야 다음 메시지를 입력할 수 있으니까 setInput("")도 호출해야겠다. Enter 키로도 전송되게 onKeyDown 이벤트도 붙여야지."
const handleKeyDown = (e) => { if(e.key === "Enter") handleSend(); // Enter 키 누르면 전송 }; // ... (input 태그에 onKeyDown={handleKeyDown} 추가)
사고 과정: "챗봇 응답을 받으려면 백엔드 API를 호출해야 해. fetch API를 사용하면 비동기적으로 HTTP 요청을 보낼 수 있지. await를 쓰려면 handleSend 함수를 async로 만들어야 해. POST 요청이니까 method, headers, body를 설정해야 하고, inputText는 JSON 형태로 보내야 하니까 JSON.stringify를 써야겠다. 네트워크 요청은 실패할 수 있으니 try-catch로 감싸서 에러 처리도 해줘야지. 서버 응답을 받으면 그걸 챗봇 메시지로 만들어서 messages에 추가해야 해."
주의 사항:body: JSON.stringify({inputText : input})에서 input을 직접 사용하면, setInput("")으로 input 상태가 초기화된 후 fetch 요청이 보내질 때 input이 빈 문자열이 될 수 있습니다. 이를 방지하기 위해 currentInput 변수에 값을 미리 저장하는 것이 좋습니다.
const handleSend = async () => { const userMessage = {sender: "user", text: input}; setMessages(prev => [...prev, userMessage]); const currentInput = input; // fetch 요청에 사용될 input 값을 미리 저장 (setInput으로 초기화되기 전) setInput(""); try { const response = await fetch("http://localhost:5500/searchChat", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({inputText: currentInput}) // 저장된 input 값 사용 }); const data = await response.text(); // 서버 응답 파싱 const chatBotMessage = {sender: "bot", text: data}; setMessages(prev => [...prev, chatBotMessage]); // 챗봇 메시지 추가 } catch (error) { console.error("메시지 전송 중 오류 발생:", error); setMessages(prev => [...prev, {sender: "bot", text: "오류가 발생했습니다. 다시 시도해주세요."}]); } };
6단계: CSS 스타일링
ChatPage.css 파일을 작성하여 챗봇 UI에 시각적인 스타일을 적용합니다.
/* ChatPage.css */
.chat-fullscreen {
display: flex;
flex-direction: column; /* 세로 방향으로 요소들을 정렬 */
height: 100vh; /* 전체 뷰포트 높이 사용 */
max-width: 600px; /* 최대 너비 설정 */
margin: 0 auto; /* 중앙 정렬 */
border: 1px solid #ccc;
border-radius: 8px;
overflow: hidden; /* 내용이 넘칠 경우 숨김 */
box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}
.chat-header {
background-color: #4CAF50; /* 헤더 배경색 */
color: white;
padding: 15px;
font-size: 1.2em;
font-weight: bold;
text-align: center;
}
.chat-window {
flex-grow: 1; /* 남은 공간을 모두 차지하도록 설정 */
padding: 15px;
overflow-y: auto; /* 내용이 넘칠 경우 스크롤바 생성 */
background-color: #f9f9f9;
display: flex;
flex-direction: column;
gap: 10px; /* 메시지 버블 간 간격 */
}
.chat-bubble {
max-width: 70%; /* 버블의 최대 너비 */
padding: 10px 15px;
border-radius: 18px;
line-height: 1.4;
word-wrap: break-word; /* 긴 단어 자동 줄바꿈 */
}
.chat-bubble.user {
align-self: flex-end; /* 사용자 메시지는 오른쪽 정렬 */
background-color: #DCF8C6; /* 사용자 버블 색상 */
color: #333;
border-bottom-right-radius: 4px; /* 모서리 조절 */
}
.chat-bubble.bot {
align-self: flex-start; /* 봇 메시지는 왼쪽 정렬 */
background-color: #E0E0E0; /* 봇 버블 색상 */
color: #333;
border-bottom-left-radius: 4px; /* 모서리 조절 */
}
.chat-input-bar {
display: flex;
padding: 15px;
border-top: 1px solid #eee;
background-color: white;
}
.chat-input-bar input {
flex-grow: 1; /* 입력 필드가 남은 공간을 모두 차지 */
padding: 10px 15px;
border: 1px solid #ddd;
border-radius: 20px;
font-size: 1em;
outline: none; /* 포커스 시 외곽선 제거 */
}
.chat-input-bar input:focus {
border-color: #4CAF50; /* 포커스 시 테두리 색상 변경 */
}
사고 과정: "챗봇 UI는 보통 세로로 쌓이는 구조니까 flex-direction: column을 사용해야겠다. 헤더는 고정, 메시지 창은 스크롤 가능하게, 입력 바는 하단에 고정해야지. 메시지 버블은 sender에 따라 색깔과 정렬을 다르게 하고, 입력 필드도 예쁘게 꾸며야겠다."
7단계: 추가 개선 사항 (선택 사항)
스크롤 자동 내리기: 새 메시지가 추가될 때마다 채팅창이 자동으로 가장 아래로 스크롤되도록 useEffect와 scrollIntoView를 사용할 수 있습니다.
로딩 인디케이터: API 요청 중임을 사용자에게 알리기 위해 로딩 스피너를 추가할 수 있습니다.
에러 메시지 UI:catch 블록에서 console.error 대신 사용자에게 보이는 에러 메시지를 messages 배열에 추가하거나 별도의 알림 UI를 사용할 수 있습니다.
입력값 유효성 검사: 빈 메시지 전송 방지 등.
백엔드 URL 설정:http://localhost:5500을 환경 변수나 설정 파일로 관리하여 배포 환경에 따라 쉽게 변경할 수 있도록 합니다.
이러한 단계들을 통해 React 챗봇 컴포넌트를 체계적으로 개발하고 완성할 수 있습니다. 각 단계에서 필요한 React 개념과 웹 개발 원칙들을 적용하며 코드를 작성하는 것이 중요합니다.
React ChatPage 컴포넌트 최종 완성 코드 및 해설
이 문서는 이전 React ChatPage 컴포넌트 상세 해설 Canvas의 내용을 바탕으로, 7단계 추가 개선 사항을 적용하고 메시지 key 값을 고유 ID로 변경한 최종 완성 코드와 그 상세 해설을 제공합니다.
1. 최종 완성 코드 (ChatPage.jsx)
import React, { useState, useEffect, useRef } from "react"; // useRef 훅을 추가로 가져옵니다.
import "./ChatPage.css"; // ChatPage 컴포넌트의 스타일을 정의하는 CSS 파일을 가져옵니다.
// 백엔드 URL을 환경 변수에서 가져오거나 기본값을 설정합니다.
// 실제 프로젝트에서는 .env 파일에 REACT_APP_BACKEND_URL=http://your-ec2-public-ip:5500 과 같이 설정합니다.
const BACKEND_URL = process.env.REACT_APP_BACKEND_URL || "http://localhost:5500";
const ChatPage = () => {
// --- 1. 상태(State) 변수 정의 ---
const [input, setInput] = useState("");
// 각 메시지에 고유 ID를 부여하기 위해 id 속성을 추가했습니다.
const [messages, setMessages] = useState([
{ id: Date.now(), sender: "bot", text: "안녕하세요, 무엇을 도와드릴까요?" }
]);
const [isLoading, setIsLoading] = useState(false); // 로딩 상태를 관리하는 상태 변수
// --- 2. useRef 훅 정의 ---
// chatWindowRef: 메시지 창의 DOM 요소에 직접 접근하여 스크롤을 제어하기 위한 ref입니다.
const chatWindowRef = useRef(null);
// --- 3. useEffect 훅 정의 ---
// 메시지가 추가될 때마다 채팅창을 자동으로 가장 아래로 스크롤합니다.
useEffect(() => {
if (chatWindowRef.current) {
chatWindowRef.current.scrollTop = chatWindowRef.current.scrollHeight;
}
}, [messages]); // messages 상태가 변경될 때마다 이 훅이 실행됩니다.
// --- 4. 이벤트 핸들러 함수 정의 ---
// handleSend: 메시지 전송 버튼 클릭 또는 Enter 키 입력 시 실행될 비동기 함수입니다.
const handleSend = async () => {
// 입력값이 비어있거나, 이미 로딩 중인 경우 함수 실행을 중단합니다.
if (!input.trim() || isLoading) {
return;
}
const userMessageText = input.trim(); // 사용자 메시지에서 앞뒤 공백 제거
const userMessage = { id: Date.now(), sender: "user", text: userMessageText }; // 고유 ID 부여
// 사용자 메시지를 즉시 화면에 추가하고 입력 필드를 초기화합니다.
setMessages(prev => [...prev, userMessage]);
setInput("");
setIsLoading(true); // 로딩 상태 시작
try {
const response = await fetch(`${BACKEND_URL}/searchChat`, { // 백엔드 URL 변수 사용
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({ inputText: userMessageText }) // 사용자 메시지 텍스트를 body에 담아 보냅니다.
});
if (!response.ok) { // HTTP 응답 상태 코드가 200번대가 아닐 경우 에러 처리
const errorData = await response.text();
throw new Error(`HTTP error! status: ${response.status}, message: ${errorData}`);
}
const data = await response.text();
const chatBotMessage = { id: Date.now() + 1, sender: "bot", text: data }; // 챗봇 메시지에도 고유 ID 부여
setMessages(prev => [...prev, chatBotMessage]);
} catch (error) {
console.error("메시지 전송 중 오류 발생:", error);
// 사용자에게 보이는 오류 메시지 추가
setMessages(prev => [...prev, { id: Date.now() + 1, sender: "bot", text: "오류가 발생했습니다. 다시 시도해주세요." }]);
} finally {
setIsLoading(false); // 로딩 상태 종료
}
};
// handleKeyDown: 입력 필드에서 키보드 이벤트 발생 시 실행될 함수입니다.
const handleKeyDown = (e) => {
if (e.key === "Enter") {
handleSend();
}
};
// --- 5. 컴포넌트 UI (JSX) 렌더링 ---
return (
<div className="chat-fullscreen">
<div className="chat-header">
챗봇 만들기
</div>
<div ref={chatWindowRef} className="chat-window"> {/* ref를 메시지 창에 연결 */}
{
messages.map((msg) => ( // key에 msg.id 사용
<div key={msg.id} className={`chat-bubble ${msg.sender}`}>
{msg.text}
</div>
))
}
{isLoading && ( // 로딩 중일 때 로딩 인디케이터 표시
<div className="chat-bubble bot loading">
<div className="dot-flashing"></div>
</div>
)}
</div>
<div className="chat-input-bar">
<input
type="text"
value={input}
onChange={e => setInput(e.target.value)}
placeholder={isLoading ? "답변을 기다리는 중..." : "메시지를 입력하세요"} // 로딩 상태에 따라 placeholder 변경
onKeyDown={handleKeyDown}
disabled={isLoading} // 로딩 중일 때 입력 필드 비활성화
></input>
<button onClick={handleSend} disabled={isLoading || !input.trim()}>전송</button> {/* 전송 버튼 추가 및 비활성화 조건 */}
</div>
</div>
);
}
export default ChatPage;
해설: React에서 리스트를 렌더링할 때 key prop은 매우 중요합니다. key는 React가 리스트의 아이템들을 식별하고, 변경(추가, 삭제, 재정렬)이 일어났을 때 어떤 아이템이 변경되었는지 효율적으로 추적하는 데 사용됩니다. i (배열 인덱스)를 key로 사용하는 것은 리스트의 아이템 순서가 변경되거나 아이템이 추가/삭제될 때 문제가 발생할 수 있습니다. Date.now()를 사용하여 각 메시지에 고유한 타임스탬프 기반 ID를 부여함으로써, React가 메시지들을 더 정확하게 식별하고 UI를 효율적으로 업데이트할 수 있게 됩니다. (실제 프로덕션에서는 UUID 같은 더 강력한 고유 ID 생성 방법을 권장합니다.)
3.2. 7단계 추가 개선 사항 적용
1. 스크롤 자동 내리기
적용 내용:useRef 훅과 useEffect 훅을 사용하여 새 메시지가 추가될 때마다 채팅창이 자동으로 가장 아래로 스크롤되도록 했습니다.
해설: 개발 환경(localhost)과 배포 환경(AWS EC2 퍼블릭 IP)에서 백엔드 URL이 달라질 수 있으므로, 코드를 수정하지 않고 환경 변수만 변경하여 유연하게 대응할 수 있도록 합니다. (Create React App 기준으로 REACT_APP_ 접두사를 사용합니다.)
