범데이의 개발노트

[AI 자동화] 웹접근성(WA) 대응 - 3,300개 이미지 Alt 텍스트 생성 자동화

범데이 — Sat, 21 Mar 2026 23:41:50 +0900

1. 문제 배경: "이미지 alt를 다 달아야 한다"

공공기관 웹페이지 고도화 작업을 진행하면서
거쳐야 했던 WA 인증(웹 접근성 인증) 과정이 있었다.

여기서 요구하는 항목 중 하나가

“모든 이미지에 대체 텍스트(alt)를 제공해야 한다”는 것이었다.

요구사항만 보면 이미지 설명을 작성하면 되는 단순한 작업처럼 보였다.
하지만 실제 데이터를 확인해보니 상황이 달랐다.

이미지가 포함된 게시글이 약 911개였고,
전체 이미지 수는 약 3,300개였다.

이 순간 느낀 것은 하나였다.

이건 사람이 일일이 처리하면 공수가 크게 발생하는 작업이다.

2. 초기 작업 방식 (ChatGPT 기반 수작업)

초기에는 ChatGPT를 활용하여 이미지를 하나씩 처리했다.

이미지를 복사하여 전달하고
해당 이미지에 대한 설명을 생성한 뒤
그 결과를 적용하는 방식이었다.

이미지 수가 적을 때는 문제가 없었지만
작업 수량이 늘어나면서 한계가 명확해졌다.

반복 작업으로 인한 피로도가 증가했고,
작업 속도 역시 크게 저하되었다.

이 방식으로는 전체 작업을 처리하기 어렵다고 판단했다.

3. OpenAI API 결제 및 연동

작업을 진행하면서
ChatGPT를 단순히 웹에서 사용하는 것만으로는 한계가 있다는 것을 인지했다.

특히 대량의 이미지를 자동으로 처리하기 위해서는
AI를 코드에서 직접 호출할 수 있는 구조가 필요했다.

이 과정에서 OpenAI API 사용이 필요했고,
기존 ChatGPT Plus 구독과는 별도로 API 결제가 필요했다.

작업 당시에는 일정 금액(약 5,000원 단위)을 설정해두고
사용량에 따라 비용이 차감되는 방식으로 사용했다.

이렇게 API를 사용할 수 있는 환경을 먼저 구성한 이후
본격적인 자동화 작업을 진행했다.

4. 데이터 구조 분석 (OpenClaw 활용)

이후 접근 방식을 변경하여
이미지 개별 처리 대신 전체 구조를 먼저 분석하기로 했다.

OpenClaw를 활용하여
대표 홈페이지의 메뉴 구조를 분석하고,
게시판 형태의 메뉴를 식별한 뒤,
각 게시판의 게시글 목록을 수집했다.

그 중 이미지가 포함된 게시글을 추려낸 결과
총 911개의 게시글이 확인되었고,
이미지 수는 약 3,300개로 집계되었다.

또한 이 과정에서
게시글 URL, 이미지 URL, 기존 alt 텍스트를 함께 정리하였다.

5. 초기 자동화 시도 (Cron Job 기반)

데이터 구조를 정리한 이후
alt 텍스트 생성을 자동화하기 위한 시도를 먼저 진행했다.

당시에는 Cron Job을 활용하여
일정 주기(약 10분 간격)로 API를 호출하고,
이미지에 대한 대체 텍스트를 생성하도록 구성했다.

하지만 실제로 운영해보니 문제가 발생했다.

한 번에 많은 이미지(약 200개 단위)를 요청하면
결과 품질이 급격히 떨어졌고,
이미지와 전혀 관련 없는 텍스트가 생성되거나
유사한 문장이 반복되는 형태가 나타났다.

그래서 요청 단위를 줄여
20개씩 나누어 처리하는 방식으로 변경했지만,
이 경우 전체 요청 횟수가 크게 증가하면서
작업 효율이 떨어지는 문제가 있었다.

또한 결과물을 확인해보면
웹 접근성 기준에 맞는 alt 텍스트로 보기 어려운 경우가 많았고,
결국 사람이 직접 검증하고 보정하는 과정이 필요했다.

이 과정에서 느낀 점은
단순 자동 생성만으로는 품질을 확보하기 어렵고,
추가적인 튜닝이나 검수 구조가 반드시 필요하다는 것이었다.

또한 반복 호출 과정에서 토큰 비용 역시 지속적으로 발생하고 있었다.

이러한 이유로 기존 방식은 유지하기 어렵다고 판단했고,
보다 통제 가능한 구조로 전환하기 위해
Cursor 기반의 스크립트 처리 방식으로 변경하게 되었다.

6. 로컬 데이터 기반 처리 방식 전환

이 단계부터는 작업 방식을 완전히 바꿨다.

기존처럼 웹에 직접 접근해서 처리하는 방식이 아니라
모든 데이터를 로컬로 내려받아서 처리하는 구조로 전환했다.

이 시점부터는 Cursor 기반으로 작업을 진행했고,
필요한 작업들은 Python 스크립트 형태로 구성하도록 했다.

구현은 직접 하나씩 작성하기보다는
Cursor에 프롬프트를 입력해서 스크립트를 생성하는 방식으로 진행했다.

게시글 HTML을 다운로드하고,
이미지를 모두 내려받고,
게시판 번호와 이미지 번호 기준으로 데이터를 정리하는 작업까지
전부 Cursor에게 요청해서 처리했다.

이후에는 Python 스크립트에서 OpenAI API를 연동하여
ChatGPT에 요청하는 것과 동일한 방식으로 alt 텍스트를 생성하도록 구성했다.

게시글 제목과 본문 내용을 함께 전달하고,
로컬에 저장된 이미지를 함께 전달하여
이미지 단독이 아닌 게시글 맥락을 기반으로 alt 텍스트를 생성하도록 했다.

이 과정 역시 프롬프트를 구성하여 요청하고
그 결과를 받아 저장하는 방식으로 처리했다.

또한 이후 작업에 활용할 수 있도록
해당 데이터들을 JSON 형태로 구조화하도록 구성했다.

이후부터는 웹이 아닌 로컬 데이터를 기준으로 작업하게 되었고,
작업 속도와 안정성이 확실히 개선되기 시작했다.

7. 자동 생성 구조 구성

로컬 데이터가 준비된 이후에는
이미지에 대한 대체 텍스트를 자동으로 생성하는 단계로 넘어갔다.

이 과정 역시 Cursor를 활용하여
Python 스크립트 기반으로 구성했다.

로컬에 저장된 이미지와 게시글 HTML,
그리고 게시글 제목 등의 정보를 함께 활용하여
이미지에 대한 설명을 생성하도록 했다.

실제 대체 텍스트 생성은 OpenAI API를 호출하는 방식으로 처리했고,
스크립트 내부에서 이미지와 문맥 정보를 함께 전달하도록 구성했다.

이를 통해 단순 이미지 설명이 아닌
게시글 맥락을 반영한 결과를 얻을 수 있었다.

8. 이미지 유형에 따른 처리 방식 분리

초기 생성 결과를 확인해보니
이미지마다 결과 품질의 편차가 있었다.

원인을 분석해보니
이미지의 성격이 서로 달랐다.

그래서 이미지를 두 가지 유형으로 구분했다.

사진형 이미지는 상황 중심으로 간단하게 설명하고,
정보형 이미지는 이미지 내 텍스트나 내용을
누락 없이 설명하도록 처리했다.

이 기준을 적용한 이후
대체 텍스트의 품질이 전반적으로 안정되었다.

9. 병렬 처리 적용

전체 이미지 수가 많다 보니
순차 처리 방식으로는 작업 시간이 과도하게 소요되었다.

이를 해결하기 위해
Python 스크립트에 병렬 처리 구조를 적용했다.

작업 단위를 나누고
동시에 여러 요청을 처리하도록 구성하여
전체 처리 시간을 단축할 수 있었다.

10. 검수 단계 및 도구 구성

자동 생성 이후 결과를 확인해보니
일부 문구에서 어색하거나 정보가 부족한 경우가 있었다.

이 부분은 자동화로 해결하기 어렵다고 판단했고,
별도의 검수 과정을 구성했다.

다만 3,300개의 이미지를 하나씩 확인하는 방식은 비효율적이었기 때문에
검수 역시 도구 형태로 구성했다.

Cursor를 활용하여
Python 기반의 간단한 검수 도구를 제작했다.

이미지와 생성된 대체 텍스트를 동시에 확인할 수 있도록 구성하고,
이전/다음 이동이 가능하도록 키 바인딩을 추가했다.

이를 통해 마우스 조작 없이 빠르게 이미지를 넘기면서
대체 텍스트를 확인할 수 있도록 했다.

또한 각 이미지에 대해 피드백을 입력할 수 있도록 구성하여
부족한 설명이나 잘못된 내용을 기록하고,
이 피드백을 이후 재생성 과정에서 참고할 수 있도록 했다.

게시판 번호, 이미지 번호, 게시글 정보까지 함께 확인할 수 있도록 구성하여
실제 원문과 비교하면서 검수가 가능하도록 했다.

이 도구를 활용하여
전체 이미지에 대한 검수를 진행했다.

Python으로 구성한 검수 툴. (좌측은 이미지, 우측 상단은 작성된 alt내용, 우측하단은 피드백 입력 구간이다.)

11. 최종 작업 완료 및 비용

총 사용된 예산, 토큰, 요청 수

결과적으로 약 3,300개의 이미지에 대해
대체 텍스트 생성과 검수를 모두 완료했다.

생성은 자동화로 처리했지만,
최종 품질은 직접 확인하는 방식으로 마무리했다.

전체 작업에 소요된 AI 비용은
약 32,000원 수준이었다.

수작업 대비 작업 시간을 크게 줄일 수 있었고,
대량 반복 작업에 대한 효율적인 처리 구조를 구축할 수 있었다.

12. 정리

이번 작업은 단순히 이미지 alt를 작성하는 작업이 아니라
대량 반복 작업을 어떻게 구조화할 것인지에 대한 과정이었다.

웹 기반 처리에서 로컬 데이터 기반 처리로 전환한 것이 핵심이었고,
AI와 스크립트를 결합하여 자동화 구조를 만들었다.

또한 자동 생성 결과를 그대로 사용하는 것이 아니라
검수 단계를 통해 품질을 보완하는 방식으로 진행했다.

이 방식은 향후 유사한 작업에도
적용 가능한 구조로 활용할 수 있을 것으로 판단된다.

[Trouble Shooting] 지도 포함 리포트 이미지 삽입 문제 해결

범데이 — Wed, 18 Feb 2026 01:26:54 +0900

최근에 참여했던 프로젝트에서 출장 여비정산 리포트를 개발 과업 중에

“주행거리 증빙 화면(지도 포함)”을 이미지로 캡쳐해 ClipReport에 삽입해야 하는 과정이 있었다.

요구사항은 단순해 보였다.

지도 화면이 반드시 포함된 상태로 캡쳐되어야 하고
매번 다른 주행 경로를 동적으로 캡쳐해야 하며
최종 결과는 리포트 안에서 이미지로 출력되어야 했다

하지만 실제 구현은 예상보다 훨씬 복잡했다.

이번 이슈는 아래와 같은 환경에서 발생했다.

Report: ClipReport
Frontend: React
Backend: Spring (Java)
Screenshot: Playwright (Headless Chromium)
Map SDK: Kakao Map SDK

그리고 문제는 단순히 “캡쳐가 안 된다” 수준이 아니었다.

이슈는 크게 세 가지 층으로 나뉘었다.

브라우저 렌더링 방식의 한계
서버 OS ↔ Playwright(Chromium) ↔ Java 패키지 호환
지도 SDK 도메인(URL) 매핑 문제

그리고 이 복잡한 문제들을 하나로 관통한 키워드는 로깅(Logging) 이었다.

1. 문제 배경: “지도 포함 주행거리 증빙 캡쳐” 요구사항

처음 목표는 아래처럼 정리할 수 있었다.

특정 URL(증빙 페이지)을 로드한다
페이지가 렌더링 완료되면 스크린샷을 찍는다
생성된 이미지 파일을 ClipReport에서 출력한다

말만 보면 쉬운데, “지도(카카오맵/타일)”이 끼어들면서 난이도가 급상승했다.

2. 1차 시도: 프론트(html2canvas) 캡쳐 — 구조적 한계로 실패

처음에는 React 화면에서 html2canvas 기반으로 캡쳐해서 증빙 이미지를 만들려고 했다.

2.1 시도한 방식

html2canvas(contentRef.current) 로 화면을 캡쳐
캡쳐된 이미지를 다운로드 또는 서버 업로드
리포트에서 해당 이미지 출력

2.2 문제: “보이는 그대로 캡쳐”가 아니다

html2canvas와 같은 라이브러리는
브라우저 화면을 실제로 그대로 캡쳐하는 방식이 아니다.

canvas 위에 현재 렌더링된 HTML / CSS 구조를 분석해서
“비슷하게 보이도록 다시 그리는 방식”이다.

이 구조적인 특성 때문에 다음과 같은 문제가 발생했다.

일부 UI 요소 (특히 input, form 요소)가 틀어짐
스타일이 완벽하게 재현되지 않음
외부 스크립트 기반 요소(지도 SDK 등)가 정상적으로 그려지지 않음
지도 영역 및 타일 이미지가 제대로 표현되지 않음

실제로 여러 캡쳐 라이브러리를 테스트해봤지만
공통적으로 동일한 문제가 발생했다.

결론적으로, “프론트에서 보이는 화면을 그대로 캡쳐한다”는 접근 자체가
기술적으로 완전한 재현을 보장하지 못한다.

특히 지도와 같은 외부 렌더링 요소가 포함되면
정확한 결과를 얻기 어렵다.

결론: “프론트에서 보이는 화면을 캡쳐” 방식은

지도/외부 리소스가 포함되면 구조적으로 실패할 가능성이 높다.

따라서 방향을 변경했다.

3. 방향 전환: 서버에서 페이지를 직접 요청/렌더링해서 캡쳐하자

프론트 캡쳐 방식의 한계를 확인했기 때문에, 서버가 Headless Chromium을 실행해서 캡쳐하도록 구조를 전환했다.

즉,

서버가 Playwright로 브라우저를 띄우고
해당 URL에 접속해 렌더링한 뒤
렌더링 결과를 스크린샷으로 저장한다

이 방식은 “보이는 그대로”를 캡쳐하기에 적합하다.

4. 2차 장애: 서버 OS ↔ Playwright 버전/Chromium 호환 문제

서버에서 Playwright를 올리고 실행하는 순간, 다음과 같은 문제가 발생했다.

Chromium이 정상 구동되지 않거나
OS 지원 경고가 뜨거나
fallback build 다운로드로 인해 불안정하게 동작했다

여기서 포인트는 “코드가 잘못됐다”가 아니라:

서버 OS 환경과 Playwright/Chromium 빌드가 맞지 않으면

브라우저 자체가 실행되지 않는다.

4.1 해결: Playwright 버전 다운그레이드

결국 이 문제는 Playwright 버전을 낮추는 방향으로 해결했다.

최신 버전은 서버 OS(또는 glibc 등)와 호환이 애매했고
낮춘 버전에서는 Chromium이 정상 실행되었다

✅ 결과:

페이지 접속 성공
스크린샷 생성 성공

여기까지 오면 끝일 줄 알았지만, 진짜 문제는 다음 단계였다.

5. 3차 장애: “캡쳐는 되는데 지도 SDK가 안 뜬다”

Chromium이 뜨고 캡쳐도 된다.

그런데 결과 이미지에 지도만 안 나온다.

페이지는 정상
텍스트/레이아웃도 정상
그런데 지도 영역만 비어 있음

이 시점부터는 코드 문제가 아니라 환경/네트워크/보안/SDK 정책 영역으로 넘어간다.

6. 이때부터 결정적으로 중요해진 것: 로깅(Logging)

여기서부터는 감으로 때려맞추면 시간이 10배 걸린다.

내가 했던 핵심은:

6.1 서버 네트워크 레벨 검증

서버에서 curl 로 해당 URL 접근 가능한지 확인
지도 SDK 스크립트 주소 접근 가능한지 확인
외부망 라우팅/DNS/방화벽 이슈 가능성 제거

6.2 Playwright 브라우저 로그 출력

브라우저 단에서만 보이는 에러가 있다.

따라서 로그를 찍었다.

console log
requestfailed
response status
network trace

이걸 통해 결론적으로 파악한 핵심은:

지도 SDK는 “등록된 URL(도메인)”에서만 정상 동작한다.

7. 근본 원인: 지도 SDK는 허용된 URL/도메인이 일치해야 로드된다

내 서버 캡쳐 환경에서는 다음과 같은 차이가 있었다.

원래 SDK 호출 기준 URL이 내부망 기반(172.x.x.x)으로 잡혀 있었고
로컬/외부에서 접근할 때는 외부망 IP로 호출되었다

지도 SDK는 도메인 정책이 강해서:

등록된 URL과 다르면
SDK가 로드되지 않거나 일부 기능이 차단된다

8. 해결: 지도 SDK가 인식하는 URL을 “등록된 주소로 통일” (URL 매핑)

따라서 해결책은 단순했다.

서버에서 지도 SDK를 호출할 때도
SDK에 등록된 URL과 동일한 형태로 인식되도록
내부망 IP → 외부망 IP 기반 호출로 변경
로컬 호출 환경과 동일한 IP/도메인 기준으로 통일

✅ 결과:

서버 Playwright 환경에서도 지도 SDK 정상 로드
지도까지 포함된 증빙 화면 캡쳐 성공

9. 최종 결론: 이번 이슈의 핵심 정리

이번 문제는 “기술”이 여러 층으로 겹쳐져 있었다.

(1) 프론트 캡쳐 방식은 구조적 한계가 존재한다

html2canvas와 같은 방식은 실제 캡쳐가 아니라 재렌더링이기 때문에
지도/외부 렌더링 요소 포함 시 정확한 결과를 보장하기 어렵다

(2) 서버 캡쳐는 OS 호환성이 승패를 가른다

Playwright 최신이 항상 정답이 아니다

서버 OS / glibc / 패키지 호환성이 맞아야 Chromium이 뜬다

(3) 지도 SDK는 “URL 정책” 때문에 예상치 못하게 실패한다

SDK는 허용 도메인 기반으로 동작한다
서버에서 띄우면 host/origin이 달라져서 SDK가 막힐 수 있다
해결은 “등록된 URL로 통일(매핑)”이다

(4) 결정타는 로깅이었다

curl로 네트워크 확인
Playwright에서 console/network 로깅
이게 없었으면 “지도 안 뜨는 이유”는 끝까지 감으로만 맞췄을 것이다

Viewport(뷰포트) 란?

범데이 — Wed, 18 Feb 2026 01:06:37 +0900

웹페이지 반응형 작업을 하면서 이런 일이 있었다.

미디어쿼리(@media)를 분명히 작성했는데
모바일에서 전혀 적용되지 않았다.

개발자도구(Device Toolbar)에서는 정상처럼 보이는데
실제 모바일에서는 레이아웃이 줄어들지 않았다.

원인을 확인해보니 <meta name="viewport"> 설정이 빠져 있었다.

<meta name="viewport" content="width=device-width, initial-scale=1">

이 한 줄을 추가하자 그동안 먹지 않던 미디어쿼리가 바로 정상 동작했다.

그래서 왜 viewport를 넣어야 반응형이 제대로 작동하는 건지

그 내용을 정리해보려고 한다.

Viewport 무엇인가?

Viewport는 사용자가 현재 보고 있는 웹 페이지의 보이는 영역이다.
즉, 브라우저가 레이아웃을 계산할 때 기준으로 삼는 화면 영역이다.

문제는 모바일 브라우저의 기본 동작 방식이다.

viewport 설정이 없으면
모바일 브라우저는 과거 PC 웹을 그대로 보여주기 위해
넓은 화면 기준으로 페이지를 먼저 렌더링한 뒤
이를 모바일 화면 크기에 맞게 축소해 보여준다.

이 상태에서는 CSS가 실제 기기 너비 기준이 아니라, 브라우저가 설정한 넓은 기준값을 토대로 계산된다.

그래서 내가 작성한

@media (max-width: 768px)

같은 코드가 모바일에서 조건을 만족하지 못하게 된다.

결과적으로,

미디어쿼리가 적용되지 않고
레이아웃이 줄어들지 않으며
반응형이 깨진 것처럼 보이는 현상이 발생한다.

Viewport는 반응형 웹의 출발점

반응형 웹이 제대로 작동하려면
미디어쿼리(media query)나 CSS 작성보다 먼저
Viewport 설정이 선행되어야 한다.

Viewport를 지정하면 브라우저는
“이 페이지를 기기 화면 크기를 기준으로 렌더링하라”는 신호를 받는다.

그제서야 미디어쿼리는
실제 디바이스 너비를 기준으로 조건을 판단하게 된다.

즉, Viewport가 없으면 반응형 조건이 어긋나고 Viewport를 선언해야 비로소 반응형이 시작된다.

기본 Viewport 설정

<meta name="viewport" content="width=device-width, initial-scale=1">

- width=device-width: 뷰포트 너비를 기기 화면 너비와 동일하게 설정

- initial-scale=1: 페이지 처음 로딩 시 확대/축소 비율을 1:1로 설정

이 설정은 거의 모든 반응형 웹에서 기본값처럼 사용된다.

viewport 사용 참고: 한국식품안전관리인증원 대표누리집

추가 Viewport Meta 속성들

아래와 같은 추가 속성들도 활용 가능하다.

- user-scalable: 사용자가 확대/축소 허용 여부 지정(yes/no)

- minimum-scale: 최소 확대 비율

- maximum-scale: 최대 확대 비율

예: <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">

단, user-scalable=no 는 접근성 측면에서 사용자의 화면 확대를 막기 때문에 주의가 필요하다.

정리

미디어쿼리가 먹지 않는다면 Viewport부터 확인
모바일 브라우저는 기본적으로 넓은 화면 기준으로 렌더링
Viewport 선언이 있어야 실제 기기 너비 기준으로 계산
반응형의 출발점은 CSS가 아니라 Viewport 설정

웹 UI 기본 내비게이션 용어 완전 정리: GNB, LNB, SNB, FNB

범데이 — Wed, 18 Feb 2026 00:46:04 +0900

웹 개발하거나 사이트 구조를 공부하다 보면 내비게이션 메뉴 용어(GNB, LNB, SNB, FNB)를 마주하게 된다.

초보자는 물론, 프론트엔드/풀스택 개발자에게도 놓치기 쉬운 UI 기본 개념이다.

이번 글에서는 이 내비게이션 개념들을 한눈에 파악할 수 있게 정리해보고자 한다.

보다 설명을 쉽게 하기 위해, 공공기관 사이트인 한국식품안전관리인증원(https://www.haccp.or.kr/main.do) 웹사이트를 실제 예시로 사용한다.

이 사이트는 식품 안전관리 인증 관련 정보를 제공하는 공공기관 홈페이지로, 다양한 내비게이션 구조가 잘 드러나는 대표적인 사례이다.

웹 내비게이션 바란?

웹사이트에서 사용자가 목적한 콘텐츠로 쉽게 이동하도록 돕는 UI 메뉴이다.

사용자는 이 메뉴를 통해 서비스 기능/페이지를 탐색하고 웹서비스를 빠르게 이해한다.

웹 UI에서 내비게이션은 위치에 따라 구분 명칭이 다르며, 각각의 역할이 있다.

1. GNB (Global Navigation Bar)

- 사이트의 최상단 공통 메뉴

- 페이지 어디에서든 항상 보이는 메인 내비게이션

대부분의 웹사이트에서 상단에 항상 보이는 메뉴이다.

전체 서비스 흐름을 보여주는 역할을 하며,

아래와 같이 "정보공개, 경용공시, 국민소통" 과 같은 전체 메뉴 리스트가 여기에 해당된다.

→ GNB는 Global이라는 이름처럼 웹 전체를 아우르는 핵심 내비게이션이다.

2. LNB (Local Navigation Bar)

- 특정 페이지나 섹션에서 세부 메뉴 역할

- 보통 GNB에서 메뉴를 클릭/호버하면 나타나는 서브 메뉴

LNB는 GNB와 달리 특정 페이지/영역에만 적용된다.

사용자가 GNB에서 메뉴를 선택했을 때, 그 아래 보여지는 세부 카테고리라고 보면 된다.

아래와 같이, "정보공개" 클릭 → 또 다른 관련 메뉴(정보공개제도/공공데이터/공무국외출장 등) 가 LNB로 나타나는 구조이다.

3. SNB (Side Navigation Bar)

- 측면 서브 메뉴

- 특정 페이지 내에서 추가적인 메뉴 제공

흔히 왼쪽 또는 오른쪽에 추가로 붙는 메뉴이다.

대부분 서비스의 콘텐츠 카테고리/필터 영역으로 활용되며,

페이지 내부 상세 탐색을 돕는 구조이기도 하다.

아래와 같이 "정보공개 > 정보공개제도 > 제도안내" 같은 계층 메뉴가 이에 속한다.

4. FNB (Foot Navigation Bar)

- 웹사이트 가장 아래 푸터 영역 메뉴

- 홈페이지 전체에서 공통으로 표시되는 정보

푸터(Footer) 영역의 내비게이션이 바로 FNB이다.

아래처럼 기관 주소, 연락처, 개인정보 처리방침 등 부가 정보와 관련된 링크들이 여기 들어간다.

마무리

웹 구조를 이해하려면 내비게이션 구조를 먼저 파악하는 것이 중요하다.

UI/UX 설계, 웹페이지 구조 분석, 프론트엔드 개발까지 모두 이 개념을 기반으로 진행된다.

- GNB부터 FNB까지 영역별 용어를 정확히 알고 있으면

→ 서비스 설계/협업 커뮤니케이션에서 훨씬 빠르게 이해할 수 있다.

Unity Android 빌드 실패: Google Mobile Ads 업데이트 후 IL2CPP Internal CLR Error 해결기

범데이 — Wed, 7 Jan 2026 23:05:14 +0900

주기적으로 개발자들을 괴롭히는 SDK 업데이트 권고사항..

사용 중인 Google Mobile Ads(GMA) SDK 버전이 sunset에 접어들면서 SDK를 버전업했을 뿐인데,

Unity Android 빌드에서 IL2CPP Internal CLR error (0x80131506) 가 발생하며 빌드가 완전히 막혔다.

결론적으로 문제의 정체는 GMA 자체가 아니라,

의존성 변경 이후 Unity/EDM/Bee 캐시가 꼬인 상태에서 증분 빌드* 가 재사용된 것이다.

*증분 빌드: 이전 빌드 결과를 재사용해서, 변경된 부분만 다시 빌드하는 방식

캐시 초기화 + unitypackage 재임포트 + Force Resolve로 해결하였다.

1. 문제 발생 배경

Unity 2021.3 LTS 프로젝트
Android 빌드 대상
기존에 정상 동작하던 프로젝트
변경 사항은 단 하나 → Google Mobile Ads SDK 버전 업데이트

2. 발생한 증상

Android + IL2CPP 빌드 실패

빌드 도중 아래와 같은 에러가 반복적으로 발생했다.

Incremental Player build failed
Failed to create CoreCLR, HRESULT: 0x8007000E
Fatal error. Internal CLR error. (0x80131506)
실패 지점:
- GoogleMobileAds.Ump.Android-FeaturesChecked.txt
- UnityEngine.*Module-FeaturesChecked.txt
- il2cpp.exe 실행 단계

특징적인 포인트

Mono로는 Android 빌드 성공
IL2CPP에서만 실패
캐시 삭제, 재빌드, 재부팅을 반복해도 동일 증상

→ 이 시점에서 Gradle/Android 설정 문제는 아님이 명확해졌다.

3. 해결 방법 (실제로 효과 있었던 절차)

1) 프로젝트 캐시 완전 삭제

Unity 종료 후, 프로젝트 루트에서 아래 폴더들을 모두 삭제

Library/
Temp/
obj/
Logs/   (선택)

Library는 Unity 캐시이므로 삭제해도 안전하며, 재실행 시 자동 재생성된다.

2) Google Mobile Ads / EDM 관련 폴더 제거

Assets/ 하위에서 다음 폴더들을 삭제:

Assets/GoogleMobileAds/
Assets/ExternalDependencyManager/
Assets/Plugins/Android/   (GMA 관련 aar/jar가 있다면)

핵심은 이전 의존성 산출물을 완전히 제거하는 것이다.

3) Unity 재실행 → GMA 재임포트

Unity 재실행 시 위와같은 팝업이 나오면 'Ignore' 로 진입했다.

Assets → Import Package → Custom Package
최신 GoogleMobileAds-x.x.x.unitypackage 전체 선택 후 Import

4) External Dependency Manager 강제 리졸브

Unity 메뉴에서:

Assets
 → External Dependency Manager
   → Android Resolver
     → Force Resolve

5) Android 빌드 재시도

Scripting Backend: IL2CPP
ARM64 only

→ 빌드 성공

4. 근본 원인은 무엇인지?

1) GMA 버전업 → Android 의존성 그래프 변경

GMA 업데이트 시 함께 바뀌는 것들:

play-services-ads
user-messaging-platform (UMP)
AndroidX / transitive dependency 구조

즉, Gradle 기준 의존성 트리가 달라진다.

2) EDM 리졸브 결과와 Unity 캐시(Bee/Library)가 불일치

Unity는 다음을 강하게 캐싱한다.

Bee Incremental Build 산출물
Library 내부 Feature 체크 파일
이전 Android Resolver 결과

이 상태에서 의존성만 바뀌면:

일부는 옛 의존성
일부는 새 의존성

이라는 정합성 붕괴 상태가 된다.

3) IL2CPP 단계에서 폭발

IL2CPP는:

방대한 C++ 코드 생성
메타데이터/어셈블리 조합에 매우 민감

입력이 꼬인 상태에서 실행되면,

CoreCLR 생성 실패
Internal CLR Error
Incremental Build 실패

처럼 원인과 전혀 달라 보이는 에러로 터진다.

즉, IL2CPP는 범인이 아니라 피해자였다.

5. 해결된 이유

"캐시 삭제 + 재임포트 + Force Resolve" 과정이 한 일을 정리하면:

잘못 재사용되던 Bee/Library 캐시 제거
이전 unitypackage들의 산출물 제거
현재 상태 기준으로 의존성 그래프를 처음부터 재계산
Unity–EDM–Gradle 간 정합성 복구

결과적으로 빌드 파이프라인이 정상 경로로 복구되었다.

6. 교훈

이번 경험을 통해 다시 한 번 느낀 점은, 의존성은 결코 가볍게 볼 수 있는 요소가 아니라는 것이다. Java의 Maven, C#의 NuGet, Node.js의 package.json처럼, Unity 역시 다양한 패키지와 라이브러리들이 서로 유기적으로 연결된 상태에서 하나의 프로젝트를 구성하고 있다. Unity 프로젝트라고 해서 이 복잡성에서 예외는 아니었다.

Google Mobile Ads처럼 외부 SDK 하나를 업데이트하는 작업은 단순한 버전 변경이 아니라, 그 패키지가 의존하고 있는 다른 라이브러리들과 빌드 파이프라인 전반에 영향을 주는 변화가 된다. 겉으로는 작은 수정처럼 보여도, 내부적으로는 의존성 그래프가 달라지면서 예상치 못한 문제가 발생할 수 있다.

그래서 패키지 업데이트는 항상 신중해야 하며, 업데이트 이후에는 의존성이 정상적으로 리졸브되고 전체 빌드 흐름이 안정적으로 동작하는지 반드시 확인해야 한다. 이번 이슈는 단순한 에러 해결을 넘어, 의존성을 관리하는 태도와 검증 과정의 중요성을 다시 한 번 상기시켜 준 사례였다.

CSS 우선순위 - 실무에서 바로 쓰는 적용 팁

범데이 — Sat, 22 Nov 2025 11:06:59 +0900

CSS 우선순위를 이해했다고 해서 실전에서 모든 충돌을 해결할 수 있는 건 아니다.

특히 수십~수백 개의 CSS 파일이 섞여 있는 레거시 프로젝트에서는 "어디서 온 스타일인지 찾는 것" 자체가 가장 큰 문제다.

이 포스팅에서는 복잡한 실무 환경에서 CSS 우선순위 문제를 관리하고 해결하는 실제 전략만 모아 정리했다.

(혹시 CSS 우선순위에 대한 기본 개념이 부족하다면, 이 포스팅을 먼저 보는 것을 추천한다.)

1. 어디서 적용되는 스타일인지 빠르게 찾는 방법

실무에서 가장 중요한 건 출처 추적이다.

1) Chrome DevTools "Computed" 패널 활용

요소를 검사하고 "Computed" 탭을 보면:

현재 적용된 스타일
어떤 파일 / 몇 번째 줄에서 왔는지
우선순위 승패 여부

까지 모두 확인 가능하다.

2) DevTools 우측 "Styles" 패널에서 충돌 비교

지워진(취소선) 스타일은 같은 속성이 다른 규칙에 의해 덮어씌워졌다는 뜻이다.

어떤 규칙이 이겼는지 즉시 파악 가능
해당 파일을 직접 찾아 빠르게 조정 가능

3) Find in all files 와 브라우저 검사 병행

특히 class명이 공통적(.btn, .card, .title)일 때 어디에 정의되었는지 파악하기 어려운 경우:

1. 크롬에서 실제 적용된 파일명/라인 확인

2. IDE에서 해당 파일명을 검색하여 수정

→ 이 과정을 자동화하면 "스타일의 출처" 를 정확히 알 수 있게 된다.

2. 단기 해결책 - override.css + 최소한의 !important

완전히 통제하기 어려운 대규모 사이트에서는 별도의 override 파일을 만들어 가장 마지막에 로드하는 것이 효과적이다.

<link rel="stylesheet" href="style.css">
<link rel="stylesheet" href="override.css"> <!-- 무조건 마지막 -->

이 방식의 특징:

빠르고 안정적
기존 구조를 건드리지 않음
페이지별 스타일도 손쉽게 대응 가능

다만 반드시 기억해야 할 점:

!important는 "정말 필요한 경우에만" 사용
override 파일이 비대해지면 또 다른 레거시가 된다.

3. 중기 해결책 - "명시도 조절(override)" 로 자연스럽게 해결

가능하다면 !important 대신 명시도를 올려서 재정의하는 방식이 훨씬 좋다.

예제:

/* 기존 */
.btn { padding: 4px; }

/* override */
.container .btn { padding: 8px; }

이 방식의 장점:

CSS 기본 규칙에 충실
유지보수성이 훨씬 높음
나중에 다른 사람이 봐도 이해하기 쉬움

4. Scoped CSS - 영향 범위를 좁혀 충돌 예방

특정 페이지나 특정 컴포넌트만 스타일을 바꿔야 한다면,

스타일의 "범위(scope)" 를 좁히는 것이 가장 안전하다.

예:

/* 결제 페이지에만 적용 */
#payment-page .btn-primary {
  background-color: #333;
}

전체 사이트에 영향을 주지 않음
의도 명확 → 협업 시 혼동 없음
우선순위 충돌 확률 ↓

5. CSS 파일 로드 순서 정리 - 가장 치명적 실수 방지

스타일 충돌의 대부분은 파일 로드 순서 때문이다.

아무리 명시도를 올려도 앞에서 이미 강한 스타일이 로드되었다면 무용지물이 될 수 있다.

실무에서는 다음과 같은 구조를 강력 추천한다.

<link rel="stylesheet" href="base.css">       <!-- reset, 공통 -->
<link rel="stylesheet" href="layout.css">     <!-- 레이아웃 -->
<link rel="stylesheet" href="component.css">  <!-- 컴포넌트 -->
<link rel="stylesheet" href="page.css">       <!-- 페이지별 -->
<link rel="stylesheet" href="override.css">   <!-- 덮어쓰기 전용 -->

override.css를 항상 마지막
구조가 명확해지고 충돌이 줄어듦

6. 장기 해결책 - CSS 구조 리팩토링(BEM 등)

레거시에서 벗어나고 싶다면 CSS 클래스 체계를 새로 잡는 것이 최선이다.

예: BEM

.header__menu__item--active { ... }

장점:

선택자 우선순위 계산이 매우 쉬움
중복 및 충돌 자체가 줄어듦
팀 개발에 최적화

CSS는 결국 구조화된 네이밍 규칙이 유지보수성을 좌우한다.

7. 실무 적용 요약

  단기
  - override.css + 최소한의 !important

  중기
  - 명시도 올려 자연스러운 override
  - 페이지 단위 Scoped CSS
  - 파일 로드 순서 재정리

  장기
  - CSS 네이밍 구조 바로잡기(BEM)
  - 중복 제거 및 사용되지 않는 스타일 정리
  - 컴포넌트 기반 CSS로 재편

마무리

CSS 우선순위 문제는 단순한 기술적 이슈가 아니라

구조, 습관, 파일 관리 전략 의 조합으로 해결되는 문제다.

레거시 프로젝트든 신규 프로젝트든

우선순위를 정확히 이해하고 적용하면 스타일 충돌은 크게 줄어들고,

유지보수 속도와 코드 품질은 비약적으로 향상된다.

앞으로 유지보수나 신규 스타일 작업을 할 때

"우선순위 → 범위조절 → 구조화"

이 세 가지를 항상 염두에 두고 작성하면 된다.

CSS 우선순위 완전 정리 (Specificity & Cascade)

범데이 — Sat, 22 Nov 2025 10:41:51 +0900

HTML에서 어떤 스타일이 최종적으로 적용되는지 헷갈린다면,

이 포스팅 하나로 모두 정리할 수 있다.

1. CSS 우선순위란?

HTML 요소에 여러 CSS 규칙이 동시에 적용될 경우, 브라우저는 특정 규칙을 선택해 적용한다.

이때 어떤 규칙을 우선할지 결정하는 기준이 바로 우선순위(Specificity & Cascade) 이다.

CSS 우선순위는 다음 4가지 요소로 결정된다.

중요도(!important)
명시도 (Specificity)
소스(origin)와 선언 위치
선언된 순서 (Order)

각 요소별로 자세히 정리해보자.

2. 우선순위 1순위: !important

동일 속성끼리 충돌할 때, !important는 모든 요소보다 우선한다.

.box {
  color: red !important;
}

단, !important끼리 충돌하면 명시도 → 선언 순서 기준으로 적용된다.

3. 명시도(Specificity) 계산법

CSS는 선택자마다 점수를 부여한다.

선택자 유형	예시	점수
Inline style	<div style="">	1000
ID 선택자	#title	100
Class / 속성 / pseudo-class	.box, [type=text], :hover	10
태그 선택자	div, span	1
전체 선택자	*	0

예시:

#header .menu li a:hover

#header → 100
.menu →10
li → 1
a → 1
:hover → 10

총합 = 122

4. 선언된 위치에 따른 우선순위 (Origin)

CSS는 HTML 내에서 어디서 선언되었는지에 따라 적용 우선순위가 달라진다.

기본 우선순위(위 → 아래 = 약함 →강함)

브라우저 기본 스타일 (User-Agent)
외부 CSS 파일 ( <link rel="stylesheet"> )
HTML 내부 <style> 태그
inline style (style="")
!important 선언된 규칙

5. HTML 내 위치에 따른 적용 예시

같은 명시도/중요도를 가진 CSS라면 나중에 선언된 스타일이 우선한다.

예제 HTML:

<head>
  <link rel="stylesheet" href="style1.css"> <!-- 먼저 로드됨 -->
  <link rel="stylesheet" href="style2.css"> <!-- 나중 로드됨 → 우선 -->
</head>

<body>
  <link rel="stylesheet" href="late.css"> 
  <!-- body 안에 있어도, head 보다 "나중"이므로 late.css 가 최우선 -->
</body>

정리하면:

style1.css  <  style2.css  <  late.css

즉, HTML 구조가 어디 있든지 뒤에서 불러온 CSS가 우선한다.

6. <style> 태그도 동일 규칙 적용

<head>
  <style>
    .box { color: red; }
  </style>
</head>

<body>
  <style>
    .box { color: blue; } /* 이게 적용됨 (나중 선언) */
  </style>
</body>

7. 전체 우선순위 요약표

1. !important
2. inline style=""
3. ID 선택자
4. class / pseudo-class / attribute 선택자
5. tag 선택자
6. 전체 선택자 (*)
7. 브라우저 기본 스타일
+ 같은 레벨이면 “나중에 선언된 것” 승리

마무리

CSS 우선순위는 단순히 암기해두는 개념처럼 보이지만, 실제로는 브라우저가 스타일을 결정하는 전체 흐름(Cascade)을 이해하는 것이 핵심이다.

어디서 선언되었는지, 어떤 선택자를 사용했는지, 그리고 어떤 순서로 로드되었는지에 따라 결과가 달라지기 때문에, 이를 정확히 알고 있으면 예상치 못한 스타일 충돌이나 적용 불가 문제를 훨씬 빠르게 해결할 수 있다.

특히 여러 CSS 파일이 혼합된 프로젝트나 레거시 구조에서는 이 우선순위 규칙을 이해하는 것만으로도 유지보수 효율이 크게 향상된다.

앞으로 CSS를 작성하거나 수정할 때,

"중요도 → 명시도 → 선언 위치 → 선언 순서" 라는 기본 원칙을 항상 염두에 두면, 보다 명확하고 예측 가능한 스타일 구조를 유지할 수 있을 것이다.

실무에서 우선순위 충돌을 해결하는 구체적 전략은 다음 포스팅으로 자세히 정리하였다.

[Spring] Filter와 Interceptor의 차이 정리

범데이 — Fri, 31 Oct 2025 08:30:46 +0900

1. 개요

Spring MVC기반 웹 애플리케이션에서는 요청(Request)와 응답(Response)이 Controller에 도달하기 전 후로

다양한 처리가 필요한 경우가 많다.

(예: 로그인 세션 확인, 인코딩 설정, 접근 권한 체크, 로깅 등)

이때 사용할 수 있는 대표적인 두 가지 기술이 바로 Filter와 Interceptor이다.

2. Filter (javax.servlet.Filter)

개념

Servlet 표준 스펙에서 제공하는 기능이다.
DispatcherServlet 이전 단계에서 모든 요청을 가로채서 전처리/후처리 가능.
Spring MVC에 종속되지 않고, 톰캣/JEUS 등 Servlet 컨테이너 레벨에서 동작한다.

적용 시점

Client → Filter → DispatcherServlet → Controller → View

즉, Controller 진입 전에 실행된다.

주요 용도

인코딩 처리(CharactorEncodingFilter)
인증/권한 체크 (세션/토큰 확인)
XSS, CORS, 로깅 등 전역적인 요청 처리

설정 예시 (web.xml)

<filter>
    <filter-name>encodingFilter</filter-name>
    <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>encodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

코드 예시

public class AuthCheckFilter implements Filter {

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {

        HttpServletRequest request = (HttpServletRequest) req;
        HttpSession session = request.getSession(false);

        if (session == null || session.getAttribute("USER") == null) {
            ((HttpServletResponse) res).sendRedirect("/login.do");
            return;
        }

        chain.doFilter(req, res); // 다음 Filter 또는 DispatcherServlet으로 이동
    }
}

3. Interceptor (org.springframework.web.servlet.HandlerInterceptor)

개념

Spring MVC 전용 요청 가로채기 기능
DispatcherServlet 이후 단계에서 동작
Spring Context 내에서 동작함으로, 빈 주입(@Autowired)이 가능하다.

적용 시점

Client → Filter → DispatcherServlet → Interceptor → Controller
                                    ↑         ↓
                            (preHandle)  (postHandle / afterCompletion)

주요 용도

Controller 호출 전 사용자 인증 / 권한 검사
Controller 실행 후 Model 데이터 가공
View 렌더링 후 로깅, 성능 측정

설정 예시 (spring-mvc.xml)

<mvc:interceptors>
    <mvc:interceptor>
        <mvc:mapping path="/**"/>
        <bean class="egovframework.example.common.interceptor.AuthInterceptor"/>
    </mvc:interceptor>
</mvc:interceptors>

코드 예시

public class AuthInterceptor extends HandlerInterceptorAdapter {

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {

        HttpSession session = request.getSession(false);
        if (session == null || session.getAttribute("USER") == null) {
            response.sendRedirect("/login.do");
            return false; // Controller 진입 차단
        }
        return true;
    }

    @Override
    public void postHandle(HttpServletRequest request,
                           HttpServletResponse response,
                           Object handler,
                           ModelAndView modelAndView) throws Exception {
        // Controller 실행 후 로직
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler,
                                Exception ex) throws Exception {
        // View 렌더링 후 로직
    }
}

4. 주요 차이점 비교

구분	Filter	Interceptor
소속	Servlet (javax.servlet)	Spring MVC
적용 위치	DispatcherServlet 이전	DispatcherServlet 이후
주요 용도	인코딩, 로깅, 보안, CORS 등 전역 처리	로그인 세션, 권한, 로직 공통화
설정 위치	web.xml	spring-mvc.xml
DI 지원 여부	X (Spring Bean 주입 불가)	O (@Autowired 가능)
실행 메서드	doFilter()	preHandle(), postHandle(), afterCompletion()
적용 범위	애플리케이션 전체 (모든 요청)	Spring MVC 컨트롤러 영역 한정

5. 함께 사용하는 구조

대부분의 프로젝트에서는 Filter → Interceptor 병행 사용이 일반적이다.

계층	역할	예시
Filter	모든 요청에 대한 전처리 (인코딩, CORS, XSS 등)	CharacterEncodingFilter, LoggingFilter
Interceptor	Controller 진입 전후 처리 (로그인, 권한, 세션 관리 등)	AuthInterceptor, MenuAccessInterceptor

예시 흐름도:

Client
 ↓
Filter (인코딩, 로깅)
 ↓
DispatcherServlet
 ↓
Interceptor (세션 검사, 공통 데이터 주입)
 ↓
Controller
 ↓
Service / DAO
 ↓
View(JSP)

6. 정리

Filter는 Servlet 레벨의 요청 흐름 제어기
Interceptor는 Spring MVC 레벨의 컨트롤러 전후 후킹 포인트

따라서,

전역 정책이나 보안/인코딩 은 Filter로,

비즈니스 로직 관련 공통 처리는 Interceptor로 관리하는 것이 이상적이다.

[Spring] Spring Framework vs Spring Boot 비교 정리

범데이 — Wed, 29 Oct 2025 08:35:42 +0900

1. 개념과 철학의 차이

Spring Framework는 개발자가 직접 조립하는 구조이다.

각 설정파일을 직접 관리하고, 필요한 라이브러리 버전도 일일히 맞춰야 했다.

반면 Spring Boot는 "실행 중심 프레임워크" 이다.

내장 서버와 자동 설정을 통해 실행만 하면 바로 서비스가 구동된다.

구분	Spring Framework	Spring Boot
핵심 철학	개발자가 설정하고 조립	설정 자동화 + 실행 중심
실행 구조	외부 WAS 기반	내장 WAS 포함 (Tomcat 등)
진입점	web.xml → DispatcherServlet	main() → SpringApplication.run()

2. 설정 구조의 진화

Spring 시절에는 web.xml, root-context.xml, servlet-context.xml 등 다수의 XML을 관리해야 했다.

Boot에서는 단 하나의 application.yml (혹은 .properties)로 모든 설정을 통합 관리한다.

Bean 등록: XML의 <bean> 태그 대신 @Configuration, @SpringBootApplication
DB/MyBatis: DataSource, Mapper를 직접 등록하던 시절 → Starter 의존성 하나로 자동 연결
환경 분리: application-dev.yml, application-prod.yml로 명확하게 구분

3. 실행과 배포 방식

Boot의 가장 큰 변화는 내장 WAS 구조이다.
기존엔 .war 파일을 만들어 Tomcat이나 JEUS에 배포했지만,
Boot에서는 .jar 하나로 독립 실행이 가능하다.

항목	Spring Framework	Spring Boot
빌드 산출물	.war	.jar
배포 형태	외부 WAS 필요	내장 Tomcat으로 단독 실행
실행 명령	WAS 기동 후 WAR 로드	java -jar 또는 IDE 실행
설정 위치	server.xml, context.xml 등	application.yml에서 통합 설정

4. 개발 생산성과 운영 효율

Boot는 설정보다 즉시 실행과 생산성에 초점을 맞췄다.
자동 구성, 통합 로깅, /actuator 모니터링 같은 기본 기능이 내장되어 있어 운영환경에서도 바로 쓸 수 있다.

항목	Spring Framework	Spring Boot
초기 설정량	많음 (XML 다수)	적음 (자동 설정)
테스트	복잡한 컨텍스트 로딩	@SpringBootTest로 간단
로깅	log4j 직접 구성	logback 기본 내장
모니터링	직접 구현	/actuator 자동 제공
배포	WAR 중심	JAR 중심 (CI/CD 용이)

5. 디렉터리 구조 예시

Spring Framework (기존형)

/src/main/webapp/WEB-INF/web.xml
/src/main/resources/spring/root-context.xml
/src/main/resources/spring/servlet-context.xml
/src/main/java/.../controller/*.java
/src/main/java/.../service/*.java
/src/main/java/.../dao/*.java

DispatcherServlet, Context 수동 등록 필요
외부 WAS(Tomcat, JEUS 등)에 WAR로 배포

Spring Boot (신형)

/src/main/java/com/example/Application.java
/src/main/resources/application.yml
/src/main/java/.../controller/*.java
/src/main/java/.../service/*.java
/src/main/java/.../mapper/*.java

@SpringBootApplication으로 자동 스캔
내장 Tomcat 포함, 별도 WAS 배포 불필요

6. 정리 및 마무리

Spring Framework와 Spring Boot는 같은 뿌리에서 발전했지만, 추구하는 방향은 다르다.
Spring Framework는 세밀한 제어와 기업형 인프라 호환성에 강점을 가지며, 대규모 레거시 시스템에 적합하다.
반면 Spring Boot는 빠른 개발과 자동 설정, 단독 실행 환경에 초점을 맞추어 클라우드나 마이크로서비스, PoC 개발에 유리하다.

Spring Framework는 설정 중심의 조립형 프레임워크로서 구조를 세밀히 다루려는 개발자에게 적합하고,
Spring Boot는 실행 중심의 통합형 프레임워크로서 빠른 실행과 배포를 중시하는 실무형 개발에 최적화되어 있다.

[Spring] 자주 사용하는 어노테이션 정리 및 예시

범데이 — Tue, 28 Oct 2025 08:13:21 +0900

Spring Framework는 객체를 관리하고 계층 간 의존성을 자동 주입하기 위해 다양한 어노테이션을 제공한다.

이 중 실제 개발 현장에서 자주 사용되는 핵심 어노테이션들을 중심으로 설명한다.

1. @Component, @Service, @Repository, @Controller

이 네 가지는 Spring Bean 등록용 어노테이션이다.

즉, Spring이 해당 클래스를 컨테이너에서 관리하도록 등록하는 역할을 한다.

내부적으로는 모두 @Component를 기반으로 하며, 역할에 따라 의미만 다르다.

(1) @Component

가장 기본적인 Bean 등록용 어노테이션이다.

Helper, Util, Validator 등 특정 계층에 속하지 않는 일반 클래스를 Bean으로 등록할 때 사용한다.

import org.springframework.stereotype.Component;

@Component
public class FileNameHelper {

    public String makeFileName(String original) {
        return System.currentTimeMillis() + "_" + original;
    }
}

이후 다른 클래스에서 자동 주입하여 사용할 수 있다.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class FileService {

    private final FileNameHelper fileNameHelper;

    @Autowired
    public FileService(FileNameHelper fileNameHelper) {
        this.fileNameHelper = fileNameHelper;
    }

    public void saveFile(String fileName) {
        String newName = fileNameHelper.makeFileName(fileName);
        System.out.println("저장 파일명: " + newName);
    }
}

(2) @Service

비즈니스 로직을 담당하는 계층에 사용한다.

트랜잭션이 걸리거나 여러 DAO를 조합하는 등의 처리를 담당한다.

코드상 기능은 @Component와 동일하지만, 역할을 명확히 구분하기 위해 사용한다.

import org.springframework.stereotype.Service;

@Service
public class MemberService {

    public String getMemberGrade(int point) {
        if (point > 1000) return "VIP";
        if (point > 500) return "GOLD";
        return "SILVER";
    }
}

(3) @Repository

데이터베이스와 직접 통신하는 DAO 계층에 사용한다.

@Repository는 예외 변환 기능이 내장되어 있어, JDBC나 MyBatis, JPA에서 발생한 예외를

Spring 공통 예외(DataAccessException)로 변환해준다.

import org.springframework.stereotype.Repository;
import java.util.HashMap;
import java.util.Map;

@Repository
public class MemberRepository {

    private static final Map<Integer, String> MEMBER_DB = new HashMap<>();

    static {
        MEMBER_DB.put(1, "홍길동");
        MEMBER_DB.put(2, "이몽룡");
    }

    public String findMemberName(int id) {
        return MEMBER_DB.get(id);
    }
}

(4) @Controller / @RestController

Controller 계층은 클라이언트의 요청을 받아 처리하는 역할을 한다.

@Controller는 View(JSP, Thymeleaf 등) 를 반환하고,

@RestController는 JSON 데이터를 직접 반환한다.

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class MemberViewController {

    @GetMapping("/member/view")
    public String showMember(Model model) {
        model.addAttribute("name", "홍길동");
        return "memberView"; // memberView.jsp
    }
}

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;

@RestController
public class MemberApiController {

    @GetMapping("/api/member")
    public Member getMember() {
        return new Member("홍길동", "VIP");
    }
}

public class Member {
    private String name;
    private String grade;

    public Member(String name, String grade) {
        this.name = name;
        this.grade = grade;
    }

    // getter, setter 생략
}

2. @Autowired와 의존성 주입(Dependency Injection)

@Autowired는 Bean을 자동 주입해주는 어노테이션이다.

즉, @Component, @Service, @Repository, @Controller로 등록된 Bean을

필요한 곳에 가져다 쓸 수 있게 해준다.

필드 주입 (비권장)

@Autowired
private MemberService memberService;

간단하지만 테스트나 유지보수 시 불편하므로 권장되지 않는다.

생성자 주입 (권장)

@Service
public class OrderService {

    private final MemberService memberService;

    @Autowired
    public OrderService(MemberService memberService) {
        this.memberService = memberService;
    }
}

Spring 4.3 이상부터는 생성자가 하나뿐이면 @Autowired를 생략할 수 있다.

Lombok과 함께 사용 (@RequiredArgsConstructor)

import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class OrderService {

    private final MemberService memberService;

    public void process() {
        System.out.println(memberService.getMemberGrade(700));
    }
}

3. @Value (프로퍼티 값 주입)

Spring의 설정 파일(application.properties 또는 .yml)에 정의된 값을 클래스에 주입할 수 있다.

# application.properties
app.title=FOO PORTAL

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class AppInfo {

    @Value("${app.title}")
    private String title;

    public void printTitle() {
        System.out.println("애플리케이션 이름: " + title);
    }
}

4. @RequestMapping 계열 (요청 매핑)

Spring MVC에서 요청 URL을 메서드에 연결할 때 사용한다.

HTTP Method별로 축약형 어노테이션이 존재한다.

예시 1. @RequestMapping

@Controller
@RequestMapping("/member")
public class MemberController {

    @RequestMapping("/list")
    public String listMembers() {
        return "memberList";
    }
}

예시 2. HTTP 메서드별 축약형

@RestController
@RequestMapping("/api/member")
public class MemberRestController {

    @GetMapping("/{id}")
    public String getMember(@PathVariable int id) {
        return "회원번호: " + id;
    }

    @PostMapping
    public String addMember(@RequestParam String name) {
        return "등록된 회원: " + name;
    }
}

5. @Transactional

DB 변경이 포함된 비즈니스 로직에 트랜잭션을 적용한다.

메서드 내 예외 발생 시 자동으로 롤백이 수행된다.

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class PaymentService {

    @Transactional
    public void pay(Long memberId, int amount) {
        // 1. 잔액 차감
        // 2. 결제 내역 기록
        // 예외 발생 시 모든 작업이 롤백됨
        System.out.println("회원 " + memberId + "에게 " + amount + "원 결제 처리 완료");
    }
}

마무리

Spring에서 자주 사용하는 어노테이션은 단순히 “문법”이 아니라,

프로젝트 구조를 명확히 하고 계층 간 책임을 분리하기 위한 약속이다.

@Component : 범용 Bean 등록
@Service : 비즈니스 로직
@Repository : 데이터 접근
@Controller / @RestController : 요청 처리
@Autowired, @Value : 의존성 및 설정값 주입
@Transactional : 트랜잭션 처리

각 어노테이션은 “Spring이 언제, 어떻게 객체를 관리할지” 결정하는 핵심 도구이며,

이 개념만 정확히 이해해도 대부분의 Spring 프로젝트 구조를 파악할 수 있다.