Code log

[AI] LangChain이란?

danieLee — Sun, 13 Sep 2026 15:26:14 +0900

생성형 AI를 활용한 서비스가 많아지면서 단순히 GPT와 대화하는 것을 넘어, 문서를 검색하거나 외부 API를 호출하고 데이터베이스와 연결하는 형태의 AI 서비스가 늘어나고 있다.

이처럼 LLM을 실제 애플리케이션에 연결할 때 자주 사용되는 프레임워크가 바로 LangChain이다.

오늘은 이 LangChain이 어떤 것인지 간단히 알아보도록 하자.

LangChain이란?

LangChain은 LLM을 활용한 애플리케이션을 쉽게 개발할 수 있도록 도와주는 오픈소스 프레임워크다.

OpenAI의 GPT나 Anthropic의 Claude처럼 직접 언어 모델을 제공하는 것은 아니다. 대신 다양한 LLM과 프롬프트, 문서, 데이터베이스, 외부 API 등을 하나의 흐름으로 연결하는 역할을 한다.

가장 단순한 LLM 서비스는 다음과 같은 구조를 가진다.

사용자 질문
    ↓
LLM
    ↓
답변

하지만 실제 서비스를 만들다 보면 LLM만 호출해서는 해결하기 어려운 경우가 많다.

예를 들어 사내 규정 문서를 기반으로 답변하는 AI 서비스를 만든다고 생각해보자.

사용자 질문
    ↓
관련 문서 검색
    ↓
필요한 내용 추출
    ↓
프롬프트 구성
    ↓
LLM 호출
    ↓
최종 답변

LangChain은 이러한 여러 단계를 연결하고 관리할 수 있도록 도와준다.

왜 이름이 LangChain일까?

LangChain이라는 이름은 크게 두 단어로 나눌 수 있다.

Lang : Language Model
Chain : 여러 작업을 연결한 흐름

즉, 언어 모델을 중심으로 여러 작업을 체인처럼 연결한다는 의미다.

예를 들어 다음과 같은 흐름을 하나의 Chain으로 구성할 수 있다.

문서 검색 → 프롬프트 생성 → LLM 호출 → 결과 반환

개발자는 각각의 기능을 따로 구현하는 것보다 LangChain이 제공하는 구성 요소를 이용해 전체 흐름을 보다 체계적으로 만들 수 있다.

LangChain의 주요 구성 요소

LangChain을 이해하려면 몇 가지 핵심 개념을 알아두는 것이 좋다.

Model

GPT, Claude와 같은 LLM을 호출하는 부분이다.

LangChain 자체가 AI 모델은 아니기 때문에 실제 답변을 생성하려면 외부 LLM을 연결해야 한다.

LangChain
    ↓
OpenAI GPT
Anthropic Claude
기타 LLM

LangChain은 여러 모델을 비슷한 방식으로 연결할 수 있도록 인터페이스를 제공한다.

Prompt

Prompt는 LLM에게 전달하는 명령이나 질문의 형식을 의미한다.

예를 들어 다음과 같이 사용할 수 있다.

너는 금융 상담 AI다.

다음 자료를 참고해서 질문에 답하라.

자료:
{context}

질문:
{question}

여기서 {context}와 {question}에 실제 데이터를 넣어 최종 프롬프트를 만든다.

이처럼 프롬프트를 템플릿 형태로 관리할 수 있다는 것도 LangChain의 특징 중 하나다.

Document와 Retriever

LLM이 외부 문서를 참고하도록 만들 때 사용되는 요소다.

예를 들어 PDF나 사내 문서에서 사용자의 질문과 관련된 부분을 찾아야 한다면 Retriever를 이용할 수 있다.

사용자 질문
    ↓
Retriever
    ↓
관련 문서 검색
    ↓
LLM

이 구조는 RAG를 구현할 때 특히 많이 사용된다.

Tool

Tool은 LLM이 외부 기능을 사용할 수 있도록 연결하는 기능이다.

예를 들어 다음과 같은 기능을 Tool로 만들 수 있다.

날씨 API
계산기
데이터베이스 조회
웹 검색
사내 API

LLM이 단순히 자신의 학습 데이터만을 이용하는 것이 아니라 실제 외부 시스템과 상호작용할 수 있게 되는 것이다.

Chain

Chain은 여러 작업을 정해진 순서로 연결한 것이다.

예를 들어 다음과 같은 Chain을 구성할 수 있다.

사용자 질문
    ↓
문서 검색
    ↓
프롬프트 생성
    ↓
LLM 호출
    ↓
답변 반환

각 단계가 미리 정해진 순서대로 실행된다는 것이 특징이다.

Agent

Agent는 Chain보다 한 단계 더 발전된 개념이다.

Chain은 개발자가 미리 처리 순서를 정하지만, Agent는 LLM이 현재 상황을 보고 어떤 Tool을 사용할지 판단할 수 있다.

예를 들어 사용자가 다음과 같이 질문했다고 하자.

서울의 현재 날씨를 확인해서
비가 오면 우산을 가져가야 하는지 알려줘.

Agent는 다음과 같이 동작할 수 있다.

사용자 질문
    ↓
LLM 판단
    ↓
날씨 정보가 필요함
    ↓
Weather Tool 호출
    ↓
결과 확인
    ↓
최종 답변 생성

즉,

Chain = 정해진 순서대로 실행

Agent = LLM이 다음 행동을 판단

이라고 이해하면 된다.

LangChain과 RAG

LangChain을 공부할 때 가장 자주 등장하는 개념 중 하나가 RAG(Retrieval-Augmented Generation)다.

RAG는 LLM이 외부 문서를 검색한 뒤 그 정보를 참고하여 답변하도록 만드는 방식이다.

대표적인 구조는 다음과 같다.

문서
 ↓
텍스트 분할
 ↓
Embedding
 ↓
Vector DB
 ↓
Retriever
 ↓
관련 문서 검색
 ↓
LLM
 ↓
답변

예를 들어 회사의 규정 PDF를 Vector DB에 저장해 두고 사용자가 질문하면 질문과 관련된 문서를 검색해 LLM에게 전달할 수 있다.

이를 통해 LLM이 학습하지 않은 최신 정보나 내부 데이터도 활용할 수 있다.

LangChain은 이러한 RAG 구조를 구현하는 데 필요한 여러 기능을 제공하기 때문에 RAG 개발에서 자주 사용된다.

LangChain과 Agent

최근에는 LangChain을 단순한 RAG 프레임워크보다 AI Agent 개발을 위한 도구로 사용하는 경우도 많다.

일반적인 LLM은 질문에 답변을 생성하는 것이 주된 역할이다.

반면 Agent는 상황에 따라 외부 도구를 사용하며 작업을 수행할 수 있다.

사용자
  ↓
Agent
  ↓
LLM
 ├─ 웹 검색
 ├─ 데이터베이스
 ├─ 계산기
 └─ 외부 API
  ↓
최종 결과

이러한 구조를 사용하면 단순한 챗봇을 넘어 여러 작업을 수행하는 AI 시스템을 만들 수 있다.

복잡한 Agent의 상태 관리나 분기, 반복 처리가 필요한 경우에는 LangChain 생태계의 LangGraph도 함께 사용된다.

LangChain은 무료일까?

LangChain 자체는 오픈소스 프레임워크이기 때문에 직접 설치해서 사용할 수 있다.

하지만 LangChain과 연결하는 모든 서비스가 무료인 것은 아니다.

예를 들어 다음과 같은 서비스에는 별도의 비용이 발생할 수 있다.

OpenAI API
Claude API
Vector Database
Cloud 서비스
외부 API

따라서

LangChain = 애플리케이션을 구성하는 프레임워크

LLM API = 실제 AI 모델을 사용하는 서비스

로 구분해서 이해해야 한다.

LangChain과 Spring AI의 차이

Java와 Spring을 사용해본 개발자라면 LangChain과 Spring AI를 비교하면 이해하기 쉽다.

LangChain	Spring AI
Python / JavaScript 중심	Java / Spring 중심
LLM 애플리케이션 개발 프레임워크	Spring 기반 AI 개발 프레임워크
Prompt	Prompt
Retriever	VectorStore / Retrieval
Tool	Tool / Function Calling
Agent	Agent
다양한 LLM 연결	다양한 LLM 연결

두 프레임워크 모두 LLM과 외부 시스템을 연결해 실제 AI 서비스를 만드는 것이 목적이라는 점에서는 비슷하다.

다만 LangChain은 Python 기반 AI 생태계에서 많이 사용되고, Spring AI는 Spring 애플리케이션에 AI 기능을 자연스럽게 통합하는 데 초점을 두고 있다.

정리

LangChain은 GPT 같은 LLM 자체가 아니다.

LLM과 프롬프트, 문서, 데이터베이스, 외부 API, Tool 등을 연결해 하나의 AI 애플리케이션을 구성할 수 있도록 도와주는 오픈소스 프레임워크다.

전체적인 구조를 간단하게 표현하면 다음과 같다.

                ┌─ 문서 / Vector DB
                │
사용자 → LangChain ─ LLM
                │
                ├─ 외부 API
                │
                └─ Tool
                     ↓
                   답변

LangChain을 공부한다면 다음 순서로 개념을 익히는 것이 좋다.

LangChain
   ↓
Prompt / Model
   ↓
Embedding
   ↓
Vector DB
   ↓
RAG
   ↓
Retriever
   ↓
Tool
   ↓
Agent
   ↓
LangGraph

LLM을 다른 데이터와 기능에 연결해주는 프레임워크라는 핵심 개념부터 잡는 것이 중요하다.

[AI] RAG란? - 검색 증강 생성의 개념과 동작 원리 이해하기

danieLee — Mon, 31 Aug 2026 13:26:09 +0900

ChatGPT와 같은 LLM은 방대한 데이터를 학습하기 때문에 다양한 질문에 답할 수 있다.

하지만 LLM이라고 해서 모든 정보를 알고 있는 것은 아니다.

예를 들어 다음과 같은 질문을 생각해보자.

우리 회사의 휴가 규정은 어떻게 돼?

지난주에 변경된 서비스 정책을 알려줘.

사내 개발 가이드에서 API Naming Rule을 찾아줘.

이러한 정보는 LLM이 학습할 때 존재하지 않았거나, 외부에 공개되지 않은 정보일 수 있다.

또한 LLM은 답을 정확히 모르는 상황에서도 그럴듯한 내용을 만들어낼 수 있다.

대표적인 문제가 다음 세 가지다.

Knowledge Cutoff
→ 학습 이후의 최신 정보를 모름

Lack of Context
→ 회사 내부 문서나 특정 도메인 정보를 모름

Hallucination
→ 사실이 아닌 내용을 그럴듯하게 생성할 수 있음

이러한 LLM과 실제 데이터 사이의 간극을 줄이기 위해 사용하는 대표적인 방법이 RAG다.

RAG

RAG란?

RAG 구조

RAG는 다음의 약자다.

Retrieval-Augmented Generation

Retrieval
→ 검색

Augmented
→ 증강, 보강

Generation
→ 생성

한 문장으로 정리하면 다음과 같다.

RAG는 사용자의 질문과 관련된 외부 정보를 먼저 검색한 뒤, 검색된 정보를 LLM에게 함께 제공하여 답변을 생성하는 방식이다.

전체적인 구조는 매우 단순하다.

사용자 질문
     │
     ▼
관련 정보 검색
Retrieval
     │
     ▼
검색 결과를 질문에 추가
Augmentation
     │
     ▼
LLM
     │
     ▼
답변 생성
Generation

즉 LLM에게 바로 질문하지 않고, 답변에 필요한 자료를 먼저 찾아준 다음 질문과 함께 전달한다.

RAG의 Runtime 과정 역시 Retrieve → Augment → Generate 흐름으로 구성된다.

RAG를 쉽게 이해해보자

RAG를 오픈북 시험에 비유해보자.

일반적인 LLM은 다음과 같다.

시험 문제
   ↓
학생의 기억
   ↓
답변

학생이 예전에 공부한 내용만 가지고 답을 작성하는 것이다.

반면 RAG는 오픈북 시험과 비슷하다.

시험 문제
   ↓
책에서 관련 내용 검색
   ↓
관련 페이지 확인
   ↓
문제 + 참고 자료
   ↓
답변 작성

LLM이 모든 내용을 기억하고 있을 필요가 없다.

필요한 순간에 외부 데이터에서 관련 정보를 찾아서 LLM에게 제공하면 된다.

따라서 RAG에서 LLM의 역할과 검색 시스템의 역할은 다르다.

검색 시스템
→ 필요한 지식을 찾아준다.

LLM
→ 찾아온 지식을 이용해서 답변을 만든다.

RAG에서 가장 중요한 개념

RAG를 이해하려면 다음 요소들의 관계를 먼저 이해해야 한다.

Document

Chunk

Embedding

Vector

Vector DB

Similarity Search

Prompt Context

LLM

전체적으로 연결하면 다음과 같다.

Document
   │
   ▼
Chunk
   │
   ▼
Embedding
   │
   ▼
Vector
   │
   ▼
Vector DB


사용자 질문
   │
   ▼
Embedding
   │
   ▼
Query Vector
   │
   ▼
Vector DB 검색
   │
   ▼
관련 Chunk
   │
   ▼
Prompt Context
   │
   ▼
LLM

결국 RAG는 문서를 잘 저장하고, 질문과 관련된 문서를 잘 찾아서, LLM에게 잘 전달하는 기술이라고 볼 수 있다.

RAG는 크게 두 과정

RAG는 하나의 과정처럼 보이지만 실제로는 크게 두 단계로 나누어 생각할 수 있다.

RAG

├─ Offline
│
│  문서를 미리 가공하고 저장
│
└─ Runtime

   질문이 들어왔을 때
   관련 문서를 검색하고 답변 생성

자료에서도 외부 데이터를 DocumentReader → DocumentTransformer → DocumentWriter로 처리하는 Offline 과정과, 실제 질문에 대해 Retrieve → Augment → Generate하는 Runtime 과정을 구분하고 있다.

Offline 과정

Offline은 RAG가 사용할 지식을 미리 준비하는 과정이다.

예를 들어 다음과 같은 회사 문서가 있다고 해보자.

사내규정.pdf
개발가이드.pdf
보안정책.docx
서비스매뉴얼.txt

이 파일을 그대로 검색하는 것이 아니라 RAG가 검색하기 좋은 형태로 가공한다.

전체 과정은 다음과 같다.

원본 Document
      │
      ▼
텍스트 추출
      │
      ▼
문서 분할
Chunking
      │
      ▼
Embedding
      │
      ▼
Vector
      │
      ▼
Vector DB 저장

이 과정은 일반적으로 다음과 같은 ETL 형태로 볼 수 있다.

Extract
→ 데이터를 읽는다.

Transform
→ 검색하기 좋은 형태로 가공한다.

Load
→ Vector DB에 저장한다.

Document

RAG에서 가장 처음 다루게 되는 것은 Document다.

Document는 말 그대로 검색에 사용할 원본 정보다.

다음과 같은 것들이 모두 Document의 원천이 될 수 있다.

PDF
TXT
DOCX
HTML
JSON

웹페이지
사내 Wiki
DB 데이터
업무 매뉴얼
정책 문서

하지만 원본 파일 하나가 반드시 검색 단위 하나가 되는 것은 아니다.

대부분의 경우 문서를 더 작은 단위로 분리해서 사용한다.

Chunk란?

Chunk는 큰 Document를 검색하기 좋은 작은 단위로 나눈 문서 조각이다.

100페이지짜리 회사 규정 문서가 있다고 해보자.

회사규정.pdf

├─ 근무 규정
├─ 휴가 규정
├─ 경조사 규정
├─ 출장 규정
├─ 보안 규정
└─ 복리후생 규정

이 문서 전체를 하나의 검색 단위로 사용하면 문제가 생긴다.

사용자가 다음과 같이 질문했다고 해보자.

경조사 휴가는 며칠이야?

필요한 내용은 전체 100페이지 중 몇 문장뿐이다.

그런데 전체 문서를 하나로 사용하면:

경조사 질문
    ↓
100페이지 전체
    ↓
LLM

처럼 너무 많은 불필요한 정보가 들어간다.

그래서 문서를 작은 Chunk로 나눈다.

회사규정.pdf

        ↓ Chunking

Chunk 1
→ 근무시간 규정

Chunk 2
→ 연차 규정

Chunk 3
→ 경조사 휴가 규정

Chunk 4
→ 출장 규정

Chunk 5
→ 보안 규정

이제 경조사 휴가에 대해 질문하면:

"경조사 휴가는 며칠이야?"

          ↓

      Chunk 검색

          ↓

Chunk 3
"경조사 휴가 규정 ..."

처럼 필요한 부분만 가져올 수 있다.

왜 Chunk가 중요한가?

RAG에서는 Chunk 크기가 검색 품질에 큰 영향을 준다.

너무 큰 Chunk를 사용하면:

Chunk가 너무 큼

→ 여러 주제가 한 Chunk에 섞임
→ Embedding 의미가 모호해짐
→ 관련 없는 정보까지 LLM에 전달

반대로 너무 작은 Chunk를 사용하면:

Chunk가 너무 작음

→ 문맥이 끊어짐
→ 필요한 정보가 여러 Chunk로 분산
→ 검색 결과 하나만으로 의미를 이해하기 어려움

예를 들어 다음 문장을 생각해보자.

직원은 입사 1년 이후 15일의 연차를 사용할 수 있다.
미사용 연차의 처리 기준은 별도 규정을 따른다.

너무 잘게 나누면:

Chunk 1
"직원은 입사 1년 이후"

Chunk 2
"15일의 연차를 사용할 수 있다."

Chunk 3
"미사용 연차의 처리 기준은"

Chunk 4
"별도 규정을 따른다."

처럼 문맥이 깨질 수 있다.

따라서 Chunk는 단순히 작게 만드는 것이 아니라 질문에 답할 수 있을 정도의 의미 있는 정보 단위로 만드는 것이 중요하다.

Embedding

Chunk를 만들었다면 다음으로 필요한 것이 Embedding이다.

Embedding은 텍스트의 의미를 숫자로 이루어진 Vector로 변환하는 과정이다.

예를 들어:

"고양이가 뛰고 있다"

        ↓

  Embedding Model

        ↓

[0.12, 0.41, -0.31, 0.72, ...]

다른 문장도 같은 방식으로 Vector가 된다.

"고양이가 달린다"

        ↓

[0.11, 0.39, -0.30, 0.70, ...]

두 문장은 의미가 비슷하다.

따라서 Embedding Model이 잘 학습되어 있다면 두 Vector 역시 서로 비슷하게 만들어진다.

반대로:

"Spring Boot 서버를 실행한다."

는 의미가 전혀 다르기 때문에 다른 위치의 Vector가 생성된다.

개념적으로 표현하면 다음과 같다.

Vector Space


 ● 고양이가 달린다
   ● 고양이가 뛰고 있다



                         ● Spring Boot 서버 실행

이렇게 의미가 비슷한 데이터가 Vector 공간에서도 가까워지도록 만드는 것이 Embedding의 핵심이다.

왜 그냥 키워드 검색을 하지 않을까?

일반적인 검색은 동일한 단어가 있는지를 중심으로 검색할 수 있다.

예를 들어 사용자가 다음과 같이 검색한다.

"휴가 일수"

그런데 문서에는 이렇게 적혀 있을 수도 있다.

"근로자는 연간 15일의 연차를 사용할 수 있다."

휴가 일수라는 단어가 정확히 존재하지 않는다.

하지만 의미적으로는 매우 관련이 있다.

휴가 일수

≈ 연간 연차 15일

Embedding을 이용하면 단순한 문자열 일치보다 의미적 유사성을 이용해 검색할 수 있다.

이것을 Semantic Search라고 한다.

Vector DB

Embedding으로 만든 Vector를 저장하는 곳이 Vector Database다.

일반적인 Database가 다음과 같은 검색에 강하다면:

WHERE name = 'Kim'

Vector DB는 다음과 같은 질문에 강하다.

"이 문장과 의미가 가장 비슷한 문서를 찾아줘."

즉 검색 기준이 다음과 같이 달라진다.

일반 DB

값이 같은가?
      ↓
Exact Match


Vector DB

의미가 비슷한가?
      ↓
Similarity Search

RAG에서 Vector Store는 Document를 Embedding하여 저장하고, 질문을 이용해 유사한 Document를 다시 검색하는 역할을 한다.

Offline 과정에서 실제로 저장되는 것

예를 들어 다음 Chunk가 있다고 해보자.

"대한민국의 영토는 한반도와 그 부속도서로 한다."

Embedding을 수행한다.

Embedding Model

        ↓

[0.13, -0.42, 0.81, 0.22, ...]

그리고 Vector DB에는 개념적으로 다음과 같은 정보가 저장된다.

Document

content
→ 대한민국의 영토는 한반도와 그 부속도서로 한다.

metadata
→ article: 3

embedding
→ [0.13, -0.42, 0.81, ...]

이러한 데이터가 수백, 수천, 수백만 개 저장될 수 있다.

여기까지가 RAG의 지식 준비 과정이다.

Runtime 과정

이제 사용자가 실제 질문을 한다.

대한민국의 영토는 어디까지야?

여기부터 Runtime RAG가 시작된다.

전체 흐름은 다음과 같다.

사용자 질문

     ↓

Query Embedding

     ↓

Query Vector

     ↓

Vector DB

     ↓

Similarity Search

     ↓

관련 Chunk 검색

     ↓

Prompt에 추가

     ↓

LLM

     ↓

최종 답변

하나씩 보면 이해하기 쉽다.

1. 사용자의 질문을 Vector로 만든다

저장된 Document만 Vector로 만드는 것이 아니다.

검색할 질문 역시 같은 Embedding Model을 이용해 Vector로 변환한다.

질문

"대한민국의 영토는 어디까지야?"

        ↓

Embedding Model

        ↓

Query Vector

[0.15, -0.40, 0.78, ...]

이 Query Vector와 Vector DB에 저장된 Vector들을 비교한다.

2. Similarity Search

Vector DB에서는 Query Vector와 가장 비슷한 Vector를 찾는다.

예를 들어 다음과 같은 결과가 나왔다고 해보자.

질문 Vector

      ↓

Vector DB

      ↓

Document A
Similarity = 0.93

Document B
Similarity = 0.82

Document C
Similarity = 0.57

Document D
Similarity = 0.21

가장 높은 문서가 질문과 의미적으로 가장 관련성이 높다고 판단할 수 있다.

자료에서는 VectorStoreDocumentRetriever가 이러한 VectorStore 기반 유사도 검색을 수행하는 Retrieval 역할을 담당한다.

Top-K

RAG에서는 일반적으로 문서 하나만 가져오지 않는다.

관련성이 높은 상위 몇 개를 가져온다.

이를 Top-K라고 한다.

예를 들어:

Top-K = 3

이면:

검색 결과

1위 0.93  ← 사용
2위 0.88  ← 사용
3위 0.82  ← 사용
4위 0.71
5위 0.65

상위 3개의 Document를 가져온다.

구조는 다음과 같다.

Query

  ↓

Vector Search

  ↓

Top-K

  ├─ Chunk A
  ├─ Chunk B
  └─ Chunk C

K가 너무 작으면 필요한 정보를 놓칠 수 있고, 너무 크면 불필요한 문서가 함께 들어올 수 있다.

Similarity Threshold

또 하나 중요한 개념이 Similarity Threshold다.

Top-K만 사용하면 문제가 하나 있다.

관련 있는 문서가 전혀 없어도 무조건 상위 몇 개를 가져올 수 있다는 것이다.

예를 들어:

질문

"회사 주차장 이용 규정 알려줘"

그런데 Vector DB에는 주차장 관련 내용이 하나도 없다고 해보자.

그래도 Top-3를 강제로 가져오면:

1위 0.34
2위 0.29
3위 0.23

같이 별로 관련 없는 문서가 선택될 수 있다.

그래서 최소 유사도를 설정한다.

Similarity Threshold = 0.7

그러면:

0.92 → 사용
0.83 → 사용
0.75 → 사용
0.63 → 제외
0.41 → 제외

처럼 일정 수준 이상의 문서만 사용한다.

Retrieval

여기까지가 RAG의 첫 번째 단계인 Retrieval이다.

Question
   │
   ▼
Embedding
   │
   ▼
Vector Search
   │
   ▼
Top-K / Threshold
   │
   ▼
관련 Chunk

Retrieval의 목적은 단순하다.

사용자의 질문에 답하기 위해 필요한 정보를 외부 데이터에서 찾아오는 것

이다.

Augmentation

그런데 문서를 찾는 것만으로 끝나지 않는다.

검색된 내용을 LLM에게 전달해야 한다.

이 과정이 Augmentation이다.

검색 결과가 다음과 같다고 해보자.

대한민국의 영토는 한반도와 그 부속도서로 한다.

이 정보를 사용자의 질문과 함께 Prompt에 넣는다.

아래 정보를 참고하여 질문에 답하세요.

[Context]

대한민국의 영토는
한반도와 그 부속도서로 한다.

[Question]

대한민국의 영토는 어디까지인가?

원래 Prompt가:

Question

이었다면 RAG에서는:

Context
+
Question

형태가 되는 것이다.

자료에서도 검색된 Document를 사용자 Query와 결합하여 최종 Prompt를 만드는 것을 Generation 단계의 증강 과정으로 설명한다.

Context란?

RAG에서 매우 자주 등장하는 단어가 Context다.

Context는 LLM에게 제공하는 참고 정보라고 보면 된다.

Context
→ LLM이 답변할 때 참고해야 하는 외부 정보

예를 들어:

사용자 질문

"경조사 휴가가 며칠이야?"

Context가 없으면:

LLM

→ 자신의 기존 지식으로 답변

RAG에서는:

Context

"회사 규정 제12조:
직계가족의 경조사 발생 시
최대 5일의 특별휴가를 제공한다."

           +

Question

"경조사 휴가가 며칠이야?"

           ↓

          LLM

이 된다.

LLM 입장에서는 검색을 직접 수행했다기보다 질문을 받았는데 참고 자료까지 같이 받은 것에 가깝다.

Generation

마지막 단계가 Generation이다.

Context
+
Question

     ↓

    LLM

     ↓

Answer

LLM은 검색된 데이터를 바탕으로 자연어 답변을 만든다.

예를 들어:

Context

"연차는 입사 1년 이후 15일이 부여된다."


Question

"1년 이상 근무하면 연차가 몇 개야?"

LLM은 이를 이용해서:

입사 후 1년 이상 근무한 직원에게는
15일의 연차가 부여된다.

같은 자연어 답변을 생성한다.

즉 RAG에서 LLM은 검색 엔진이 아니다.

Retriever
→ 정보를 검색

LLM
→ 검색된 정보를 이해하고 답변 생성

역할이 나누어져 있다.

RAG의 전체 원리

지금까지 내용을 하나로 연결하면 다음과 같다.

                 [ Offline ]


             원본 Document
                   │
                   ▼
               Chunking
                   │
                   ▼
             Embedding Model
                   │
                   ▼
                Vector
                   │
                   ▼
               Vector DB


────────────────────────────────


                 [ Runtime ]


             User Question
                   │
                   ▼
             Embedding Model
                   │
                   ▼
              Query Vector
                   │
                   ▼
               Vector DB
                   │
                   ▼
           Similarity Search
                   │
              Retrieval
                   ▼
             Related Chunks
                   │
              Augmentation
                   ▼
           Context + Question
                   │
                   ▼
                  LLM
                   │
              Generation
                   ▼
                Answer

이 구조가 가장 기본적인 RAG다.

RAG의 핵심은 사실 LLM보다 Retrieval

RAG에서는 검색 결과가 매우 중요하다.

아무리 좋은 LLM을 사용하더라도 검색에서 잘못된 Document를 가져오면 제대로 답변하기 어렵다.

좋은 Retrieval

정확한 Document
      ↓
좋은 Context
      ↓
좋은 Answer

반대로:

나쁜 Retrieval

관련 없는 Document
       ↓
나쁜 Context
       ↓
잘못된 Answer

이런 구조가 될 수 있다.

따라서 RAG 품질을 개선할 때는 단순히 LLM만 좋은 모델로 바꾸는 것이 아니라 다음 요소들을 함께 고려해야 한다.

Embedding Model

Chunk 크기

Chunk 분할 방식

검색 방식

Top-K

Similarity Threshold

Metadata Filtering

Prompt 구성

Hallucination이 사라지는 것은 아니다

RAG의 대표적인 목적 중 하나는 LLM에게 근거를 제공하는 것이다.

하지만 RAG를 사용했다고 해서 항상 정확한 답변이 만들어지는 것은 아니다.

예를 들어 검색 단계에서 잘못된 문서를 가져오면:

잘못된 Retrieval
      ↓
잘못된 Context
      ↓
LLM
      ↓
잘못된 답변

이 가능하다.

또 제대로 된 문서를 검색했어도 Prompt가 좋지 않다면 LLM이 외부 지식을 섞어서 답할 수도 있다.

그래서 RAG Prompt에는 다음과 같은 규칙을 넣기도 한다.

제공된 Context만 이용하여 답변하세요.

Context에 답이 없다면
답을 찾을 수 없다고 응답하세요.

자료에서도 검색 결과가 없을 경우 별도의 응답을 사용하거나, 제공된 Context만을 사용하도록 Prompt를 구성하는 방법을 다룬다.

기본 RAG의 한계

지금까지 설명한 구조를 흔히 가장 기본적인 RAG 형태로 볼 수 있다.

Question
   ↓
Vector Search
   ↓
Context
   ↓
LLM

하지만 실제 사용자가 항상 검색하기 좋은 질문을 입력하는 것은 아니다.

예를 들어:

아 그 저번에 얘기했던 거 있잖아
그거 기간 얼마나 돼?

이 문장만 Vector Search하면 무엇을 의미하는지 알기 어렵다.

또 다음과 같이 필요 이상으로 장황한 질문도 있을 수 있다.

제가 지금 프로젝트를 하다가 문득 궁금해졌는데요.
Spring AI에서 RAG를 쓰고 있는데 혹시 검색 정확도를
높일 수 있는 방법이 있나 해서 질문드립니다.

검색에 필요한 핵심은 사실:

RAG 검색 정확도 향상 방법

이다.

이러한 문제를 개선하기 위해 Advanced RAG에서는 검색 전후에 추가 처리를 수행한다.

Pre-Retrieval

Pre-Retrieval은 실제 검색을 하기 전에 사용자의 Query를 가공하는 단계다.

User Query
    │
    ▼
Pre-Retrieval
    │
    ▼
검색에 최적화된 Query

대표적인 방법은 다음과 같다.

Query Rewrite
→ 불필요한 표현을 제거하고 질문을 다시 작성

Query Compression
→ 이전 대화까지 참고해 독립적인 질문으로 변경

Multi Query
→ 하나의 질문을 여러 형태의 검색 Query로 확장

Translation
→ 검색에 적합한 언어로 변환

예를 들어:

원본

"오늘 날씨도 좋고 갑자기 궁금해졌는데
Spring AI RAG 검색 속도 올리는 방법이 있을까?"

다음처럼 바꿀 수 있다.

Spring AI RAG 검색 성능 최적화 방법

이렇게 하면 검색 품질을 높일 수 있다.

Multi Query

하나의 질문을 여러 형태로 바꾸어 검색하는 방법도 있다.

예를 들어:

원본 Query

"RAG 성능 개선 방법"

을 다음처럼 확장한다.

Query 1
RAG 검색 정확도 향상 방법

Query 2
Embedding 기반 RAG 성능 개선 방법

Query 3
Vector DB Retrieval 최적화 방법

그 후 각 Query로 문서를 검색한다.

             Original Query
                   │
                   ▼
             Query Expander
                   │
        ┌──────────┼──────────┐
        ▼          ▼          ▼

      Query 1    Query 2    Query 3

        │          │          │
        └──────────┼──────────┘
                   ▼

               Retrieval

검색 범위를 넓혀 관련 정보를 찾을 가능성을 높이는 방식이다. 자료에서도 MultiQueryExpander의 목적을 단일 질문을 다양한 질문으로 확장해 더 많은 관련 문서를 찾는 것으로 설명한다.

Post-Retrieval

검색 결과를 그대로 LLM에게 전달할 필요도 없다.

검색된 문서를 다시 가공하는 과정을 Post-Retrieval이라고 한다.

Vector Search

     ↓

Documents

     ↓

Post-Retrieval

     ↓

정제된 Documents

대표적으로 다음과 같은 작업이 있다.

Filtering
→ 관련 없는 문서 제거

Reranking
→ 질문과 관련성이 높은 순서로 다시 정렬

Deduplication
→ 중복 Document 제거

Compression
→ Document에서 필요한 부분만 추출 또는 요약

자료에서도 Post-Retrieval의 역할로 재정렬, 관련 없는 문서 제거, 압축 등을 설명한다.

기본 RAG와 Advanced RAG

결국 두 구조를 비교하면 다음과 같다.

기본 RAG

Question
   │
   ▼
Retrieval
   │
   ▼
Context
   │
   ▼
LLM

Advanced RAG

Question
   │
   ▼
Pre-Retrieval
Query Rewrite / Expansion
   │
   ▼
Retrieval
Vector Search
   │
   ▼
Post-Retrieval
Filtering / Reranking
   │
   ▼
Augmentation
Context + Query
   │
   ▼
Generation
LLM
   │
   ▼
Answer

즉 RAG가 발전할수록 단순히 Vector DB에서 몇 개 가져와 LLM에게 넣는 구조를 넘어, 검색 품질 자체를 개선하는 방향으로 확장된다.

RAG를 사용할 때 중요한 포인트

RAG를 이해할 때 다음 네 가지를 기억하면 된다.

1. 무엇을 저장할 것인가?

Document / Data


2. 어떻게 나눌 것인가?

Chunking


3. 어떻게 찾을 것인가?

Embedding / Retrieval


4. 어떻게 LLM에게 전달할 것인가?

Augmentation / Prompt

결국 RAG 성능은 이 네 과정의 결과가 합쳐져 만들어진다.

RAG 전체 구조 다시 보기

                         RAG


              ┌─────────────────────┐
              │      Offline        │
              └─────────────────────┘

                  Original Data
                       │
                       ▼
                    Extract
                       │
                       ▼
                    Document
                       │
                       ▼
                    Chunking
                       │
                       ▼
                 Embedding Model
                       │
                       ▼
                     Vector
                       │
                       ▼
                   Vector DB


════════════════════════════════════════════════


              ┌─────────────────────┐
              │       Runtime       │
              └─────────────────────┘

                  User Question
                       │
                       ▼
                   Embedding
                       │
                       ▼
                  Query Vector
                       │
                       ▼
                   Vector DB
                       │
                  Retrieval
                       ▼
                Related Documents
                       │
                  Augmentation
                       ▼
                 Context + Query
                       │
                       ▼
                      LLM
                       │
                   Generation
                       ▼
                     Answer

정리

RAG는 Retrieval-Augmented Generation, 즉 검색 증강 생성이다.

LLM에게 질문을 바로 전달하는 대신, 질문과 관련된 정보를 외부 데이터에서 먼저 검색하여 함께 전달한다.

핵심은 세 단계다.

Retrieval

질문과 관련된 정보를 검색한다.


Augmentation

검색된 정보를
Prompt의 Context로 추가한다.


Generation

LLM이 질문과 Context를 이용하여
최종 답변을 생성한다.

하지만 실제 RAG는 그 전에 데이터를 준비하는 과정까지 포함해서 이해해야 한다.

문서
 ↓
Chunking
 ↓
Embedding
 ↓
Vector DB

그리고 질문이 들어오면:

질문
 ↓
Embedding
 ↓
Similarity Search
 ↓
관련 Chunk
 ↓
Context
 ↓
LLM
 ↓
답변

이라는 흐름으로 동작한다.

따라서 RAG에서 가장 중요한 것은 단순히 LLM에게 문서를 전달하는 것이 아니다.

사용자의 질문에 필요한 정보를 얼마나 정확하게 찾아서, 적절한 Context로 LLM에게 전달하느냐가 RAG의 핵심이다.

그리고 이 관점에서 보면 RAG는 단순한 LLM + Vector DB가 아니라,

문서 준비
+
Chunking
+
Embedding
+
Retrieval
+
Context 구성
+
Generation

이 모두 연결된 하나의 정보 검색 + 생성 파이프라인이라고 이해하는 것이 가장 정확하다.

[Spring AI] Spring AI란? 개념부터 전체 구조까지 이해하기

danieLee — Fri, 28 Aug 2026 17:06:54 +0900

최근 LLM을 활용한 애플리케이션이 빠르게 늘어나면서 기존 웹 서비스에서도 ChatGPT, Claude, Gemini 같은 AI 모델을 사용하는 경우가 많아지고 있다.

예를 들자면 다음과 같은 기능을 생각해볼 수 있다.

AI 챗봇
문서 기반 질의응답
사내 데이터 검색
코드 분석
문서 요약
AI Agent
외부 API 자동 호출

Spring Boot 애플리케이션에서도 OpenAI API를 직접 호출하면 이러한 기능을 구현할 수 있다.

구조만 보면 간단하다.

Spring Application
        │
        │ HTTP Request
        ▼
     OpenAI API
        │
        │ Response
        ▼
       LLM

하지만 실제 서비스를 만들기 시작하면 단순히 HTTP 요청 한 번 보내는 것으로 끝나지 않는다.

OpenAI뿐만 아니라 Claude나 Gemini 같은 다른 모델을 사용해야 할 수도 있고, 대화 기록을 관리하거나 사내 문서를 검색하고, AI가 외부 API를 호출하도록 만들어야 할 수도 있다.

Prompt 관리
Streaming 응답
모델 변경
대화 Memory
Structured Output
RAG
Vector DB
Tool Calling
MCP
Observability

이러한 AI 애플리케이션의 공통 기능을 매번 직접 구현하면 코드와 구조가 빠르게 복잡해진다.

이 문제를 Spring 방식으로 해결하기 위해 등장한 것이 Spring AI다.

Spring AI란?

Spring AI는 Spring 애플리케이션에서 생성형 AI 기능을 쉽게 사용할 수 있도록 지원하는 AI 애플리케이션 프레임워크다.

LLM뿐만 아니라 Embedding Model, Vector Database, RAG, Tool Calling, MCP 등의 기능을 Spring의 방식으로 사용할 수 있도록 여러 추상화와 API를 제공한다.

한 문장으로 정리하면 다음과 같다.

Spring AI는 AI 모델과 기업의 데이터 및 서비스를 Spring 애플리케이션에 연결하기 위한 프레임워크다.

Spring AI 공식 문서에서도 핵심 문제를 기업의 Data와 API를 AI Model에 연결하는 것으로 설명하고 있다.

중요한 점은 Spring AI 자체가 AI 모델은 아니라는 것이다.

Spring AI ≠ ChatGPT
Spring AI ≠ LLM
Spring AI ≠ AI 모델

Spring AI는 OpenAI, Anthropic, Google 등의 AI 모델을 Spring 애플리케이션에서 편리하게 사용할 수 있도록 연결해주는 계층에 가깝다.

Spring Application
        │
        ▼
    Spring AI
        │
        ▼
   AI Provider
        │
        ▼
       LLM

예를 들어 실제 모델은 다음과 같은 것들이 될 수 있다.

OpenAI
→ GPT

Anthropic
→ Claude

Google
→ Gemini

Ollama
→ Local LLM

Spring AI는 이 모델들과 애플리케이션 사이에서 요청과 응답을 중재한다.

왜 Spring AI가 필요한가?

사실 Spring AI가 없어도 LLM API를 호출할 수 있다.

Spring에는 이미 다음과 같은 HTTP Client가 존재한다.

RestClient
WebClient
RestTemplate

따라서 OpenAI API를 직접 호출하는 코드도 충분히 만들 수 있다.

문제는 애플리케이션이 커질수록 나타난다.

예를 들어 처음에는 OpenAI만 사용했다고 해보자.

Application
     │
     ▼
 OpenAI API

그런데 이후 Claude도 사용해야 한다면?

Application
   │
   ├── OpenAI API
   │
   └── Anthropic API

각 AI 제공업체마다 API의 요청 구조와 응답 구조가 다를 수 있다.

OpenAI

{
  "model": "...",
  "messages": [...]
}

Claude

{
  "model": "...",
  "system": "...",
  "messages": [...]
}

인증 방법이나 Streaming 방식, 모델 옵션 등도 서로 차이가 있다.

결국 개발자는 모델마다 별도의 코드를 작성해야 한다.

기존 방식의 문제점

Spring 애플리케이션에서 LLM API를 직접 사용하면 여러 문제가 발생할 수 있다.

대표적으로 다음과 같다.

API 파편화

OpenAI, Anthropic, Bedrock, Gemini 등 AI Provider마다 API 구조가 다르다.

OpenAI API
     │
     ├─ Request 형식
     └─ Response 형식

Claude API
     │
     ├─ Request 형식
     └─ Response 형식

모델을 변경하면 관련 코드도 함께 변경해야 할 가능성이 커진다.

반복되는 구현

AI 애플리케이션에서는 반복적으로 필요한 기능들이 있다.

Prompt 구성
Streaming
Retry
Timeout
응답 Parsing
Token 사용량
Logging

이러한 기능을 프로젝트마다 직접 구현하면 중복 코드가 늘어난다.

AI 패턴을 직접 구현해야 함

서비스가 조금 복잡해지면 단순한 질문과 답변만으로는 부족하다.

이전 대화 기억
→ Memory

사내 문서 검색
→ RAG

외부 API 실행
→ Tool Calling

외부 도구 연결
→ MCP

이러한 구조까지 모두 직접 설계하면 AI 관련 코드가 상당히 복잡해진다.

Spring AI는 이러한 문제를 Spring의 추상화, DI, Auto Configuration 방식으로 해결하려는 프레임워크다.

Spring의 추상화를 AI에 적용한다

Spring AI를 이해할 때 가장 중요한 개념이 바로 추상화다.

Spring 개발을 해봤다면 Spring Data를 떠올려볼 수 있다.

Spring Data에서는 사용하는 데이터베이스가 달라져도 공통된 방식으로 데이터를 다룰 수 있도록 여러 인터페이스를 제공한다.

             Repository

                 │
       ┌─────────┼─────────┐
       ▼         ▼         ▼

      JPA      MongoDB    Redis

Spring AI도 비슷한 구조를 사용한다.

예를 들어 다양한 AI 모델을 ChatModel이라는 공통 인터페이스로 추상화한다.

               ChatModel

                  │
       ┌──────────┼──────────┐
       ▼          ▼          ▼

     OpenAI    Anthropic    Gemini

개발자는 각 Provider의 HTTP API를 매번 직접 처리하기보다는 Spring AI가 제공하는 공통 API를 사용한다.

공식 문서 역시 Spring AI가 AI Provider에 대한 공통 Model API를 제공해 구현체를 비교적 쉽게 교체할 수 있도록 설계되어 있다고 설명한다.

Spring AI의 기본 구조

전체 구조를 단순화하면 다음과 같이 볼 수 있다.

                Application

                     │
                     ▼

                 ChatClient
                     │
                     ▼

                  Prompt
                     │
                     ▼

                 ChatModel
                     │
                     ▼

                AI Provider

           OpenAI / Claude / Gemini
                     │
                     ▼

                    LLM

여기에서 중요한 개념들이 하나씩 등장한다.

ChatClient
→ LLM을 편리하게 호출하기 위한 고수준 API

Prompt
→ AI 모델에 전달할 요청 정보

ChatModel
→ 다양한 Chat AI Model을 추상화한 인터페이스

ChatResponse
→ AI 모델의 응답을 Spring AI 형식으로 표현한 객체

앞으로 Spring AI를 공부할 때 이 구조를 먼저 기억해두면 이해하기 쉽다.

ChatModel

ChatModel은 다양한 LLM의 요청과 응답을 공통된 방식으로 사용할 수 있도록 추상화한 인터페이스다.

예를 들어 애플리케이션 입장에서는 다음처럼 생각할 수 있다.

            ChatModel

               │
     ┌─────────┼─────────┐
     ▼         ▼         ▼

   OpenAI    Claude     Gemini

각 Provider가 내부적으로 사용하는 API는 다르지만 Spring AI가 중간에서 이를 변환한다.

Spring AI Prompt
       │
       ▼
    ChatModel
       │
       ▼
Provider Native Request
       │
       ▼
      LLM

그리고 LLM에서 받은 응답도 Spring AI의 공통 응답 형태로 변환한다.

LLM Response
     │
     ▼
Provider Native Response
     │
     ▼
Spring AI
     │
     ▼
ChatResponse

따라서 애플리케이션 코드가 특정 AI Provider의 API 구조에 지나치게 종속되는 것을 줄일 수 있다.

ChatClient

실제 애플리케이션에서는 ChatModel을 직접 사용하는 것보다 ChatClient를 사용하는 경우가 많다.

ChatClient는 ChatModel을 보다 편리하게 사용할 수 있도록 만든 고수준 Fluent API다.

예를 들어 다음과 같이 사용할 수 있다.

String result = chatClient
    .prompt()
    .user("Spring AI란 무엇인가?")
    .call()
    .content();

코드를 읽어보면 동작을 거의 그대로 이해할 수 있다.

prompt()
→ AI 요청 생성

user()
→ 사용자 질문 전달

call()
→ AI 모델 호출

content()
→ 응답 내용 추출

전체 흐름은 다음과 같다.

사용자 질문
    │
    ▼
ChatClient
    │
    ▼
ChatModel
    │
    ▼
   LLM
    │
    ▼
ChatResponse
    │
    ▼
응답 Content

Spring AI에서는 이러한 Fluent API를 통해 AI 호출 코드를 Spring 개발자가 익숙하게 사용할 수 있도록 구성한다.

공식 문서에서도 ChatClient를 WebClient, RestClient와 유사한 방식으로 사용할 수 있는 Fluent API로 설명하고 있다.

Spring AI는 어떤 기능을 제공할까?

Spring AI는 단순히 LLM API를 호출하는 기능만 제공하지 않는다.

AI 애플리케이션을 만들 때 필요한 여러 기능을 함께 제공한다.

대표적인 기능은 다음과 같다.

Model API

다양한 AI Model을 공통 인터페이스로 사용할 수 있다.

Chat Model
Embedding Model
Image Model

현재 공식 문서에서는 Chat, Embedding뿐만 아니라 이미지 생성, 음성 인식, 음성 생성 등 다양한 모델 유형을 지원하고 있다.

Prompt

LLM에게 전달하는 입력을 관리한다.

System Message
User Message
Assistant Message
ChatOptions

예를 들어 다음과 같은 정보를 AI에게 전달할 수 있다.

너는 Spring 전문가다.
        ↓
System Message

Spring AI가 무엇인지 설명해줘.
        ↓
User Message

Structured Output

LLM의 자유로운 문자열 응답을 Java 객체와 같은 정형화된 데이터로 변환할 수 있다.

LLM

"홍길동의 나이는 30살입니다."

        ↓

Structured Output

{
  "name": "홍길동",
  "age": 30
}

        ↓

Java Object

즉 AI 응답을 다른 애플리케이션 로직에서 사용하기 쉽게 만들 수 있다.

Advisor

LLM 요청과 응답 사이에 공통 기능을 끼워 넣을 수 있다.

Request
   │
   ▼
Advisor
   │
   ▼
LLM
   │
   ▼
Advisor
   │
   ▼
Response

이를 이용해 다음과 같은 기능을 구현할 수 있다.

Logging
Memory
RAG
요청 가공
응답 가공

Spring AI에서는 반복되는 생성형 AI 패턴을 Advisor라는 확장 메커니즘으로 캡슐화한다.

Embedding과 Vector Store

문장이나 문서의 의미를 Vector로 변환하고 저장할 수 있다.

"Spring AI는 AI 통합 프레임워크다"

            ↓

      Embedding Model

            ↓

[0.12, -0.45, 0.88, ...]

이 벡터를 Vector DB에 저장하면 의미적으로 비슷한 문서를 검색할 수 있다.

RAG

RAG는 외부 문서를 검색하여 그 정보를 LLM의 Prompt에 추가하는 방식이다.

사용자 질문
     │
     ▼
Vector DB 검색
     │
     ▼
관련 문서
     │
     ▼
Prompt에 추가
     │
     ▼
    LLM
     │
     ▼
문서 기반 답변

이를 이용하면 사내 문서나 서비스 데이터를 기반으로 답변하는 AI를 만들 수 있다.

Chat Memory

기본적으로 LLM 호출은 각각 독립적인 요청이다.

따라서 이전 대화를 기억하려면 애플리케이션이 대화 이력을 관리해야 한다.

Spring AI에서는 이를 위한 ChatMemory 기능을 제공한다.

사용자
"내 이름은 철수야"
      │
      ▼
 ChatMemory
      │
      ▼
사용자
"내 이름이 뭐였지?"
      │
      ▼
이전 대화와 함께 LLM 호출

Tool Calling

LLM이 외부 시스템의 기능을 사용하도록 만들 수도 있다.

예를 들어 사용자가 다음과 같이 질문했다고 해보자.

"서울의 현재 날씨 알려줘"

LLM 자체에는 실시간 날씨 정보가 없을 수 있다.

이때 Weather API를 Tool로 등록할 수 있다.

사용자

"서울 날씨 알려줘"

      ↓

     LLM

"Weather Tool이 필요하다"

      ↓

Spring AI

      ↓

Weather API

      ↓

현재 날씨

      ↓

     LLM

      ↓

"서울의 현재 기온은 ...입니다."

Tool Calling은 AI가 단순히 텍스트를 생성하는 것을 넘어 외부 데이터를 조회하거나 실제 작업을 수행하도록 만드는 중요한 기반이다.

MCP

MCP(Model Context Protocol)는 AI 애플리케이션과 외부 Tool 및 Resource를 연결하기 위한 표준 프로토콜이다.

Spring AI는 MCP Client와 MCP Server를 모두 지원한다.

개념적으로는 다음과 같다.

AI Application
      │
      ▼
  MCP Client
      │
      ▼
  MCP Server
      │
      ├─ Tool
      ├─ Resource
      └─ 외부 시스템

이 부분은 이후 별도의 글에서 자세히 살펴볼 예정이다.

결국 Spring AI가 해결하려는 것은 무엇일까?

Spring AI의 핵심을 다시 단순하게 생각해보면 된다.

기업의 기존 Spring 애플리케이션에는 이미 수많은 데이터와 기능이 존재한다.

Database

Service

Repository

REST API

Kafka

Batch

사내 문서

그리고 외부에는 AI Model이 존재한다.

GPT

Claude

Gemini

Local LLM

Spring AI의 중요한 역할은 이 둘을 연결하는 것이다.

Spring AI의 핵심 설계 철학을 기업 DATA와 기업 API를 AI 모델에 연결하는 것으로 정리한다.

기존 Spring Application

 ┌────────────────────────────┐
 │                            │
 │  Service       Database    │
 │                            │
 │  Repository    REST API    │
 │                            │
 │  사내 문서      업무 시스템   │
 │                            │
 └─────────────┬──────────────┘
               │
               ▼

           Spring AI

               │
               ▼

           AI Model

     GPT / Claude / Gemini

즉 기존 서비스를 버리고 AI 전용 애플리케이션을 새로 만드는 것이 아니라, 기존 Spring 생태계 위에 AI 기능을 확장하는 것이 Spring AI의 큰 목적이다.

Spring 개발자 입장에서의 장점

기존 Spring 개발자에게 Spring AI가 특히 유용한 이유는 이미 알고 있는 Spring 개발 방식을 그대로 활용할 수 있기 때문이다.

Spring IoC / DI
Spring Boot
Auto Configuration
Spring Security
Spring Data
Micrometer
MVC / WebFlux

AI 관련 컴포넌트 역시 Bean으로 등록하고 DI를 이용할 수 있다.

@Service
public class AiService {

    private final ChatClient chatClient;

    public AiService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }
}

즉 완전히 새로운 개발 생태계를 배우는 것이 아니라 기존 Spring 애플리케이션 안으로 AI 기능을 가져오는 형태다.

기존 Spring 개발 방식

Controller
Service
Repository
DI
Configuration

        +

AI

ChatClient
RAG
Memory
Tool
MCP

        ↓

Spring AI Application

Spring Security를 이용한 인증·인가, 기존 도메인 Service와 Repository, 운영 환경과 Observability 등을 AI 기능과 함께 활용할 수 있다는 것도 Spring 기반 AI 개발의 장점이다.

Spring AI의 전체 그림

지금까지 살펴본 내용을 하나의 그림으로 정리하면 다음과 같다.

                        Spring Application

                                │
                                ▼

                            ChatClient
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
              ▼                 ▼                 ▼

           Prompt            Advisor            Tool

              │             Memory / RAG          │
              │                                   │
              └─────────────────┬─────────────────┘
                                │
                                ▼

                            ChatModel
                                │
              ┌─────────────────┼─────────────────┐
              ▼                 ▼                 ▼

            OpenAI          Anthropic           Gemini
              │                 │                 │
              └─────────────────┼─────────────────┘
                                │
                                ▼

                               LLM


                         별도의 데이터 영역

              Document
                  │
                  ▼
           Embedding Model
                  │
                  ▼
             Vector Store
                  │
                  ▼
                 RAG
                  │
                  └──────────→ ChatClient

처음 보면 구성 요소가 많아 보이지만 앞으로 하나씩 나누어 보면 어렵지 않다.

가장 먼저 이해해야 할 것은 다음 정도다.

ChatClient
→ AI와 대화하기 위한 고수준 API

ChatModel
→ AI Model을 추상화한 인터페이스

Prompt
→ LLM에 전달하는 요청

Advisor
→ 요청/응답 과정에 기능 추가

Embedding
→ 데이터를 의미 기반 Vector로 변환

Vector Store
→ Vector 저장 및 검색

RAG
→ 외부 지식을 검색해서 Prompt에 추가

Memory
→ 대화 이력 관리

Tool
→ 외부 기능 실행

MCP
→ 외부 Tool/Resource 연결 표준

Spring AI와 AI Agent

Spring AI를 공부하다 보면 최종적으로 AI Agent라는 개념으로 이어진다.

기존 LLM 애플리케이션이 단순히 질문에 답하는 구조였다면,

사용자 질문
    ↓
   LLM
    ↓
텍스트 답변

Agent는 사용자의 목표를 이해하고 필요한 데이터를 찾거나 Tool을 실행할 수 있다.

예를 들어:

사용자

"내일 비가 오면 회의 장소를 실내로 변경해줘."

              ↓

            Agent

              ↓

      내일 날씨 확인
              │
              ▼
         Weather Tool
              │
              ▼
          비 여부 판단
              │
              ▼
        Calendar Tool
              │
              ▼
        회의 장소 변경
              │
              ▼
          Email Tool
              │
              ▼
       참석자에게 알림

즉 AI가 단순한 글쓰기 도구를 넘어 실제 시스템과 연결되어 일을 수행하는 시스템으로 발전하는 것이다.

Spring AI는 이러한 애플리케이션을 만들기 위해 필요한 Model, RAG, Memory, Tool Calling, MCP 등의 기반 기능을 제공한다.

정리

Spring AI는 Spring Framework 기반 애플리케이션에서 생성형 AI 기능을 개발하기 위한 프레임워크다.

단순히 OpenAI API를 호출하는 라이브러리가 아니라 다양한 AI Provider와 AI 애플리케이션 패턴을 Spring 방식으로 사용할 수 있도록 추상화한다.

Spring AI

├─ Model
│   └─ 다양한 AI Model 추상화
│
├─ ChatClient
│   └─ LLM 호출을 위한 Fluent API
│
├─ Prompt
│   └─ LLM 입력 관리
│
├─ Structured Output
│   └─ AI 응답 구조화
│
├─ Advisor
│   └─ 요청/응답 기능 확장
│
├─ Embedding / Vector Store
│   └─ 의미 기반 데이터 검색
│
├─ RAG
│   └─ 외부 지식 활용
│
├─ Chat Memory
│   └─ 대화 기억
│
├─ Tool Calling
│   └─ 외부 기능 실행
│
└─ MCP
    └─ 외부 Tool과 Resource 연결

그리고 이 모든 기능의 중심에는 다음 목적이 있다.

기업 Data
기업 API
기존 업무 시스템

      │
      ▼

   Spring AI

      │
      ▼

   AI Model

한 문장으로 정리하면 다음과 같다.

Spring AI는 기존 Spring 애플리케이션의 데이터와 기능을 AI 모델과 연결하여 생성형 AI 애플리케이션을 만들 수 있도록 도와주는 Spring 기반 AI 프레임워크다.

Spring이 데이터베이스, 웹, 보안 등의 기술을 Spring 방식으로 추상화해왔던 것처럼, Spring AI는 그 방식을 AI 개발 영역까지 확장한 것이라고 이해하면 된다.

[JavaScript][Vue.js] Pinia와 Store 정리 - 전역 상태 관리 이해하기

danieLee — Wed, 26 Aug 2026 16:57:58 +0900

Vue 애플리케이션이 커지면 여러 컴포넌트가 같은 데이터를 함께 사용해야 하는 경우가 많아진다.

예를 들어 다음과 같은 데이터가 있다.

로그인 사용자 정보
장바구니
알림 개수
다크모드 설정
날씨 단위

이런 데이터를 부모에서 자식으로 계속 Props로 전달하면 구조가 복잡해질 수 있다.

App
 ↓
Layout
 ↓
Header
 ↓
Menu
 ↓
UserInfo

중간 컴포넌트가 데이터를 사용하지 않더라도 계속 전달해야 하는 문제가 생긴다.

이럴 때 사용하는 것이 Pinia다.

Pinia는 Vue 애플리케이션에서 여러 컴포넌트가 함께 사용하는 데이터를 중앙에서 관리하기 위한 전역 상태 관리 라이브러리다.

Pinia란?

Pinia는 여러 컴포넌트가 같은 상태를 공유할 수 있도록 Store라는 중앙 저장소를 제공한다.

구조는 다음과 같다.

Component A ─┐
             │
Component B ─┼──→ Store
             │
Component C ─┘

각 컴포넌트가 서로 직접 데이터를 전달하지 않고 같은 Store를 바라보는 방식이다.

예를 들어 로그인 정보를 Store에 저장하면 다음과 같이 사용할 수 있다.

Header
→ 로그인 사용자 이름 표시

MyPage
→ 사용자 정보 표시

Navigation Guard
→ 로그인 여부 확인

모두 같은 로그인 상태를 공유할 수 있다.

Store란?

Store는 여러 컴포넌트가 함께 사용할 상태와 로직을 보관하는 저장소다.

예를 들어 로그인 Store라면 다음과 같은 데이터를 관리할 수 있다.

authStore

user
token
isLoggedIn
login()
logout()

즉 Store에는 단순한 데이터만 들어가는 것이 아니라, 데이터를 가공하거나 변경하는 로직도 함께 들어간다.

Pinia Store의 핵심은 크게 세 가지로 나눌 수 있다.

State
Getters
Actions

Vue의 Composition API와 연결하면 다음과 같다.

Pinia         Vue

State    →    ref / reactive
Getters  →    computed
Actions  →    function

State

State는 Store가 가지고 있는 원본 데이터다.

예를 들어 카운터 Store라면 다음과 같다.

const count = ref(0)

여기서 count가 State다.

로그인 Store라면 다음과 같은 값들이 State가 될 수 있다.

const user = ref(null)
const token = ref(null)

정리하면:

State는 애플리케이션에서 여러 컴포넌트가 공유하는 원본 상태다.

Getters

Getters는 State를 기반으로 계산한 값이다.

Vue의 computed()와 같은 역할을 한다.

예를 들어:

const count = ref(10)

const doubleCount = computed(() => {
  return count.value * 2
})

여기서:

count
→ State

doubleCount
→ Getter

가 된다.

로그인 여부도 Getter로 만들 수 있다.

const isLoggedIn = computed(() => {
  return token.value !== null
})

즉 Getter는 원본 상태를 직접 저장하는 것이 아니라 State를 이용해 만들어진 계산 결과다.

Actions

Actions는 State를 변경하거나 특정 로직을 실행하는 함수다.

예를 들어:

const increment = () => {
  count.value++
}

이 함수가 Action이다.

로그인 Store라면 다음처럼 작성할 수 있다.

const login = (userData, authToken) => {
  user.value = userData
  token.value = authToken
}

로그아웃은 다음과 같이 만들 수 있다.

const logout = () => {
  user.value = null
  token.value = null
}

즉:

Action은 Store의 State를 변경하거나 서버 통신 같은 로직을 처리하는 함수다.

Pinia Store 만들기

예를 들어 카운터 Store를 만든다고 해보자.

파일 구조는 다음과 같이 만들 수 있다.

src/
└─ stores/
   └─ counter.js

Store 코드는 다음과 같다.

import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useCounterStore = defineStore('counter', () => {

  const count = ref(0)

  const doubleCount = computed(() => {
    return count.value * 2
  })

  const increment = () => {
    count.value++
  }

  return {
    count,
    doubleCount,
    increment,
  }
})

구조를 정리하면 다음과 같다.

useCounterStore

├─ count
│   → State
│
├─ doubleCount
│   → Getter
│
└─ increment()
    → Action

defineStore()는 Pinia Store를 만드는 함수다.

defineStore('counter', () => {
  ...
})

첫 번째 값인 'counter'는 Store를 구분하는 고유한 이름이다.

컴포넌트에서 Store 사용하기

Store를 사용할 컴포넌트에서는 먼저 import한다.

<script setup>
import { useCounterStore } from '@/stores/counter'

const counterStore = useCounterStore()
</script>

이제 Template에서 State, Getter, Action을 사용할 수 있다.

<template>
  <p>
    Count: {{ counterStore.count }}
  </p>

  <p>
    Double: {{ counterStore.doubleCount }}
  </p>

  <button @click="counterStore.increment">
    증가
  </button>
</template>

동작 구조는 다음과 같다.

Component
   ↓
useCounterStore()
   ↓
Store 접근
   ↓
State 읽기
Getter 사용
Action 실행

main.js에서 Pinia 등록하기

Pinia를 사용하려면 Vue 애플리케이션에 먼저 등록해야 한다.

import { createApp } from 'vue'
import { createPinia } from 'pinia'

import App from './App.vue'

const app = createApp(App)

app.use(createPinia())

app.mount('#app')

여기서:

createPinia()

는 Pinia 인스턴스를 만들고,

app.use()

를 통해 Vue 애플리케이션에 등록한다.

구조는 다음과 같다.

createPinia()
      ↓
Pinia 생성
      ↓
app.use()
      ↓
Vue Application에 등록

날씨 프로젝트에 적용하기

예를 들어 날씨 프로젝트에서 섭씨와 화씨 설정을 여러 화면에서 함께 사용한다고 해보자.

다음과 같은 Store를 만들 수 있다.

configStore

unit
→ celsius / fahrenheit

unitSymbol
→ ℃ / ℉

toggleUnit()
→ 단위 변경

코드는 다음과 같이 구성할 수 있다.

import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useConfigStore = defineStore('config', () => {

  const unit = ref('celsius')

  const unitSymbol = computed(() => {
    return unit.value === 'celsius'
      ? '℃'
      : '℉'
  })

  const toggleUnit = () => {
    unit.value =
      unit.value === 'celsius'
        ? 'fahrenheit'
        : 'celsius'
  }

  return {
    unit,
    unitSymbol,
    toggleUnit,
  }
})

여기서 역할은 다음과 같다.

unit
→ State

unitSymbol
→ Getter

toggleUnit()
→ Action

이 Store를 여러 컴포넌트에서 사용할 수 있다.

             configStore
                 │
       ┌─────────┼─────────┐
       ▼         ▼         ▼

UnitToggler  HomeView   DetailView

예를 들어 UnitToggler에서:

configStore.toggleUnit()

을 실행하면 Store의 값이 변경된다.

그리고 HomeView, DetailView도 같은 Store를 사용하고 있다면 해당 값이 함께 반영된다.

Props와 Pinia 차이

Props는 부모와 자식 관계에서 데이터를 전달할 때 사용한다.

Parent
   ↓ Props
Child

Pinia는 컴포넌트의 부모·자식 관계와 상관없이 공통 상태를 공유할 때 사용한다.

Component A
     │
     ▼
    Store
     ▲
     │
Component B

비교하면 다음과 같다.

구분	Props	Pinia
범위	부모 → 자식	애플리케이션 전역
목적	컴포넌트 데이터 전달	전역 상태 관리
관계	부모·자식 구조 필요	관계 없어도 됨
대표 예	WeatherCard 데이터	로그인, 장바구니, 설정

즉 단순히 자식에게 필요한 데이터를 전달한다면 Props를 사용하고, 여러 페이지나 여러 컴포넌트에서 같은 데이터를 공유해야 한다면 Pinia를 사용하는 구조다.

provide / inject와 Pinia 차이

provide / inject 역시 깊은 컴포넌트로 데이터를 전달할 수 있다.

하지만 범위가 다르다.

provide / inject
→ 특정 컴포넌트 트리 안에서 공유

Pinia
→ 애플리케이션 전체에서 공유

예를 들어 특정 Form 내부 설정값을 여러 하위 컴포넌트가 사용하는 경우에는 provide / inject를 사용할 수 있다.

반면 다음과 같은 데이터는 Pinia가 적합하다.

로그인 상태
사용자 정보
장바구니
전역 테마
알림 상태
공통 설정값

Pinia의 전체 구조

Pinia 구조를 한 번에 보면 다음과 같다.

                  Pinia

                   │
                 Store
                   │
        ┌──────────┼──────────┐
        │          │          │
        ▼          ▼          ▼

      State      Getter      Action

      ref()     computed()   function

        │          │          │
        └──────────┴──────────┘
                   │
                   ▼

              Components

컴포넌트들은 각각 Store를 불러와 같은 상태를 공유한다.

          Component A
              │
              ▼
          ┌─────────┐
          │  Store  │
          └─────────┘
          ▲    ▲    ▲
          │    │    │
 Component B   │  Component C
               │
          Component D

이 구조 덕분에 컴포넌트 간에 Props를 여러 단계로 전달하지 않고도 공통 상태를 사용할 수 있다.

정리

Pinia는 Vue 애플리케이션의 전역 상태 관리 라이브러리다.

그리고 Store는 Pinia 안에서 실제 데이터를 관리하는 저장소다.

Store의 핵심은 다음 세 가지다.

State
→ 원본 상태
→ ref / reactive

Getters
→ State를 이용한 계산값
→ computed

Actions
→ State 변경 및 로직 실행
→ function

Vue Composition API와 연결하면 다음처럼 이해할 수 있다.

Vue Component

ref()
computed()
function()

      ↓

Pinia Store로 이동

      ↓

State
Getter
Action

즉 기존에는 각 컴포넌트가 자기 상태를 가지고 있었다면, 여러 컴포넌트가 공통으로 사용해야 하는 상태를 Store로 끌어올려 중앙에서 관리하는 것이다.

한 문장으로 정리하면 다음과 같다.

Pinia는 Vue 애플리케이션의 여러 컴포넌트가 함께 사용할 상태를 중앙에서 관리하는 도구이며, Store는 그 안에서 State, Getter, Action을 관리하는 전역 저장소다.

[JavaScript][Vue.js] Slot 정리 - 부모가 자식 컴포넌트에 UI를 주입하는 방법

danieLee — Wed, 26 Aug 2026 13:27:28 +0900

Vue에서 컴포넌트를 만들다 보면 겉모양은 같지만 내부 내용만 바뀌는 UI를 만들고 싶은 경우가 있다.

예를 들어 다음과 같은 카드 컴포넌트를 생각해보자.

┌──────────────────────┐
│                      │
│        내용           │
│                      │
└──────────────────────┘

카드의 외곽 디자인은 같지만 내부에는 상황에 따라 서로 다른 내용을 넣고 싶을 수 있다.

카드 1
→ 날씨 정보

카드 2
→ 사용자 정보

카드 3
→ 공지사항

이럴 때 사용하는 것이 Slot이다.

Slot은 쉽게 말하면,

자식 컴포넌트가 미리 비워둔 영역에 부모 컴포넌트가 원하는 HTML이나 컴포넌트를 넣을 수 있게 하는 기능이다.

Slot의 기본 구조

먼저 자식 컴포넌트에서 <slot>을 선언한다.

<!-- BaseCard.vue -->
<template>
  <div class="card">
    <slot></slot>
  </div>
</template>

여기서

<slot></slot>

부분이 부모가 내용을 넣을 자리다.

부모 컴포넌트에서는 다음과 같이 사용할 수 있다.

<BaseCard>
  <h2>공지사항</h2>
  <p>새로운 공지가 있습니다.</p>
</BaseCard>

그러면 부모가 작성한 내용이 자식 컴포넌트의 <slot> 위치에 들어간다.

개념적으로는 다음과 같이 렌더링된다.

<div class="card">
  <h2>공지사항</h2>
  <p>새로운 공지가 있습니다.</p>
</div>

전체 흐름은 다음과 같다.

Parent Component

<BaseCard>
  <h2>공지사항</h2>
</BaseCard>

        ↓

Child Component

<div class="card">
  <slot />
</div>

        ↓

실제 화면

<div class="card">
  <h2>공지사항</h2>
</div>

Slot과 Props의 차이

Props와 Slot은 둘 다 부모에서 자식으로 무언가를 전달한다는 점에서는 비슷하다.

하지만 전달하는 대상이 다르다.

Props는 데이터를 전달한다.

<WeatherCard
  :city-name="cityName"
  :temperature="25"
/>

여기서 전달하는 것은 다음과 같은 값이다.

"서울"
25
true
객체
배열

반면 Slot은 HTML 구조나 UI 자체를 전달한다.

<BaseCard>
  <h2>서울 날씨</h2>
  <p>현재 기온 25도</p>
  <button>상세보기</button>
</BaseCard>

즉 차이를 정리하면 다음과 같다.

Props
→ 데이터 전달

Slot
→ HTML / UI 전달

왜 Slot을 사용할까?

Slot의 가장 큰 장점은 레이아웃을 재사용할 수 있다는 점이다.

예를 들어 카드 디자인이 다음과 같이 동일하다고 해보자.

<template>
  <div class="card">
    ...
  </div>
</template>

카드마다 내용을 직접 작성하면 비슷한 구조를 계속 반복해야 한다.

하지만 Slot을 사용하면 카드의 공통 디자인은 하나만 만들고 내부 내용만 바꿀 수 있다.

<BaseCard>
  <h2>사용자 정보</h2>
  <p>홍길동</p>
</BaseCard>

<BaseCard>
  <h2>날씨 정보</h2>
  <p>서울 25도</p>
</BaseCard>

<BaseCard>
  <h2>공지사항</h2>
  <p>서버 점검 안내</p>
</BaseCard>

같은 BaseCard를 계속 재사용하면서 내용만 바꾸는 것이다.

기본 Slot

가장 기본적인 Slot은 이름이 없는 Slot이다.

자식:

<!-- BaseCard.vue -->
<template>
  <div class="card">
    <slot></slot>
  </div>
</template>

부모:

<BaseCard>
  <h2>Vue Slot</h2>
  <p>Slot 기본 예제입니다.</p>
</BaseCard>

부모가 전달한 모든 내용이 자식의 <slot> 위치에 삽입된다.

Slot의 기본값

부모가 아무 내용도 전달하지 않는 경우를 대비해 기본 내용을 지정할 수도 있다.

<template>
  <div class="card">
    <slot>
      <p>기본 콘텐츠입니다.</p>
    </slot>
  </div>
</template>

부모가 다음처럼 사용하면

<BaseCard />

화면에는

기본 콘텐츠입니다.

가 표시된다.

반대로 부모가 내용을 전달하면

<BaseCard>
  <h2>새로운 내용</h2>
</BaseCard>

기본값 대신 부모가 전달한 내용이 표시된다.

부모 콘텐츠 있음
→ 부모 콘텐츠 사용

부모 콘텐츠 없음
→ slot 기본값 사용

Named Slot

하나의 컴포넌트에 여러 개의 내용을 각각 다른 위치에 넣고 싶다면 Named Slot을 사용할 수 있다.

예를 들어 카드가 다음 구조라고 해보자.

┌──────────────────────┐
│ Header               │
├──────────────────────┤
│ Main Content         │
├──────────────────────┤
│ Footer               │
└──────────────────────┘

자식 컴포넌트에서 각 Slot에 이름을 지정한다.

<template>
  <div class="card">

    <header>
      <slot name="header"></slot>
    </header>

    <main>
      <slot></slot>
    </main>

    <footer>
      <slot name="footer"></slot>
    </footer>

  </div>
</template>

부모에서는 각 이름에 맞는 내용을 전달한다.

<BaseCard>

  <template #header>
    <h2>게시글 제목</h2>
  </template>

  <p>게시글 내용입니다.</p>

  <template #footer>
    <button>확인</button>
  </template>

</BaseCard>

여기서

#header

는

v-slot:header

의 축약형이다.

마찬가지로

#footer

는

v-slot:footer

를 줄여 쓴 것이다.

정리하면 다음과 같다.

#header
→ header slot

#footer
→ footer slot

이름이 없는 영역
→ 기본 slot

Scoped Slot

일반 Slot은 부모가 자식에게 UI를 전달하는 구조다.

Parent
   ↓
HTML / UI
   ↓
Child

Scoped Slot은 여기서 조금 더 나아가 자식 컴포넌트가 가진 데이터를 부모가 받아서 화면을 구성할 수 있게 한다.

예를 들어 자식이 사용자 데이터를 가지고 있다고 해보자.

<script setup>
const userName = '홍길동'
</script>

<template>
  <slot :name="userName"></slot>
</template>

자식은 Slot을 통해 userName을 전달한다.

부모에서는 이를 받을 수 있다.

<ChildComponent v-slot="slotData">
  <p>사용자 이름: {{ slotData.name }}</p>
</ChildComponent>

흐름은 다음과 같다.

Child Component

userName = "홍길동"

      ↓

slot에 데이터 전달

      ↓

Parent Component

slotData.name

      ↓

홍길동 출력

즉 Scoped Slot은 자식이 데이터를 제공하고, 부모가 그 데이터를 이용해 어떤 HTML을 그릴지 결정하는 방식이다.

Props, Emits, Slot 비교

Vue 컴포넌트 간 통신을 정리하면 다음과 같이 구분할 수 있다.

Props

Parent
   ↓
Child

데이터 전달

Emits

Child
   ↓
Parent

이벤트 전달

Slot

Parent
   ↓
Child의 빈 영역

HTML / UI 전달

Scoped Slot

Child
   ↓
Parent

Slot용 데이터 전달

간단히 비교하면 다음과 같다.

기능	방향	전달하는 것
Props	부모 → 자식	데이터
Emits	자식 → 부모	이벤트, Payload
Slot	부모 → 자식	HTML, UI
Scoped Slot	자식 → 부모	Slot에서 사용할 데이터

어떤 상황에서 Slot을 사용할까?

Slot은 외곽 구조는 같고 내부 내용만 달라지는 컴포넌트에 적합하다.

대표적으로 다음과 같은 UI가 있다.

Card
Modal
Dialog
Layout
Panel
Popup
Form Wrapper

예를 들어 Modal 컴포넌트를 만들 수 있다.

<template>
  <div class="modal">
    <div class="modal-content">
      <slot></slot>
    </div>
  </div>
</template>

사용할 때는 내용만 바꾼다.

<BaseModal>
  <h2>삭제 확인</h2>
  <p>정말 삭제하시겠습니까?</p>
</BaseModal>

또 다른 곳에서는

<BaseModal>
  <h2>로그인</h2>
  <LoginForm />
</BaseModal>

처럼 같은 Modal 디자인을 재사용할 수 있다.

즉 Slot을 이용하면 컴포넌트가 특정 내용에 종속되지 않고 훨씬 유연해진다.

Props와 Slot을 같이 사용할 수도 있다

Props와 Slot은 서로 대체하는 관계가 아니다.

하나의 컴포넌트에서 동시에 사용할 수도 있다.

예를 들어 카드의 상태는 Props로 받고, 카드 내부 내용은 Slot으로 받을 수 있다.

<!-- BaseCard.vue -->

<script setup>
defineProps({
  title: String
})
</script>

<template>
  <div class="card">
    <h2>{{ title }}</h2>

    <slot></slot>
  </div>
</template>

부모:

<BaseCard title="사용자 정보">
  <p>이름: 홍길동</p>
  <button>수정</button>
</BaseCard>

구조를 보면 다음과 같다.

title
→ Props

<p>, <button>
→ Slot

이런 방식으로 데이터와 UI를 각각 적절한 방식으로 전달할 수 있다.

전체 구조 정리

Slot의 기본적인 구조를 하나로 정리하면 다음과 같다.

        Parent Component

        <BaseCard>
          원하는 HTML
        </BaseCard>

               │
               │ UI 전달
               ▼

         Child Component

       ┌─────────────────┐
       │                 │
       │     <slot>      │
       │                 │
       └─────────────────┘

               ↓

         실제 화면 출력

Named Slot을 사용하면 여러 위치를 나눌 수도 있다.

          Parent

   #header   기본   #footer
       │      │       │
       ▼      ▼       ▼

┌─────────────────────────┐
│       header slot       │
├─────────────────────────┤
│       default slot      │
├─────────────────────────┤
│       footer slot       │
└─────────────────────────┘

정리

Slot은 자식 컴포넌트 내부에 부모가 원하는 HTML이나 UI를 넣을 수 있게 하는 기능이다.

가장 기본적인 형태는 다음과 같다.

<slot></slot>

부모에서는

<BaseCard>
  <h2>내용</h2>
</BaseCard>

처럼 사용한다.

기능별로 보면 다음과 같다.

Default Slot
→ 하나의 기본 영역에 콘텐츠 삽입

Named Slot
→ 여러 위치를 이름으로 구분

Scoped Slot
→ 자식의 데이터를 부모가 받아 UI 구성

Props와 비교하면 차이는 더욱 명확하다.

Props
→ 데이터를 전달

Slot
→ HTML / UI를 전달

따라서 한 문장으로 정리하면 다음과 같다.

Slot은 재사용 가능한 컴포넌트의 특정 영역을 비워두고, 부모 컴포넌트가 그 영역에 원하는 HTML이나 컴포넌트를 주입할 수 있게 하는 Vue의 UI 조합 기능이다.

[JavaScript][Vue.js] provide / inject 정리 - 깊은 컴포넌트 간 데이터 전달

danieLee — Wed, 26 Aug 2026 11:03:34 +0900

Props / Emits 는 이전 글 참조

[JavaScript][Vue.js] Props와 Emits 정리 - 부모·자식 컴포넌트 통신

Vue는 화면을 여러 개의 컴포넌트로 나누어 구성한다.예를 들어 하나의 페이지가 다음과 같이 구성되어 있다고 해보자.ParentComponent ├─ HeaderComponent ├─ SearchBar ├─ WeatherCard └─ FooterComponent

daniellee09.tistory.com

Vue에서는 부모와 자식 컴포넌트 사이의 기본적인 데이터 전달 방식으로 Props와 Emits를 사용한다.

하지만 컴포넌트 계층이 깊어지면 단순한 Props 전달만으로는 구조가 복잡해질 수 있다.

예를 들어 다음과 같은 구조가 있다고 해보자.

GrandParent
   ↓
Parent
   ↓
Child
   ↓
GrandChild

GrandParent가 가진 데이터를 GrandChild에서 사용해야 한다면, Props만으로는 중간 컴포넌트들을 계속 거쳐야 한다.

GrandParent
   ↓ Props
Parent
   ↓ Props
Child
   ↓ Props
GrandChild

이때 Parent나 Child는 실제로 그 데이터를 사용하지 않더라도, 단순히 아래 컴포넌트로 전달하기 위해 Props를 받아야 한다.

이런 현상을 Props Drilling이라고 한다.

Props Drilling

Props Drilling은 데이터를 필요로 하지 않는 중간 컴포넌트까지 계속 Props를 전달해야 하는 상황을 의미한다.

예를 들어 최상위 컴포넌트에서 테마 정보를 가지고 있다고 해보자.

const theme = ref('dark')

실제로 이 데이터를 사용하는 것은 가장 아래의 MenuItem 컴포넌트뿐인데, 구조가 다음과 같다면

App
 │
 └─ Layout
      │
      └─ Sidebar
           │
           └─ Menu
                │
                └─ MenuItem

Props 방식에서는 다음처럼 전달해야 한다.

App
 │ theme
 ↓
Layout
 │ theme
 ↓
Sidebar
 │ theme
 ↓
Menu
 │ theme
 ↓
MenuItem

중간 컴포넌트들은 theme을 사용하지 않더라도 계속 전달해야 한다.

이런 구조가 커질수록 Props 관리가 번거로워질 수 있다.

provide / inject란?

provide / inject는 상위 컴포넌트의 데이터를 중간 컴포넌트를 거치지 않고 깊은 하위 컴포넌트에서 직접 사용할 수 있게 하는 기능이다.

역할은 다음과 같이 나뉜다.

provide
→ 상위 컴포넌트가 데이터 제공

inject
→ 하위 컴포넌트가 데이터 사용

구조를 보면 다음과 같다.

GrandParent
   │
   │ provide
   │
   ├─────────────────┐
   │                 │
Parent               │
   │                 │
Child                │
   │                 │
GrandChild ◀─────────┘
           inject

중간에 있는 Parent, Child는 데이터를 전달할 필요가 없다.

즉 provide / inject의 핵심은 컴포넌트 계층을 건너뛰어 데이터를 전달할 수 있다는 것이다.

provide()

상위 컴포넌트에서는 provide()를 이용해 데이터를 제공한다.

기본 형태는 다음과 같다.

provide('key', value)

예를 들어 테마 데이터를 전달하고 싶다면 다음과 같이 작성할 수 있다.

<script setup>
import { ref, provide } from 'vue'

const theme = ref('dark')

provide('theme', theme)
</script>

여기서

provide('theme', theme)

은

theme이라는 이름으로 이 데이터를 하위 컴포넌트들에게 제공한다.

는 의미다.

첫 번째 인자는 데이터를 찾기 위한 key이고, 두 번째 인자는 실제로 전달할 값이다.

provide(
  'theme',
  theme
)

   │
   ├─ key
   └─ value

inject()

하위 컴포넌트에서는 inject()를 이용해 상위 컴포넌트가 제공한 데이터를 가져온다.

<script setup>
import { inject } from 'vue'

const theme = inject('theme')
</script>

<template>
  <p>현재 테마: {{ theme }}</p>
</template>

inject()의 key는 provide()에서 사용한 key와 같아야 한다.

provide('theme', theme)

와

inject('theme')

이 서로 연결된다.

전체 구조는 다음과 같다.

상위 Component

provide('theme', theme)

          ↓

중간 Component

          ↓

하위 Component

inject('theme')

전체 예제

최상위 컴포넌트에서 사용자 이름을 제공하고, 가장 아래에 있는 컴포넌트에서 해당 값을 사용하는 구조를 만들어보자.

GrandParent.vue

<script setup>
import { ref, provide } from 'vue'
import ParentComponent from './ParentComponent.vue'

const userName = ref('홍길동')

provide('userName', userName)
</script>

<template>
  <ParentComponent />
</template>

ParentComponent.vue

<script setup>
import ChildComponent from './ChildComponent.vue'
</script>

<template>
  <ChildComponent />
</template>

ParentComponent에서는 userName과 관련된 코드를 작성하지 않는다.

ChildComponent.vue

<script setup>
import { inject } from 'vue'

const userName = inject('userName')
</script>

<template>
  <p>사용자: {{ userName }}</p>
</template>

데이터 흐름은 다음과 같다.

GrandParent

userName = '홍길동'

provide('userName', userName)

        │
        │
        ▼

ParentComponent

        │
        │ 별도 전달 없음
        ▼

ChildComponent

inject('userName')

        ↓

홍길동

중간 컴포넌트가 데이터를 전달할 필요가 없다는 것이 가장 큰 특징이다.

반응형 데이터도 전달할 수 있다

provide()를 통해 ref나 reactive 같은 반응형 데이터를 전달할 수도 있다.

예를 들어 상위 컴포넌트에서 다음과 같이 선언했다고 해보자.

<script setup>
import { ref, provide } from 'vue'

const theme = ref('dark')

provide('theme', theme)
</script>

하위에서는 그대로 받을 수 있다.

<script setup>
import { inject } from 'vue'

const theme = inject('theme')
</script>

상위 컴포넌트에서 값을 변경하면

theme.value = 'light'

하위 컴포넌트에도 변경 사항이 반영된다.

상위

theme = dark

    ↓

provide

    ↓

inject

    ↓

하위

theme = dark

이후 상위에서

dark
 ↓
light

로 변경하면 하위에서도 같은 반응형 데이터를 참조하고 있기 때문에 화면이 함께 변경된다.

기본값 지정

inject()를 사용할 때 해당 key를 제공하는 상위 컴포넌트가 없을 수도 있다.

이때 기본값을 지정할 수 있다.

const theme = inject('theme', 'light')

동작은 다음과 같다.

상위에서 theme 제공
→ 제공된 값 사용

상위에서 theme 제공 안 함
→ 'light' 사용

컴포넌트를 독립적으로 사용할 가능성이 있다면 기본값을 지정하는 방식이 도움이 된다.

Props와 provide / inject 차이

Props와 provide / inject는 모두 컴포넌트 간 데이터 전달에 사용하지만 목적이 다르다.

구분	Props	provide / inject
기본 방향	부모 → 자식	조상 → 하위
중간 컴포넌트	계속 전달 필요	건너뛸 수 있음
데이터 흐름 확인	명확함	상대적으로 숨겨짐
사용 목적	일반적인 부모·자식 통신	깊은 계층의 공통 데이터 전달

Props는 다음처럼 바로 연결된 관계에 적합하다.

Parent
   ↓ Props
Child

반면 provide / inject는 다음처럼 계층이 깊은 경우에 유용하다.

GrandParent
   │
   ├───────────────┐
   ↓               │
Parent             │
   ↓               │
Child              │
   ↓               │
GrandChild ◀───────┘

따라서 모든 Props를 provide / inject로 바꾸는 것이 아니라, 각각의 목적에 맞게 사용하는 것이 중요하다.

provide / inject와 Pinia의 차이

provide / inject와 Pinia는 모두 여러 컴포넌트에서 데이터를 사용할 수 있게 하지만 범위와 역할이 다르다.

provide / inject는 특정 컴포넌트 계층을 기준으로 동작한다.

App
 │
 └─ Layout
      │
      └─ Sidebar
           │
           └─ Menu

이 구조 안에서 공통으로 사용할 테마나 설정값을 전달하는 데 적합하다.

Pinia는 별도의 전역 Store를 만들어 컴포넌트 계층과 관계없이 데이터를 공유한다.

Component A
      │
      │
      ▼
    Store
      ▲
      │
Component B
      │
Component C

단순하게 구분하면 다음과 같다.

구분	provide / inject	Pinia
범위	특정 컴포넌트 트리	애플리케이션 전체
목적	계층 간 데이터 전달	전역 상태 관리
구조	조상 → 하위	Store 중심
예	테마, 언어, 폼 설정	로그인, 장바구니, 전역 사용자 상태

예를 들어

특정 화면 내부 테마
특정 Form의 설정
공통 UI 옵션

등은 provide / inject로 처리할 수 있다.

반면

로그인 상태
사용자 정보
장바구니
전역 알림

같은 애플리케이션 전체 상태는 Pinia와 같은 상태 관리 도구가 적합하다.

provide / inject 전체 흐름

전체 구조를 하나로 보면 다음과 같다.

               GrandParent

        const theme = ref('dark')

       provide('theme', theme)

                  │
                  │
        ┌─────────┴─────────┐
        │                   │
        ▼                   │
      Parent                │
        │                   │
        ▼                   │
       Child                │
        │                   │
        ▼                   │
    GrandChild ◀────────────┘

       inject('theme')

중간 컴포넌트는 해당 데이터의 존재를 몰라도 된다.

이것이 Props Drilling을 줄일 수 있는 이유다.

정리

Vue의 일반적인 부모·자식 데이터 전달은 Props를 사용한다.

Parent
   ↓ Props
Child

하지만 컴포넌트 계층이 깊어지면 Props를 여러 단계에 걸쳐 전달해야 하는 Props Drilling 문제가 생길 수 있다.

GrandParent
   ↓
Parent
   ↓
Child
   ↓
GrandChild

provide / inject를 사용하면 중간 단계를 건너뛸 수 있다.

상위 Component
      │
      │ provide
      ▼
      ·
      ·
      ·
      ▼
하위 Component
      │
      └─ inject

각 역할은 다음과 같다.

provide()
→ 상위 컴포넌트에서 데이터 제공

inject()
→ 하위 컴포넌트에서 데이터 사용

따라서 한 문장으로 정리하면 다음과 같다.

provide / inject는 상위 컴포넌트가 데이터를 제공하고, 깊은 하위 컴포넌트가 중간 컴포넌트를 거치지 않고 직접 받아 사용할 수 있게 하는 Vue의 의존성 주입 방식이다.

Props는 일반적인 부모·자식 통신에 사용하고, provide / inject는 깊은 컴포넌트 계층에서 공통 데이터를 전달해야 할 때 사용하는 방식으로 구분하면 된다.

[JavaScript][Vue.js] Props와 Emits 정리 - 부모·자식 컴포넌트 통신

danieLee — Wed, 26 Aug 2026 10:49:35 +0900

Vue는 화면을 여러 개의 컴포넌트로 나누어 구성한다.

예를 들어 하나의 페이지가 다음과 같이 구성되어 있다고 해보자.

ParentComponent
   ├─ HeaderComponent
   ├─ SearchBar
   ├─ WeatherCard
   └─ FooterComponent

각 컴포넌트는 서로 독립적으로 동작하지만, 실제 애플리케이션에서는 부모와 자식이 데이터를 주고받아야 한다.

Vue에서는 이때 기본적으로 다음 두 가지 방식을 사용한다.

Props
→ 부모 → 자식

Emits
→ 자식 → 부모

즉,

데이터는 부모에서 자식으로 내려가고, 이벤트는 자식에서 부모로 올라간다.

이 구조를 보통 Props Down, Events Up이라고 한다.

Props란?

Props는 부모 컴포넌트가 자식 컴포넌트에게 데이터를 전달하는 방법이다.

예를 들어 부모 컴포넌트가 도시 이름을 가지고 있다고 해보자.

<script setup>
import WeatherCard from './WeatherCard.vue'

const cityName = '서울'
</script>

<template>
  <WeatherCard :city-name="cityName" />
</template>

여기서

:city-name="cityName"

은 부모의 cityName 데이터를 자식 컴포넌트에 전달한다는 의미다.

자식 컴포넌트에서는 defineProps()를 이용해 받을 데이터를 정의한다.

<script setup>
defineProps({
  cityName: String
})
</script>

<template>
  <p>{{ cityName }}</p>
</template>

전체 흐름은 다음과 같다.

Parent Component
      │
      │ Props
      ▼
Child Component

cityName = "서울"

즉 Props는 부모가 가진 데이터를 자식에게 내려주는 통로다.

defineProps()

Props를 받을 때 사용하는 함수가 defineProps()다.

가장 간단하게는 다음처럼 작성할 수 있다.

defineProps({
  cityName: String,
  temperature: Number
})

조금 더 세밀하게 지정할 수도 있다.

defineProps({
  cityName: {
    type: String,
    required: true
  },

  temperature: {
    type: Number,
    default: 20
  }
})

여기서는 각각 다음 의미를 가진다.

cityName
→ String
→ 반드시 전달 필요

temperature
→ Number
→ 전달되지 않으면 기본값 20

Props는 단순히 데이터를 받는 것뿐 아니라, 어떤 타입의 값을 받을지 규격을 정할 수도 있다.

Props는 읽기 전용이다

부모에게 받은 Props는 자식 컴포넌트에서 직접 수정하면 안 된다.

예를 들어 다음과 같은 코드는 잘못된 방식이다.

const props = defineProps({
  count: Number
})

props.count = 100

Props는 부모가 소유한 데이터이기 때문이다.

Parent
  │
  │ owns data
  ▼
Child

자식 컴포넌트는 전달받은 값을 읽을 수는 있지만, 부모의 원본 상태를 직접 바꾸는 역할을 하지 않는다.

따라서 Props는 다음과 같이 기억하면 된다.

Props
→ 부모 → 자식
→ 데이터 전달
→ 읽기 전용

자식에서 부모 상태를 변경하고 싶다면 직접 수정하는 대신 이벤트를 발생시켜 부모에게 변경을 요청해야 한다.

이때 사용하는 것이 Emits다.

Emits란?

Emits는 자식 컴포넌트에서 발생한 일을 부모 컴포넌트에게 전달하는 방식이다.

예를 들어 WeatherCard를 클릭했을 때 선택된 도시 이름을 부모에게 전달한다고 해보자.

자식 컴포넌트에서는 먼저 사용할 이벤트를 정의한다.

<script setup>
const emit = defineEmits(['select-city'])
</script>

그리고 실제 이벤트를 발생시킨다.

emit('select-city', '서울')

여기서

select-city

는 이벤트 이름이고,

서울

은 부모에게 함께 전달할 데이터다.

자식 컴포넌트를 전체로 보면 다음과 같다.

<script setup>
const emit = defineEmits(['select-city'])

const handleClick = () => {
  emit('select-city', '서울')
}
</script>

<template>
  <button @click="handleClick">
    도시 선택
  </button>
</template>

부모 컴포넌트에서는 @를 사용해 이벤트를 받는다.

<script setup>
import WeatherCard from './WeatherCard.vue'

const handleSelectCity = (city) => {
  console.log(city)
}
</script>

<template>
  <WeatherCard @select-city="handleSelectCity" />
</template>

흐름은 다음과 같다.

Child Component
      │
      │ emit
      ▼
Parent Component

select-city
+
"서울"

즉 Emits는 자식이 부모에게 이벤트를 발생시키고, 필요한 데이터를 함께 전달하는 통로다.

defineEmits()

defineEmits()는 자식 컴포넌트가 어떤 이벤트를 발생시킬지 정의하는 함수다.

const emit = defineEmits([
  'select-city',
  'delete-item'
])

이후 이벤트를 발생시킬 때는 다음과 같이 사용한다.

emit('select-city', cityName)

구조를 보면 다음과 같다.

defineEmits()
→ 사용할 이벤트 정의

emit()
→ 실제 이벤트 발생

Props와 Emits를 함께 사용하기

Props와 Emits는 따로 떨어진 기능이라기보다 부모와 자식 컴포넌트 사이의 하나의 통신 구조로 이해하는 것이 좋다.

예를 들어 부모가 자식에게 도시 정보를 전달하고, 자식이 클릭되면 다시 부모에게 선택된 도시를 알려준다고 해보자.

부모 컴포넌트:

<script setup>
import { ref } from 'vue'
import WeatherCard from './WeatherCard.vue'

const selectedCity = ref('선택된 도시 없음')

const handleSelectCity = (cityName) => {
  selectedCity.value = cityName
}
</script>

<template>
  <p>선택된 도시: {{ selectedCity }}</p>

  <WeatherCard
    city-name="서울"
    status="맑음"
    @select-city="handleSelectCity"
  />
</template>

자식 컴포넌트:

<script setup>
const props = defineProps({
  cityName: String,
  status: String
})

const emit = defineEmits(['select-city'])

const handleClick = () => {
  emit('select-city', props.cityName)
}
</script>

<template>
  <div @click="handleClick">
    <h3>{{ cityName }}</h3>
    <p>{{ status }}</p>
  </div>
</template>

전체 흐름은 다음과 같다.

Parent
  │
  │ Props
  │
  ├─ cityName = 서울
  └─ status = 맑음
  │
  ▼
WeatherCard
  │
  │ 사용자 클릭
  │
  │ emit('select-city', '서울')
  ▼
Parent
  │
  └─ selectedCity = 서울

부모가 데이터를 내려주고,

Parent
   ↓
Props
   ↓
Child

자식은 발생한 이벤트를 다시 부모에게 알린다.

Child
   ↓
Emits
   ↓
Parent

이 두 방향을 합치면 Vue의 기본적인 부모·자식 통신 구조가 완성된다.

:와 @의 의미

부모 컴포넌트에서 자식 컴포넌트를 사용할 때 Props와 Emits는 보통 다음 형태로 함께 나타난다.

<WeatherCard
  :city-name="cityName"
  @select-city="handleSelectCity"
/>

여기서 :는 v-bind의 축약형이다.

:
→ v-bind
→ 자식에게 데이터 전달
→ Props

@는 v-on의 축약형이다.

@
→ v-on
→ 자식 이벤트 수신
→ Emits

따라서 다음 코드는

<ChildComponent
  :data="value"
  @update="handleUpdate"
/>

이렇게 해석할 수 있다.

:data="value"
→ 부모의 value를 자식에게 전달

@update="handleUpdate"
→ 자식이 update 이벤트를 발생시키면
   부모의 handleUpdate 실행

Payload

emit()을 사용할 때 이벤트와 함께 부모에게 데이터를 전달할 수 있다.

이 데이터를 Payload라고 한다.

예를 들어 다음과 같다.

emit('select-city', '서울')

여기서 '서울'이 Payload다.

부모에서는 이벤트 핸들러의 매개변수로 받을 수 있다.

const handleSelectCity = (cityName) => {
  console.log(cityName)
}

여러 데이터를 객체로 묶어 전달하는 것도 가능하다.

emit('select-city', {
  id: 1,
  name: '서울',
  temperature: 28
})

부모에서는 다음처럼 처리한다.

const handleSelectCity = (city) => {
  console.log(city.id)
  console.log(city.name)
  console.log(city.temperature)
}

즉 Emits는 단순한 신호뿐 아니라 필요한 데이터까지 함께 전달할 수 있다.

왜 자식이 Props를 직접 수정하면 안 될까?

Props를 읽기 전용으로 두는 이유는 데이터의 흐름을 명확하게 만들기 위해서다.

만약 부모와 자식이 같은 데이터를 마음대로 변경할 수 있다면 상태가 어디에서 바뀌었는지 추적하기 어려워진다.

예를 들어 다음과 같은 구조라면

Parent
  ↓
Child A
  ↓
Child B

여러 컴포넌트가 같은 상태를 마음대로 수정하면 데이터 흐름을 파악하기 어려워질 수 있다.

Vue에서는 이를 다음과 같이 단순화한다.

상태를 가진 곳
→ Parent

데이터 전달
→ Props

변경 요청
→ Emits

실제 상태 변경
→ Parent

즉 데이터의 소유권은 부모에게 두고, 자식은 변경이 필요하다는 이벤트만 전달하는 방식이다.

이러한 단방향 흐름 덕분에 상태 변화를 추적하기 쉬워진다.

컴포넌트 통신 전체 구조

Props와 Emits를 하나의 그림으로 정리하면 다음과 같다.

              Parent Component
                    │
                    │ Props
                    │
                    ▼
              Child Component
                    │
                    │ Emits
                    │
                    ▼
              Parent Component

좀 더 구체적으로 표현하면 다음과 같다.

         Parent State

        cityName = 서울
              │
              │ :city-name
              ▼
        ┌─────────────┐
        │ WeatherCard │
        └─────────────┘
              │
              │ 사용자 클릭
              │
              │ emit
              ▼
       @select-city
              │
              ▼
      handleSelectCity()
              │
              ▼
       Parent State 변경

이 구조가 Vue 컴포넌트 통신의 가장 기본적인 형태다.

정리

Props와 Emits는 Vue에서 부모와 자식 컴포넌트가 통신하는 기본 방식이다.

구분	Props	Emits
방향	부모 → 자식	자식 → 부모
목적	데이터 전달	이벤트 전달
정의	defineProps()	defineEmits()
부모 Template	:prop="value"	@event="handler"
데이터 변경	자식 직접 수정 X	부모에게 변경 요청
전달 데이터	상태 값	Payload 가능

가장 핵심인 구조는 다음과 같다.

Props Down
Events Up

즉,

부모
 │
 │ Props
 ▼
자식
 │
 │ Emits
 ▼
부모

Vue에서는 부모가 상태를 관리하고 자식에게 필요한 데이터를 Props로 전달한다.

자식 컴포넌트에서 상태 변경이 필요하면 부모의 데이터를 직접 수정하는 대신 Emits를 통해 이벤트를 발생시킨다.

결국 Props와 Emits는 컴포넌트 사이의 데이터 흐름을 한 방향으로 명확하게 유지하기 위한 Vue의 기본 통신 구조라고 정리할 수 있다.

[JavaScript][Vue.js] Component Lifecycle과 Lifecycle Hook 정리

danieLee — Wed, 26 Aug 2026 10:37:30 +0900

Vue의 컴포넌트는 단순히 화면에 나타나기만 하는 것이 아니라, 생성되고 화면에 붙고, 데이터 변화에 따라 갱신되고, 마지막에는 화면에서 제거되는 과정을 거친다.

이 전체 과정을 Component Lifecycle이라고 한다.

쉽게 정리하면 다음과 같다.

생성
 ↓
마운트
 ↓
업데이트
 ↓
언마운트

그리고 Vue는 각 단계마다 특정 시점에 원하는 코드를 실행할 수 있도록 Lifecycle Hook을 제공한다.

대표적으로 다음과 같은 함수들이 있다.

onMounted()
onUpdated()
onUnmounted()

즉, Lifecycle은 컴포넌트의 전체 생명주기이고, Lifecycle Hook은 그 생명주기의 특정 시점에 실행되는 함수라고 보면 된다.

Component Lifecycle이란?

컴포넌트는 화면에 등장하기 전부터 내부적으로 여러 단계를 거친다.

예를 들어 다음과 같은 Vue 컴포넌트가 있다고 해보자.

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">
    {{ count }}
  </button>
</template>

이 컴포넌트가 실행되면 내부적으로 다음과 같은 흐름을 거친다.

컴포넌트 생성
      ↓
반응형 데이터 준비
      ↓
DOM에 연결
      ↓
화면 표시
      ↓
count 변경
      ↓
화면 업데이트
      ↓
컴포넌트 제거

이처럼 컴포넌트는 한 번 만들어지고 끝나는 것이 아니라 여러 상태를 거쳐 움직인다.

Vue에서는 이 과정을 크게 다음 네 단계로 나눌 수 있다.

Creation
Mounting
Updating
Unmounting

생성 단계 Creation

생성 단계는 컴포넌트가 메모리상에 만들어지는 시점이다.

이 단계에서는 <script setup> 내부의 코드가 실행되고, ref, reactive, computed, watch 같은 반응형 데이터와 로직이 준비된다.

예를 들어 다음과 같다.

<script setup>
import { ref } from 'vue'

const count = ref(0)

console.log('컴포넌트 생성')
</script>

이 시점에는 컴포넌트가 아직 실제 브라우저 DOM에 완전히 붙기 전이다.

따라서 화면 요소에 직접 접근하는 작업은 아직 적절하지 않다.

생성 단계는 주로 다음과 같이 이해하면 된다.

컴포넌트 메모리 생성
       ↓
반응형 상태 초기화
       ↓
함수와 계산 로직 준비

마운트 단계 Mounting

마운트는 컴포넌트가 실제 브라우저 DOM에 연결되는 단계다.

즉, <template>에 작성한 div, button, input 같은 요소가 실제 화면에 만들어진 상태다.

이 시점에 사용하는 대표적인 Lifecycle Hook이 onMounted()다.

<script setup>
import { onMounted } from 'vue'

onMounted(() => {
  console.log('컴포넌트가 DOM에 연결됨')
})
</script>

onMounted()는 컴포넌트가 실제 화면에 붙은 뒤 실행된다.

흐름을 보면 다음과 같다.

컴포넌트 생성
      ↓
Virtual DOM 구성
      ↓
Real DOM에 연결
      ↓
onMounted()

이 시점에는 실제 DOM 요소가 존재하므로 DOM 접근이 가능하다.

또한 초기 데이터를 가져오는 작업도 이 단계에서 처리할 수 있다.

예를 들어 서버에서 사용자 목록을 가져온다고 해보자.

<script setup>
import { ref, onMounted } from 'vue'
import axios from 'axios'

const users = ref([])

onMounted(async () => {
  const response = await axios.get('/api/users')

  users.value = response.data
})
</script>

전체 흐름은 다음과 같다.

컴포넌트 생성
      ↓
DOM에 연결
      ↓
onMounted()
      ↓
API 요청
      ↓
데이터 저장
      ↓
화면 갱신

업데이트 단계 Updating

Vue에서 ref나 reactive 같은 반응형 데이터가 변경되면 화면도 함께 변경된다.

예를 들어 다음과 같은 코드가 있다고 해보자.

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">
    {{ count }}
  </button>
</template>

버튼을 누르면 count 값이 변경된다.

count = 0
   ↓
버튼 클릭
   ↓
count = 1

Vue는 이 변화를 감지하고 화면을 다시 갱신한다.

반응형 데이터 변경
        ↓
Vue가 변경 감지
        ↓
Virtual DOM 갱신
        ↓
변경된 부분 확인
        ↓
Real DOM 반영

업데이트가 완료된 이후 실행되는 Hook이 onUpdated()다.

<script setup>
import { onUpdated } from 'vue'

onUpdated(() => {
  console.log('화면 업데이트 완료')
})
</script>

따라서 데이터 변경 이후 DOM 상태를 확인해야 하는 경우 사용할 수 있다.

다만 onUpdated()는 컴포넌트가 업데이트될 때마다 실행될 수 있기 때문에 무거운 작업을 넣는 것은 피하는 것이 좋다.

예를 들어 onUpdated() 내부에서 또 다른 반응형 데이터를 계속 변경하면 반복적인 업데이트가 발생할 수 있다.

언마운트 단계 Unmounting

언마운트는 컴포넌트가 화면에서 제거되는 단계다.

예를 들어 다음과 같은 부모 컴포넌트가 있다고 해보자.

<ChildComponent v-if="isVisible" />

isVisible이 false가 되면 ChildComponent는 화면에서 제거된다.

isVisible = true
      ↓
ChildComponent 존재

isVisible = false
      ↓
ChildComponent 제거

이 시점에 사용하는 대표적인 Hook이 onUnmounted()다.

<script setup>
import { onUnmounted } from 'vue'

onUnmounted(() => {
  console.log('컴포넌트 제거 완료')
})
</script>

언마운트 단계에서 중요한 것은 Cleanup 작업이다.

왜 Cleanup이 필요할까?

컴포넌트가 사라졌다고 해서 모든 JavaScript 작업이 자동으로 종료되는 것은 아니다.

예를 들어 컴포넌트에서 타이머를 실행했다고 해보자.

const timerId = setInterval(() => {
  console.log('실행 중')
}, 1000)

컴포넌트가 화면에서 제거되어도 setInterval()은 계속 실행될 수 있다.

이를 그대로 두면 불필요한 연산이 계속 발생하고 메모리 누수의 원인이 될 수 있다.

그래서 컴포넌트가 제거될 때 타이머도 함께 정리한다.

<script setup>
import { onMounted, onUnmounted } from 'vue'

let timerId

onMounted(() => {
  timerId = setInterval(() => {
    console.log('실행 중')
  }, 1000)
})

onUnmounted(() => {
  clearInterval(timerId)
})
</script>

전체 흐름은 다음과 같다.

컴포넌트 생성
      ↓
onMounted()
      ↓
setInterval 시작
      ↓
컴포넌트 사용
      ↓
컴포넌트 제거
      ↓
onUnmounted()
      ↓
clearInterval()

타이머뿐만 아니라 전역 이벤트 리스너 같은 작업도 같은 방식으로 정리할 수 있다.

Before Hook도 있다

Vue에는 각 주요 단계가 실행되기 직전 시점을 다룰 수 있는 Hook도 있다.

대표적으로 다음과 같다.

onBeforeMount()
onBeforeUpdate()
onBeforeUnmount()

전체 흐름을 보면 이해하기 쉽다.

컴포넌트 생성
      ↓
onBeforeMount()
      ↓
DOM에 연결
      ↓
onMounted()
      ↓
데이터 변경
      ↓
onBeforeUpdate()
      ↓
DOM 업데이트
      ↓
onUpdated()
      ↓
컴포넌트 제거 시작
      ↓
onBeforeUnmount()
      ↓
DOM에서 제거
      ↓
onUnmounted()

주요 Lifecycle Hook 정리

Lifecycle Hook	실행 시점	주요 용도
onBeforeMount()	DOM에 연결되기 직전	마운트 전 처리
onMounted()	DOM에 연결된 후	API 호출, DOM 접근
onBeforeUpdate()	DOM 업데이트 직전	업데이트 전 상태 확인
onUpdated()	DOM 업데이트 완료 후	변경된 DOM 처리
onBeforeUnmount()	컴포넌트 제거 직전	제거 전 정리
onUnmounted()	컴포넌트 제거 후	타이머, 이벤트 정리

처음에는 다음 세 가지를 중심으로 이해하면 된다.

onMounted()
→ 컴포넌트가 화면에 붙은 뒤

onUpdated()
→ 화면이 업데이트된 뒤

onUnmounted()
→ 컴포넌트가 제거된 뒤

onMounted와 API 호출

Lifecycle Hook 중 onMounted()는 초기 데이터 조회와 연결되는 경우가 많다.

예를 들어 날씨 데이터를 가져오는 컴포넌트를 만든다고 해보자.

<script setup>
import { ref, onMounted } from 'vue'
import axios from 'axios'

const weather = ref(null)

onMounted(async () => {
  const response = await axios.get('/api/weather')

  weather.value = response.data
})
</script>

<template>
  <div v-if="weather">
    {{ weather.temperature }}
  </div>
</template>

흐름은 다음과 같다.

Weather Component 생성
          ↓
DOM Mount
          ↓
onMounted()
          ↓
Backend API 호출
          ↓
JSON 응답
          ↓
weather 변경
          ↓
화면 업데이트

이 구조는 Lifecycle과 Vue의 반응형 데이터가 어떻게 연결되는지를 보여준다.

전체 Lifecycle 흐름

Component Lifecycle 전체를 하나로 정리하면 다음과 같다.

        Component 생성
               ↓
        <script setup>
               ↓
       onBeforeMount()
               ↓
          DOM Mount
               ↓
          onMounted()
               ↓
        ┌─────────────┐
        │             │
        │ 데이터 변경 │
        │             │
        └──────┬──────┘
               ↓
      onBeforeUpdate()
               ↓
         DOM Update
               ↓
          onUpdated()
               ↓
       데이터가 변경되면
       위 과정 반복
               ↓
     onBeforeUnmount()
               ↓
        DOM에서 제거
               ↓
        onUnmounted()

즉 컴포넌트는 단순히 한 번 렌더링되는 것이 아니라, 상태 변화에 따라 여러 번 업데이트되다가 필요 없어지면 제거된다.

정리

Component Lifecycle은 Vue 컴포넌트가 생성되고 제거될 때까지 거치는 전체 과정이다.

크게 네 단계로 구분할 수 있다.

Creation
   ↓
Mounting
   ↓
Updating
   ↓
Unmounting

그리고 Vue는 각 단계에 맞춰 코드를 실행할 수 있도록 Lifecycle Hook을 제공한다.

Mount
→ onMounted()

Update
→ onUpdated()

Unmount
→ onUnmounted()

실제로 중요한 흐름은 다음과 같다.

컴포넌트 생성
      ↓
화면에 연결
      ↓
초기 데이터 요청
      ↓
사용자의 입력
      ↓
반응형 데이터 변경
      ↓
화면 업데이트
      ↓
컴포넌트 제거
      ↓
타이머 / 이벤트 정리

한 문장으로 정리하면 다음과 같다.

Component Lifecycle은 Vue 컴포넌트가 생성, 마운트, 업데이트, 언마운트되는 전체 생명주기이며, Lifecycle Hook은 각 시점에 원하는 로직을 실행할 수 있도록 제공되는 함수다.

[JavaScript][Vue.js] Composition API란? - Options API와의 차이부터 ref, computed, watch까지

danieLee — Wed, 26 Aug 2026 10:29:39 +0900

Vue 3에서 컴포넌트의 로직을 작성하는 대표적인 방식이 Composition API다.

Composition API는 컴포넌트에서 사용하는 데이터, 함수, 계산된 값, 감시 로직 등을 하나의 기능 단위로 묶어서 작성하는 방식이다.

Vue 2에서는 주로 Options API를 사용했지만, Vue 3에서는 Composition API와 <script setup> 방식이 기본적인 작성 방식으로 사용된다.

Composition API란?

Composition은 말 그대로 여러 로직을 조합(Composition)한다는 의미다.

예를 들어 카운터 기능을 만든다고 해보자.

카운터에는 최소한 다음과 같은 요소가 필요하다.

count 데이터
증가 함수
감소 함수
count를 이용한 계산값

Composition API에서는 이와 관련된 코드를 한곳에 모아 작성할 수 있다.

<script setup>
import { ref, computed } from 'vue'

const count = ref(0)

const increment = () => {
  count.value++
}

const decrement = () => {
  count.value--
}

const doubleCount = computed(() => {
  return count.value * 2
})
</script>

<template>
  <div>
    <p>현재 값: {{ count }}</p>
    <p>2배 값: {{ doubleCount }}</p>

    <button @click="increment">증가</button>
    <button @click="decrement">감소</button>
  </div>
</template>

카운터와 관련된 상태와 함수가 하나의 영역에 모여 있다.

[카운터 기능]

count
increment()
decrement()
doubleCount

이처럼 기능과 관련된 로직을 하나의 묶음으로 구성하는 것이 Composition API의 핵심이다.

기존 Options API와 무엇이 다른가?

Vue 2에서는 주로 Options API를 사용했다.

Options API는 컴포넌트의 코드를 역할별로 나눈다.

export default {
  data() {
    return {
      count: 0
    }
  },

  computed: {
    doubleCount() {
      return this.count * 2
    }
  },

  methods: {
    increment() {
      this.count++
    }
  },

  watch: {
    count(newValue) {
      console.log(newValue)
    }
  }
}

구조를 보면 다음과 같다.

data
→ 데이터

computed
→ 계산된 값

methods
→ 함수

watch
→ 데이터 감시

즉, 기능이 아니라 역할을 기준으로 코드를 나누는 방식이다.

컴포넌트의 규모가 작다면 구조가 명확하다.

하지만 하나의 기능이 커지면 관련 코드가 여러 영역에 흩어질 수 있다.

예를 들어 로그인 기능을 만든다고 해보자.

data
 └─ user

computed
 └─ isLoggedIn

methods
 ├─ login()
 └─ logout()

watch
 └─ user 감시

로그인이라는 하나의 기능을 수정하기 위해 data, computed, methods, watch 영역을 각각 확인해야 한다.

Composition API는 이를 기능 중심으로 모은다.

const user = ref(null)

const isLoggedIn = computed(() => {
  return user.value !== null
})

const login = () => {
  user.value = {
    name: 'Kim'
  }
}

const logout = () => {
  user.value = null
}

watch(user, () => {
  console.log('로그인 상태 변경')
})

구조를 보면 다음과 같다.

[로그인 기능]

user
isLoggedIn
login()
logout()
watch()

자료에서도 Options API는 data, methods, computed와 같은 정해진 옵션에 코드를 나누는 방식이고, Composition API는 관련 있는 데이터와 함수를 논리적인 기능별로 묶는 방식으로 구분한다.

정리하면 다음과 같다.

구분	Options API	Composition API
코드 구성 기준	역할별	기능별
상태 선언	data()	ref(), reactive()
함수	methods	일반 JavaScript 함수
계산값	computed 옵션	computed()
감시	watch 옵션	watch()
작성 방식	<script>	주로 <script setup>
Vue 기준	Vue 2 중심	Vue 3 표준

<script setup>은 무엇인가?

Composition API는 Vue 3.2부터 <script setup> 안에서 간결하게 작성할 수 있다.

Vue의 Single File Component는 기본적으로 다음 구조를 가진다.

<script setup>
  // JavaScript
</script>

<template>
  <!-- HTML -->
</template>

<style scoped>
  /* CSS */
</style>

각 영역의 역할은 다음과 같다.

<script setup>
→ 데이터
→ 함수
→ 비즈니스 로직

<template>
→ 화면 구조

<style>
→ 디자인

자료에서도 Vue 3의 SFC는 <script setup>, <template>, <style>의 구조로 구성되며, <script setup>에서 데이터와 함수 등의 기능 로직을 작성한다고 설명한다.

예를 들어 간단한 카운터는 다음과 같이 작성할 수 있다.

<script setup>
import { ref } from 'vue'

const count = ref(0)

const increment = () => {
  count.value++
}
</script>

<template>
  <button @click="increment">
    {{ count }}
  </button>
</template>

Options API처럼

export default {
  data() {},
  methods: {}
}

구조를 만들 필요 없이 일반 JavaScript처럼 변수와 함수를 선언한다.

Composition API의 핵심 함수

Composition API는 Vue에서 제공하는 여러 함수를 조합해서 사용한다.

대표적인 기능은 다음과 같다.

ref()
reactive()
computed()
watch()
watchEffect()

onMounted()
onUpdated()
onUnmounted()

자료에서도 Vue 3 내장 기능을 Reactive State, Computed & Watchers, Lifecycle Hooks 등으로 구분하고 있다.

ref()

ref()는 값을 반응형 상태(Reactive State)로 만드는 함수다.

import { ref } from 'vue'

const count = ref(0)

일반 JavaScript 변수와 달리 ref()로 만든 데이터는 값이 변경되면 Vue가 그 변화를 감지하고 화면을 업데이트한다.

<script setup>
import { ref } from 'vue'

const count = ref(0)

const increment = () => {
  count.value++
}
</script>

<template>
  <p>{{ count }}</p>

  <button @click="increment">
    증가
  </button>
</template>

count.value++

하지만 <template>에서는 .value가 필요 없다.

<p>{{ count }}</p>

즉 다음과 같다.

<script setup>

count.value


<template>

count

자료에서도 ref()는 원시 타입뿐 아니라 배열과 객체도 반응형 상태로 만들 수 있으며, script에서는 .value, template에서는 .value 없이 사용한다고 설명한다.

reactive()

reactive() 역시 반응형 데이터를 만드는 함수다.

주로 객체나 배열과 같은 참조형 데이터를 다룬다.

import { reactive } from 'vue'

const user = reactive({
  name: '홍길동',
  age: 20
})

ref()와 달리 .value를 사용하지 않는다.

user.age++

Template에서도 동일하다.

<p>{{ user.name }}</p>
<p>{{ user.age }}</p>

다만 reactive() 객체 자체를 새로운 객체로 재할당하면 반응성 연결이 끊어질 수 있다는 점을 주의해야 한다.

예를 들어 다음과 같은 방식은 피해야 한다.

let state = reactive({
  count: 0
})

state = {
  count: 10
}

대신 내부 속성을 변경한다.

state.count = 10

또는 객체와 배열까지 ref()로 통일해서 사용하는 방식도 가능하다.

const state = ref({
  count: 0
})

state.value.count = 10

computed()

computed()는 기존 반응형 데이터를 이용해서 새로운 값을 계산할 때 사용한다.

예를 들어 상품 가격과 수량이 있다고 해보자.

const price = ref(10000)
const quantity = ref(3)

총 가격은 다음과 같이 계산할 수 있다.

const totalPrice = computed(() => {
  return price.value * quantity.value
})

Template에서는 다음과 같이 사용한다.

<p>총 가격: {{ totalPrice }}원</p>

구조는 다음과 같다.

price
   +
quantity
   ↓
computed
   ↓
totalPrice

price 또는 quantity가 변경되면 totalPrice도 자동으로 다시 계산된다.

computed()의 중요한 특징은 캐싱(Caching)이다.

const doubleCount = computed(() => {
  return count.value * 2
})

count 값이 바뀌지 않았다면 이전 계산 결과를 재사용한다.

일반 함수가 컴포넌트가 다시 렌더링될 때마다 재실행되는 반면, computed()는 의존하는 반응형 데이터가 변경됐을 때만 다시 계산된다.

그래서

값을 만들어서 화면에 보여주고 싶다
→ computed

라고 생각하면 된다.

watch()

watch()는 특정 반응형 데이터가 변경되는 것을 감시하고, 변경되었을 때 특정 작업을 수행한다.

import { ref, watch } from 'vue'

const city = ref('서울')

watch(city, (newValue, oldValue) => {
  console.log(oldValue)
  console.log(newValue)
})

city가

서울

에서

수원

으로 변경되면 watch()의 callback이 실행된다.

city 변경
   ↓
watch 감지
   ↓
callback 실행

watch()는 다음과 같은 상황에서 활용할 수 있다.

검색어 변경
→ API 다시 호출

선택 도시 변경
→ 날씨 데이터 다시 조회

로그인 상태 변경
→ 사용자 정보 저장

설정값 변경
→ LocalStorage 저장

watch()를 반응형 데이터의 변경을 감지한 뒤 서버 통신이나 데이터 저장 같은 후속 로직을 실행하기 위한 함수로 설명할 수 있다.

watchEffect()

watchEffect() 역시 데이터를 감시하지만 watch()와 차이가 있다.

watch()는 감시할 변수를 직접 지정한다.

watch(city, () => {

})

반면 watchEffect()는 내부에서 사용하는 반응형 데이터를 Vue가 자동으로 추적한다.

watchEffect(() => {
  console.log(city.value)
  console.log(age.value)
})

Vue가 내부 코드를 확인한 뒤

city
age

를 자동으로 감시한다.

또한 watchEffect()는 컴포넌트가 생성될 때 최초 한 번 즉시 실행된다.

watchEffect()는 감시 대상을 별도로 지정하지 않고 함수 내부에서 접근한 반응형 데이터를 자동으로 추적하며, 최초 실행 시에도 즉시 실행된다.

차이를 단순하게 보면 다음과 같다.

구분	watch()	watchEffect()
감시 대상	직접 지정	자동 추적
이전 값	사용 가능	사용 불가
현재 값	사용 가능	내부에서 직접 사용
최초 실행	기본적으로 X	O

Lifecycle Hook

컴포넌트에도 생성부터 제거까지의 생명주기가 있다.

생성
 ↓
Mount
 ↓
Update
 ↓
Unmount

Composition API에서는 이 시점에 맞춰 특정 함수를 실행할 수 있다.

대표적으로 다음 세 가지가 있다.

onMounted()
onUpdated()
onUnmounted()

onMounted()

컴포넌트가 실제 DOM에 연결된 이후 실행된다.

import { onMounted } from 'vue'

onMounted(() => {
  console.log('화면에 컴포넌트가 생성됨')
})

초기 API 요청 등을 처리할 수 있다.

onMounted(async () => {
  const response = await axios.get('/api/users')
})

onUpdated()

반응형 데이터가 변경되고 화면이 다시 그려진 이후 실행된다.

onUpdated(() => {
  console.log('화면 업데이트 완료')
})

onUnmounted()

컴포넌트가 화면에서 제거된 이후 실행된다.

onUnmounted(() => {
  console.log('컴포넌트 제거 완료')
})

타이머나 이벤트 리스너를 정리할 때 사용할 수 있다.

onUnmounted(() => {
  clearInterval(timerId)
})

Mount 시점은 초기 DOM 조작과 API 호출, Unmount 시점은 타이머 및 이벤트 리스너 정리 등에 활용하는 단계이다.

하나의 기능으로 묶어보면

Composition API의 장점은 각각의 함수 자체보다 이 함수들을 하나의 기능 단위로 조합할 수 있다는 점에 있다.

예를 들어 상품 검색 기능을 만든다고 해보자.

<script setup>
import { ref, computed, watch } from 'vue'

const searchKeyword = ref('')

const products = ref([
  { id: 1, name: '노트북' },
  { id: 2, name: '키보드' },
  { id: 3, name: '마우스' }
])

const filteredProducts = computed(() => {
  return products.value.filter((product) =>
    product.name.includes(searchKeyword.value)
  )
})

watch(searchKeyword, (newKeyword) => {
  console.log('검색어 변경:', newKeyword)
})

const clearSearch = () => {
  searchKeyword.value = ''
}
</script>

검색 기능과 관련된 코드가 한곳에 정리된다.

[상품 검색 기능]

searchKeyword
products
filteredProducts
watch()
clearSearch()

이것이 Composition API가 말하는 Composition이다.

각 기능에 필요한 상태와 로직을 하나의 묶음으로 구성하는 것이다.

Composable

Composition API의 기능 묶음은 별도의 JavaScript 함수로 분리할 수도 있다.

이를 Composable이라고 한다.

예를 들어 여러 컴포넌트에서 공통으로 사용하는 카운터 기능이 있다고 해보자.

// useCounter.js

import { ref } from 'vue'

export function useCounter() {
  const count = ref(0)

  const increment = () => {
    count.value++
  }

  const decrement = () => {
    count.value--
  }

  return {
    count,
    increment,
    decrement
  }
}

컴포넌트에서는 필요한 기능을 가져온다.

<script setup>
import { useCounter } from './useCounter'

const {
  count,
  increment,
  decrement
} = useCounter()
</script>

하나의 기능을 별도의 JavaScript 모듈로 분리했기 때문에 여러 컴포넌트에서 재사용할 수 있다.

useCounter()

        ↓

Component A
Component B
Component C

Composable을 Vue의 반응형 상태와 로직을 묶어서 재사용할 수 있도록 만든 함수로 설명한다.

Composition API 전체 구조

지금까지 살펴본 내용을 하나로 정리하면 다음과 같다.

            Composition API

                  │
       ┌──────────┼──────────┐
       │          │          │
       ↓          ↓          ↓

   Reactive    Computed    Watcher
    State

       │          │          │
       ↓          ↓          ↓

    ref()      computed()   watch()
  reactive()              watchEffect()

                  │
                  ↓

          Lifecycle Hooks

         onMounted()
         onUpdated()
         onUnmounted()

                  │
                  ↓

             Component

결국 Composition API는 특정 함수 하나를 의미하는 것이 아니다.

ref
+
reactive
+
computed
+
watch
+
Lifecycle Hook
+
일반 JavaScript 함수

같은 기능들을 조합해서 하나의 컴포넌트 로직을 구성하는 방식 전체를 의미한다.

정리

Options API와 Composition API의 가장 중요한 차이는 코드를 어떤 기준으로 구성하느냐다.

Options API는 역할을 기준으로 나눈다.

data
methods
computed
watch

Composition API는 기능을 기준으로 묶는다.

로그인 기능

user
isLoggedIn
login()
logout()
watch()

그리고 Vue 3에서는 다음과 같은 형태로 구성한다.

<script setup>
import {
  ref,
  computed,
  watch,
  onMounted
} from 'vue'

const data = ref(...)

const result = computed(() => {
  ...
})

watch(data, () => {
  ...
})

const functionName = () => {
  ...
}

onMounted(() => {
  ...
})
</script>

핵심을 한 문장으로 정리하면 다음과 같다.

Composition API는 Vue 컴포넌트에서 사용하는 상태, 함수, 계산 로직, 감시 로직 등을 기능 단위로 조합해서 작성하는 Vue 3의 코드 구성 방식이다.

Composition API를 이해한 뒤에는 ref(), reactive(), computed(), watch()를 각각 구체적으로 정리하면 Vue의 반응형 데이터 처리 구조를 이해하기 쉬워진다.

[JavaScript][Vue.js] Vue Directive 문법 정리 - v-bind부터 v-if, v-for까지

danieLee — Mon, 24 Aug 2026 22:16:45 +0900

Vue에서 <template>을 작성하다 보면 일반 HTML에서는 볼 수 없었던 속성들이 등장한다.

v-html
v-bind
v-if
v-show
v-for

이처럼 v-로 시작하는 Vue 전용 특수 속성을 Directive(디렉티브)라고 한다.

Directive를 사용하면 HTML 태그와 JavaScript 데이터를 연결하여 화면의 내용, 속성, 스타일, 조건, 반복 등을 동적으로 제어할 수 있다.

Vue의 Directive에서 특히 중요한 점은 다음과 같은 코드에서

<img :src="imageUrl">

"imageUrl"이 단순한 문자열이 아니라 JavaScript 표현식이 실행되는 영역이라는 것이다.

즉 Vue의 Template은 단순한 HTML이 아니라 JavaScript 데이터와 연결되어 동적으로 변경되는 화면이라고 볼 수 있다.

데이터를 화면에 출력하는 방법

Vue에서 데이터를 화면에 출력하는 가장 기본적인 방법은 {{ }}를 사용하는 것이다.

<script setup>
const message = 'Hello Vue'
</script>

<template>
  <p>{{ message }}</p>
</template>

화면에는 다음과 같이 출력된다.

Hello Vue

이를 Text Interpolation(텍스트 보간법)이라고 한다.

하지만 문자열 안에 HTML 코드가 들어 있다면 상황이 조금 달라진다.

const message = '<strong>Hello Vue</strong>'

일반 보간법으로 출력하면

<p>{{ message }}</p>

화면에는 HTML이 적용되는 것이 아니라 문자열 그대로 출력된다.

<strong>Hello Vue</strong>

v-html

문자열을 실제 HTML Element로 해석해서 출력하고 싶다면 v-html을 사용할 수 있다.

<script setup>
const rawHtmlData =
  '이 글자는 <span style="color:red; font-weight:bold;">빨간색 굵은 글자</span>이다.'
</script>

<template>
  <p v-html="rawHtmlData"></p>
</template>

v-html은 JavaScript의 innerHTML과 유사하게 동작한다.

개념적으로 보면 다음과 같다.

{{ data }}
    ↓
문자열 그대로 출력

v-html="data"
    ↓
HTML로 해석하여 출력

다만 v-html을 사용할 때는 XSS(Cross-Site Scripting)에 주의해야 한다.

사용자가 입력한 값을 그대로 v-html에 넣으면 해당 문자열이 HTML로 해석되기 때문에 악의적인 코드가 브라우저에서 실행될 위험이 있다.

게시판이나 입력창에 악성 코드가 삽입되고, 다른 사용자가 이를 조회할 때 실행되는 상황을 XSS의 대표적인 위험이다.

따라서 일반적으로는

{{ data }}

를 사용하고, 신뢰할 수 있는 HTML을 반드시 렌더링해야 할 때만 v-html을 사용하는 것이 좋다.

v-text

v-text도 데이터를 텍스트로 출력하는 Directive다.

<script setup>
const content = '안녕하세요! Vue 강의입니다.'
</script>

<template>
  <p v-text="content"></p>
</template>

이는 일반 보간법과 거의 같은 역할을 한다.

<p>{{ content }}</p>

자료에서도 v-text는 텍스트 내용을 채워 넣으며, 일반적인 경우에는 v-text보다 {{ }}를 주로 사용하는 방식으로 설명하고 있다.

따라서 세 가지를 비교하면 다음과 같다.

문법	역할
{{ data }}	데이터를 텍스트로 출력
v-text="data"	데이터를 텍스트로 출력
v-html="data"	데이터를 HTML로 해석하여 출력

HTML 속성과 Vue 데이터를 연결하는 v-bind

Vue에서 가장 많이 사용하는 Directive 중 하나가 v-bind다.

v-bind는 HTML의 Attribute와 JavaScript 데이터를 동적으로 연결하는 기능이다.

예를 들어 일반 HTML에서는 이미지 주소를 다음과 같이 고정한다.

<img src="/images/logo.png">

Vue에서는 이미지 주소를 변수로 관리할 수 있다.


const logoImgSrc = '<a href=https://vuejs.org/images/logo.png'>https://vuejs.org/images/logo.png'</a>

Vue에서 v-bind는 매우 자주 사용되기 때문에 일반적으로 다음과 같이 :로 축약한다.

<img :src="logoImgSrc">

즉

v-bind:src="logoImgSrc"

와

:src="logoImgSrc"

는 같은 의미다.

href, src, disabled 등 다양한 HTML 속성과 연결할 수 있다.

<a :href="dynamicUrl">사이트 이동</a>

<img :src="logoImgSrc">

<button :disabled="isButtonDisabled">
  버튼
</button>

전체적인 구조는 다음과 같이 이해하면 된다.

JavaScript 데이터
        ↓
      v-bind
        ↓
HTML Attribute

class도 동적으로 변경할 수 있다

v-bind는 단순히 src, href와 같은 속성만 연결하는 것이 아니다.

CSS 클래스도 데이터 상태에 따라 동적으로 추가하거나 제거할 수 있다.

가장 대표적인 방법은 객체 형태다.

<p :class="{ 'text-danger': isWarning }">
  경고 메시지
</p>

isWarning이

true

이면 text-danger 클래스가 적용되고,

false

이면 클래스가 제거된다.

즉 다음과 같다.

isWarning = true
        ↓
class="text-danger"

isWarning = false
        ↓
클래스 제거

Vue에서는 여러 개의 클래스를 배열 형태로 조합하는 것도 가능하다.

<div
  :class="[
    themeClass,
    isWarning ? 'border-red' : 'border-gray'
  ]"
>
  내용
</div>

:class가 객체와 배열 형식을 지원하며, 객체에서는 Boolean 조건으로 클래스 포함 여부를 정하고 배열에서는 여러 클래스를 조합할 수 있다.

style도 동적으로 변경할 수 있다

인라인 스타일 역시 v-bind로 연결할 수 있다.

<script setup>
const textColor = 'purple'
const fontSize = 20
</script>

<template>
  <p :style="{
    color: textColor,
    fontSize: fontSize + 'px'
  }">
    Hello Vue
  </p>
</template>

Vue에서는 style 객체의 CSS 속성명을 일반적으로 camelCase로 작성한다.

backgroundColor
fontSize
fontWeight

여러 스타일 객체를 합칠 수도 있다.

<div :style="[baseStyle, borderStyle]">
  Box
</div>

:style은 객체와 배열을 지원하며, 실시간으로 색상이나 크기 같은 CSS 값을 변경할 때 사용할 수 있다.

다만 대부분의 일반적인 디자인 변경은 :style보다 :class를 사용하는 것이 관리하기 편하다.

:class
→ 미리 만들어놓은 CSS 디자인을 조건에 따라 적용

:style
→ 색상, 크기 등의 값을 직접 동적으로 변경

예를 들어 다크모드나 경고 상태처럼 이미 정의한 디자인을 전환할 때는 :class가 적합하고, 프로그레스바 너비처럼 숫자가 계속 변하는 경우에는 :style이 적합하다.

Vue 3.4의 v-bind 축약 문법

Vue 3.4부터는 HTML 속성명과 JavaScript 변수명이 같다면 더 짧게 작성할 수도 있다.

기존에는

<img :src="src">

라고 작성했다면,

<img :src>

처럼 사용할 수 있다.

예를 들어


const id = 'user-profile-card'
const src = '<a href=https://vuejs.org/images/logo.png'>https://vuejs.org/images/logo.png'</a>

과 같이 작성한다.

즉

:src="src"

에서 이름이 동일하기 때문에

:src

만 남긴 것이다.

조건에 따라 화면을 바꾸는 v-if와 v-show

웹 화면에서는 로그인 여부나 데이터 상태에 따라 특정 요소를 보여주거나 숨겨야 하는 경우가 많다.

Vue에서는 이를 위해 v-if를 사용한다.

<script setup>
import { ref } from 'vue'

const isLogged = ref(false)
</script>

<template>
  <p v-if="isLogged">
    환영합니다.
  </p>

  <p v-else>
    로그인이 필요합니다.
  </p>
</template>

isLogged 값에 따라서 두 요소 중 하나가 렌더링된다.

isLogged = true

→ 환영합니다.


isLogged = false

→ 로그인이 필요합니다.

JavaScript의 if / else if / else처럼 여러 조건도 사용할 수 있다.

<div v-if="score >= 90">
  A 학점
</div>

<div v-else-if="score >= 80">
  B 학점
</div>

<div v-else-if="score >= 70">
  C 학점
</div>

<div v-else>
  F 학점
</div>

v-if, v-else-if, v-else는 조건에 따라 실제 DOM 요소를 생성하거나 제거하는 방식으로 동작한다.

v-show는 무엇이 다를까

v-show도 조건에 따라 화면을 보여주거나 숨긴다.

<div v-show="isVisible">
  화면에 표시할 영역
</div>

그러나 v-if와 동작 방식이 다르다.

v-if는 조건이 false이면 실제 DOM에서 요소를 제거한다.

v-if = false

DOM에서 제거

반면 v-show는 DOM 요소를 그대로 유지한 상태에서 CSS를 사용한다.

display: none;

즉

v-show = false

DOM에는 존재
↓
display: none
↓
화면에서만 숨김

이다.

두 방식을 비교하면 다음과 같다.

구분	v-if	v-show
false일 때	DOM에서 제거	DOM 유지
동작 방식	DOM 생성/삭제	display 변경
초기 렌더링 비용	낮음	상대적으로 높음
반복적인 화면 전환	상대적으로 부담	유리
v-else 사용	가능	불가능

따라서 화면이 거의 변경되지 않는 경우라면 v-if를,

로그인 권한
관리자 메뉴
특정 데이터 존재 여부

처럼 사용할 수 있다.

반대로 자주 열고 닫는 UI라면 v-show가 적합하다.

Modal
Tab
Accordion
Dropdown

이와 같은 기준으로 v-if와 v-show를 구분하고 있다.

반복되는 화면을 만드는 v-for

웹에서는 같은 형태의 데이터를 반복해서 출력하는 경우가 매우 많다.

예를 들어 과일 목록이 있다고 해보자.

const fruits = ['사과', '바나나', '딸기']

HTML을 직접 작성한다면

<li>사과</li>
<li>바나나</li>
<li>딸기</li>

처럼 각각 만들어야 한다.

Vue에서는 v-for를 사용할 수 있다.

<li
  v-for="fruit in fruits"
  :key="fruit"
>
  {{ fruit }}
</li>

배열의 index도 함께 받을 수 있다.

<li
  v-for="(fruit, index) in fruits"
  :key="index"
>
  {{ index + 1 }}번 과일: {{ fruit }}
</li>

구조를 보면

fruits

['사과', '바나나', '딸기']

          ↓

        v-for

          ↓

<li>사과</li>
<li>바나나</li>
<li>딸기</li>

가 된다.

객체 역시 반복할 수 있다.

const user = {
  name: '홍길동',
  age: 25,
  role: '개발자'
}

<li
  v-for="(value, key) in user"
  :key="key"
>
  {{ key }} : {{ value }}
</li>

그리고 실제 개발에서 가장 자주 만나는 형태는 객체를 가진 배열이다.

const items = [
  { id: 'prod_101', name: '아이폰' },
  { id: 'prod_102', name: '갤럭시' }
]

<li
  v-for="item in items"
  :key="item.id"
>
  {{ item.name }}
</li>

v-for를 사용할 때 Vue가 각각의 요소를 고유하게 구분할 수 있도록 :key를 함께 지정하는 것을 중요한 규칙으로 설명한다.

따라서 일반적으로

v-for="item in items"
:key="item.id"

를 하나의 세트처럼 기억하는 것이 좋다.

특히 고유한 id가 있다면 index보다 해당 id를 key로 사용하는 방식이 적절하다.

알아두면 좋은 기타 Directive

앞에서 본 Directive들은 Vue 개발에서 매우 자주 사용한다.

반면 다음 Directive들은 사용 빈도는 상대적으로 낮지만 Vue의 렌더링 원리를 이해하는 데 도움이 된다.

v-pre

v-pre는 Vue에게

이 영역은 Vue 문법으로 해석하지 말고 그대로 보여줘.

라고 알려주는 Directive다.

<script setup>
const message = '안녕하세요!'
</script>

<template>
  <p>{{ message }}</p>

  <p v-pre>
    {{ message }}
  </p>
</template>

첫 번째는

안녕하세요!

가 출력되지만,

v-pre가 적용된 두 번째는

{{ message }}

가 그대로 표시된다.

Vue의 Template Compiler가 해당 영역을 해석하지 않는 것이다.

v-cloak

Vue가 완전히 로딩되기 전에 화면이 먼저 나타나면 아주 잠깐

{{ message }}

같은 미완성 템플릿 문법이 사용자에게 보일 수 있다.

이를 방지하기 위한 Directive가 v-cloak이다.

<div v-cloak>
  {{ message }}
</div>

그리고 CSS와 함께 사용한다.

[v-cloak] {
  display: none !important;
}

Vue의 렌더링이 끝날 때까지 화면을 숨겼다가, 준비가 완료되면 표시하는 방식이다.

v-once

Vue의 반응형 데이터는 값이 변경되면 화면도 다시 갱신된다.

하지만 한 번 출력된 후 절대 변경할 필요가 없는 데이터도 있을 수 있다.

이럴 때 v-once를 사용할 수 있다.

<p v-once>
  {{ count }}
</p>

count가 처음에 1이었다면 이 영역은 최초 렌더링 이후 count가 변경돼도 계속 1을 유지한다.

최초 count = 1
       ↓
v-once 렌더링
       ↓
화면 : 1
       ↓
count = 2
       ↓
화면 : 여전히 1

즉 최초 한 번만 렌더링하고 이후의 반응형 업데이트를 받지 않는다.

v-memo

v-memo는 조금 더 선택적인 렌더링 최적화 기능이다.

<div v-memo="[name]">
  <p>이름: {{ name }}</p>
  <p>나이: {{ age }}</p>
</div>

여기서는 name을 감시 대상으로 지정했다.

name 변경
   ↓
해당 영역 다시 렌더링

age만 변경
   ↓
기존 렌더링 결과 재사용

즉 지정된 값이 변경됐을 때만 해당 영역을 업데이트하고, 그렇지 않으면 이전에 렌더링한 결과를 재사용한다.

일반적인 작은 화면에서는 자주 사용할 필요가 없지만, 렌더링 비용이 큰 UI를 최적화해야 할 때 사용할 수 있는 Directive다.

Vue Directive 전체 흐름 정리

이번에 살펴본 Directive를 역할별로 묶으면 생각보다 간단하다.

Vue Directive
│
├─ 콘텐츠 출력
│   ├─ v-html
│   └─ v-text
│
├─ 데이터 연결
│   └─ v-bind (:)
│       ├─ Attribute
│       ├─ Class
│       └─ Style
│
├─ 조건
│   ├─ v-if
│   └─ v-show
│
├─ 반복
│   └─ v-for
│
└─ 렌더링 제어
    ├─ v-pre
    ├─ v-cloak
    ├─ v-once
    └─ v-memo

이 중 처음 Vue를 공부할 때 가장 중요하게 볼 것은 다음 정도다.

{{ }}
→ 화면에 데이터 출력

:
→ v-bind
→ HTML 속성에 데이터 연결

v-if
→ 조건에 따라 DOM 생성/삭제

v-show
→ 조건에 따라 표시/숨김

v-for
→ 배열이나 객체 반복 출력

그리고 다음 단계에서 여기에

@click
v-model

이 추가된다.

그러면 Vue Template의 기본적인 화면 제어 문법은 거의 완성된다.

실제로 Vue 코드를 보면 다음과 같은 형태가 매우 자주 등장한다.

<script setup>
import { ref } from 'vue'

const isLoggedIn = ref(true)

const users = ref([
  { id: 1, name: 'Kim' },
  { id: 2, name: 'Lee' },
  { id: 3, name: 'Park' }
])
</script>

<template>
  <div v-if="isLoggedIn">

    <h2>사용자 목록</h2>

    <ul>
      <li
        v-for="user in users"
        :key="user.id"
      >
        {{ user.name }}
      </li>
    </ul>

  </div>

  <p v-else>
    로그인이 필요합니다.
  </p>
</template>

처음에는 여러 문법이 섞여 있어 복잡해 보이지만 하나씩 해석하면 단순하다.

v-if
→ 로그인 상태 확인

v-for
→ users 반복

:key
→ 각각의 사용자 식별

{{ user.name }}
→ 사용자 이름 출력

결국 Vue의 Template 문법은 JavaScript 데이터와 HTML 화면을 연결하기 위한 문법이라고 볼 수 있다.

Vue에서는 개발자가 Real DOM을 직접 찾아서 수정하기보다,

데이터를 선언하고
      ↓
Directive로 HTML과 연결하고
      ↓
데이터를 변경하면
      ↓
Vue가 화면을 갱신한다

라는 흐름으로 개발하게 된다.