이 장은 완전 자급자족 버전입니다. 독자가 이 글만 보고도 처음부터 실행할 수 있도록, 4장(학습)과 5장(평가), 6장(배포: LoRA 병합 → GGUF 변환 → Ollama 실행)까지 한 번에 마칩니다. 모델은 meta-llama/Llama-3.2-1B-Instruct 를 사용합니다. (GGUF/Ollama 호환)

원칙(중요): 파인튜닝에서는 토크나이저 어휘를 절대 바꾸지 않습니다. pad_token은 “추가(add)”가 아니라 eos를 pad로 “지정”만 하세요. 어휘가 변하면 GGUF 변환에서 체크섬이 실패합니다.

0) 환경 준비

# (선택) 가상환경
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate

# 필수 패키지
pip install -U transformers datasets peft accelerate bitsandbytes torch torchvision torchaudio

GPU가 없다면 bitsandbytes는 설치에 실패할 수 있어요. 상관없이 LoRA는 CPU에서도 동작하긴 하지만 느립니다. 우선 코드는 동일합니다.

1) 데이터 준비 (예시 JSONL) — Instruction/Response 포맷

cat > train.jsonl << 'EOF'
{"text":"### Instruction:\nExplain regression vs classification.\n### Response:\nRegression predicts continuous values; classification predicts discrete categories."}
{"text":"### Instruction:\nWhat is overfitting?\n### Response:\nOverfitting occurs when a model memorizes training data patterns and fails to generalize."}
{"text":"### Instruction:\nDefine gradient descent.\n### Response:\nAn optimization algorithm that iteratively updates parameters to minimize a loss function."}
EOF

실제로는 수천~수만 샘플을 사용하세요. 포맷만 위와 같이 맞추면 됩니다.

PART 4장) LoRA 파인튜닝 — 학습 전체 코드

# 4_train_lora.py
from datasets import load_dataset
from transformers import (
    AutoTokenizer, AutoModelForCausalLM,
    DataCollatorForLanguageModeling, Trainer, TrainingArguments
)
from peft import LoraConfig, get_peft_model
import torch, os, json

BASE_MODEL = "meta-llama/Llama-3.2-1B-Instruct"
OUT_DIR    = "./lora-out"

os.makedirs(OUT_DIR, exist_ok=True)

# 1) 데이터 로드
dataset = load_dataset("json", data_files="train.jsonl")

# 2) 토크나이저/모델 로드 (어휘 불변!)
tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, use_fast=True)
if tokenizer.pad_token is None:
    # '추가'가 아니라 '지정'만! vocab 크기가 바뀌지 않음.
    tokenizer.pad_token = tokenizer.eos_token

model = AutoModelForCausalLM.from_pretrained(BASE_MODEL)
# 토큰 길이에 맞춰 임베딩 리사이즈 (어휘 변경이 없으므로 길이는 원본과 동일)
model.resize_token_embeddings(len(tokenizer))

# 3) LoRA 설정
lora_cfg = LoraConfig(
    r=8,
    lora_alpha=16,
    target_modules=["q_proj", "v_proj"],  # 시작은 가볍게. 필요시 k/o_proj 추가
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)
model = get_peft_model(model, lora_cfg)

# 4) 전처리 (labels = input_ids, pad=-100 마스킹)
def tok_fn(batch):
    enc = tokenizer(batch["text"], truncation=True, padding="max_length", max_length=512)
    enc["labels"] = [
        [t if t != tokenizer.pad_token_id else -100 for t in ids]
        for ids in enc["input_ids"]
    ]
    return enc

tokenized = dataset.map(tok_fn, batched=True, remove_columns=["text"])
collator = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)

# 5) 학습 인자
use_fp16 = torch.cuda.is_available()
args = TrainingArguments(
    output_dir=OUT_DIR,
    num_train_epochs=2,
    per_device_train_batch_size=2,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    logging_steps=10,
    save_strategy="epoch",
    report_to="none",
    fp16=use_fp16,
)

# 6) 학습
trainer = Trainer(
    model=model,
    args=args,
    train_dataset=tokenized["train"],
    data_collator=collator
)
trainer.train()

# 7) 저장 (어댑터 + 토크나이저)
model.save_pretrained(f"{OUT_DIR}/adapter")
tokenizer.save_pretrained(f"{OUT_DIR}/tokenizer")

# 8) 메타 기록(선택: 검사용)
meta = {
    "base_model": BASE_MODEL,
    "tokenizer_length": len(tokenizer),
    "pad_token": tokenizer.pad_token,
    "pad_token_id": tokenizer.pad_token_id,
}
with open(f"{OUT_DIR}/train_meta.json", "w", encoding="utf-8") as f:
    json.dump(meta, f, ensure_ascii=False, indent=2)

print("✅ LoRA training complete. Saved to", OUT_DIR)

실행:

python 4_train_lora.py

PART 5장) 성능 평가 — Perplexity + 생성 예시 전체 코드

# 5_eval_ppl_and_generate.py
from datasets import load_dataset
from transformers import (
    AutoTokenizer, AutoModelForCausalLM,
    DataCollatorForLanguageModeling, Trainer, TrainingArguments, pipeline
)
from peft import PeftModel
import torch, math, json

BASE_MODEL   = "meta-llama/Llama-3.2-1B-Instruct"
ADAPTER_DIR  = "./lora-out/adapter"
TOKENIZER_DIR= "./lora-out/tokenizer"

# 1) 평가 데이터 분리
raw = load_dataset("json", data_files="train.jsonl")
split = raw["train"].train_test_split(test_size=0.2, seed=42)
eval_ds = split["test"]

# 2) 토크나이저/모델 로드 (어휘 불변)
tokenizer = AutoTokenizer.from_pretrained(TOKENIZER_DIR, use_fast=True)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

base = AutoModelForCausalLM.from_pretrained(BASE_MODEL)
base.resize_token_embeddings(len(tokenizer))
model = PeftModel.from_pretrained(base, ADAPTER_DIR).eval()

# 3) 전처리
def tok_eval(batch):
    enc = tokenizer(batch["text"], truncation=True, padding="max_length", max_length=512)
    enc["labels"] = [
        [t if t != tokenizer.pad_token_id else -100 for t in ids]
        for ids in enc["input_ids"]
    ]
    return enc

eval_tok = eval_ds.map(tok_eval, batched=True, remove_columns=["text"])
collator = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)

# 4) Perplexity (낮을수록 좋음)
use_fp16 = torch.cuda.is_available()
args = TrainingArguments(
    output_dir="./eval-out",
    per_device_eval_batch_size=2,
    dataloader_drop_last=False,
    report_to="none",
    fp16=use_fp16,
)

trainer = Trainer(
    model=model,
    args=args,
    eval_dataset=eval_tok,
    data_collator=collator
)

metrics = trainer.evaluate()
loss = metrics["eval_loss"]
ppl  = math.exp(loss) if loss < 20 else float("inf")
print(f"📊 eval loss: {loss:.4f} | ppl: {ppl:.2f}")

# 5) 생성 예시 (정성 평가)
prompt = """### Instruction:
Explain the difference between regression and classification.
### Response:
"""

gen = pipeline(
    "text-generation",
    model=model,
    tokenizer=tokenizer,
    device_map="auto" if torch.cuda.is_available() else None
)
out = gen(prompt, max_new_tokens=120, do_sample=False)[0]["generated_text"]
print("=== Sample Output ===\n", out)

실행:

python 5_eval_ppl_and_generate.py

PART 6장) 배포 — LoRA 병합 → GGUF 변환 → Ollama 실행 (풀 코드/명령)

중요: 여기서부터는 토크나이저가 섞이지 않도록 “베이스 기준”으로 다시 로드 후 병합합니다. (간혹 ./lora-out/tokenizer 안에 다른 계열 토크나이저가 섞이면 어휘 크기(128000 ↔ 50265) 불일치가 납니다)

6-1) LoRA 병합 (완전 가중치)

# 6_merge_lora_clean.py
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel
import os

BASE_MODEL  = "meta-llama/Llama-3.2-1B-Instruct"
ADAPTER_DIR = "./lora-out/adapter"
MERGED_DIR  = "./merged-llama"

# 1) 베이스 기준 토크나이저/모델 로드
tok = AutoTokenizer.from_pretrained(BASE_MODEL, use_fast=True)
if tok.pad_token is None:
    tok.pad_token = tok.eos_token  # '추가' 아님. 어휘 불변

print("Base tokenizer vocab_size:", tok.vocab_size)  # LLaMA3.2는 128000 여야 정상

base = AutoModelForCausalLM.from_pretrained(BASE_MODEL)
base.resize_token_embeddings(len(tok))

# 2) LoRA 어댑터 병합
model = PeftModel.from_pretrained(base, ADAPTER_DIR)
model = model.merge_and_unload()

# 3) 저장(베이스 기준으로 깨끗하게)
os.makedirs(MERGED_DIR, exist_ok=True)
model.save_pretrained(MERGED_DIR)
tok.save_pretrained(MERGED_DIR)

print("✅ merged model saved to:", MERGED_DIR)

실행:

python 6_merge_lora_clean.py

6-2) GGUF 변환 (llama.cpp 최신본)

# llama.cpp 최신 리포 준비
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
python -m pip install -U pip wheel setuptools
python -m pip install -U -r requirements.txt
python -m pip install -U tiktoken tokenizers transformers sentencepiece protobuf

# GGUF로 변환 (상위 폴더에 결과 생성)
python ./convert-hf-to-gguf.py ../merged-llama --outfile ../merged-llama.gguf --verbose

실패 시 대부분 토크나이저가 섞였거나 llama.cpp가 구버전입니다. 위 6-1 과정을 다시 정확히 실행하고, 최신본으로 재시도하세요.

6-3) Modelfile 작성 & Ollama 등록

Modelfile (프로젝트 루트에 저장)

FROM ./merged-llama.gguf

PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 4096

TEMPLATE """### Instruction:
{{prompt}}

### Response:"""

등록 & 실행:

ollama create my-llama -f Modelfile
ollama run my-llama "Explain gradient descent simply."

(부록) 토크나이저 섞임 방지 가드 스니펫

언제든 실행해서 베이스/병합 토크나이저의 vocab 크기(128000) 를 확인하세요.

# tokenizer_guard.py
from transformers import AutoTokenizer
BASE_MODEL = "meta-llama/Llama-3.2-1B-Instruct"
MERGED_DIR = "./merged-llama"

tb = AutoTokenizer.from_pretrained(BASE_MODEL, use_fast=True)
if tb.pad_token is None: tb.pad_token = tb.eos_token
tm = AutoTokenizer.from_pretrained(MERGED_DIR, use_fast=True)
if tm.pad_token is None: tm.pad_token = tm.eos_token

print("base vocab:", tb.vocab_size, "| merged vocab:", tm.vocab_size)
assert tb.vocab_size == tm.vocab_size == 128000, "Tokenizer vocab mismatch. Clean and redo merge."
print("✅ tokenizer sizes aligned (128000).")

마무리

이 글 하나로 다음을 끝냈습니다.

1. LoRA 파인튜닝(4장 풀 코드)
2. Perplexity/생성 평가(5장 풀 코드)
3. LoRA 병합 → GGUF 변환 → Ollama 실행(6장 풀 코드 + 명령)

핵심은 토크나이저 불변성입니다. pad_token은 추가가 아니라 지정, add_tokens()/train_new_from_iterator() 는 파인튜닝에선 금지 — 이 원칙만 지키면 GGUF 변환과 Ollama 실행은 매끄럽게 이어집니다.

앞선 장에서 우리는 SLM(Small Language Model)과 Ollama 환경을 구축하고, Hugging Face 모델을 불러오는 과정을 모두 끝냈다. 이제는 그 모델을 내 데이터로 파인튜닝(fine-tuning) 하고, 그 결과를 Perplexity 및 생성 예시로 평가한다.

이번 장은 두 파트로 구성된다.

PART 1 — 4장 : LoRA 파인튜닝 수행

1. 환경 설정

pip install -U transformers datasets peft accelerate bitsandbytes

• transformers — Hugging Face 모델 관리
• datasets — 데이터셋 로딩 및 전처리
• peft — LoRA/QLoRA 어댑터 관리
• bitsandbytes — 4bit/8bit 양자화 지원 (GPU에서만 사용)

2. 데이터 로드 및 전처리

이전 장에서 만든 train.jsonl 파일에는 instruction–response 쌍이 포함되어 있다.

from datasets import load_dataset

dataset = load_dataset("json", data_files="train.jsonl")

print(dataset)
print(dataset["train"][0])

데이터는 다음과 같이 구성되어 있어야 한다.

{"text": "### Instruction:\nExplain regression vs classification.\n### Response:\nRegression predicts continuous values..."}

3. 토크나이저 및 모델 준비

from transformers import AutoTokenizer, AutoModelForCausalLM

BASE_MODEL = "facebook/opt-1.3b"
tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, use_fast=True)

# pad_token 지정
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

model = AutoModelForCausalLM.from_pretrained(BASE_MODEL)
model.resize_token_embeddings(len(tokenizer))

4. LoRA 설정 및 적용

from peft import LoraConfig, get_peft_model

lora_cfg = LoraConfig(
    r=8,                        # 랭크 (조정 강도)
    lora_alpha=16,              # LoRA 스케일링
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

model = get_peft_model(model, lora_cfg)
print("LoRA 설정 완료")

5. 데이터 토크나이징 및 라벨 생성

언어모델은 labels가 필요하다. labels = input_ids로 설정하되, padding 부분은 -100으로 마스킹한다.

def tokenize_function(batch):
    enc = tokenizer(batch["text"], truncation=True, padding="max_length", max_length=512)
    labels = [
        [tok if tok != tokenizer.pad_token_id else -100 for tok in ids]
        for ids in enc["input_ids"]
    ]
    enc["labels"] = labels
    return enc

tokenized = dataset.map(tokenize_function, batched=True, remove_columns=["text"])

6. 학습 실행

from transformers import Trainer, TrainingArguments, DataCollatorForLanguageModeling
import torch

args = TrainingArguments(
    output_dir="./lora-out",
    num_train_epochs=2,
    per_device_train_batch_size=2,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    logging_steps=20,
    save_strategy="epoch",
    report_to="none",
    fp16=torch.cuda.is_available(),
)

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=tokenized["train"],
    data_collator=DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False),
)

trainer.train()

첫 학습에서는 작은 데이터(100개 이하)로 테스트한 뒤 전체 데이터로 확장하는 것이 좋다.

7. 모델 저장

model.save_pretrained("./lora-out/adapter")
tokenizer.save_pretrained("./lora-out/tokenizer")
print("파인튜닝 모델 저장 완료")

이제 학습이 끝났으니, 다음 단계로 넘어가자. 모델이 얼마나 좋아졌는지를 평가해보는 것이다.

PART 2 — 5장 : 파인튜닝 모델 평가와 결과 분석

1. 평가용 데이터셋 구성

훈련용 데이터에서 5%를 분리하여 평가용으로 사용한다.

from datasets import load_dataset

dataset = load_dataset("json", data_files="train.jsonl")
split = dataset["train"].train_test_split(test_size=0.05, seed=42)
eval_data = split["test"]

print(f"평가 데이터 수: {len(eval_data)}")

2. 모델과 토크나이저 불러오기

from transformers import AutoModelForCausalLM, AutoTokenizer, DataCollatorForLanguageModeling
from peft import PeftModel
import torch

BASE_MODEL = "facebook/opt-1.3b"
ADAPTER_DIR = "./lora-out/adapter"
TOKENIZER_DIR = "./lora-out/tokenizer"

# 토크나이저 로드
tokenizer = AutoTokenizer.from_pretrained(TOKENIZER_DIR, use_fast=True)
tokenizer.pad_token = tokenizer.eos_token

# 기본 모델 로드
base_model = AutoModelForCausalLM.from_pretrained(BASE_MODEL)

# 토크나이저의 어휘 크기에 맞춰 모델의 임베딩 레이어 크기 조정
base_model.resize_token_embeddings(len(tokenizer))

# LoRA 어댑터 로드
model = PeftModel.from_pretrained(base_model, ADAPTER_DIR)
model.eval()

3. Perplexity 계산

from transformers import Trainer, TrainingArguments
import math

def tokenize_eval(batch):
    enc = tokenizer(batch["text"], truncation=True, padding="max_length", max_length=512)
    enc["labels"] = [
        [tok if tok != tokenizer.pad_token_id else -100 for tok in ids]
        for ids in enc["input_ids"]
    ]
    return enc

eval_tokenized = eval_data.map(tokenize_eval, batched=True, remove_columns=["text"])
collator = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)

args = TrainingArguments(
    output_dir="./eval-out",
    per_device_eval_batch_size=2,
    dataloader_drop_last=False,
    report_to="none",
    fp16=torch.cuda.is_available(),
)

trainer = Trainer(
    model=model,
    args=args,
    eval_dataset=eval_tokenized,
    data_collator=collator,
)

result = trainer.evaluate()
loss = result["eval_loss"]
ppl = math.exp(loss)

print(f"평가 손실(loss): {loss:.4f}")
print(f"Perplexity(PPL): {ppl:.2f}")

4. 샘플 생성 비교

from transformers import pipeline

prompt = """### Instruction:
Explain the difference between regression and classification.
### Response:
"""

gen = pipeline(
    "text-generation",
    model=model,
    tokenizer=tokenizer,
    device_map="auto" if torch.cuda.is_available() else None
)

output = gen(prompt, max_new_tokens=120, do_sample=False)[0]["generated_text"]
print("=== 모델 생성 결과 ===\n")
print(output)

이제 파인튜닝된 모델이 instruction-response 구조를 명확히 따르고, 훈련 데이터의 문체를 반영하는지 직접 확인할 수 있다.

5. 실험 로그 저장

import csv, os, time
from pathlib import Path

Path("experiments").mkdir(exist_ok=True)
log_file = "experiments/results.csv"
new_file = not os.path.exists(log_file)

row = [int(time.time()), BASE_MODEL, ADAPTER_DIR, f"{loss:.4f}", f"{ppl:.2f}"]
fields = ["timestamp", "model", "adapter", "eval_loss", "ppl"]

with open(log_file, "a", newline="", encoding="utf-8") as f:
    w = csv.writer(f)
    if new_file:
        w.writerow(fields)
    w.writerow(row)

print(f"평가 결과가 '{log_file}'에 저장되었습니다.")

6. 결론 및 다음 단계

지금까지 우리는

• Hugging Face 모델을 이용해 LoRA 방식으로 SLM을 파인튜닝하고,
• Perplexity로 정량 평가,
• 샘플 생성으로 정성 평가를 수행했으며,
• 결과를 CSV로 자동 기록했다.

다음 6장에서는 이 모델을 Ollama에서 직접 실행 가능한 형태(GGUF 변환 + Modelfile 생성) 로 내보내는 배포 단계를 다룬다.

1. 환경 준비(필수 패키지)

pip install -U transformers datasets peft accelerate bitsandbytes
# GPU가 없다면 bitsandbytes는 생략 가능(QLoRA 미사용)

Python 3.10+ 권장. GPU가 없으면 QLoRA 대신 LoRA만 시도하세요(속도 이슈 고려).

2. 데이터 불러오기(3장의 train.jsonl 사용)

• 3장에서 만든 train.jsonl(한 줄에 {"text": "..."}형태)을 그대로 사용한다.

from datasets import load_dataset

dataset = load_dataset("json", data_files="train.jsonl")
# 작은 샘플로 먼저 확인하고 싶다면:
# dataset["train"] = dataset["train"].select(range(200))

3. 토크나이저/모델 준비 + “labels” 생성

• 핵심: labels = input_ids + 패딩 토큰 위치는 -100으로 마스킹

from transformers import AutoTokenizer, AutoModelForCausalLM, DataCollatorForLanguageModeling

# SLM 계열: 크기가 너무 큰 모델은 내 머신에서 과부하가 날 수 있습니다.
# 예시 1) OPT 1.3B
model_name = "facebook/opt-1.3b"

tokenizer = AutoTokenizer.from_pretrained(model_name, use_fast=True)
# pad 토큰 지정(없으면 eos를 pad로 사용)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

def tokenize_and_label(batch):
    enc = tokenizer(
        batch["text"],
        truncation=True,
        padding="max_length",
        max_length=512,
    )
    # labels = input_ids (언어모델용 next-token 예측)
    labels = []
    for ids in enc["input_ids"]:
        # pad 토큰 위치는 -100으로 마스킹 → loss에서 제외
        labels.append([tok if tok != tokenizer.pad_token_id else -100 for tok in ids])
    enc["labels"] = labels
    return enc

tokenized = dataset.map(tokenize_and_label, batched=True, remove_columns=["text"])

# causal LM용 collator (MLM=False 중요)
collator = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)

# 모델 로드(LoRA 적용 전 base 모델)
base_model = AutoModelForCausalLM.from_pretrained(model_name)
# 토큰 개수 변경 시(위에서 pad_token 추가) 안전하게 resize
base_model.resize_token_embeddings(len(tokenizer))

4. LoRA 적용(메모리 절약형 미세조정)

from peft import LoraConfig, get_peft_model

lora_cfg = LoraConfig(
    r=8,
    lora_alpha=16,
    target_modules=["q_proj", "v_proj"],  # OPT/LLaMA 계열에서 널리 쓰는 패턴
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

lora_model = get_peft_model(base_model, lora_cfg)

모델 유형에 따라 target_modules가 다를 수 있다. 만약 architecture가 달라 에러가 나면 ['q_proj','k_proj','v_proj','o_proj'] 중 존재하는 레이어로 조정하라.

5. 학습 루프(Trainer)

from transformers import Trainer, TrainingArguments
import torch

# bfloat16/float16 자동 선택
use_bf16 = torch.cuda.is_available() and torch.cuda.get_device_capability(0)[0] >= 8
use_fp16 = torch.cuda.is_available() and not use_bf16

args = TrainingArguments(
    output_dir="./lora-out",
    num_train_epochs=2,
    per_device_train_batch_size=2,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    logging_steps=20,
    save_strategy="epoch",
    save_total_limit=2,
    report_to="none",
    bf16=use_bf16,
    fp16=use_fp16,
    optim="paged_adamw_8bit" if torch.cuda.is_available() else "adamw_torch",
)

trainer = Trainer(
    model=lora_model,
    args=args,
    train_dataset=tokenized["train"],
    data_collator=collator,
)
trainer.train()

• 이 시점에서 loss가 정상적으로 출력되어야 한다.
• CPU만 있는 환경에서는 시간이 오래 걸린다. 처음엔 select(range(200))로 200개 정도만 학습해 파이프라인 정상 작동 먼저 확인하는 것을 권장.

6. QLoRA(선택) — GPU 메모리가 아주 적을 때

import torch
from peft import prepare_model_for_kbit_training
from transformers import BitsAndBytesConfig

bnb_cfg = BitsAndBytesConfig(
    load_in_4bit=True,                      # 4비트 양자화
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
)

qlora_base = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_cfg,
    device_map="auto",
)
qlora_base.resize_token_embeddings(len(tokenizer))
qlora_base = prepare_model_for_kbit_training(qlora_base)
qlora_model = get_peft_model(qlora_base, lora_cfg)

trainer = Trainer(
    model=qlora_model,
    args=args,
    train_dataset=tokenized["train"],
    data_collator=collator,
)
trainer.train()

GPU가 없다면 QLoRA는 불가(또는 무의미). 이 경우 LoRA만 사용.

7. 저장(어댑터/토크나이저)

lora_model.save_pretrained("./lora-out/adapter")  # 또는 qlora_model
tokenizer.save_pretrained("./lora-out/tokenizer")

• 후속 장에서 이 LoRA 어댑터를 base 모델에 merge → GGUF 변환 → Ollama용 Modelfile 생성까지 진행한다.
• 주의(중요): Ollama는 Hugging Face LoRA 어댑터를 곧바로 읽지 않는다. 다음 장에서 LoRA merge → GGUF 변환 절차를 반드시 수행한다.

8. 간단 검증(학습 전후 비교)

학습 전/후 비교는 간단한 프롬프트로도 감이 온다. (정교 평가는 다음 장)

from transformers import pipeline

gen = pipeline("text-generation", model=lora_model, tokenizer=tokenizer, device_map="auto")
print(gen("### Instruction:\nExplain the difference between regression and classification.\n### Response:\n", 
          max_new_tokens=80)[0]["generated_text"])

9. 정리 — 이번 수정에서 달라진 점

• 오류 해결: labels가 없어서 loss가 없던 문제를 해결 → 학습(loss) 정상 출력
• 안전 장치: pad_token 지정 및 -100 마스킹, collator 설정(mlm=False)
• 실행 신뢰성: GPU/CPU 환경 모두 고려한 설정(bf16/fp16 자동)

다음 5장에서는 성능 평가와 실험 추적(Perplexity/ROUGE 등) 을 다루고, 6장에서는 LoRA 병합 → GGUF 변환 → Ollama용 모형 생성(Modelfile) → 로컬 실행을 마무리한다.

참고(문서/가이드)

• Hugging Face Transformers — Causal LM 학습에서 labels 필요성, DataCollatorForLanguageModeling(mlm=False) 사용
• PEFT(LoRA/QLoRA) 기본 개념 및 사용법
• bitsandbytes — 4bit 양자화 설정(BitsAndBytesConfig)

위 참고 문서는 변동될 수 있으니, 최신 버전 기준의 Transformers / PEFT 공식 문서를 확인해 주세요.

언어모델을 잘 학습시키는 데에는 “좋은 데이터”가 필수다. 데이터는 모델의 지식, 스타일, 응답 품질을 결정짓는다. 이 장에서는 Hugging Face datasets를 이용한 데이터 준비와, Ollama로 학습 가능한 포맷(GGUF · GGML 변환 전 단계) 을 만드는 과정을 다룬다.

1. 데이터 구조 설계

파인튜닝을 위한 데이터는 보통 아래 세 가지 형태 중 하나로 구성된다.

이번 장에서는 Instruction – Response 구조를 기준으로 실습한다. 이 형태는 Ollama의 대화형 모델에도 그대로 적용할 수 있다.

2. Hugging Face datasets로 데이터 불러오기

Hugging Face datasets 라이브러리를 사용하면 이미 공개된 데이터셋을 바로 로드할 수 있다. 예를 들어 databricks/databricks-dolly-15k는 대표적인 instruction – response 구조 데이터다.

from datasets import load_dataset

dataset = load_dataset("databricks/databricks-dolly-15k")
print(dataset)
print(dataset['train'][0])

출력 예시:

{
 'instruction': 'Explain the difference between regression and classification.',
 'context': '',
 'response': 'Regression predicts continuous values, classification predicts discrete labels.'
}

📘 참고: https://huggingface.co/datasets/databricks/databricks-dolly-15k

3. 데이터 필터링 및 정제

데이터셋을 그대로 사용하기보다 다음 과정을 수행하는 것이 좋다.

def clean_text(example):
    example["instruction"] = example["instruction"].strip()
    example["response"] = example["response"].strip()
    return example

dataset = dataset.map(clean_text)
dataset = dataset.filter(lambda x: len(x["instruction"]) > 5 and len(x["response"]) > 5)
print(f"After cleaning: {len(dataset['train'])} samples")

• 공백 · 특수문자 제거
• 너무 짧은 샘플 제거
• 불필요한 HTML tag / 이모지 제거

이 과정을 통해 학습 안정성이 높아진다.

4. 데이터셋 포맷 맞추기 (Instruction – Response → Text)

Ollama의 파인튜닝 입력 포맷은 단일 텍스트로 구성된다. 따라서 아래처럼 instruction과 response를 하나의 문장으로 병합한다.

def format_chat(example):
    instruction = f"### Instruction:\n{example['instruction']}\n"
    response = f"### Response:\n{example['response']}\n"
    example["text"] = instruction + response
    return example

dataset = dataset.map(format_chat)
dataset = dataset.remove_columns(['instruction', 'context', 'response'])

이제 모델 입력으로 사용할 컬럼은 text 하나뿐이다.

5. 데이터셋 저장

파인튜닝 단계에서 Ollama 또는 Transformers Trainer가 접근할 수 있도록 JSONL 형태로 저장한다.

import json

with open("train.jsonl", "w", encoding="utf-8") as f:
    for item in dataset["train"]:
        f.write(json.dumps({"text": item["text"]}, ensure_ascii=False) + "\n")

출력 예시:

{"text": "### Instruction:\nExplain the difference...\n### Response:\nRegression predicts..."}

💡 Ollama는 이후 Modelfile 내에서 이 JSONL을 FROM 또는 SYSTEM 명령으로 불러올 수 있다.

6. 파인튜닝 전 검증용 샘플 출력

데이터가 잘 포맷팅되었는지 샘플을 직접 확인하자.

with open("train.jsonl", "r", encoding="utf-8") as f:
    for _ in range(3):
        print(f.readline())

출력 결과가 “Instruction → Response” 순서로 표시되면 정상이다.

7. 데이터 품질 체크포인트

좋은 파인튜닝 데이터의 핵심 기준은 다음과 같다.

데이터의 품질이 학습 효과의 70%를 결정한다는 점을 명심해야 한다.

8. Ollama용 데이터 경로 설정

학습 준비가 끝났다면, Modelfile에서 학습 데이터 경로를 지정한다.

FROM llama3.2
SYSTEM "Fine-tuning with custom dataset"
DATASET "./train.jsonl"
TEMPLATE "### Instruction:\n{{prompt}}\n### Response:\n"

다음 장에서 이 Modelfile 을 이용해 실제 파인튜닝 명령(ollama create)을 실행하게 된다.

9. 마무리

이 장에서는 Hugging Face 데이터셋을 가져와, Instruction – Response 형태로 정리하고, Ollama 파인튜닝이 바로 가능한 JSONL 포맷으로 변환하는 과정을 마쳤다.

이제 다음 4장에서 본격적으로 모델 파인튜닝(Fine-Tuning) 을 진행한다. LoRA 방식, QLoRA 경량화, 학습률 / 에폭 조정 / 체크포인트 저장 등을 단계별로 다룰 것이다.

언어모델을 학습하거나 파인튜닝하려면 먼저 환경을 통일해야 한다. 모델을 불러오고, 데이터를 전처리하고, 학습 결과를 저장하는 과정은 모두 환경 설정에 좌우된다. 이 장에서는 로컬 환경에서 Ollama와 Hugging Face 모델을 함께 사용할 준비를 완료한다.

1. 개발 환경 구성

모델을 훈련하거나 튜닝할 때 반드시 맞춰야 하는 요소는 다음 네 가지다.

가상환경 생성

python3 -m venv venv
source venv/bin/activate     # Windows는 venv\Scripts\activate
pip install --upgrade pip

2. 필수 라이브러리 설치

이제 학습과 모델 불러오기를 위한 핵심 패키지를 설치한다.

pip install transformers datasets peft accelerate torch torchvision torchaudio
pip install ollama

설명:

• transformers — Hugging Face 모델 및 토크나이저 관리.
• datasets — 데이터셋 다운로드 및 전처리.
• peft / accelerate — LoRA, QLoRA 등 파인튜닝 최적화용.
• ollama — 로컬에서 모델 관리 및 실행용 CLI + Python API.

3. Ollama 환경 확인

Ollama가 설치되어 있지 않다면 공식 스크립트를 이용한다.

curl -fsSL https://ollama.com/install.sh | sh
ollama --version

모델 목록을 확인한다.

ollama list

아직 아무 모델도 없을 것이다. 다음 단계에서 Hugging Face에서 모델을 불러와 Ollama에 통합할 것이다.

4. Hugging Face 모델 가져오기

Ollama는 Hugging Face Hub의 모델을 직접 사용하지는 않지만, 파인튜닝에 사용할 사전학습(pretrained) 모델을 불러와 로컬 환경에서 변환할 수 있다.

예시: BERT 모델 불러오기

from transformers import AutoModelForSequenceClassification, AutoTokenizer

model_name = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

print("모델과 토크나이저 로드 완료:", model_name)

이제 모델 파라미터 구조와 입력 토큰 형태를 확인할 수 있다.

text = "Ollama fine-tuning with Hugging Face integration works perfectly."
tokens = tokenizer(text, return_tensors="pt")
outputs = model(**tokens)
print(outputs.logits)

이 코드가 정상적으로 실행되면 Hugging Face 모델 사용 준비가 완료된 것이다.

5. 모델 → Ollama 통합 준비

Hugging Face 모델을 Ollama에 바로 학습시킬 순 없지만, 파인튜닝 후 내보내기(export) → Ollama용 모델 포맷으로 패키징 이라는 절차로 연결할 수 있다.

이를 위해서는 LoRA / QLoRA 형태의 가벼운 어댑터만 저장하고, Ollama가 지원하는 GGUF 또는 GGML 포맷으로 변환해야 한다. 다음 장에서 이 과정을 단계별로 다룰 예정이다.

예시 워크플로:

Hugging Face 모델 (Transformers)
   ↓
파인튜닝 (LoRA, QLoRA)
   ↓
export → GGUF / GGML 형태
   ↓
ollama create -f Modelfile
   ↓
ollama run <custom-model>

6. 모델 다운로드 및 테스트 (Ollama 측)

Hugging Face 모델 실험 전, Ollama 환경이 정상적으로 작동하는지도 확인해야 한다.

ollama pull llama3.2
ollama run llama3.2

응답이 나오면 Ollama 측 환경도 정상 준비된 것이다. 이제 Hugging Face 모델과 Ollama 모델 양쪽 모두 실행할 수 있는 이중 환경이 완성되었다.

7. 마무리

이번 2장에서는

• 학습 및 튜닝을 위한 Python 환경 구축,
• Hugging Face 모델 불러오기,
• Ollama 환경 검증,
• 양쪽 환경의 연동 구조 설명까지 마쳤다.

이제 다음 3장에서는 데이터 준비 및 전처리를 다룬다. 직접 CSV 또는 JSON 데이터를 읽어 토크나이징하고, 파인튜닝 입력 형식에 맞게 가공하는 과정을 진행할 예정이다.

이 글은 개발 초심자의 시선으로 작성된 기록이다. 내 PC에서도 언어모델을 직접 돌려보겠다는 목표로 시작한다. 앞으로 이어질 장들에서는 환경 설정 → 모델 선택 → 데이터 준비 → 학습 및 튜닝 → 활용까지 순서대로 나아간다.

1. SLM(Small Language Model)이란 무엇인가

언어모델 분야에서 “SLM”이라는 개념이 중요해지고 있다. 간단히 말하면, 대형 언어모델(LLM: Large Language Model)의 일부 특징을 유지하면서도 더 작고, 덜 무겁게, 덜 자원으로 실행될 수 있게 설계된 모델이다.

특징

• 파라미터(Parameter)의 수가 비교적 적다 → 모델 크기와 연산량이 적다. (mlsysbook.ai)
• 특정 도메인(예: 내부 보고서 요약, 코드 리뷰, FAQ 챗봇) 등에 맞춰 튜닝하기에 적합하다. (Hugging Face)
• 리소스가 제한된 환경(내 PC, 노트북, 엣지 디바이스)에서도 실행 가능하다. (mlsysbook.ai)

한계

• 범용적으로 질문 받고 답변하고 추론하는 데 있어 대형 모델만큼 깊이 있는 성능을 내기 어려울 수 있다. (Medium)
• 문맥이 길거나 복잡한 추론을 요구하는 작업에서는 성능 저하가 나타날 수 있다. (mlsysbook.ai)

내가 SLM을 선택한 이유

내 노트북(혹은 데스크탑)이 막연히 “언어모델을 돌릴 수 없다”는 한계에 머물러 있었기에, 작고 효율적인 모델로 직접 경험해보자는 마음이 생겼다. 즉, “리소스 제약 → 경험 불가능”이라는 흐름을 끊고 싶었다.

2. Ollama란 무엇인가

모델만 확보한다고 끝나는 게 아니다. 다운로드하고 실행하고 관리할 수 있는 환경이 필요하다. 여기서 선택한 도구가 바로 Ollama이다.

Ollama의 특징

• 로컬 환경(내 PC, 노트북)에서 언어모델을 다운로드하고 실행할 수 있다. (Hugging Face)
• 커맨드라인(CLI)을 통해 모델을 제어할 수 있어 개발 흐름에 잘 맞는다. (thenewstack.io)
• 다양한 운영체제(macOS, Linux, Windows/WSL)를 지원하는 경우가 많아서 환경 제약이 크게 적다. (mlsysbook.ai)

이 시리즈에서 Ollama를 선택한 이유

내가 모델을 선택 → 다운로드 → 실행 → 활용하는 흐름을 경험하고 싶었고, Ollama는 이 흐름을 비교적 매끄럽게 만들어준다. 특히 주니어 입장에서 “설정이 어렵다→포기한다”가 되지 않게 만들고 싶었다.

3. 이 시리즈에서 달성하고자 하는 것들

앞으로 이 장 다음으로 이어질 글들을 통해 내가 이루고 싶은 목표다:

• 내 PC 또는 노트북에서 SLM 모델을 직접 다운로드하고 실행하는 경험을 쌓는다.
• 준비한 데이터를 전처리하고, 모델을 간단히 튜닝하거나 활용해본다.
• 그 결과물을 간단한 애플리케이션(예: 챗봇, 문서 요약 툴)으로 연결해본다.
• 메모리·저장공간·GPU여부 같은 “현실적 제약”을 고려하면서 실습을 한다.
• 또한 “로컬 언어모델”, “언어모델 튜닝”, “SLM 실습”, “Ollama 모델 사용법” 같은 키워드도 접하면서 블로그 글로서 검색 유입 가능성도 고려한다.

4. 따라하기 준비 체크리스트

다음 2장부터 바로 실습에 들어가야 하므로, 지금 이 순간 준비해야 할 항목들을 체크해보자.

Ollama 설치 예제

아래는 리눅스 또는 맥 환경에서 실행 가능한 설치 예제 명령어이다.

curl -fsSL https://ollama.com/install.sh | sh

설치 후 터미널에서 아래 명령어로 설치가 성공했는지 확인한다.

ollama --version

모델 다운로드 및 실행 예제

예를 들어 “smollm:1.7b” 같은 SLM 모델을 다운로드하고 실행해볼 수 있다.

ollama pull smollm:1.7b
ollama run smollm:1.7b

실행 후 터미널이 입력 대기 상태가 되면 예를 들어 다음과 같은 질문을 입력해본다.

Explain what small language models are and how they differ from large language models.

정상적으로 답변이 나오면 준비 완료다!

5. 마무리

이제 첫 장을 통해 왜 SLM이 중요한가, 왜 Ollama인가, 그리고 내가 이 시리즈로 무엇을 이루려 하는가를 정리했다. 다음 장에서는 환경 설정 + 모델 선택으로 더 깊이 들어가겠다. 어떤 모델을 선택해야 할지 분석하고, 나도 선택 기준을 세워보겠다.

다음 장에서 뵙자.

SLM, SmallLanguageModel, Ollama, 로컬LLM, 모델튜닝, 언어모델, AI개발, 개발블로그, 머신러닝, 모델학습

출처

• “Small Language Models (SLM): A Comprehensive Overview.” – Hugging Face Blog. (Hugging Face)
• “How to get started running Small Language Models at the edge.” – The New Stack. (thenewstack.io)
• “Small Language Models: The Rise of SLMs — Are Tiny LMs Ready for Prime Time?” – Medium. (Medium)

1. BFF란 무엇인가?

BFF(Backend for Frontend)는 이름 그대로 특정 프론트엔드 애플리케이션에 최적화된 백엔드 레이어입니다. 즉, “하나의 거대한 API 게이트웨이” 대신 각 클라이언트(웹, 모바일, IoT 등)에 맞춤형 백엔드를 두어 API를 설계하는 방식입니다.

• 웹 프론트엔드 → Web BFF
• 모바일 앱 → Mobile BFF
• 관리자 페이지 → Admin BFF

이런 식으로 나누어지며, 클라이언트의 특성과 화면 단위 요청을 고려해 데이터 가공과 최적화를 처리합니다.

2. 왜 BFF가 필요한가?

기존 구조(단일 API Gateway)에서는 이런 문제가 생깁니다:

1. 과도한 데이터: 모바일 앱에는 필요 없는 필드까지 내려줌.
2. 빈번한 API 호출: 화면 하나를 렌더링하기 위해 3~4개의 API를 호출해야 함.
3. 개발 속도 저하: 프론트엔드 요구사항이 많아질수록 백엔드 수정이 잦음.

👉 이를 해결하기 위해 BFF는 **“클라이언트 친화적 API 레이어”**로 동작합니다.

3. BFF 아키텍처 구조

[웹 브라우저] ──▶ [Web BFF] ──▶ [Microservices]
[모바일 앱]   ──▶ [Mobile BFF] ──▶ [Microservices]

• 각 BFF는 특정 프론트엔드의 UX 요구사항에 맞춰 API를 조합/가공합니다.
• 내부적으로는 동일한 마이크로서비스들을 호출하지만, 출력 형식과 호출 횟수 최적화가 다릅니다.

4. BFF의 장점

✅ 프론트엔드 맞춤 최적화 : 화면 1개 → API 1번 호출 가능 (Overfetching/Underfetching 최소화).

✅ 개발 효율성 증가 : 프론트엔드 팀이 독립적으로 BFF 레이어를 관리 가능.

✅ 보안 & 정책 분리 : Admin BFF에는 관리자 권한 정책을 추가하고, Mobile BFF에는 트래픽 최적화를 적용.

5. BFF의 단점

⚠️ 서비스가 늘어나면 BFF도 많아져 운영 복잡성 증가. ⚠️ 동일한 로직이 여러 BFF에 중복될 수 있음.

👉 따라서, 공통 로직은 마이크로서비스에서 관리하고, 표현 최적화는 BFF에서 처리하는 구조가 적합합니다.

6. 실무 적용 예시

1. NestJS로 Web BFF 구축

@Controller('dashboard')
export class DashboardBFFController {
  constructor(
    private readonly orderService: OrderService,
    private readonly userService: UserService
  ) {}

  @Get()
  async getDashboardData() {
    const orders = await this.orderService.getRecentOrders();
    const user = await this.userService.getProfile();
    return { orders, user };
  }
}

→ 프론트엔드 대시보드 화면에서 필요한 데이터만 조합해 반환.

2. Mobile BFF에서는 같은 데이터를 더 경량화하여 내려줄 수 있음.

7. BFF 선택 가이드

Docker를 활용해 애플리케이션을 운영하다 보면 반드시 마주치는 개념이 **네트워크(Network)**입니다. 특히 컨테이너 간 통신을 어떻게 구성할지에 따라 서비스 구조가 달라지기 때문에, bridge, host, overlay 같은 네트워크 드라이버의 차이를 명확히 이해하는 것이 중요합니다.

이번 글에서는 단순한 정의를 넘어, 실무에서 어떤 상황에서 어떤 네트워크를 선택해야 하는지를 예시와 함께 정리해보겠습니다.

1. Docker Network 기본 개념

Docker 컨테이너는 기본적으로 격리된 환경에서 실행됩니다. 네트워크가 없다면, 각 컨테이너는 마치 인터넷이 끊긴 독립 PC처럼 동작하게 됩니다.

따라서 Docker는 다양한 **네트워크 드라이버(driver)**를 제공하여 컨테이너 간 통신, 외부 연결, 포트 매핑 등을 지원합니다.

확인 방법은 다음과 같습니다:

docker network ls

출력 예시:

NETWORK ID     NAME      DRIVER    SCOPE
a12b3c4d5e6f   bridge    bridge    local
f23g4h5i6j7k   host      host      local
g34h5i6j7k8l   none      null      local

2. Bridge 네트워크 (기본값)

• 정의: 컨테이너끼리 연결되는 가상 네트워크 스위치 역할.

• 특징:

  • 같은 bridge 네트워크에 속한 컨테이너끼리만 이름(DNS) 기반 통신 가능.
  • 외부 통신은 -p 옵션으로 포트를 노출해야 가능.

• 실습 예시:

# 새 브리지 네트워크 생성
docker network create my-bridge

# 같은 네트워크에 두 개의 컨테이너 연결
docker run -d --name web1 --network my-bridge nginx
docker run -d --name web2 --network my-bridge nginx

# 컨테이너끼리 ping 가능
docker exec -it web1 ping web2

• 사용 사례:

  • 단일 서버에서 여러 개의 컨테이너가 서비스할 때 (예: 웹 + DB).
  • 네임 기반 접근이 가능해 로컬 개발 환경에 적합.

3. Host 네트워크

• 정의: 컨테이너가 호스트와 네트워크 스택을 공유.

• 특징:

  • 포트 매핑(-p) 불필요 → 호스트와 동일한 네트워크 인터페이스 사용.
  • 오버헤드가 적고 성능이 뛰어남.
  • 하지만 컨테이너 간 네트워크 격리가 없음 → 보안 이슈 가능.

• 실습 예시:

docker run -d --name web --network host nginx

→ 이제 http://localhost:80 으로 바로 접속 가능 (포트 매핑 불필요).

• 사용 사례:

  • 성능 최적화가 중요한 고성능 애플리케이션.
  • Prometheus, ELK 같은 모니터링/로깅 툴.

4. Overlay 네트워크

• 정의: 여러 Docker Host 간 네트워크를 연결해주는 분산 네트워크.

• 특징:

  • Swarm 또는 Kubernetes 같은 오케스트레이션 환경에서 사용.
  • 서로 다른 물리 서버의 컨테이너끼리 같은 네트워크처럼 동작.

• 실습 예시 (Swarm 모드):

# Swarm 초기화
docker swarm init

# Overlay 네트워크 생성
docker network create -d overlay my-overlay

# Service 실행
docker service create --name web --network my-overlay nginx

• 사용 사례:

  • 멀티 노드 환경에서 마이크로서비스 아키텍처.
  • 분산 시스템 구축.

5. 네트워크 선택 가이드

💡 정리

• 단일 서버 환경 → Bridge
• 성능 우선, 네트워크 단순화 → Host
• 멀티 노드/클러스터 환경 → Overlay

실무에서는 개발 단계는 bridge → 운영 단계는 host/overlay로 전환하는 경우가 많습니다.

1. git fetch – *"최신 정보를 가져오기만 해!"*

git fetch origin

• 원격 저장소의 변경사항을 가져오되, 내 로컬 브랜치에는 적용하지 않음
• 단지 .git 디렉토리 내부의 정보를 최신화
• git log origin/main 혹은 git diff origin/main 등으로 확인 가능

언제 쓰냐?

• 변경사항을 확인하고 싶지만, 아직 내 코드에 적용하고 싶지 않을 때
• 특히 CI/CD로 충돌을 미리 체크하고 싶을 때 아주 유용

2. git rebase – *"내 작업을 최신 커밋 위에 깔끔하게 다시 올려줘"*

git rebase origin/main

• 현재 브랜치에 있는 커밋을, 원격 브랜치의 최신 커밋 이후로 옮김
• 즉, 내가 한 작업을 나중에 한 것처럼 만들기 (히스토리가 깨끗해짐)
• 충돌이 날 수 있지만, 충돌을 직접 해결할 수 있어서 협업에 적합

언제 쓰냐?

• 팀에서 rebase 전략을 쓰는 경우
• 커밋 로그를 깔끔하게 유지하고 싶을 때

주의!

• rebase는 공유된 브랜치에서는 신중히! git push --force가 필요할 수 있음. 잘못 쓰면 동료의 작업이 날아갈 수 있음.

3. git pull – *"최신 걸 가져오고 바로 병합해줘"*

git pull origin main

• git fetch + git merge를 한 번에 수행
• 가장 많이 쓰이지만, 커밋 히스토리가 지저분해질 수 있음
• 충돌도 발생 가능

🔧 언제 쓰냐?

• 혼자 작업할 때 빠르게 최신화하려면 편함
• 그러나 팀 협업에서는 **의도치 않은 병합 커밋(Merge commit)**이 생겨 버그 추적이 힘들 수 있음

실전 예시

협업 중이라면?

git fetch origin
git rebase origin/main

✔️ 충돌을 내가 직접 해결하면서 커밋 히스토리를 깔끔하게 유지할 수 있음

그냥 빠르게 동기화하고 싶다면?

git pull origin main

✔️ 단, 히스토리 관리에 민감하지 않을 때만

추가 꿀팁

차이점 비교 요약

마무리하며

예전엔 git pull만 써도 충분했지만, 협업이 잦아지고 충돌/히스토리 문제가 늘어나면서 fetch + rebase 조합을 더 많이 쓰게 되더라구요.

실제로 큰 서비스팀에서 일할수록, 커밋 하나하나가 버그 추적의 단서가 되기 때문에 rebase를 쓰는 게 디폴트인 팀도 많아요.

가드는 단일 책임을 갖습니다 . 런타임에 존재하는 특정 조건(권한, 역할, ACL 등)에 따라 주어진 요청을 경로 처리기가 처리할지 여부를 결정합니다. 이를 권한 부여(authorization)라고 합니다 . 권한 부여(authorization)와 그 사촌격인 인증 (authentication)은 기존 Express 애플리케이션에서 일반적으로 미들웨어 가 처리해 왔습니다 . 토큰 검증이나 객체에 속성 연결과 같은 작업은 request특정 경로 컨텍스트(및 해당 메타데이터)와 긴밀하게 연결되지 않기 때문에 미들웨어는 인증에 적합한 선택입니다.

next()함수를 호출한 후 어떤 핸들러가 실행될지 알 수 없습니다. 반면, 가드는 인스턴스 에 접근하여 ExecutionContext다음에 무엇이 실행될지 정확히 알고 있습니다. 가드는 예외 필터, 파이프, 인터셉터와 마찬가지로 요청/응답 주기의 정확한 시점에 처리 로직을 삽입할 수 있도록 설계되었으며, 이를 선언적으로 수행할 수 있습니다. 이는 코드를 DRY하고 선언적으로 유지하는 데 도움이 됩니다.

Q1. NestJS의 Guard란 무엇인가요? 언제 사용하나요?

A1. Guard는 NestJS에서 요청(Request)을 컨트롤러에 전달하기 전에 실행되는 클래스입니다. 주로 인증(Authentication) 또는 권한(Authorization)과 같은 조건을 검증할 때 사용됩니다. 예를 들어, 사용자가 특정 API에 접근 가능한지를 판단할 때 Guard를 설정하면, 조건이 맞지 않으면 요청 자체를 차단할 수 있어요.

Q2. Guard를 구현할 때 어떤 인터페이스와 메서드를 사용하나요?

A2. Guard는 @Injectable() 데코레이터가 붙은 클래스이며, CanActivate 인터페이스를 구현해야 합니다. 핵심은 canActivate(context: ExecutionContext): boolean | Promise<boolean> 메서드입니다. 이 메서드가 true를 반환하면 요청이 통과되고, false를 반환하면 요청이 거부됩니다.

Q3. ExecutionContext는 어떤 역할을 하나요?

A3. ExecutionContext는 현재 실행 중인 요청의 정보를 추상화한 객체입니다. context.switchToHttp().getRequest()를 통해 HTTP 요청 객체에 접근할 수 있어요. RPC, GraphQL, WebSocket 등 다양한 플랫폼에서도 사용할 수 있도록 추상화되어 있어 유연성이 큽니다.

Q4. Guard와 Interceptor, Middleware의 차이는 무엇인가요?

A4. 이 셋은 모두 요청 처리 흐름에서 관여하지만 시점과 목적이 달라요.

• Middleware: 요청이 애플리케이션에 들어오기 전에 실행. 주로 로깅, 요청 변형, CORS 처리 등.
• Guard: 요청이 컨트롤러에 도달하기 직전에 실행. 인증/인가 로직에 최적화.
• Interceptor: 컨트롤러 실행 전/후에 실행. 응답 가공, 캐싱, 트랜잭션 처리 등에 사용.

Q5. Guard는 어디에 적용할 수 있나요?

A5. Guard는 다음과 같이 다양한 범위에 적용할 수 있어요.

• 메서드 단위: @UseGuards(MyGuard)
• 컨트롤러 전체: @UseGuards(MyGuard)를 컨트롤러 클래스에
• 전역 적용: app.useGlobalGuards()를 main.ts에서 설정

Q6. Role 기반 접근 제어는 어떻게 구현하나요?

A6. 주로 커스텀 데코레이터 @Roles()와 RolesGuard를 조합해서 사용합니다.

1. @Roles() 데코레이터로 필요한 역할을 지정하고
2. RolesGuard에서 사용자의 역할이 그에 포함되는지를 검사하는 방식입니다.

이런 구조는 NestJS의 메타데이터(Reflector)와 Guard의 궁합을 잘 보여주는 예시죠.

Q7. NestJS Guard를 사용하면서 겪은 어려움이나 깨달음이 있다면?

A7. 처음에는 ExecutionContext 구조나 HTTP 외의 컨텍스트 전환 방식이 헷갈릴 수 있었어요. 하지만 구조를 하나하나 뜯어보고 나면 NestJS의 확장성과 철학이 잘 드러나는 부분이기도 합니다. 특히 인증 시스템과 역할 기반 인가를 설계할 때 Guard는 핵심 역할을 하기 때문에, 실제 프로젝트에서도 Guard의 잘 설계된 구조는 시스템 안정성과 보안성에 큰 도움이 되었습니다.

권한 부여 가드

권한 부여는 Guards의 훌륭한 사용 사례입니다. 특정 경로는 호출자(일반적으로 특정 인증된 사용자)가 충분한 권한을 가지고 있을 때만 사용할 수 있어야 하기 때문입니다. AuthGuard이제 만들 는 인증된 사용자(따라서 요청 헤더에 토큰이 첨부됨)를 가정합니다. 토큰을 추출하고 유효성을 검사한 후, 추출된 정보를 사용하여 요청 진행 여부를 결정합니다.

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    return validateRequest(request);
  }
}

역할 기반 인증

특정 역할을 가진 사용자에게만 접근을 허용하는 더욱 기능적인 가드를 만들어 보겠습니다. 기본 가드 템플릿부터 시작하여 다음 섹션에서 이를 기반으로 확장해 보겠습니다. 지금은 모든 요청이 진행되도록 허용합니다.

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class RolesGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    return true;
  }
}

바인딩 가드

파이프 및 예외 필터처럼 가드는 컨트롤러 범위 , 메서드 범위 또는 전역 범위일 수 있습니다. 아래에서는 @UseGuards()데코레이터를 사용하여 컨트롤러 범위 가드를 설정합니다. 이 데코레이터는 단일 인수 또는 쉼표로 구분된 인수 목록을 받을 수 있습니다. 이를 통해 하나의 선언으로 적절한 가드 세트를 쉽게 적용할 수 있습니다.

@Controller('cats')
@UseGuards(RolesGuard)
export class CatsController {}

@Controller('cats')
@UseGuards(new RolesGuard())
export class CatsController {}

const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new RolesGuard());

import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: RolesGuard,
    },
  ],
})
export class AppModule {}

핸들러당 역할 설정

RolesGuard시스템은 잘 작동하지만, 아직 그다지 똑똑하지는 않습니다. 가장 중요한 가드 기능인 실행 컨텍스트 를 아직 활용하지 못하고 있습니다 . 아직 역할, 즉 각 핸들러에 허용되는 역할에 대해 알지 못합니다.예를 들어 CatsController, 는 경로마다 다른 권한 체계를 가질 수 있습니다. 어떤 경로는 관리자에게만 제공되고, 어떤 경로는 모든 사용자에게 공개될 수 있습니다. 유연하고 재사용 가능한 방식으로 역할과 경로를 어떻게 일치시킬 수 있을까요?

여기서 사용자 지정 메타데이터가 중요한 역할을 합니다. Nest는 정적 메서드를 통해 생성된 데코레이터 또는 기본 제공 데코레이터를 통해 경로 핸들러에 사용자 지정 메타데이터를 첨부할 수 있는 기능을 제공합니다

예를 들어, 메타데이터를 핸들러에 첨부하는 메서드를 @Roles()사용하여 데코레이터를 만들어 보겠습니다 . 이는 프레임워크에서 기본적으로 제공되며 패키지에서 노출됩니다.

import { Reflector } from '@nestjs/core';

export const Roles = Reflector.createDecorator<string[]>();

@Post()
@Roles(['admin'])
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Roles } from './roles.decorator';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const roles = this.reflector.get(Roles, context.getHandler());
    if (!roles) {
      return true;
    }
    const request = context.switchToHttp().getRequest();
    const user = request.user;
    return matchRoles(roles, user.roles);
  }
}

기본적으로 이 작업은 내장된 전역 예외 필터 에 의해 수행되며 , 이 필터는 유형 HttpException(및 해당 하위 클래스)의 예외를 처리합니다. 예외가 인식되지 않는HttpException 경우( 또는 를 상속하는 클래스가 아닌 경우 HttpException), 내장된 예외 필터는 다음과 같은 기본 JSON 응답을 생성합니다.

표준 예외 발생

Nest는 패키지 HttpException에 내장된 클래스를 제공합니다 @nestjs/common. 일반적인 HTTP REST/GraphQL API 기반 애플리케이션의 경우, 특정 오류 발생 시 표준 HTTP 응답 객체를 전송하는 것이 가장 좋습니다.

예를 들어, 에 메서드( 라우트 핸들러) CatsController가 있습니다 . 이 라우트 핸들러가 어떤 이유로든 예외를 발생시킨다고 가정해 보겠습니다. 이를 보여주기 위해 다음과 같이 하드코딩합니다.

// cats.controller.ts

import { Controller, Get, Param, NotFoundException } from '@nestjs/common';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get(':id')
  async findOne(@Param('id') id: string) {
    const cat = await this.catsService.findById(id);
    if (!cat) {
      throw new NotFoundException(`고양이 ID ${id}를 찾을 수 없습니다.`);
    }
    return cat;
  }
}

생성자 HttpException는 응답을 결정하는 두 가지 필수 인수를 사용합니다.

1. response는 JSON 응답 본문을 정의합니다. 아래 설명된 대로 string 또는 object 일 수 있습니다.
2. HTTP 상태 코드를status 정의합니다 .

기본적으로 JSON 응답 본문에는 두 가지 속성이 포함됩니다.

1. statusCodestatus: 인수 에 제공된 HTTP 상태 코드를 기본값으로 사용합니다.
2. message: HTTP 오류에 대한 간략한 설명status JSON 응답 본문의 메시지 부분만 재정의하려면 response인수에 문자열을 제공하세요. JSON 응답 본문 전체를 재정의하려면 response인수에 객체를 전달하세요. Nest는 객체를 직렬화하여 JSON 응답 본문으로 반환합니다.

두 번째 생성자 인수 - status는 유효한 HTTP 상태 코드여야 합니다. .@nestjs/common HttpStatus에서 가져온 열거형을 사용하는 것이 가장 좋습니다.

세 번째 생성자 인수(선택 사항) 인 options-HttpException 는 오류 원인을 제공하는 데 사용할 수 있습니다 . 이 cause객체는 응답 객체로 직렬화되지 않지만, 로깅 목적으로 유용할 수 있으며, 오류 발생의 원인이 된 내부 오류에 대한 중요한 정보를 제공합니다 .

import { HttpException, HttpStatus } from '@nestjs/common';

throw new HttpException(
  {
    statusCode: HttpStatus.BAD_REQUEST,
    message: '입력한 값이 유효하지 않습니다.',
    error: 'Bad Request',
    details: {
      field: 'email',
      issue: '이메일 형식이 아닙니다.',
    },
  },
  HttpStatus.BAD_REQUEST,
  {
    cause: new Error('ValidationError: 이메일 형식 오류'),
  },
);

다음은 전체 응답 본문을 재정의하고 오류 원인을 제공하는 예입니다.

생성자 인수 설명

1. response (첫 번째 인수)

• 타입: string 또는 object
• 역할: 클라이언트에 반환될 JSON 응답의 본문(body) 정의
• 위 예시에서는 아래 객체 전체가 클라이언트에게 응답됩니다:

{
  "statusCode": 400,
  "message": "입력한 값이 유효하지 않습니다.",
  "error": "Bad Request",
  "details": {
    "field": "email",
    "issue": "이메일 형식이 아닙니다."
  }
}

• 이처럼 커스텀 필드(details)를 넣어서 응답을 세부적으로 제어할 수 있습니다.

2. status (두 번째 인수)

• 타입: number (HTTP 상태코드)
• 역할: 응답의 HTTP 상태 코드를 정의
• HttpStatus.BAD_REQUEST는 400이며, Nest에서는 @nestjs/common에서 제공하는 HttpStatus enum을 사용하는 것이 좋습니다.

3. options (세 번째 인수) - 선택

• 타입: { cause?: Error }
• 역할: 로깅 또는 디버깅용 내부 에러 정보를 담는 옵션
• 이 값은 클라이언트에게는 보이지 않지만, Nest의 내부 로거에서 예외 원인(cause)을 추적하거나 에러 스택을 기록하는 데 유용합니다.

실제 사용 예: 유효성 검사 실패 시

예를 들어, 사용자가 이메일 필드에 잘못된 값을 보냈을 때, 아래와 같이 사용할 수 있습니다:

if (!isValidEmail(input.email)) {
  throw new HttpException(
    {
      statusCode: 400,
      message: '입력한 이메일이 유효하지 않습니다.',
      error: 'Bad Request',
      details: {
        field: 'email',
        issue: '형식이 이메일이 아닙니다.',
      },
    },
    HttpStatus.BAD_REQUEST,
    {
      cause: new Error('이메일 정규표현식 검사 실패'),
    },
  );
}

이렇게 하면 프론트엔드에서는 구체적인 오류 메시지를 기반으로 사용자에게 피드백을 줄 수 있고, 백엔드에서는 cause를 기반으로 로깅이나 디버깅이 용이해집니다.

예외 로깅

기본적으로 예외 필터는 (해당 필터에서 상속되는 모든 예외)와 같은 내장 예외를 기록하지 않습니다 . 이러한 예외가 발생하면 일반 애플리케이션 흐름의 일부로 처리되므로 콘솔에 표시되지 않습니다.WsExceptionRpcException 및 HttpException와 같은 다른 내장 예외에도 동일한 동작이 적용됩니다 .

@nestjs/common IntrinsicException예외는 모두 패키지 에서 내보내는 기본 클래스를 상속합니다 . 이 클래스는 일반적인 애플리케이션 동작에 포함되는 예외와 그렇지 않은 예외를 구분하는 데 도움이 됩니다.

이러한 예외를 기록하려면 사용자 지정 예외 필터를 만들 수 있습니다. 다음 섹션에서 이 작업을 수행하는 방법을 설명하겠습니다.

사용자 정의 예외

대부분의 경우 사용자 지정 예외를 작성할 필요가 없으며, 기본 Nest HTTP 예외를 사용할 수 있습니다. 사용자 지정 예외를 생성해야 하는 경우, 사용자 지정 예외가 기본 클래스를 상속하는 자체 예외 계층 구조를 HttpException으로 만드는 것이 좋습니다 . 이 방법을 사용하면 Nest가 예외를 인식하고 오류 응답을 자동으로 처리합니다. 이러한 사용자 지정 예외를 구현해 보겠습니다.

export class ForbiddenException extends HttpException {
  constructor() {
    super('Forbidden', HttpStatus.FORBIDDEN);
  }
}

내장된 HTTP 예외

Nest는 기본 .NET Framework에서 상속되는 표준 예외 집합을 제공합니다 HttpException. 이러한 예외는 @nestjs/common패키지에 포함되어 있습니다.

• BadRequestException
• UnauthorizedException
• NotFoundException
• ForbiddenException
• NotAcceptableException
• RequestTimeoutException
• ConflictException
• GoneException
• HttpVersionNotSupportedException
• PayloadTooLargeException
• UnsupportedMediaTypeException
• UnprocessableEntityException
• InternalServerErrorException
• NotImplementedException
• ImATeapotException
• MethodNotAllowedException
• BadGatewayException
• ServiceUnavailableException
• GatewayTimeoutException
• PreconditionFailedException 모든 내장 예외는 매개변수 cause를 사용하여 오류와 오류 설명을 모두 제공할 수도 있습니다.

예외 필터

기본(내장) 예외 필터는 여러 사례를 자동으로 처리할 수 있지만, 예외 계층을 완벽하게 제어 하고 싶을 수도 있습니다. 예를 들어, 로깅을 추가하거나 일부 동적 요소에 따라 다른 JSON 스키마를 사용하고 싶을 수 있습니다. 예외 필터는 바로 이러한 목적을 위해 설계되었습니다. 이를 통해 클라이언트로 전송되는 응답의 내용과 제어 흐름을 정확하게 제어할 수 있습니다.

클래스의 인스턴스인 예외를 포착하고, 이에 대한 사용자 지정 응답 로직을 구현하는 예외 필터를 만들어 보겠습니다 . 이를 위해서는 기본 플랫폼 과 HttpException 객체 에 접근해야 합니다 . 객체에 접근하여 원본 객체를 추출 하고 로깅 정보에 포함할 것입니다. 또한, 이 객체를 사용하여 메서드를 통해 전송되는 응답을 직접 제어합니다.

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  Logger,
} from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(HttpExceptionFilter.name);

  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();
    const exceptionResponse = exception.getResponse();

    // 예외 로깅
    this.logger.error(
      `[${request.method}] ${request.url} ${status} - ${JSON.stringify(exceptionResponse)}`,
    );

    // 클라이언트에게 반환
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      ...(typeof exceptionResponse === 'string'
        ? { message: exceptionResponse }
        : exceptionResponse),
    });
  }
}

바인딩 필터

@Post()
@UseFilters(new HttpExceptionFilter())
async create(@Body() createCatDto: CreateCatDto) {
  throw new ForbiddenException();
}

또는 전역

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './filters/http-exception.filter';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter());
  await app.listen(3000);
}
bootstrap();

또는 전역 모듈

import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: HttpExceptionFilter,
    },
  ],
})
export class AppModule {}

Catch Every

모든 예외를 처리할 때에는 @Catch를 비워두세요

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

@Catch()
export class CatchEverythingFilter implements ExceptionFilter {
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(exception: unknown, host: ArgumentsHost): void {
    // In certain situations `httpAdapter` might not be available in the
    // constructor method, thus we should resolve it here.
    const { httpAdapter } = this.httpAdapterHost;

    const ctx = host.switchToHttp();

    const httpStatus =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    const responseBody = {
      statusCode: httpStatus,
      timestamp: new Date().toISOString(),
      path: httpAdapter.getRequestUrl(ctx.getRequest()),
    };

    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
  }
}

미들웨어 (Middleware)

미들웨어는 라우트 핸들러 보다 먼저 호출되는 함수입니다 . 미들웨어 함수는 요청 및 응답 객체에 접근할 수 있으며, next()애플리케이션의 요청-응답 주기에서 미들웨어 함수에 접근할 수 있습니다.

Nest 미들웨어는 기본적으로 Express 미들웨어와 동일합니다. Express 공식 문서의 다음 설명은 미들웨어의 기능을 설명합니다.

미들웨어 기능은 다음과 같은 작업을 수행할 수 있습니다.

• 모든 코드를 실행합니다.
• 요청 및 응답 객체를 변경합니다.
• 요청-응답 주기를 종료합니다.
• 스택의 다음 미들웨어 함수를 호출합니다.
• 미들웨어 함수가 요청-응답 주기를 종료하지 않으면 next()다음 미들웨어 함수로 제어권을 넘기기 위해 호출해야 합니다. 그렇지 않으면 요청은 중단 상태로 남게 됩니다.

import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log('Request...');
    next();
  }
}

Spring 에서 Filter 코드

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Component
public class LoggerInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {
        System.out.println("Request...");
        return true; // false 반환 시 요청 중단
    }
}

종속성 주입

Nest 미들웨어는 의존성 주입을 완벽하게 지원합니다. 공급자와 컨트롤러와 마찬가지로, 동일한 모듈 내에서 사용 가능한 의존성을 주입 할 수 있습니다

미들웨어 적용

데코레이터 에는 미들웨어를 위한 공간이 없습니다 . 대신 모듈 클래스의 메서드를 @Module()사용하여 미들웨어를 설정합니다 . 미들웨어를 포함하는 모듈은 인터페이스를 구현해야 합니다. 해당 레벨에서 미들웨어를 설정해 보겠습니다

import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { CatsController } from './cats/cats.controller';
import { CatsModule } from './cats/cats.module';
import { LoggerMiddleware } from './logger/logger.middleware';


@Module({
  imports: [CatsModule],
  controllers: [AppController, CatsController],
  providers: [AppService],
})
export class AppModule implements NestModule {  
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('cats');
  }
}

특정 경로로 제한

...
.forRoutes({ path: 'cats', method: RequestMethod.GET });

경로 와일드카드

패턴 기반 경로는 NestJS 미들웨어에서도 지원됩니다. 예를 들어, 명명된 와일드카드( )를 사용하여 경로의 모든 문자 조합을 일치시킬 수 있습니다. 다음 예제에서 미들웨어는 뒤에 오는 문자 수에 관계없이 *splat로 시작하는 모든 경로에 대해 실행됩니다 .

...
forRoutes({
  path: 'abcd/*splat',
  method: RequestMethod.ALL,
});

경로 경로는 , , 등과 'abcd/*'일치합니다 . 하이픈( )과 마침표( )는 문자열 기반 경로에서 문자 그대로 해석됩니다. 그러나 추가 문자가 없으면 경로와 일치하지 않습니다. 이 경우 와일드카드를 중괄호로 묶어 선택 사항으로 만들어야 합니다.

...

forRoutes({
  path: 'abcd/{*splat}',
  method: RequestMethod.ALL,
});

경로 제외

때로는 특정 경로를 미들웨어 적용에서 제외exclude() 해야 할 수 있습니다. 이는 메서드를 사용하여 쉽게 구현할 수 있습니다. 이 메서드는 제외할 경로를 식별하기 위해 exclude()단일 문자열, 여러 문자열 또는 객체를 받습니다.

consumer
  .apply(LoggerMiddleware)
  .exclude(
    { path: 'cats', method: RequestMethod.GET },
    { path: 'cats', method: RequestMethod.POST },
    'cats/{*splat}',
  )
  .forRoutes(CatsController);

위의 예제를 사용하면 메서드 에 전달된 세 개의 경로를 제외한LoggerMiddleware , 내부에 정의된 모든 경로에 바인딩됩니다

이 접근 방식은 특정 경로나 경로 패턴에 따라 미들웨어를 적용하거나 제외하는 데 있어 유연성을 제공합니다.

함수형 미들웨어

우리가 사용해 온 클래스 LoggerMiddleware는 매우 간단합니다. 멤버도, 추가 메서드도, 종속성도 없습니다. 왜 클래스 대신 간단한 함수로 정의할 수 없는 걸까요? 사실, 가능합니다. 이러한 유형의 미들웨어를 함수형 미들웨어 라고 합니다 . 차이점을 보여주기 위해 로거 미들웨어를 클래스 기반에서 함수형 미들웨어로 변환해 보겠습니다.

import { Request, Response, NextFunction } from 'express';

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log(`Request...`);
  next();
};

다중 미들웨어

위에서 언급했듯이 순차적으로 실행되는 여러 미들웨어를 바인딩하려면 apply()메서드 내부에 쉼표로 구분된 목록을 제공하기만 하면 됩니다.

import { MiddlewareConsumer, Module, NestModule, RequestMethod } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { CatsController } from './cats/cats.controller';
import { CatsModule } from './cats/cats.module';
import { logger, LoggerMiddleware } from './logger/logger.middleware';


@Module({
  imports: [CatsModule],
  controllers: [AppController, CatsController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {

    consumer
      .apply(LoggerMiddleware,logger)
      .exclude(
        { path: 'cats', method: RequestMethod.GET },
        { path: 'cats', method: RequestMethod.POST },
        'cats/{*splat}',
      )
      .forRoutes(CatsController);


  }
}

글로벌 미들웨어

등록된 모든 경로에 미들웨어를 한 번에 바인딩하려면 인스턴스 use()에서 제공하는 메서드를 사용할 수 있습니다.

const app = await NestFactory.create(AppModule);
app.use(logger);
await app.listen(process.env.PORT ?? 3000);

모든 Nest 애플리케이션에는 최소 하나의 모듈, 즉 루트 모듈 이 있으며, 이 모듈은 Nest가 애플리케이션 그래프를 구축하는 시작점 역할을 합니다 . 이 그래프는 Nest가 모듈과 제공자 간의 관계와 종속성을 확인하는 데 사용하는 내부 구조입니다. 소규모 애플리케이션에는 루트 모듈만 있을 수 있지만, 일반적으로는 그렇지 않습니다. 모듈은 구성 요소를 효과적으로 구성하는 방법으로 적극 권장됩니다 . 대부분의 애플리케이션에는 여러 모듈이 있으며, 각 모듈은 밀접하게 관련된 기능 집합을 캡슐화합니다 .

데코레이터 @Module()는 모듈을 설명하는 속성을 가진 단일 객체를 가져옵니다.

• providers: Nest 인젝터에 의해 인스턴스화되고 최소한 이 모듈 전체에서 공유될 수 있는 공급자

• controllers: 이 모듈에 정의된 컨트롤러 세트는 인스턴스화되어야 합니다.

• imports: 이 모듈에 필요한 공급자를 내보내는 가져온 모듈 목록

• exports: 이 모듈에서 제공하는 하위 집합은 providers이 모듈을 가져오는 다른 모듈에서도 사용할 수 있어야 합니다. 제공자 자체를 사용하거나 토큰( provide값) 만 사용할 수 있습니다.

  모듈은 기본적으로 프로바이더를 캡슐화합니다 . 즉, 현재 모듈에 포함되어 있거나 다른 가져온 모듈에서 명시적으로 내보낸 프로바이더만 주입할 수 있습니다. 모듈에서 내보낸 프로바이더는 기본적으로 해당 모듈의 공용 인터페이스 또는 API 역할을 합니다.

기능 모듈

CatsController는 CatsService밀접한 관련이 있으며 동일한 애플리케이션 도메인을 담당합니다. 따라서 이들을 기능 모듈로 그룹화하는 것이 좋습니다. 기능 모듈은 특정 기능과 관련된 코드를 구성하여 명확한 경계를 유지하고 더 나은 구성을 유지하는 데 도움이 됩니다. 이는 애플리케이션이나 팀이 성장함에 따라 특히 중요하며, SOLID 원칙과도 일치합니다.

CatsModule다음으로, 컨트롤러와 서비스를 그룹화하는 방법을 보여주기 위해 를 생성하겠습니다 .

CLI

nest g service cats

Code

Service

import { Injectable } from '@nestjs/common';
import { Cat } from './interfaces/cat.interface';

@Injectable()
export class CatsService {
  private readonly cats: Cat[] = [];

  create(cat: Cat) {
    this.cats.push(cat);
  }

  findAll(): Cat[] {
    return this.cats;
  }
}

이제 고양이를 검색하는 서비스 클래스가 생겼으니, 이를 : 내부에서 사용해 보겠습니다

Controller

import { Controller, Get, Post, Body } from '@nestjs/common';
import { CreateCatDto } from './dto/create-cat.dto';
import { CatsService } from './cats.service';
import { Cat } from './interfaces/cat.interface';

@Controller('cats')
export class CatsController {
  constructor(private catsService: CatsService) {}

  @Post()
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto);
  }

  @Get()
  async findAll(): Promise<Cat[]> {
    return this.catsService.findAll();
  }
}

클래스 생성자를 통해 주입됩니다

종속성 주입

Nest는 의존성 주입(Dependency Injection) 이라는 강력한 디자인 패턴을 기반으로 구축되었습니다 . 공식 Angular 문서 에서 이 개념에 대한 유용한 글을 읽어보시기를 강력히 추천합니다 .

Nest에서는 TypeScript의 기능 덕분에 종속성이 유형에 따라 해결되므로 관리가 간편합니다. 아래 예시에서 Nest는 catsService인스턴스를 생성하고 반환하여 종속성을 해결합니다 CatsService(싱글턴의 경우 이미 다른 곳에서 요청된 경우 기존 인스턴스를 반환합니다). 이 종속성은 컨트롤러의 생성자에 주입되거나 지정된 속성에 할당됩니다.

범위

공급자는 일반적으로 애플리케이션 수명 주기와 일치하는 수명("범위")을 갖습니다. 애플리케이션이 부트스트랩될 때 각 종속성을 해결해야 하므로 모든 공급자가 인스턴스화됩니다. 마찬가지로 애플리케이션이 종료되면 모든 공급자가 삭제됩니다. 하지만 공급자를 요청 범위로 지정할 수도 있습니다. 즉, 공급자의 수명이 애플리케이션의 수명 주기가 아닌 특정 요청에 따라 결정됩니다. 이러한 기법에 대한 자세한 내용은 주입 범위 장 에서 확인할 수 있습니다.

Controllers

NestJS에서는 Spring과 마찬가지로 controller에서 들어오는 요청을 처리하고 클라이언트에게 응답을 다시 보내는 역할을 합니다 .

Controller에서는 애플리케이션의 특정 요청을 처리합니다. NestJS에서의 Controller는 Spring과 마찬가지로 @Controller 데코레이터를 사용합니다.

메타프로그래밍 기능을 사용해 클래스, 메서드, 파라미터 등에 추가 정보를 붙이는 문법. Nest의 선언형 프로그래밍 핵심 메타프로그래밍(Metaprogramming)이란 자기 자신 혹은 다른 컴퓨터 프로그램을 데이터로 취급하며 프로그램을 작성·수정하는 것을 말한다. 넓은 의미에서, 런타임에 수행해야 할 작업의 일부를 컴파일 타임 동안 수행하는 프로그램을 말하기도 한다.

@Controller 또는 클래스 메소드에 작성된 @Get,@Post 등의 데코레이터에 입력된 문자열은 애플리케이션에서 들어오는 요청에 대한 경로를 의미합니다.

라우팅 메커니즘은 각 요청을 처리할 컨트롤러를 결정합니다.

라우팅 메커니즘 클라이언트의 요청 URL과 HTTP 메서드(GET, POST 등)를 해당 컨트롤러 메서드에 연결하는 기능

컨트롤러는 여러 경로를 가지며, 각 경로는 서로 다른 작업을 수행할 수 있습니다.

기본 컨트롤러를 만들려면 클래스와 데코레이터를 사용합니다 . 데코레이터는 클래스를 필요한 메타데이터와 연결하여 Nest가 요청을 해당 컨트롤러에 연결하는 라우팅 맵을 생성할 수 있도록 합니다.

라우팅

다음 예제에서는 기본 컨트롤러를 정의하는 데 필요한@Controller() 데코레이터를 사용합니다. 선택적으로 경로 경로 접두사로 . 를 지정합니다 . 데코레이터에 경로 접두사를 사용하면 관련 경로를 그룹화하고 반복적인 코드를 줄일 수 있습니다. 예를 들어, 경로 아래에 있는 cat 엔터티와의 상호 작용을 관리하는 경로를 그룹화하려면 데코레이터 에 경로 접두사를 지정할 수 있습니다 . 이렇게 하면 파일의 각 경로에 대해 해당 경로 부분을 반복할 필요가 없습니다.cats@Controller()/catscats@Controller()

import { Controller, Get } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(): string {
    return 'This action returns all cats';
  }
}

CLI

nest g controller [name] 

명령어를 통해서 controller 를 class 파일을 생성할 수 있습니다.

기타

• NestJS Controller는 JavaScript 객체 또는 배열을 반환할 때 JSON으로 자동 직렬화
• 응답의 상태 코드는 기본적으로 항상 200입니다. 단, POST 요청은 201을 사용합니다. @HttpCode(...)핸들러 수준에서 데코레이터를 추가하여 이 동작을 쉽게 변경할 수 있습니다
• 응답 객체를 사용할 수 있으며 , 이 객체는 @Res()메서드 핸들러 시그니처(예: findAll(@Res() response))에 데코레이터를 사용하여 주입할 수 있습니다. 이 방식을 사용하면 해당 객체가 제공하는 네이티브 응답 처리 메서드를 사용할 수 있습니다.

Hello, nest

NestJS에 대해서 처음 접했던 건 아르바이트로 참여했던 프로젝트에서 사용했던 스택으로 시작합니다. 기존에는 Spring 또는 전자정부프레임워크로 진행하는 SI 프로젝트에 참여하고 있었습니다. Javascript로 기존의 화면 기능에대한 부분을 개발하고 있었기 때문에 언어에 대한 부담감은 없었지만, 새로운 프레임워크를 사용한다는 건 언제나 두근두근 하게 만드는 것 같습니다.

막연하게나마 어떻게 개발을 하게 될까라는 호기심으로 배움으로 또는 새로운 영역에 대한 확장으로 이어질 수 있지 않을까라는 기대감을 가지게 됩니다.

처음 프레임워크나 라이브러리를 사용할때 다들 어떻게 하시나요 ? 요즘은 아무래도 Chatgpt를 사용하거나, Cursor나 windsurf등으로 개발을 하게되면 쉽게 특정 부분에 대한 내용을 바로 코딩해주기 때문에 편할 걸로 생각됩니다.

스터디 겸 정리 겸 nestjs 공식문서를 참고해 볼 까 합니다.

NestJS

Introduction

Nest (NestJS) is a framework for building efficient, scalable Node.js server-side applications. It uses progressive JavaScript, is built with and fully supports TypeScript (yet still enables developers to code in pure JavaScript) and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Reactive Programming). Under the hood, Nest makes use of robust HTTP Server frameworks like Express (the default) and optionally can be configured to use Fastify as well! Nest provides a level of abstraction above these common Node.js frameworks (Express/Fastify), but also exposes their APIs directly to the developer. This gives developers the freedom to use the myriad of third-party modules which are available for the underlying platform.출처

공식문서에서 소개하는 NestJS에 대한 내용입니다.

요약하면

• NestJS는 효율적이고 확장 가능한 Node.js 기반 서버 프레임워크

• pure Javascript 와 Typescript 작성 및 지원

• 객체지향 프로그래밍(OOP)

  객체지향 프로그래밍(Object-Oriented Programming, OOP)은 데이터를 객체로 모델링하여 소프트웨어를 설계하는 프로그래밍 패러다임입니다. 각 객체는 속성(데이터)과 메서드(동작)를 포함하며, 주요 특징으로는 캡슐화, 상속, 다형성, 추상화가 있습니다.

• 함수형 프로그래밍 (FP)

  함수형 프로그래밍(Functional Programming, FP)은 순수 함수를 기반으로 하는 선언형 프로그래밍 패러다임입니다. 상태 변경이나 부작용을 피하고, 함수를 일급 시민으로 취급하여 고차 함수, 불변성, 함수 합성 등을 강조합니다.

• 함수형 반응형 프로그래밍(FRP)

  함수형 반응형 프로그래밍(Functional Reactive Programming, FRP)은 함수형 프로그래밍과 반응형 프로그래밍을 결합한 패러다임으로, 시간에 따라 변하는 데이터 흐름을 선언적으로 모델링합니다. 이벤트 스트림과 동작(behavior)을 조합하여 비동기 데이터 흐름을 효율적으로 처리합니다.

• 기본적으로 Express를 사용

  Express는 Node.js를 위한 빠르고 유연한 웹 애플리케이션 프레임워크로, 최소한의 기능으로 웹 및 모바일 애플리케이션을 구축할 수 있도록 지원합니다. 라우팅, 미들웨어, HTTP 유틸리티 메서드 등을 제공하여 RESTful API 개발에 널리 사용됩니다.

• 선택적으로 Fastify로 구성할 수 있음

  Fastify는 Node.js를 위한 고성능 웹 프레임워크로, 낮은 오버헤드와 강력한 플러그인 아키텍처를 특징으로 합니다. Express보다 빠른 요청 처리를 목표로 하며, JSON 직렬화 및 비동기 처리를 최적화하여 대규모 애플리케이션에 적합합니다.

• Node.js 프레임워크(Express/Fastify) 위에 추상화 계층 제공, 동시에 개발자에게 API를 직접 노출

• 수많은 서드 파티 모듈들을 자유롭게 사용가능

위와 같은 내용으로 설명하고 있습니다.

nestjs를 시작하려면 어떻게 해야할까요?

Nest CLI

먼저 nest CLI 를 사용하기 위한 패키지 설치를 해야합니다.공식 문서에서는 npm을 이용해 패키지를 관리합니다.

npm install -g @nestjs/cli

@nestjs/cli 패키지를 글로벌로 설치하면 nest 명령어를 사용할 수 있습니다.

nest --help

보통 cli 커맨드에서 제공하는 --help를 nest cli에서 사용하면 nest cli 에서 사용가능한 명령어 목록을 볼 수 있습니다.

Options:
  -v, --version                                   Output the current version.
  -h, --help                                      Output usage information.

Commands:
  new|n [options] [name]                          Generate Nest application.
  build [options] [apps...]                       Build Nest application.
  start [options] [app]                           Run Nest application.
  info|i                                          Display Nest project details.
  add [options] <library>                         Adds support for an external library to your project.
  generate|g [options] <schematic> [name] [path]  Generate a Nest element.
    Schematics available on @nestjs/schematics collection:
      ┌────────────────┬──────────────┬───────────────────────────────────────────────────┐
      │ name          │ alias       │ description                                  │
      │ application   │ application │ Generate a new application workspace         │
      │ class         │ cl          │ Generate a new class                         │
      │ configuration │ config      │ Generate a CLI configuration file            │
      │ controller    │ co          │ Generate a controller declaration            │
      │ decorator     │ d           │ Generate a custom decorator                  │
      │ filter        │ f           │ Generate a filter declaration                │
      │ gateway       │ ga          │ Generate a gateway declaration               │
      │ guard         │ gu          │ Generate a guard declaration                 │
      │ interceptor   │ itc         │ Generate an interceptor declaration          │
      │ interface     │ itf         │ Generate an interface                        │
      │ library       │ lib         │ Generate a new library within a monorepo     │
      │ middleware    │ mi          │ Generate a middleware declaration            │
      │ module        │ mo          │ Generate a module declaration                │
      │ pipe          │ pi          │ Generate a pipe declaration                  │
      │ provider      │ pr          │ Generate a provider declaration              │
      │ resolver      │ r           │ Generate a GraphQL resolver declaration      │
      │ resource      │ res         │ Generate a new CRUD resource                 │
      │ service       │ s           │ Generate a service declaration               │
      │ sub-app       │ app         │ Generate a new application within a monorepo │
      └────────────────┴───────────────┴──────────────────────────────────────────────────┘

프로젝트 생성

프로젝트 생성은 new 명령어를 통해 생성합니다.

nest new <project_name>

공식문서에서는 starter 프로젝트를 제공합니다.

git clone https://github.com/nestjs/typescript-starter.git project
cd project
npm install
npm run start

프로젝트를 실행하면 http://localhost:3000 주소로 접속 어떤 프로그래밍이든 처음 시작하면 만날 수 있는 Hello World 문구가 보입니다.

마무리

여기까지 NestJS에 대한 설명을 공식문서를 통해서 알아보고 starter 프로젝트를 실해시켜 보았습니다.

처음이지만 다른 프레임워크들과 마찬가지로 설치나 프로젝트 생성은 nodejs, npm을 통해서 쉽게 사용할 수 있어 좋은 것 같습니다.

다음은 starter 프로젝트와 공식문서를 함께 살펴보면서 프로젝트 구조는 어떻게 되어 있는지 알아보면 좋을 거 같습니다.

다요소 인증(多要素認證, Multi-factor authentication, MFA)은 적어도 다음 분류 중 두 가지에 한해 별도의 여러 증거 부분을 인증 매커니즘에 성공적으로 제시한 이후에만 사용자가 접근 권한이 주어지는 컴퓨터 접근 제어 방식의 하나이다: 지식(knowledge), 소유(possession), 속성(inherence).출처:위키

다중 인증(MFA, Multi-Factor Authentication)은 사용자의 신원을 확인하기 위해 두 가지 이상의 인증 요소를 요구하는 보안 절차입니다. 이는 단일 인증 방식보다 보안을 강화하여 무단 접근을 방지하는 데 효과적입니다.

역사와 배경

1. 초기 형태: ATM과 PIN

1967년 영국 Barclays 은행에서 도입된 최초의 ATM은 카드(소유 요소)와 PIN(지식 요소)을 요구하여 초기의 2단계 인증 형태를 구현했습니다.

2. 1990년대: 기업용 2FA 도입

1990년대 후반, AT&T는 하드웨어 토큰을 활용한 2FA 시스템을 개발했습니다. 이러한 시스템은 기업 환경에서 보안을 강화하는 데 사용되었습니다.

3. 2000년대: 소비자용 2FA 확산

2000년대 초반, 온라인 뱅킹 및 전자상거래의 성장과 함께 소비자용 2FA가 확산되었습니다. SMS 기반 OTP와 같은 방식이 일반화되었으며, 이는 피싱 공격과 같은 위협에 대응하기 위한 조치였습니다.

4. 2010년대 이후: 모바일 및 생체 인증

스마트폰의 보급과 함께 모바일 앱 기반의 인증 방식이 등장했으며, 지문, 얼굴 인식 등 생체 인증 기술도 MFA에 통합되었습니다. 또한, FIDO2 및 WebAuthn과 같은 표준이 개발되어 비밀번호 없는 인증 환경이 조성되고 있습니다.

구성요소

MFA는 일반적으로 다음 세 가지 요소 중 두 가지 이상을 조합하여 사용합니다:

지식 요소: 사용자가 알고 있는 정보 (예: 비밀번호, PIN)

소유 요소: 사용자가 소유한 물리적 장치 (예: 스마트폰, 보안 토큰)

고유 요소: 사용자의 생체 정보 (예: 지문, 얼굴 인식)

고려사항

비밀번호:

강력한 비밀번호 정책 필요 (예: 길이, 복잡성, 반복 방지 등)

해시(예: bcrypt, Argon2) 처리 필수

토큰, 앱, SMS, 이메일:

SMS/이메일 OTP: 일정 시간 만료, 횟수 제한, 서버-클라이언트 동기화 필요

Authenticator App (TOTP): 시간 기반 알고리즘(HOTP/TOTP), Google Authenticator, Authy 등 연동

FIDO2/WebAuthn: 생체 기반 또는 보안키 기반 → 브라우저/디바이스 호환성 고려

생체 정보 기반:

일반적으로 클라이언트(기기)에 저장, 서버에는 생체 정보 저장 안함

WebAuthn API, Android/iOS 생체 인증 API 사용

보안 고려사항

MFA 인증 흐름을 탈취 방지 설계

토큰 재사용 불가, 단일 사용성 확보

TLS(HTTPS) 적용 필수

타이밍 공격, 브루트포스 방지

MFA 실패 시 반복 제한 및 알림 기능

TOTP 사용 시 서버와 클라이언트의 시간 동기화 관리

사용자 경험(UX) 최적화

MFA 등록/삭제 기능 제공 (사용자 선택 가능하게)

백업 수단 제공 (예: 백업 코드, 보조 이메일)

MFA 단계에서의 안내 메시지 명확화 (예: "인증 코드를 입력하세요", "앱에서 승인해주세요")

MFA 오류 시 유연한 예외 처리 (예: 디바이스 분실 시)

기술 스택별 구현 도구

통신 프로토콜 또는 통신 규약은 컴퓨터나 원거리 통신 장비 사이에서 메시지를 주고 받는 양식과 규칙의 체계이다. 통신 프로토콜은 신호 체계, 인증, 그리고 오류 감지 및 수정 기능을 포함할 수 있다. 프로토콜은 형식, 의미론, 그리고 통신의 동기 과정 등을 정의하기는 하지만 구현되는 방법은 독립적이다. 이때문에 프로토콜은 하드웨어 또는 소프트웨어 그리고 때로는 모두를 사용하여 구현되기도 한다. 출처:위키

프로토콜이란 단어를 생각보다 많이 듣게 되지도, 사용하지도 않아습니다. 보통 HTTP,HTTPS,MCP,TCP/IP 등 용어안에서 다른 단어들과 함께 사용되기 때문이지 않을까 생각됩니다.

프로토콜의 주요 종류

1. 네트워크 계층 프로토콜

• IP (Internet Protocol): 데이터 패킷의 주소 지정과 라우팅을 담당합니다.
• TCP (Transmission Control Protocol): 신뢰성 있는 데이터 전송을 보장하며, 연결 지향적입니다.
• UDP (User Datagram Protocol): 비연결형 프로토콜로, 빠른 전송이 필요할 때 사용됩니다.

2. 응용 계층 프로토콜

• HTTP/HTTPS: 웹 브라우저와 서버 간의 통신을 위한 프로토콜입니다.
• FTP: 파일 전송을 위한 프로토콜입니다.
• SMTP/IMAP/POP3: 이메일 송수신을 위한 프로토콜입니다.

3. 데이터 직렬화 및 API 통신 프로토콜

• JSON: 가볍고 인간이 읽기 쉬운 데이터 형식으로, 웹 API에서 널리 사용됩니다.
• XML: 구조화된 데이터를 표현하는 데 사용되며, 과거에 많이 사용되었습니다.
• GraphQL: 클라이언트가 필요한 데이터만 요청할 수 있게 해주는 쿼리 언어입니다.
• Protocol Buffers (Protobuf): Google에서 개발한 이진 직렬화 형식으로, 빠르고 효율적인 데이터 전송을 제공합니다.

프로토콜은 백엔드와 프론트엔드 개발자 모두에게 필수적인 개념입니다. 백엔드는 데이터의 처리와 보안을, 프론트엔드는 사용자와의 원활한 상호작용을 위해 프로토콜을 활용합니다. 각자의 역할에 맞는 프로토콜의 이해와 활용이 성공적인 애플리케이션 개발의 핵심입니다.

HTTP란?

HTTP(HyperText Transfer Protocol)는 웹 브라우저(클라이언트)와 웹 서버 간에 정보를 주고받기 위한 통신 규약입니다. 1989년 팀 버너스 리(Tim Berners-Lee)가 CERN에서 하이퍼텍스트 기반의 정보 공유를 위해 개발하였으며, 이후 월드 와이드 웹(WWW)의 핵심 프로토콜로 자리 잡았습니다.

HTTP의 주요 특징

비연결성(Connectionless): 각 요청마다 독립적으로 처리되며, 연결이 유지되지 않습니다.

무상태성(Stateless): 서버는 이전 요청의 상태를 저장하지 않습니다.

텍스트 기반 프로토콜: 사람이 읽을 수 있는 형태로 메시지를 주고받습니다.

클라이언트-서버 모델: 클라이언트가 요청을 보내고, 서버가 응답을 제공합니다.

HTTP 통신 과정

클라이언트 요청: 브라우저가 서버에 요청을 보냅니다.

서버 응답: 서버가 요청에 대한 응답을 반환합니다.

데이터 전송: HTML, CSS, 이미지 등 웹 페이지를 구성하는 요소들이 전송됩니다.

HTTPS의 설명과 특징

HTTPS란?

HTTPS(HyperText Transfer Protocol Secure)는 HTTP에 보안 계층을 추가한 프로토콜로, SSL/TLS를 통해 데이터 암호화 및 서버 인증을 제공합니다.

HTTPS의 주요 특징

데이터 암호화: 전송되는 데이터가 암호화되어 제3자가 내용을 볼 수 없습니다.

서버 인증: SSL/TLS 인증서를 통해 서버의 신원을 확인합니다.

데이터 무결성: 데이터가 전송 중 변경되지 않았음을 보장합니다. 배움이 즐거운 개발자

HTTPS 통신 과정

브라우저가 서버에 연결 요청: HTTPS를 통해 서버에 접속합니다.

SSL/TLS 핸드셰이크: 서버는 인증서를 제공하고, 클라이언트는 이를 검증합니다.

세션 키 생성: 클라이언트와 서버는 대칭키를 생성하여 데이터를 암호화합니다.

암호화된 데이터 전송: 세션 키를 사용하여 안전하게 데이터를 주고받습니다.