오늘은 FastAPI에서 익숙했던 구조를 Express에서 어떻게 대응시켰는지 정리해본다.

폴더 구조 매핑

FastAPI에서는 보통 이런 구조로 개발했다.

app/
├── api/          # 라우터 (엔드포인트)
├── core/         # 설정, DB 연결
├── schema/       # Pydantic 모델 (요청/응답 검증)
├── models/       # ORM/ODM 모델
├── service/      # 비즈니스 로직
└── util/         # 공통 유틸

Express + TypeScript에서는 이렇게 대응시켰다.

src/
├── api/
│   ├── routes/        # 라우터 (URL 매핑만)
│   └── controllers/   # 컨트롤러 (요청 처리 + 응답)
├── core/
│   ├── config/        # 환경변수, Swagger 설정
│   ├── db/            # DB 연결
│   ├── middlewares/    # 인증, 에러 핸들러
│   └── security/      # JWT 관련
├── models/            # Mongoose 스키마
├── schemas/           # Zod 검증 스키마
├── services/          # 비즈니스 로직
├── types/             # TypeScript 타입 선언
└── server.ts          # 진입점

가장 큰 차이는 controller 레이어의 유무다. FastAPI에서도 service 레이어는 분리해서 사용했지만, 라우터 함수가 곧 컨트롤러 역할을 했다. Express에서는 route, controller, service 세 단계로 명시적으로 나뉜다.

route → controller → service 패턴

FastAPI에서는 (route + service)

라우터 함수가 컨트롤러 역할까지 했다. service는 별도로 분리했지만, 라우터에서 직접 service를 호출하고 응답을 반환했다.

# router (컨트롤러 역할 포함)
@router.post("/login")
async def login(request: LoginRequest):       # 검증 자동
    result = await auth_service.login(request.code)
    return result                              # return만 하면 끝

# service
async def login(code: str):
    token = await get_kakao_token(code)
    user = await find_or_create_user(...)
    return {"accessToken": token}

Express에서는 (route + controller + service)

controller가 추가로 들어간다.

route — URL이랑 함수 연결만

router.post("/login", loginHandler);

controller — 요청 파싱 + 서비스 호출 + 응답 반환

export const loginHandler = async (req, res, next) => {
    try {
        const { code } = loginSchema.parse(req.body);
        const result = await login(code);
        res.status(200).json(result);
    } catch (err) {
        next(err);
    }
};

service — 순수 비즈니스 로직 (FastAPI의 service와 동일)

export const login = async (code: string) => {
    const kakaoToken = await getKakaoToken(code);
    const { user, isNewUser } = await findOrCreateUser(...);
    return { accessToken, userId, ... };
};

FastAPI에서는 라우터가 검증, 응답 반환까지 자동으로 해줘서 controller가 필요 없었다. Express는 그런 자동화가 없어서 controller 레이어가 그 역할을 대신한다. 결국 service 로직 자체는 거의 동일하고, HTTP 처리 방식만 다른 셈이다.

FastAPI가 자동으로 해주던 것들

Express로 오면서 가장 체감했던 건 FastAPI가 얼마나 많은 걸 자동으로 해줬는지였다.

1. 요청 검증

# FastAPI — 파라미터 타입만 쓰면 자동 검증
async def login(request: LoginRequest):

// Express — 수동으로 해야 함
const { code } = loginSchema.parse(req.body);

FastAPI는 Pydantic 모델을 파라미터에 넣으면 자동 검증 + 422 응답까지 해줬다. Express는 Zod로 직접 검증하고, 에러 핸들러에서 422를 반환하도록 직접 만들어줘야 한다.

2. 에러 처리

# FastAPI — HTTPException 던지면 끝
raise HTTPException(status_code=401, detail="인증 실패")

// Express — try/catch + next(err) 필수
try {
    // ...
} catch (err) {
    next(err);
}

3. 응답 타입

# FastAPI — response_model로 자동 필터링
@router.post("/login", response_model=Token)

// Express — 인터페이스로 수동 매핑
const response: LoginResponse = {
    accessToken: result.accessToken,
    userId: result.userId,
    // ...
};
res.status(200).json(response);

라이브러리 대응표

Beanie에서 Mongoose로 전환하면서 느낀 차이도 있다. Beanie는 Document 클래스가 타입 + 스키마 + ODM 역할을 동시에 했는데, Mongoose는 인터페이스(타입) + 스키마(검증) + 모델(DB 조작)이 분리되어 있다.

// 1. 타입 정의
interface IUser extends Document {
    name: string;
    kakao_id: string;
}

// 2. 스키마 정의
const userSchema = new Schema<IUser>({
    name: { type: String, required: true },
    kakao_id: { type: String, required: true, unique: true },
});

// 3. 모델 생성
export const UserModel = model<IUser>("User", userSchema);

Beanie에서는 한 클래스로 끝났던 걸 세 단계로 나눠야 하지만, 오히려 각 역할이 명확해지는 장점이 있었다.

types 폴더의 역할 — .d.ts 파일은 왜 만들어야 하나?

TypeScript를 쓰면서 가장 낯설었던 건 types/ 폴더에 .d.ts 파일을 직접 만들어줘야 하는 상황이었다.

JavaScript 라이브러리는 세 가지 유형이 있다.

타입이 없는 라이브러리를 import하면 에러가 난다.

import { WebsocketProvider } from "y-websocket";
// ❌ Cannot find module 'y-websocket' or its corresponding type declarations.

이럴 때 직접 타입 선언 파일을 만들어줘야 한다.

// src/types/y-websocket.d.ts
declare module "y-websocket" {
    export class WebsocketProvider {
        constructor(serverUrl: string, roomname: string, doc: any);
        destroy(): void;
    }
}

Python은 타입이 없어도 실행되지만, TypeScript는 타입을 모르면 컴파일 자체가 안 되기 때문이다.

또 하나 유용했던 건 Express의 Request 타입 확장이다. 인증 미들웨어에서 req.user를 넣어주는데, Express 기본 타입에는 user가 없다.

// src/types/express/index.d.ts
declare global {
    namespace Express {
        interface Request {
            user?: {
                userId: string;
                name: string;
            };
        }
    }
}
export {};

이걸 만들어두면 (req as any).user 대신 req.user로 타입 안전하게 쓸 수 있다.

느낀 점

• FastAPI가 정말 많은 걸 자동화해주고 있었다는 걸 Express를 쓰면서 체감했다.
• 대신 Express는 자유도가 높아서 구조를 원하는 대로 잡을 수 있다.
• TypeScript의 타입 시스템은 처음에 번거롭지만, 프로젝트가 커질수록 안전망 역할을 해준다.
• FastAPI와 Express는 겉보기엔 다르지만 route → 비즈니스 로직 → DB라는 큰 흐름은 동일하다. 하나를 알면 다른 하나도 금방 적응할 수 있다.

핵심 기능이 실시간 채팅, 동시 문서 편집이라 다수 클라이언트가 동시 접속해서 이벤트를 계속 주고받는 구조인데, Node.js의 이벤트 루프 기반 비동기 I/O가 이런 워크로드에 잘 맞고 Socket.io, Yjs 등 관련 라이브러리 생태계도 npm 쪽이 두터워서 스택을 바꾸기로 결정했다.

1. 로컬 Node.js + TypeScript 환경 세팅

패키지 초기화 및 설치

npm init -y

# 개발용 도구
npm install -D typescript tsx @types/node @types/express

# 운영용 라이브러리
npm install express dotenv

Node.js는 패키지를 프로젝트 폴더 안 node_modules에 설치하기 때문에 폴더 자체가 이미 격리된 환경이다. 파이썬의 venv 같은 가상환경 개념이 따로 필요 없다.

npm install할 때 -D(--save-dev) 옵션을 붙이면 devDependencies(개발용)로, 안 붙이면 dependencies(운영용)로 package.json에 기록된다.

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

TypeScript 컴파일러(tsc)가 .ts 파일을 어떻게 .js로 변환할지 정하는 설정 파일이다.

package.json

{
  "name": "gooum-be",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "tsx src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/ureca-Gooum/Gooum-BE.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs",
  "bugs": {
    "url": "https://github.com/ureca-Gooum/Gooum-BE/issues"
  },
  "homepage": "https://github.com/ureca-Gooum/Gooum-BE#readme",
  "devDependencies": {
    "@types/express": "^5.0.6",
    "@types/node": "^26.1.1",
    "ts-node": "^10.9.2",
    "tsx": "^4.23.1",
    "typescript": "^7.0.2"
  },
  "dependencies": {
    "dotenv": "^17.4.2",
    "express": "^5.2.1"
  }
}

• npm run dev : 로컬 개발 중 TS 파일 바로 실행 (tsx 사용, 별도 설정 없이 esbuild 기반으로 즉시 실행됨)
• npm run build : TS → JS 컴파일 (dist/ 생성)
• npm start : 컴파일된 JS로 실제 서버 구동 (배포 환경에서 사용)
• "type": "commonjs" : 모듈 시스템을 CommonJS로 명시. tsx가 import 문법을 알아서 처리해주고, tsc 빌드나 일부 라이브러리와의 호환성을 위해 module(ESM)이 아닌 commonjs로 고정
• ts-node는 devDependencies에 남아있지만 실제 실행은 tsx로 하고 있어 사실상 미사용 상태 (정리 대상)

기본 서버 코드 (src/server.ts)

import express, { Request, Response } from "express";
import dotenv from "dotenv";

dotenv.config();

const app = express();
// Azure가 임의로 부여하는 포트(process.env.PORT)를 우선적으로 사용하도록 설정!
const PORT = process.env.PORT || 8000;

app.use(express.json());

// 배포 테스트용 핑 API
app.get("/ping", (req: Request, res: Response) => {
  res.status(200).json({
    message: "pong! Node.js TS server is running on Azure!",
  });
});

app.listen(PORT, () => {
  console.log(`🚀 Server is running on port ${PORT}`);
});

• dotenv.config()는 다른 코드가 process.env를 사용하기 전에 가장 먼저 실행되어야 하므로 파일 최상단에 둔다.
• process.env.PORT || 8000 : 로컬에서는 8000번을 쓰고, 배포 환경(Azure)에서는 플랫폼이 지정한 포트를 우선 사용하도록 유연하게 작성.

.gitignore

# 환경 변수 및 비밀값
.env
.env.local

# 의존성 패키지 폴더
node_modules/

# 빌드 결과물
dist/
out/
build/

# 개발 도구 및 IDE 설정
.vscode/
.idea/

# OS 및 임시 파일
.DS_Store
Thumbs.db
npm-debug.log*

2. Azure App Service 생성

• 게시(Publish): 코드(Code)
• 런타임 스택: Node 20 LTS 또는 Node 22 LTS
• 운영체제: Linux
• 요금제: 테스트 단계면 Free(F1) 또는 최소 사양

기존에 다른 스택(Python 등)으로 쓰던 App Service가 있다면, 설정만 바꾸는 것보다 새로 생성하는 편이 안전하다. 내부 빌드 엔진이나 환경변수가 이전 스택 기준으로 남아 있어 오류가 나기 쉽다.

3. GitHub Actions로 자동 배포 연결

1. Azure Portal → App Service → 배포 센터(Deployment Center)
2. 원본(Source): GitHub 선택 후 계정 연동
3. 배포할 레포지토리 / 브랜치(예: main) 선택 후 저장

저장하면 Azure가 자동으로 .github/workflows/*.yml 워크플로 파일을 레포지토리에 생성해준다. 이후 해당 브랜치에 push할 때마다 아래 과정이 자동으로 실행된다.

1. 코드 checkout
2. Node.js 설치
3. npm install → npm run build
4. 빌드 결과물 아티팩트 업로드
5. Azure App Service에 배포

package.json에 build 스크립트가 정확히 정의돼 있어야 3번 단계가 정상 동작한다.

4. 시작 명령(Startup Command) 설정

Azure Portal → App Service → 구성(Configuration) → 일반 설정(General settings) → 시작 명령

포트는 명령어에 별도로 적을 필요 없다. 코드에서 process.env.PORT를 리슨하도록 작성했다면 Azure가 내부적으로 지정한 포트와 자동으로 맞물린다.

5. 포트 설정 (필요한 경우만)

Azure Linux App Service는 기본적으로 내부 포트를 8080으로 사용한다. 코드에서 process.env.PORT || 8000으로 작성해뒀다면 별도 설정 없이 자동으로 맞춰지지만, 만약 배포 후 502 Bad Gateway가 발생한다면 아래처럼 명시적으로 지정한다.

• Azure Portal → 구성(Configuration) → 애플리케이션 설정(Application settings)
• 이름: WEBSITES_PORT
• 값: 실제 코드에서 사용 중인 포트 번호 (예: 8080)

6. 배포 확인

https://<앱이름>.azurewebsites.net/ping

{ "message": "pong! Node.js TS server is running!" }

Log stream에서 아래 메시지가 뜨면 정상 기동 상태다.

🚀 Server is running on port 8080

요약

1. tsx로 TS 실행 환경 구성, dotenv로 비밀값 분리, .gitignore로 민감 정보 제외
2. Azure에 Node.js 런타임(Linux)으로 App Service 생성
3. 배포 센터에서 GitHub 레포 연결 → push할 때마다 GitHub Actions가 자동 빌드/배포
4. 시작 명령은 node dist/server.js, 포트는 코드에서 process.env.PORT로 동적으로 대응
5. 필요 시 WEBSITES_PORT 환경변수로 포트 명시

0. 사용한 패키지

# 백엔드
npm install express jsonwebtoken cors cookie-parser

# 프론트엔드는 fetch API만 사용, 별도 HTTP 라이브러리 없음

1. JWT란?

JWT(JSON Web Token)는 두 당사자 간 정보를 안전하게 전송하기 위한 개방형 표준(RFC 7519)이다.

구조: Header.Payload.Signature

⚠️ 가장 중요한 포인트: Base64 인코딩 ≠ 암호화. 누구나 디코딩해서 payload를 볼 수 있다. 따라서 JWT payload에는 비밀번호 같은 민감 정보를 절대 넣으면 안 된다.

JWT의 핵심 장점: Stateless(무상태) 서버가 세션을 별도 저장하지 않고 토큰 자체에 정보가 담겨있어서, 서버를 여러 대로 확장해도 세션 동기화 문제가 없다.

2. 토큰을 어디에 저장할까? localStorage vs Cookie

localStorage 방식

• 전송: Authorization: Bearer <token> 헤더에 직접 담아서 전송
• 장점: 구현이 간단, 클라이언트에서 자유롭게 접근 가능
• 단점: XSS 공격에 취약 — 악성 스크립트가 삽입되면 localStorage.getItem()으로 토큰을 그대로 탈취 가능

HttpOnly Cookie 방식

• 전송: credentials: "include" 옵션으로 브라우저가 자동 전송
• 장점: httpOnly: true 설정 시 JavaScript로 절대 접근 불가 → XSS로부터 토큰 자체는 안전
• 단점: CSRF(사이트 간 요청 위조) 공격에는 별도 방어가 필요 (sameSite 옵션으로 완화)

  쿠키 옵션 정리

httpOnly: true   // JS 접근 차단 (XSS 방어의 핵심)
secure: false    // 개발환경(false) / 프로덕션(true, HTTPS 필수)
sameSite: "lax"  // CSRF 방어 (strict/lax/none)
maxAge: 3600000  // 만료시간(ms), 토큰 만료시간과 맞춤
path: "/"        // 쿠키 사용 가능 경로

결론: XSS는 HttpOnly 쿠키로 막고, CSRF는 sameSite + 서버 측 검증으로 막는 게 실무 정석 조합.

4. 로그인 ~ 인증 검증 흐름

(1) 서버: 로그인 시 토큰 발급 (server.js)

jsonwebtoken 패키지에서 jwt.sign, jwt.verify, jwt.decode 세 함수를 가져와 사용한다.

import jwt from "jsonwebtoken";

app.post("/api/login", (req, res) => {
    const { username, password, storageType = "localStorage" } = req.body;

    const user = users.find(
        (u) => u.username === username && u.password === password,
    );

    if (!user) {
        return res.status(401).json({
            success: false,
            message: "사용자 이름 또는 비밀번호가 잘못되었습니다.",
        });
    }

    const payload = {
        userId: user.id,
        username: user.username,
        role: user.role,
    };

    const options = {
        expiresIn: "1h",
        issuer: "jwt-education-server",
        subject: user.username,
    };

    const token = jwt.sign(payload, JWT_SECRET, options);

    if (storageType === "cookie") {
        res.cookie("jwt_token", token, {
            httpOnly: true,
            secure: false,
            sameSite: "lax",
            maxAge: 60 * 60 * 1000,
            path: "/",
        });
        res.json({ success: true, storageType: "cookie", user });
    } else {
        res.json({ success: true, storageType: "localStorage", token, user });
    }
});

storageType 값 하나로 쿠키 발급과 JSON 응답을 분기하는 구조가 핵심이다. 로그인 로직 자체(비밀번호 검증, 토큰 서명)는 동일하고, 토큰을 어떻게 클라이언트에 넘겨줄지만 달라진다.

(2) 서버: 토큰 검증 미들웨어 (verifyToken)

const verifyToken = (req, res, next) => {
    let token = null;

    // 1. 쿠키에서 토큰 확인
    if (req.cookies && req.cookies.jwt_token) {
        token = req.cookies.jwt_token;
    }
    // 2. Authorization 헤더에서 토큰 확인
    else {
        const authHeader = req.headers["authorization"];
        if (authHeader) {
            token = authHeader.split(" ")[1]; // "Bearer <token>" 중 토큰만 추출
        }
    }

    if (!token) {
        return res.status(401).json({ success: false, message: "인증 토큰이 제공되지 않았습니다" });
    }

    try {
        const decoded = jwt.verify(token, JWT_SECRET);
        req.user = decoded;
        next();
    } catch (err) {
        if (err.name === "TokenExpiredError") {
            return res.status(401).json({ success: false, message: "토큰이 만료되었습니다. 다시 로그인해주세요." });
        }
        if (err.name === "JsonWebTokenError") {
            return res.status(401).json({ success: false, message: "유효하지 않은 토큰입니다" });
        }
        return res.status(401).json({ success: false, message: "토큰 검증 중 오류가 발생했습니다." });
    }
};

쿠키를 먼저 확인하고, 없으면 헤더를 확인하는 순서로 짜여있어서 두 저장 방식을 하나의 미들웨어로 동시에 지원한다. jwt.verify()가 던지는 에러 이름(TokenExpiredError, JsonWebTokenError)으로 실패 원인을 구분해서 메시지를 다르게 내려주는 부분도 눈여겨볼 만하다.

(3) 클라이언트: 요청마다 인증 정보 자동 첨부 (api.js)

const getAuthHeaders = () => {
    const headers = { "Content-Type": "application/json" };

    // localStorage 방식일 때만 헤더에 토큰을 직접 담는다
    if (currentStorageType === "localStorage") {
        const token = getToken();
        if (token) {
            headers["Authorization"] = `Bearer ${token}`;
        }
    }
    // 쿠키 방식은 credentials: "include" 설정만으로 자동 전송됨
    return headers;
};

const getFetchOptions = (method = "GET", body = null) => {
    const options = {
        method,
        headers: getAuthHeaders(),
        credentials: "include", // 쿠키 포함 요청 (CORS 시 필수)
    };
    if (body) {
        options.body = typeof body === "string" ? body : JSON.stringify(body);
    }
    return options;
};

getProfile, getAdminData, refreshToken 등 인증이 필요한 API는 전부 이 getFetchOptions()를 통해 호출하도록 통일해서, 저장 방식이 바뀌어도 각 API 함수 코드는 건드릴 필요가 없게 설계되어 있다.

export const getProfile = async () => {
    const response = await fetch(`${API_BASE_URL}/profile`, getFetchOptions("GET"));
    const data = await response.json();

    if (data.success) {
        return { success: true, user: data.user };
    } else {
        if (response.status === 401) {
            removeToken(); // 만료/무효 토큰은 즉시 폐기
        }
        return { success: false, message: data.message || "프로필 조회 실패" };
    }
};

401 응답이 오면 클라이언트가 알아서 removeToken()을 호출해 로컬에 남은 만료 토큰을 정리하는 흐름도 실무적으로 유용했다.

jwt.decode() vs jwt.verify()

• jwt.decode(): 서명 검증 없이 디코딩만 함 (위조된 토큰도 그냥 읽힘)
• jwt.verify(): 서명 검증 + 디코딩 → 실제 인증 로직에는 반드시 이것만 사용

// 교육용 디코딩 엔드포인트 - 실제 서비스에서는 절대 노출 금지
app.post("/api/decode-token", (req, res) => {
    const decoded = jwt.decode(token, { complete: true });
    // complete: true → Header, Payload, Signature 모두 반환
    res.json({ success: true, decoded });
});

⚠️ 주의: 라이브러리마다 decode()의 동작이 다르다

예전에 Python으로 JWT를 구현했을 때 PyJWT를 썼는데, 거기서는 decode()가 기본적으로 서명 검증까지 포함해서 동작한다. Node의 jsonwebtoken과 정반대라 헷갈리기 딱 좋은 부분이라 따로 정리한다.

import jwt

# PyJWT: decode()가 기본적으로 서명 검증까지 수행
decoded = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])  # 여기서 이미 검증됨

# 검증 없이 payload만 보고 싶다면 명시적으로 꺼야 함
unsafe_decoded = jwt.decode(token, options={"verify_signature": False})

정리: 같은 "decode"라는 이름이라도 라이브러리마다 검증 포함 여부가 다르니, 새 언어/라이브러리로 JWT를 다룰 때는 공식 문서에서 decode 함수가 서명 검증을 포함하는지 반드시 확인하는 습관을 들이는 게 중요하다. (jsonwebtoken은 이름 그대로 decode=안전하지 않음, verify=안전함으로 명확히 분리되어 있지만, PyJWT는 이름만 봐서는 구분이 안 되기 때문에 실수하기 쉽다.)

5. 토큰 갱신(Refresh)

만료 전에 유효한 토큰으로 새 토큰을 재발급받는 흐름도 구현했다. verifyToken 미들웨어를 그대로 재사용해서 "현재 토큰이 유효한 사람만 갱신 가능"하도록 설계한 점이 인상적이었다.

app.post("/api/refresh", verifyToken, (req, res) => {
    const { storageType = "localStorage" } = req.body;

    const payload = {
        userId: req.user.userId,
        username: req.user.username,
        role: req.user.role,
    };

    const options = {
        expiresIn: "1h",
        issuer: "jwt-education-server",
        subject: req.user.username,
    };

    const newToken = jwt.sign(payload, JWT_SECRET, options);

    if (storageType === "cookie") {
        res.cookie("jwt_token", newToken, {
            httpOnly: true,
            secure: false,
            sameSite: "lax",
            maxAge: 60 * 60 * 1000,
            path: "/",
        });
        res.json({ success: true, storageType: "cookie" });
    } else {
        res.json({ success: true, token: newToken, storageType: "localStorage" });
    }
});

라우트 앞에 verifyToken을 붙이기만 하면 인증 체크가 자동으로 적용된다는 점에서, Express 미들웨어 체이닝이 왜 편한지 체감할 수 있었다.

6. 마무리

• Base64 ≠ 암호화 "토큰이 암호화됐으니 안전하겠지"라고 착각하기 쉬운데, payload는 jwt.io 같은 곳에서 누구나 디코딩 가능하다.
• XSS는 저장 위치(HttpOnly), CSRF는 전송 방식(sameSite/CSRF 토큰)으로 막는다
• CORS credentials 설정은 클라이언트 + 서버 양쪽 다 필요하다

1. CORS (Cross-Origin Resource Sharing)

CORS란?

브라우저가 한 출처(Origin)에서 실행 중인 웹 애플리케이션이 다른 출처의 리소스에 접근할 수 있도록 허용하는 메커니즘.

동일 출처 정책 (Same-Origin Policy, SOP)

브라우저는 보안을 위해 SOP를 적용하며, 두 URL이 아래 세 가지가 모두 같아야 같은 출처로 간주한다.

• 프로토콜 (http vs https)
• 도메인 (example.com vs api.example.com)
• 포트 (3000 vs 8080)

실습으로 확인한 것

• 다른 출처 요청: GitHub API처럼 CORS를 허용해둔 서버는 다른 도메인에서도 정상적으로 응답을 받을 수 있음
• 같은 출처 요청: 애초에 CORS 제한 자체가 없음
• CORS 미설정 서버: 다른 포트로 요청 시 브라우저가 요청 자체를 차단 (Failed to fetch 형태의 에러)
• CORS 허용 서버: 서버가 Access-Control-Allow-Origin 헤더를 설정해두면 다른 출처에서도 요청 가능

기억할 점

• CORS는 브라우저의 보안 정책이라 서버 간 통신(server-to-server)에는 적용되지 않는다
• 결국 CORS 문제 해결의 열쇠는 서버 쪽 헤더 설정에 있다
• 개발 환경에서는 프록시로 우회 가능하지만, 프로덕션에서는 서버에서 반드시 CORS 헤더를 제대로 설정해야 함

2. XMLHttpRequest vs Fetch API

XMLHttpRequest (XHR)

브라우저와 서버가 비동기로 데이터를 주고받는 전통적인 방식 (Ajax의 핵심 기술). onload, onerror 같은 이벤트 콜백 기반으로 동작.

Fetch API

XHR의 현대적 대안. Promise 기반이라 .then() 체이닝이나 async/await와 훨씬 잘 어울리고 문법도 간결하다.

Promise 체이닝

fetch(url)
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

.then()으로 비동기 흐름을 연결하고, .catch()로 에러를 한 곳에서 처리할 수 있다는 게 핵심.

비교 정리

→ 실무에서는 대부분 Fetch API를 권장.

3. React에서의 CORS 처리

• React에서는 보통 Fetch API나 axios로 API를 호출하고, useEffect로 컴포넌트 마운트 시점에 데이터를 불러온다
• CORS 에러가 발생하면 vite.config.js 등에서 개발 서버 프록시를 설정해 우회할 수 있음
• 단, 프록시는 개발 환경 전용이며, 실서비스에서는 결국 서버에서 Access-Control-Allow-Origin 헤더를 제대로 설정해야 한다
• 민감한 데이터를 다루는 API일수록 CORS 허용 도메인을 신뢰할 수 있는 출처로 제한하는 것이 중요

4. SQL Injection / XSS / CSRF 실습

SQL Injection

사용자 입력을 그대로 쿼리에 끼워 넣으면, ' OR '1'='1' 같은 입력값이 조건문을 항상 참으로 만들어버려 인증을 무력화시킬 수 있다.

• 취약한 방식: 문자열 그대로 쿼리에 삽입
• 방어 방식: Prepared Statement(준비된 구문) 사용 — 쿼리 구조(?)와 값을 분리해서 바인딩하면, 입력값은 항상 '문자열'로만 취급되어 명령어로 실행되지 않는다

XSS (Cross-Site Scripting)

악성 스크립트를 페이지에 삽입해 사용자 브라우저에서 실행시키는 공격.

• 취약한 방식: 사용자 입력을 검증 없이 그대로 화면에 렌더링
• 방어 방식: <, >, ", ', & 같은 특수문자를 HTML 엔티티로 이스케이프 처리 → 코드가 아닌 순수 텍스트로 인식되게 만듦
• React/Vue 등은 기본적으로 XSS를 방어해주지만, innerHTML을 직접 다룰 때는 주의 필요

CSRF (Cross-Site Request Forgery)

사용자가 의도하지 않은 요청이 자신도 모르게 실행되는 공격.

• 방어 방식: 서버가 발급한 CSRF 토큰을 요청에 포함시키고, 서버는 세션에 저장된 토큰과 일치하는지 검증
• 그 외 SameSite 쿠키 속성, Referer 헤더 검증, 중요 작업 시 재인증 요구도 함께 사용

인증/세션 관리 모범 사례

• 비밀번호는 bcrypt, Argon2 등으로 해시 + 솔트 처리
• 세션 ID는 안전하게 생성하고 적절한 만료 시간 설정, HTTPS 필수
• JWT 사용 시 서명 검증 + 짧은 만료시간 + Refresh Token 분리
• 2FA/MFA로 인증 강화, 무차별 대입 공격 방지를 위한 계정 잠금 기능

오늘의 한 줄 요약

CORS는 브라우저의 보안장치일 뿐이고, 진짜 보안은 서버의 입력값 검증 + 인증/인가 + 암호화 + 지속적인 모니터링에서 나온다.

나는 항상 벼락치기를 한다. 시험 날이 되면 매번 후회한다. "아 미리 할걸..."

근데 이게 왜 반복되는지 궁금했다. 그냥 의지력 부족인건지, 아니면 다른 이유가 있는건지.

그래서 실패를 기록하고 분석하는 앱을 만들어봤다.

처음에는 다른 사람들과 비교하는 기능도 기획했는데 결국 빼버렸다. 남들과 경쟁하고 싶은 게 아니라 그냥 어제의 나보다 나아지고 싶었기 때문이다.

그래서 이 앱의 핵심은 하나다. "나는 언제, 왜 포기하는가"

2. 어떤 앱인가 ?

작심삼일 수사대는 목표 달성 과정에서 실패 원인을 기록하고, AI가 탐정처럼 반복되는 습관의 패턴을 분석해주는 서비스다.

기존 습관 앱들은 성공을 기록하는 데 집중하는데 이 앱은 반대로 실패에 집중했다.

3. 기술 스택

• Language: TypeScript
• Framework: React
• Styling: Tailwind CSS
• State Management: Zustand
• HTTP: Axios
• 차트: recharts
• 달력: react-calendar
• 백엔드: FastAPI + MongoDB
• AI: Gemini API
• 배포: Vercel + Azure

4. 주요 기능

1. 카카오 로그인

• 로그인은 카카오 로그인 API 를 사용했고, JWT 토큰을 이용해 사용자 인증처리를 구현했다.

2. 목표 생성 및 기록

• 목표를 생성하고 매일 성공/실패를 체크하는 기능이다. 실패하면 이유를 입력하면 Gemini API가 자동으로 카테고리를 분류해준다.

3. 기록 달력

• react-calendar를 커스텀해서 날짜별로 성공/실패/혼합 동그라미를 표시했다.

4. 분석 대시보드

• recharts로 요일별 실패율 바 차트와 실패 원인 도넛 차트를 구현했다.

5. AI 수사 브리핑

• 홈: 최근 7일 실패 기록 기반 동기부여 메시지

• 분석: 요일별 실패율 + 실패 키워드 기반 인사이트

하루에 한 번만 생성하고 DB에 캐싱해서 API 비용을 절약했다.

6. 다크모드 / 반응형

• CSS 변수를 재정의하는 방식으로 다크모드를 구현했다.

.dark {
    --color-bg-primary: #1f1b18;
    --color-text-primary: #f5f1eb;
}

• 모바일에서는 하단 네비바로 전환했다.

5. Zustand로 전역 상태 관리

로그인 후 accessToken, nickname, theme을 어디서든 꺼내 쓸 수 있어야 했다. Zustand를 사용해서 전역으로 관리했다.

import { create } from "zustand";
import { persist } from "zustand/middleware";

interface AuthStore {
    accessToken: string | null;
    nickname: string | null;
    theme: string | null;
    setAuth: (accessToken: string, nickname: string, theme: string) => void;
    clearAuth: () => void;
}

export const useAuthStore = create<AuthStore>()(
    persist(
        (set) => ({
            accessToken: null,
            nickname: null,
            theme: null,
            setAuth: (accessToken, nickname, theme) =>
                set({ accessToken, nickname, theme }),
            clearAuth: () =>
                set({ accessToken: null, nickname: null, theme: null }),
        }),
        {
            name: "auth-storage", // localStorage 키 이름
        },
    ),
);

persist 미들웨어를 사용해서 새로고침해도 로그인 상태가 유지되게 했다. Redux보다 코드가 훨씬 간결해서 소규모 프로젝트에 적합했다.

6. react-calendar 커스텀

react-calendar 기본 스타일이 너무 밋밋해서 전부 커스텀했다.

Tailwind를 쓰고 있었는데 react-calendar 기본 스타일을 덮어쓰려면 별도 CSS 파일이 필요했다.

날짜 숫자가 abbr 태그로 감싸져 있어서 동그라미를 표시하려면 abbr 에 스타일을 적용해야 한다는 걸 한참 헤매다 알았다.

/* 성공한 날 → 초록 동그라미 */
.react-calendar__tile.tile-success abbr {
    display: inline-flex;
    justify-content: center;
    align-items: center;
    width: 36px;
    height: 36px;
    border-radius: 50%;
    background-color: #4caf50;
    color: white;
}

/* 실패한 날 → 빨간 동그라미 */
.react-calendar__tile.tile-fail abbr {
    background-color: #f44336;
}

/* 성공 + 실패 혼합 → 반반 동그라미 */
.react-calendar__tile.tile-partial abbr {
    background: linear-gradient(90deg, #4caf50 50%, #f44336 50%);
}

tileClassName prop으로 날짜마다 클래스를 붙여서 구현했다.

const tileClassName = ({ date }: { date: Date }) => {
    const status = getDateStatus(dateStr)
    if (status === 'all_success') return 'tile-success'
    if (status === 'all_fail') return 'tile-fail'
    if (status === 'partial') return 'tile-partial'
    return null
}

7. 아직 해결하지 못한 부분

날짜 처리

DB에는 UTC로 저장하고 응답할 때 KST로 변환하는 게 표준이라고 알고 있는데 기록을 등록할 때는 KST 기준으로 날짜를 저장해야 해서 어떤 곳은 UTC, 어떤 곳은 KST로 처리하다 보니 헷갈리는 부분이 많다.

예를 들면 새벽 1시에 기록하면 UTC로는 전날이 되어버리는 문제가 있었다.

// KST 기준으로 오늘 날짜 계산
const getKoreaToday = () => {
    const today = new Date()
    const koreaToday = new Date(today.getTime() + 9 * 60 * 60 * 1000)
    return koreaToday.toISOString().split('T')[0]
}

날짜 처리를 더 명확하게 정리할 필요가 있을 것 같다.

8. 마무리

그동안 배운 것들을 참고해 혼자서 화면을 구현해보니 확실히 어느 정도 감을 잡게 된 것 같다. 수업 시간에 이해가 되지 않았던 부분들도 직접 부딪혀보니 훨씬 잘 이해됐다.

특히 Tailwind는 처음에는 불편하다고 생각했는데 직접 프로젝트에 적용해보니 훨씬 편하게 느껴졌다.

아직 계획한 기능을 다 구현하지 못했고, 데이터 로딩도 느리고 사용자 경험이 불편한 부분도 많다. 앞으로 찬찬히 개선해나갈 예정이다!

🔍 Redux 미들웨어

1. Redux가 필요한 이유

React에서 state는 컴포넌트 안에 있다. 근데 여러 컴포넌트가 같은 데이터를 써야 하면?

App
├── Header      ← 여기서도 로그인 정보 필요
├── Sidebar     ← 여기서도 로그인 정보 필요
└── Main
    └── Profile ← 여기서도 로그인 정보 필요

Redux는 state를 컴포넌트 밖, Store라는 창고에 모아둔다. 모든 컴포넌트가 여기서 꺼내 쓴다.

Store의 state는 직접 바꾸면 안 된다. 반드시 dispatch → Reducer를 통해서만 바꿔야 한다.

버튼 클릭 → dispatch(액션) → Reducer → 새 state → 화면 업데이트

• Store — state 보관 창고. 앱에 딱 하나.
• Reducer — "이 액션이 오면 state를 이렇게 바꿔라" 규칙서. 역할별로 여러 개 만들고 combineReducers로 합친다.
• dispatch — "야 Reducer야, 이 액션 처리해줘!" 하고 전달하는 함수.

2. Store는 어디에 있나?

앱 최상단에서 딱 한 번 만들어진다.

// index.js
const store = createStore(rootReducer, applyMiddleware(logger, thunk));

ReactDOM.render(
  <Provider store={store}> // 전체 앱을 감싸서 Store를 공급
    <App />
  </Provider>,
  document.getElementById('root')
);

combineReducers로 역할별 Reducer를 하나로 합친다:

// modules/index.js
const rootReducer = combineReducers({
  counter,  // 카운터 담당
  sample,   // post, users 담당
  loading,  // 로딩 상태 담당
});

3. 미들웨어가 필요한 이유

dispatch는 기본적으로 객체(액션) 만 받는다. 즉시 Reducer로 보내버린다. 근데 "1초 뒤에 실행", "API 응답 오면 실행" 같은 걸 하려면 끼워넣을 공간이 없다. 미들웨어는 dispatch와 Reducer 사이에 자리를 만들어준다.

dispatch(액션) → logger → thunk → Reducer → 새 state

미들웨어는 Store를 만들 때 등록한다:

const store = createStore(
  rootReducer,
  applyMiddleware(logger, thunk) // 순서대로 통과
);

4. logger 미들웨어 - 직접 만들어보기(개념 이해용)

실무에서는 redux-logger 라이브러리를 쓰면 된다. 여기서는 미들웨어가 내부적으로 어떻게 동작하는지 이해하기 위해 직접 만들어봤다.

미들웨어 구조는 함수가 3겹으로 중첩된 형태다. Redux가 store → next → action 순서로 하나씩 넘겨주는 구조에 맞춰진 것이다.

const loggerMiddleware = (store) => (next) => (action) => {
  // store  : Redux가 처음에 넘겨줌 (상태 조회용)
  // next   : Redux가 두 번째로 넘겨줌 (다음 미들웨어 or Reducer로 넘기는 함수)
  // action : 실제 dispatch될 때 넘겨줌
  console.log("이전 상태", store.getState()); // 아직 안 바뀜
  console.log("액션", action);
  next(action); // ← 없으면 Reducer에 도달 안 함!
  console.log("다음 상태", store.getState()); // 바뀐 후
};

next(action)을 호출해야 다음 미들웨어 또는 Reducer로 넘어간다. 이게 없으면 액션이 거기서 멈춘다.

5. Thunk

dispatch가 호출될 때 thunk 미들웨어가 이걸 확인한다: "넘어온 게 함수야, 객체야?"

// thunk 내부 동작 (개념)
if (typeof action === "function") {
  action(dispatch); // 함수면 → thunk가 직접 실행시켜줌
} else {
  next(action);     // 객체면 → 그냥 Reducer로 보냄
}

평소엔 dispatch({ type: "INCREASE" }) 처럼 객체를 넘기면 Reducer로 직행한다. 근데 함수를 넘기면 thunk가 가로채서 실행시켜준다. 덕분에 아래와 같이 가능해진다.

// counter.js — increaseAsync를 풀어서 읽으면
export const increaseAsync = () => { // 1. increaseAsync() 호출하면
  return (dispatch) => {             // 2. 함수를 반환 (thunk가 이걸 실행)
    setTimeout(() => {
      dispatch(increase());          // 3. 1초 뒤에 dispatch
    }, 1000);
  }
};

6. connect와 useEffect

useEffect — 컴포넌트가 화면에 나타났을 때 실행할 것을 지정한다.

useEffect(() => {
  getPost(1);   // 화면 뜨자마자 API 호출
  getUsers(1);
}, []); // [] = 처음 화면 떴을 때 딱 한 번만 실행

두 번째 인자에 따라 실행 시점이 달라진다:

• useEffect(() => {...}) — 매 렌더링마다 실행
• useEffect(() => {...}, []) — 처음 한 번만 실행
• useEffect(() => {...}, [count]) — count가 바뀔 때마다 실행

connect — Redux Store와 컴포넌트를 연결한다. 두 가지 일을 한다:

export default connect(
  ({ sample, loading }) => ({
    post: sample.post,                      // Store에서 꺼내서 props로
    loadingPost: loading["sample/GET_POST"],
  }),
  { getPost, getUsers }, // dispatch 연결
)(SampleContainer);

7. 전체 비동기 흐름

1. 화면 뜸
   → useEffect 실행 → getPost(1) 호출

2. dispatch(thunk 함수)
   → logger: 콘솔에 찍음
   → thunk: "함수네!" → 실행시켜줌
   → loading: true → 로딩 스피너 표시

3. API 호출 (axios)
   → 서버 응답 대기 중...

4. dispatch({ type: GET_POST_SUCCESS, payload: data })
   → Reducer가 state 업데이트
   → loading: false → 로딩 스피너 사라짐

5. connect가 변화 감지
   → 새 state를 props로 전달
   → 화면 리렌더링 → 데이터 표시 🎉

🔍 코드 스플리팅

왜 필요할까?

React 앱을 빌드하면 모든 JS가 하나의 파일로 합쳐진다. 앱이 커질수록 사용자가 첫 접속 시 받아야 하는 파일이 무거워진다. 한 번도 방문하지 않는 페이지 코드까지 미리 다운로드하는 건 낭비다.

코드 스플리팅: 필요한 코드만 그때그때 로드해서 초기 로딩 속도를 높인다.

1단계: 정적 import (스플리팅 없음)

import notify from "./notify"; // 앱 시작할 때 무조건 다운로드

버튼을 한 번도 안 눌러도 notify.js는 이미 다운로드 돼 있다. 낭비.

2단계: 동적 import

const onClick = () => {
  import("./notify").then((result) => result.default());
};

버튼을 클릭하는 그 순간 처음으로 notify.js를 다운로드한다. import()는 Promise를 반환하므로 .then()으로 완료 후 처리한다.

3단계: React.lazy + Suspense

컴포넌트를 스플리팅할 때 사용한다.

const SplitMe = React.lazy(() => import("./SplitMe"));

React.lazy는 이 컴포넌트가 화면에 처음 나타날 때 그제야 다운로드한다. 다운로드가 끝나기 전까지 React는 "아직 준비 안 됨" 상태다. 이때 Suspense가 대신 fallback UI를 보여준다.

// 식당에 앉자마자 음식 나오기 전 물 먼저 주는 것과 같다
<Suspense fallback={<div>loading...</div>}>
  {visible && <SplitMe />}
</Suspense>

단점: SSR 미지원, Suspense로 반드시 감싸야 함.

4단계: @loadable/component

3단계의 단점을 보완한 라이브러리.

const SplitMe = loadable(() => import("./SplitMe"), {
  fallback: <div>loading...</div>,
});

• Suspense 없이 fallback을 옵션으로 바로 넘김
• SSR 지원
• preload() 기능 제공

// 마우스 올리는 순간 미리 다운로드 → 클릭 시 즉각 표시
const onMouseOver = () => {
  SplitMe.preload();
};

preload: 사용자가 마우스를 올리는 순간 파일을 미리 받아놓는다. 실제 클릭 시 이미 로드되어 있어 즉각 표시 → UX 향상.

코드 스플리팅 단계 정리

오늘은 Context API와 Redux를 배웠다. 둘 다 컴포넌트 간 데이터 공유 문제를 해결하지만 목적이 다르다. Context API는 props drilling을 피하기 위한 값 전달 메커니즘이고, Redux는 앱 전체 상태를 체계적으로 관리하는 상태 관리 라이브러리다.

Props Drilling 문제

컴포넌트 트리가 깊어지면 중간 컴포넌트들이 해당 데이터를 실제로 사용하지 않더라도 props를 계속 전달해야 하는 Props Drilling 문제가 생긴다.

// ❌ Props Drilling
function App() {
  const [color, setColor] = useState('black');

  return <Parent color={color} setColor={setColor} />;
}

function Parent({ color, setColor }) {
  // Parent는 color를 쓰지도 않는데 받아서 넘겨야 함
  return <Child color={color} setColor={setColor} />;
}

function Child({ color, setColor }) {
  return <div style={{ background: color }} onClick={() => setColor('red')} />;
}

Context를 쓰면 중간 단계 없이 필요한 컴포넌트가 직접 값을 꺼내 쓸 수 있다.

Context API는 상태 관리를 해주는 게 아니다. 상태는 여전히 useState로 따로 관리하고, Context는 그 값을 props 없이 트리 전체에 전달해주는 통로 역할이다.

Context API 핵심 구조

Context는 크게 세 단계로 나뉜다.

1단계 — createContext로 Context 생성

// contexts/Colors.jsx
import { createContext, useState } from 'react';

// createContext(기본값)
// 기본값은 Provider 없이 useContext를 사용할 때만 적용됨
// 실제로는 타입 힌트 / 자동완성 용도로 쓰는 경우가 많음
const ColorContext = createContext({
  state: { color: 'black', subColor: 'red' },
  actions: {
    setColor: () => {},
    setSubColor: () => {},
  },
});

state / actions 분리 패턴

• state: 읽기 전용 데이터 (color, subColor)
• actions: 상태를 변경하는 함수 (setColor, setSubColor)

"무엇을 보여줄지"와 "무엇을 바꿀 수 있는지"를 분리하면 컴포넌트 역할이 명확해진다.

2단계 — Provider로 상태 공급

// contexts/Colors.jsx (이어서)

const ColorProvider = ({ children }) => {
  const [color, setColor] = useState('black');
  const [subColor, setSubColor] = useState('red');

  // createContext의 기본값 구조와 동일하게 맞춰야
  // Consumer / useContext에서 일관성 있게 사용 가능
  const value = {
    state: { color, subColor },
    actions: { setColor, setSubColor },
  };

  return (
    <ColorContext.Provider value={value}>
      {children}
    </ColorContext.Provider>
  );
};

// Consumer는 ColorContext에 내장된 컴포넌트를 꺼내 쓰는 것
const { Consumer: ColorConsumer } = ColorContext;

export { ColorProvider, ColorConsumer };
export default ColorContext;

3단계 — App에서 Provider로 감싸기

// App.jsx
import { ColorProvider } from './contexts/Colors';
import { SelectColors } from './components/SelectColors';
import { ColorBox } from './components/ColorBox';

function App() {
  return (
    // ColorProvider로 감싸면 내부의 모든 컴포넌트에서 Context 값에 접근 가능
    <ColorProvider>
      <div>
        <SelectColors />
        <ColorBox />
      </div>
    </ColorProvider>
  );
}

Provider가 없다면 SelectColors와 ColorBox가 color를 공유하려면 App에 useState를 두고 props로 각각 내려줘야 한다.

Context 값 소비하기 — 두 가지 방법

방법 1: useContext Hook (권장 ✅)

// components/ColorBox.jsx
import { useContext } from 'react';
import ColorContext from '../contexts/Colors';

export const ColorBox = () => {
  // useContext 한 줄로 Context 값을 꺼내 일반 변수처럼 사용
  // ColorBox는 색상을 보여주기만 하므로 state만 필요
  const { state } = useContext(ColorContext);

  return (
    <div>
      {/* 왼쪽 클릭으로 선택한 색상 */}
      <div style={{ width: '64px', height: '64px', background: state.color }} />
      {/* 오른쪽 클릭으로 선택한 색상 */}
      <div style={{ width: '32px', height: '32px', background: state.subColor }} />
    </div>
  );
};

방법 2: Consumer — render props 패턴 (구버전)

// components/SelectColors.jsx
import { ColorConsumer } from '../contexts/Colors';

const colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];

export const SelectColors = () => {
  return (
    <div>
      <h2>색상을 선택하세요. 왼쪽 클릭 혹은 오른쪽 클릭으로</h2>

      {/* render props 패턴: 자식으로 함수를 전달, 함수의 인자로 Context 값이 들어옴 */}
      <ColorConsumer>
        {({ actions }) => (
          <div style={{ display: 'flex' }}>
            {colors.map((color) => (
              <div
                key={color}
                style={{ background: color, width: '24px', height: '24px', cursor: 'pointer' }}
                // 왼쪽 클릭: 큰 사각형 색상 변경
                onClick={() => actions.setColor(color)}
                // 오른쪽 클릭: 작은 사각형 색상 변경
                onContextMenu={(e) => {
                  e.preventDefault(); // 브라우저 기본 우클릭 메뉴 차단
                  actions.setSubColor(color);
                }}
              />
            ))}
          </div>
        )}
      </ColorConsumer>
    </div>
  );
};

두 방법 비교

전체 파일 구조 정리

src/
├── contexts/
│   └── Colors.jsx       ← createContext + Provider + Consumer 정의
├── components/
│   ├── ColorBox.jsx     ← useContext로 state 소비 (읽기)
│   └── SelectColors.jsx ← Consumer로 actions 소비 (쓰기)
└── App.jsx              ← Provider로 트리 감싸기

정리

• Props Drilling 문제 → Context로 해결. 중간 컴포넌트 없이 필요한 곳에서 바로 꺼내 씀
• createContext(기본값) → 기본값은 Provider 없을 때만 적용. 타입 힌트 용도
• state / actions 분리 → 읽기 데이터와 변경 함수를 나눠서 역할을 명확하게
• Provider → 최상위에서 감싸면 하위 모든 컴포넌트에서 Context 접근 가능
• useContext vs Consumer → 함수형 컴포넌트라면 useContext, 클래스 컴포넌트라면 Consumer

Context는 "전역 상태가 필요한데 Redux는 무겁다" 싶을 때 딱 좋다. 단, 자주 바뀌는 값에 쓰면 불필요한 리렌더링이 생길 수 있으니 주의!

Redux

Redux란?

앱 전체의 상태(state)를 하나의 저장소(store) 에서 관리하는 상태 관리 라이브러리다.

Redux의 3가지 원칙

1. 스토어는 하나 — 앱 전체의 상태를 단일 스토어에서 관리
2. 상태는 읽기 전용 — 오직 액션(Action)을 통해서만 상태 변경 가능
3. 변화는 순수 함수(리듀서)로만 — 리듀서는 이전 state + action을 받아 새 state를 반환

데이터 흐름 (단방향)

사용자 이벤트 → dispatch(action) → Reducer → 새 state → 화면 업데이트

Context API vs Redux

Redux 핵심 개념

Action — 무슨 일이 일어났는가

상태를 어떻게 바꿀지 설명하는 객체. type 필드는 필수다.

// 액션 타입 상수 — 오타 방지 + 자동완성을 위해 상수로 관리
const INCREASE = 'counter/INCREASE';
const DECREASE = 'counter/DECREASE';

// 액션 생성자 — dispatch에 넘길 액션 객체를 만들어주는 함수
export const increase = () => ({ type: INCREASE });
export const decrease = () => ({ type: DECREASE });

Reducer — 새 state를 반환하는 순수 함수

현재 state와 action을 받아 새로운 state를 반환한다. 직접 state를 수정하면 안 되고, 반드시 새 객체를 반환해야 한다 (불변성 유지).

// 기본 switch/case 패턴
function counter(state = initialState, action) {
  switch (action.type) {
    case INCREASE:
      return { number: state.number + 1 };
    case DECREASE:
      return { number: state.number - 1 };
    default:
      return state; // 해당 없는 액션은 state 그대로 반환
  }
}

handleActions를 쓰면 switch/case 없이 더 깔끔하게 작성할 수 있다.

import { createAction, handleActions } from 'redux-actions';

export const increase = createAction(INCREASE);
export const decrease = createAction(DECREASE);

// handleActions(핸들러맵, initialState)
const counter = handleActions(
  {
    [INCREASE]: (state, action) => ({ number: state.number + 1 }),
    [DECREASE]: (state, action) => ({ number: state.number - 1 }),
  },
  initialState,
);

스토어 설정

combineReducers — 여러 리듀서를 하나로 합치기

Redux 스토어는 리듀서를 하나만 받는다. 기능이 많아지면 리듀서도 여러 개로 나뉘는데, combineReducers로 하나로 합쳐준다.

// modules/index.jsx
import { combineReducers } from 'redux';
import counter from './counter';
import todos from './todos';

// 객체 키 이름이 state의 슬라이스 이름이 됨
// state.counter, state.todos 로 접근 가능
const rootReducer = combineReducers({
  counter,
  todos,
});

export default rootReducer;

configureStore + Provider로 앱 감싸기

// main.jsx
import { configureStore } from '@reduxjs/toolkit';
import { Provider } from 'react-redux';
import rootReducer from './modules/index';

const store = configureStore({ reducer: rootReducer });

createRoot(document.getElementById('root')).render(
  <Provider store={store}>
    <App />
  </Provider>
);

Provider로 감싸면 하위 모든 컴포넌트에서 useSelector / useDispatch로 스토어에 접근할 수 있다.

Redux DevTools @redux-devtools/extension을 연결하고 크롬 확장 "Redux DevTools"를 설치하면, 액션이 dispatch될 때마다 어떤 액션이 발생했고 state가 어떻게 바뀌었는지 실시간으로 확인할 수 있다. "Time Travel Debugging"으로 과거 state로 되돌아가 버그를 재현할 수도 있다.

컴포넌트에서 Redux 사용하기

UI 컴포넌트 vs 컨테이너 컴포넌트 분리 원칙

Redux를 쓸 때는 두 가지 역할을 분리하는 게 관례다.

// components/Counter.jsx — UI 컴포넌트 (Redux 모름)
export const Counter = ({ number, onIncrease, onDecrease }) => {
  return (
    <div>
      <h1>{number}</h1>
      <button onClick={onIncrease}>1 더하기</button>
      <button onClick={onDecrease}>1 빼기</button>
    </div>
  );
};

// containers/CounterContainer.jsx — 컨테이너 (Redux 연결 담당)
import { useSelector, useDispatch } from 'react-redux';
import { useCallback } from 'react';
import { increase, decrease } from '../modules/counter';
import { Counter } from '../components/Counter';

export const CounterContainer = () => {
  // useSelector: 스토어의 state에서 필요한 값만 선택
  const number = useSelector((state) => state.counter.number);

  // useDispatch: 액션을 스토어에 전달하는 dispatch 함수 반환
  const dispatch = useDispatch();

  const onIncrease = useCallback(() => dispatch(increase()), [dispatch]);
  const onDecrease = useCallback(() => dispatch(decrease()), [dispatch]);

  return (
    <Counter number={number} onIncrease={onIncrease} onDecrease={onDecrease} />
  );
};

immer로 불변성 쉽게 관리하기

배열/객체가 중첩된 복잡한 state를 다룰 때, 불변성을 직접 지키면 코드가 길고 복잡해진다. immer의 produce를 쓰면 마치 직접 수정하는 것처럼 코드를 작성해도 내부적으로 불변성을 지켜준다.

// modules/todos.jsx
import { createAction, handleActions } from 'redux-actions';
import { produce } from 'immer';

const CHANGE_INPUT = 'todos/CHANGE_INPUT';
const INSERT     = 'todos/INSERT';
const TOGGLE     = 'todos/TOGGLE';
const REMOVE     = 'todos/REMOVE';

export const changeInput = createAction(CHANGE_INPUT, (input) => input);
export const insert      = createAction(INSERT, (text) => ({ id: id++, text, done: false }));
export const toggle      = createAction(TOGGLE, (id) => id);
export const remove      = createAction(REMOVE, (id) => id);

let id = 3;

const initialState = {
  input: '',
  todos: [
    { id: 1, text: '리덕스 기초 배우기', done: false },
    { id: 2, text: '리액트와 리덕스 사용하기', done: true },
  ],
};

const todos = handleActions(
  {
    [CHANGE_INPUT]: (state, { payload: input }) =>
      produce(state, (draft) => { draft.input = input; }),

    [INSERT]: (state, { payload: todo }) =>
      produce(state, (draft) => { draft.todos.push(todo); }),

    [TOGGLE]: (state, { payload: id }) =>
      produce(state, (draft) => {
        const todo = draft.todos.find((t) => t.id === id);
        todo.done = !todo.done;
      }),

    [REMOVE]: (state, { payload: id }) =>
      produce(state, (draft) => {
        const index = draft.todos.findIndex((t) => t.id === id);
        draft.todos.splice(index, 1);
      }),
  },
  initialState,
);

export default todos;

useActions 커스텀 훅 — dispatch 연결 자동화

액션 생성자가 많아지면 useCallback을 여러 번 반복해야 한다. bindActionCreators와 커스텀 훅으로 한 번에 묶을 수 있다.

// lib/useActions.js
import { bindActionCreators } from 'redux';
import { useDispatch } from 'react-redux';
import { useMemo } from 'react';

// bindActionCreators: 액션 생성자를 dispatch와 묶어주는 redux 내장 함수
// 호출 시 자동으로 dispatch(actionCreator(...))가 실행되는 함수가 만들어짐
export default function useActions(actions, deps) {
  const dispatch = useDispatch();
  return useMemo(
    () => {
      if (Array.isArray(actions)) {
        return actions.map((a) => bindActionCreators(a, dispatch));
      }
      return bindActionCreators(actions, dispatch);
    },
    deps ? [dispatch, ...deps] : deps,
  );
}

// containers/TodosContainer.jsx
import { useSelector } from 'react-redux';
import { changeInput, insert, toggle, remove } from '../modules/todos';
import useActions from '../lib/useActions';
import { Todos } from '../components/Todos';

export const TodosContainer = () => {
  const { input, todos } = useSelector(({ todos }) => ({
    input: todos.input,
    todos: todos.todos,
  }));

  // useActions 덕분에 useCallback 4번 쓸 필요 없이 한 줄로 해결
  const [onChangeInput, onInsert, onToggle, onRemove] = useActions(
    [changeInput, insert, toggle, remove],
    [],
  );

  return (
    <Todos
      input={input}
      todos={todos}
      onChangeInput={onChangeInput}
      onInsert={onInsert}
      onToggle={onToggle}
      onRemove={onRemove}
    />
  );
};

전체 파일 구조 정리

src/
├── modules/
│   ├── index.jsx     ← combineReducers로 루트 리듀서 생성
│   ├── counter.jsx   ← 카운터 액션 타입 / 액션 생성자 / 리듀서
│   └── todos.jsx     ← 할 일 목록 액션 타입 / 액션 생성자 / 리듀서
├── containers/
│   ├── CounterContainer.jsx  ← Redux 연결 (useSelector, useDispatch)
│   └── TodosContainer.jsx    ← Redux 연결 + useActions 커스텀 훅
├── components/
│   ├── Counter.jsx   ← UI 컴포넌트 (Redux 모름)
│   └── Todos.jsx     ← UI 컴포넌트 (Redux 모름)
└── main.jsx          ← configureStore + Provider로 앱 감싸기

정리

• Action → 상태 변경을 설명하는 객체. type 필드 필수
• Reducer → (state, action) => newState. 반드시 새 객체 반환 (불변성)
• Store → 앱 전체에 하나. configureStore로 생성, Provider로 공급
• combineReducers → 여러 리듀서를 하나로 합쳐 스토어에 전달
• useSelector → 스토어에서 필요한 state만 선택
• useDispatch → 액션을 스토어에 전달하는 dispatch 함수
• handleActions → switch/case 없이 리듀서를 깔끔하게 작성
• immer → 복잡한 중첩 state도 직접 수정하듯 불변성 유지
• bindActionCreators → 액션 생성자와 dispatch를 자동으로 묶기
• UI / 컨테이너 분리 → UI 컴포넌트는 Redux를 몰라야 재사용성이 높아짐

Redux는 처음엔 개념이 많아서 복잡해 보이지만, "액션으로만 상태를 바꾼다"는 원칙 덕분에 코드가 커져도 흐름을 추적하기 쉽다. DevTools의 Time Travel이 생각보다 꽤 강력하다.

오늘 수업에서는 React 개념들을 총동원한 Todo 앱을 만들어봤다. useState보다 복잡한 상태 관리를 위해 useReducer + Immer를 쓰고, React Router로 다중 페이지도 구성했다.

목차

• Action Type 상수
• useReducer + Immer
• useCallback
• useMemo
• props를 객체로 묶어서 스프레드로 전달하는 방식
• BrowserRouter & 동적 라우팅
• Todo 앱 만들기

Action Type 상수

const ADD_TODO = "ADD_TODO";
const TOGGLE_TODO = "TOGGLE_TODO";
const DELETE_TODO = "DELETE_TODO";

dispatch를 쓸 때 'ADD_TODO'처럼 문자열을 직접 넣으면 오타가 나도 에러가 안 뜨고 그냥 조용히 동작을 안 한다. 상수로 빼두면 오타가 났을 때 'ADD_TODO is not defined'처럼 에러가 바로 나서 어디가 잘못됐는지 바로 알 수 있다. reducer 쪽이랑 dispatch 호출하는 쪽이 같은 상수를 쓰니까 일관성도 생긴다.

useReducer + Immer

import { produce } from "immer";

const todoReducer = (state, action) => {
    return produce(state, (draft) => {
        switch (action.type) {
            case ADD_TODO:
                draft.todos.push({
                    id: Date.now(),
                    text: action.payload.text,
                    completed: false,
                    priority: action.payload.priority || "medium",
                    category: action.payload.category || "기타",
                });
                break;

            case TOGGLE_TODO: {
                const todo = draft.todos.find((t) => t.id == action.payload);
                if (todo) todo.completed = !todo.completed;
                break;
            }

            case DELETE_TODO:
                draft.todos = draft.todos.filter((t) => t.id !== action.payload);
                break;
        }
    });
};

useReducer는 상태를 바꾸는 로직을 한 군데 모아두는 방식이다. 상태가 복잡해질수록 useState보다 훨씬 관리하기 편하다.

여기에 Immer를 같이 쓰면 draft를 직접 수정하듯이 코드를 쓸 수 있다. 실제로는 원본 state를 건드리는 게 아니라 Immer가 알아서 새 상태를 만들어주는 거라 불변성은 지켜진다.

useCallback

const addTodo = useCallback((todo) => {
    dispatch({ type: ADD_TODO, payload: todo });
}, []);

const toggleTodo = useCallback((id) => {
    dispatch({ type: TOGGLE_TODO, payload: id });
}, []);

useCallback은 함수를 메모이제이션해주는 훅이다. dispatch는 useReducer가 항상 같은 참조를 보장해주기 때문에 의존성 배열을 []로 써도 된다. 덕분에 이 함수들은 컴포넌트가 처음 렌더링될 때 딱 한 번만 만들어지고, 자식 컴포넌트에 넘겨도 참조가 바뀌지 않아서 불필요한 리렌더링을 줄일 수 있다.

useMemo

const filteredTodos = useMemo(() => {
    return state.todos.filter((todo) => {
        const matchFilter =
            state.filter === "all" ||
            (state.filter === "active" && !todo.completed) ||
            (state.filter === "completed" && todo.completed);

        const matchesSearch = todo.text
            .toLowerCase()
            .includes(state.searchQuery.toLowerCase());

        return matchFilter && matchesSearch;
    });
}, [state.todos, state.filter, state.searchQuery]);

필터링을 Todos 페이지 안에서 하면 관련 없는 이유로 리렌더링이 일어날 때도 매번 다시 계산한다. App에서 useMemo로 미리 계산해두면 todos, filter, searchQuery 이 세 값 중 하나라도 바뀔 때만 다시 계산하고, 그 외엔 이전 결과를 그대로 쓴다.

props를 객체로 묶어서 스프레드로 전달하는 방식

const todoProps = {
    todos: state.todos,
    filteredTodos,
    filter: state.filter,
    searchQuery: state.searchQuery,
    addTodo,
    toggleTodo,
    deleteTodo,
    updateTodo,
    setFilter,
    setSearchQuery,
    clearCompleted,
};

// 사용할 때
<Todos {...todoProps} />

자식한테 넘길 props가 많아지면 하나씩 쓰는 게 너무 길어진다. 객체로 묶어서 스프레드로 한 번에 넘기면 코드가 훨씬 깔끔해진다. 물론 props가 몇 개 안 된다면 그냥 직접 넘기는 게 낫다.

BrowserRouter & 동적 라우팅

// App.jsx
<BrowserRouter>
    <Navigation />
    <Routes>
        <Route path="/" element={<Home todos={state.todos} />} />
        <Route path="/todos" element={<Todos {...todoProps} />} />
        <Route path="/statistics" element={<Statistics todos={state.todos} />} />
        <Route path="/posts" element={<PostList posts={POSTS} />} />
        <Route path="/posts/:id" element={<PostDetail posts={POSTS} />} />
    </Routes>
</BrowserRouter>

BrowserRouter로 감싸면 URL이 바뀔 때 페이지 새로고침 없이 해당 컴포넌트로 전환된다. 보통 main.jsx에서 쓰는데 App.jsx에서 써도 된다.

/posts/:id처럼 :id 부분을 동적으로 처리하면 게시글마다 다른 URL을 가질 수 있다. 해당 페이지에서는 useParams()로 URL에 있는 값을 꺼내 쓴다.

// PostDetail.jsx
import { useParams } from "react-router-dom";

const { id } = useParams(); // URL의 :id 값
const post = posts.find((p) => p.id === parseInt(id)); // URL 파라미터는 문자열이라 parseInt 필요

Todo 앱 만들기

전체 라우팅 구조

/             -> Home       (요약 통계 + 이동 버튼)
/todos        -> Todos      (할 일 CRUD + 필터/검색)
/statistics   -> Statistics (우선순위/카테고리별 통계)
/posts        -> PostList   (게시글 목록)
/posts/:id    -> PostDetail (동적 라우팅으로 상세 보기)

폴더 구조

src/
├── components/
│   ├── Navigation.jsx   # 상단 공통 네비게이션
│   ├── TodoForm.jsx     # 할 일 입력 폼
│   ├── TodoList.jsx     # 할 일 목록 렌더링
│   ├── TodoItem.jsx     # 개별 할 일 항목 (수정/삭제/토글)
│   └── FilterBar.jsx    # 필터 버튼 + 검색창
├── pages/
│   ├── Home.jsx
│   ├── Todos.jsx
│   ├── Statistics.jsx
│   ├── PostList.jsx
│   └── PostDetail.jsx
└── App.jsx

주요 코드 설명

App.jsx — 상태 관리 허브

todos, filter, searchQuery 전체 상태를 useReducer 하나로 관리한다. useCallback으로 만든 함수들과 useMemo로 계산한 filteredTodos를 todoProps로 묶어서 Todos 페이지에 넘겨준다.

const [state, dispatch] = useReducer(todoReducer, initialState);

const todoProps = {
    todos: state.todos,
    filteredTodos,
    filter: state.filter,
    // ...
};

TodoForm.jsx — 입력 폼

export const TodoForm = memo(({ addTodo }) => {
    const [text, setText] = useState("");
    const [priority, setPriority] = useState("medium");
    const [category, setCategory] = useState("기타");

    const handleSubmit = useCallback(
        (e) => {
            e.preventDefault();
            if (text.trim()) {
                addTodo({ text: text.trim(), priority, category });
                setText("");
                setPriority("medium");
                setCategory("기타");
            }
        },
        [text, priority, category, addTodo],
    );
    // ...
});

React.memo로 감싸서 addTodo 참조가 바뀌지 않는 한 리렌더링되지 않게 했다. 입력값은 굳이 App까지 올릴 필요가 없어서 로컬 useState로 관리한다.

TodoItem.jsx — 수정 모드 전환

const [isEditing, setIsEditing] = useState(false);
const [editText, setEditText] = useState(todo.text);

const handleSave = () => {
    if (editText.trim()) {
        updateTodo(todo.id, { text: editText });
        setIsEditing(false);
    }
};

const handleCancel = () => {
    setEditText(todo.text); // 원본으로 되돌리기
    setIsEditing(false);
};

isEditing으로 보기 모드와 수정 모드를 전환한다. 취소를 누르면 todo.text(원본 텍스트)로 다시 세팅해서 수정 전 상태로 돌아간다.

TodoList.jsx — 이중 메모이제이션

export const TodoList = memo(({ filteredTodos, toggleTodo, deleteTodo, updateTodo }) => {
    const memoizedTodos = useMemo(() => {
        return filteredTodos.map((todo) => (
            <TodoItem key={todo.id} todo={todo} ... />
        ));
    }, [filteredTodos, toggleTodo, deleteTodo, updateTodo]);

    // ...
});

• memo : TodoList 자체가 리렌더링될 필요가 있는지 확인
• useMemo : TodoItem 배열을 새로 만들 필요가 있는지 확인

Navigation.jsx — displayName

export const Navigation = memo(() => {
    // ...
});

Navigation.displayName = "Navigation";

memo()로 감싸면 React DevTools에서 컴포넌트 이름이 "memo(Anonymous)"로 뜬다. displayName을 지정해두면 DevTools에서 제대로 된 이름으로 보여서 디버깅할 때 편하다.

정리

가위바위보

컴포넌트 분리

UI를 역할별로 나눠서 관리했다. App.jsx가 전체 게임 상태를 관리하고, Button과 Card는 각각 버튼과 카드 UI만 담당했다.

useState로 상태 관리

게임에 필요한 상태들을 useState로 관리했다.

const [userChoice, setUserChoice] = useState(null);
const [computerChoice, setComputerChoice] = useState(null);
const [result, setResult] = useState(null);
const [isPlaying, setIsPlaying] = useState(false);

props로 데이터 전달

부모 컴포넌트(App)에서 자식 컴포넌트(Card, Button)로 props를 통해 데이터를 전달했다.

<Card userTitle="유저" choice={userChoice} result={result} type="user" />

CSS Module

CSS Module을 사용해 클래스명이 겹치지 않도록 스타일을 컴포넌트별로 분리했다.

import css from "./css/App.module.css";

<div className={css.container}>

숫자 맞추기 게임 만들기

가위바위보 코드를 응용해서 1~10 사이의 숫자를 맞추는 게임을 만들었다. 컴퓨터가 랜덤으로 숫자를 정해두고, 유저가 버튼을 클릭해서 맞추는 방식이다. 힌트로 "더 높아요 ⬆️ / 더 낮아요 ⬇️"를 보여주고, 시도 횟수와 정답률도 표시된다.

폴더 구조

src/
├── components/
│   ├── NumberButtons.jsx   # 숫자 버튼
│   ├── ResultMessage.jsx   # 결과 메시지
│   └── ScoreBoard.jsx      # 점수판
├── css/
│   ├── App.module.css
│   ├── NumberButtons.module.css
│   └── ScoreBoard.module.css
└── App.jsx

주요 코드 설명

App.jsx — 게임 상태 관리

const [userChoice, setUserChoice] = useState(null);
const [computerChoice, setComputerChoice] = useState(
    Math.floor(Math.random() * 10) + 1
);
const [result, setResult] = useState(null);
const [count, setCount] = useState(0);

가위바위보와 다르게 컴퓨터 선택을 게임 시작 시 바로 정해두고, 유저가 맞출 때까지 유지한다.

결과 판단 로직

const numberChoiceResult = (user, computer) => {
    if (user === computer) return "정답이에요 🎉";
    if (user > computer) return "더 낮아요 ⬇️";
    return "더 높아요 ⬆️";
};

가위바위보의 determineWinner 함수를 응용해서 숫자 비교 로직으로 바꿨다.

정답률 계산

const correctRate =
    result === "정답이에요 🎉" ? Math.round((1 / count) * 100) + " %" : "-";

정답을 맞췄을 때만 정답률을 계산한다. 1번에 맞추면 100%, 5번에 맞추면 20%.

ResultMessage.jsx — 결과 메시지 컴포넌트

export const ResultMessage = ({ result, choice }) => {
    let resultSubMessage = "버튼을 클릭해 보세요!";
    if (result === "정답이에요 🎉") resultSubMessage = "게임을 다시 시작해 보세요!";
    if (result === "더 높아요 ⬆️") resultSubMessage = "보다 높은 숫자를 골라보세요.";
    if (result === "더 낮아요 ⬇️") resultSubMessage = "보다 낮은 숫자를 골라보세요.";

    return (
        <div>
            <h3>{result}</h3>
            <p>{result === "정답이에요 🎉" ? resultSubMessage : `${choice || ""} ${resultSubMessage}`}</p>
        </div>
    );
};

결과에 따라 다른 안내 메시지를 보여준다. 정답이 아닐 때는 유저가 선택한 숫자도 함께 표시된다.

React는 Facebook(현 Meta) 이 2013년에 오픈소스로 공개한 UI 구축을 위한 JavaScript 라이브러리다. 지속적으로 데이터가 변화하는 대규모 애플리케이션을 효율적으로 구축하기 위해 만들어졌으며, 현재 가장 널리 사용되는 프론트엔드 기술 중 하나다.

프레임워크 vs 라이브러리

React를 제대로 이해하려면 먼저 이 둘의 차이를 알아야 한다.

프레임워크 (Framework)

• 뼈대, 골조
• 개발자가 정해진 규칙 안에서 코드를 작성해야 함
• 주도권이 프레임워크에 있음
• ex) Angular, Next.js, Django, Spring

라이브러리 (Library)

• 도서관에서 책을 꺼내오듯 필요한 기능만 가져다 쓰는 방식
• 특정 기능을 수행하는 도구로서, 개발자가 원하는 시점에 직접 호출
• 주도권이 개발자에게 있음
• ex) React, Lodash, Axios

✅ React는 라이브러리다. 라우팅(React Router), 상태관리(Redux, Zustand) 등은 React가 직접 제공하지 않고 별도 라이브러리를 조합해서 사용한다. 이것이 프레임워크인 Angular와의 가장 큰 차이점이다.

React의 핵심 개념

1. SPA (Single Page Application)

React는 SPA 방식으로 동작한다.

전통적인 웹(MPA)은 페이지를 이동할 때마다 서버에서 새로운 HTML을 받아와 화면 전체를 새로 그린다. 반면 SPA는 하나의 HTML 파일 안에서 JavaScript가 필요한 부분만 동적으로 교체하기 때문에 페이지 깜빡임 없이 앱처럼 부드럽게 동작한다.

MPA vs SPA 비교

2. 컴포넌트 (Component)

React 애플리케이션은 컴포넌트 단위로 구성된다. UI를 독립적이고 재사용 가능한 조각으로 나눠서 개발하는 것이 핵심이다.

좋은 컴포넌트의 조건

• 단독으로 기능을 수행할 수 있어야 한다.
• 재사용이 가능하면서 최소한 하나의 기능이 내장되어 있어야 한다.
• 화면만 보여주는 컴포넌트(Presentational Component)만 있을 수도 있지만, 데이터 처리나 이벤트 핸들링 없이 UI만 그리는 컴포넌트는 좋은 설계라고 보기 어렵다.

// 예시: 버튼 컴포넌트
function Button({ label, onClick }) {
  return <button onClick={onClick}>{label}</button>;
}

3. Virtual DOM

일반적인 DOM 조작은 변경이 생길 때마다 브라우저가 전체 렌더링을 다시 수행해서 느리다.

React는 Virtual DOM(가상 DOM) 을 사용해 이 문제를 해결한다.

동작 방식

1. 상태(state)가 변경되면 새로운 Virtual DOM을 생성한다.
2. 이전 Virtual DOM과 새 Virtual DOM을 비교(Diffing) 한다.
3. 실제로 변경된 부분만 찾아 Real DOM에 최소한으로 반영한다.

이 과정을 재조정(Reconciliation) 이라고 한다. 덕분에 데이터가 빈번하게 바뀌는 대규모 앱에서도 빠른 성능을 유지할 수 있다.

4. 라이프사이클 (Life Cycle)

React 컴포넌트는 생성되고 → 업데이트되고 → 사라지는 생명주기를 가진다.

클래스형 컴포넌트 방식 (구 방식)

class MyComponent extends React.Component {
  componentDidMount() { /* 마운트 후 실행 */ }
  componentDidUpdate() { /* 업데이트 후 실행 */ }
  componentWillUnmount() { /* 언마운트 전 실행 */ }
  render() { return <div>Hello</div>; }
}

함수형 컴포넌트 방식 (현재 표준)

import { useEffect } from 'react';

function MyComponent() {
  useEffect(() => {
    // 마운트 시 실행
    return () => {
      // 언마운트 시 실행 (클린업)
    };
  }, []); // 의존성 배열

  return <div>Hello</div>;
}

현재는 함수형 컴포넌트 + Hooks 방식이 표준이다. 클래스형은 레거시 코드에서 마주칠 수 있으므로 읽을 줄은 알아야 한다.

프로젝트 시작하기

방법 1: Create React App (CRA)

npx create-react-app my-app
cd my-app
npm start

• 설정 없이 바로 시작할 수 있어 입문자에게 적합하다.
• 다만 빌드 속도가 느리고 불필요한 설정이 많아 최근에는 잘 사용하지 않는 추세다.

방법 2: Vite (권장) ⭐

npm create vite@latest   # 최신 Vite 버전으로 프로젝트 생성

• CRA보다 빌드 속도가 훨씬 빠르다.
• 가볍고 설정이 유연해서 현재 가장 많이 사용되는 방식이다.
• 실행 후 프레임워크(React), 언어(JS/TS) 등을 선택하면 된다.

1. 터미널 창에 명령어 입력 (npm create vite@latest) > 프로젝트 이름 입력 > react 선택 > JavaScript 선택
2. npm run dev 입력 시 아래와 이미지와 같이 초기화면이 뜬다.

폴더 구조

Vite 기준으로 생성된 기본 폴더 구조는 다음과 같다.

my-app/
├── public/              # 정적 파일 (빌드 시 그대로 복사됨)
│   └── favicon.ico      # 거의 바뀌지 않는 이미지 (파비콘 등)
│
├── src/                 # 실제 개발이 이루어지는 폴더
│   ├── assets/          # 개발 중 변경될 수 있는 이미지, 폰트 등
│   ├── components/      # 재사용 가능한 컴포넌트 모음
│   ├── pages/           # 라우트별 페이지 컴포넌트
│   ├── App.jsx          # 루트 컴포넌트
│   └── main.jsx         # 진입점 (ReactDOM.render)
│
├── index.html           # 앱의 HTML 껍데기
├── vite.config.js       # Vite 설정 파일
└── package.json         # 프로젝트 정보 및 의존성 목록

public vs src/assets 차이

정리

재사용 가능한 디자인 요소. 자주 쓰는 UI를 컴포넌트로 만들어두면 효율적으로 작업할 수 있다.

인스턴스 (Instance)

컴포넌트를 복사하면 생기는 일시적인 복사본.

• 기본적으로 부모(원본) 컴포넌트의 속성을 따라간다
• 단, 인스턴스에서 개별적으로 속성을 변경하면 부모 변경사항이 반영되지 않는다

에셋 (Assets)

에셋 탭에서 내가 만든 컴포넌트를 불러와 사용할 수 있다.

메인 컴포넌트로 푸시 (Push to Main Component)

다른 페이지에서 에셋으로 컴포넌트를 만든 후, 메인 페이지로 이동시킬 수 있다.

Create Multiple Components

여러 요소를 한 번에 컴포넌트로 만드는 기능. 각각 일일이 만들지 않아도 되어서 작업 속도가 빨라진다.

베리언트 (Variant)

컴포넌트에 속성(Property)을 부여해서 다양한 변형을 관리하는 기능.

• 속성을 정의하면 그 조합만큼 자동으로 변형 세트가 생성된다
• 에셋에서 인스턴스를 가져온 후, 속성 패널에서 원하는 값으로 바꾸는 것만으로 디자인 변경 가능

인터랙션 (Interaction)

피그마에서 컴포넌트에 동작을 부여하는 기능. 프로토타입처럼 실제 앱과 유사한 UX를 구현할 수 있다.

1. 피그마 시작하기

1. 사이트 접속 및 로그인
2. 팀 만들기
3. 초안(Draft) 만들기

2. 그룹 vs 프레임 vs 컴포넌트 차이

	그룹 (Group)	프레임 (Frame)	컴포넌트 (Component)
역할	단순 묶음	레이아웃 단위	재사용 단위
크기	내부 요소에 따라 자동 조절	고정 크기 설정 가능	고정 크기 설정 가능
특징	클리핑 없음	클리핑 가능, 컨스트레인트·오토레이아웃 동작	인스턴스로 복제, 원본 수정 시 전체 반영
언제 쓰나	임시로 요소 묶을 때	화면/섹션 구성할 때	버튼, 카드 등 반복 요소

3. 컨스트레인트(Constraints)란?

컨스트레인트는 프레임 크기가 변할 때 내부 요소의 위치와 크기가 어떻게 반응할지 설정하는 기능이다.

쉽게 말해 요소를 상하좌우 어디에 고정할지, 아니면 프레임에 맞게 늘어날지를 정해주는 것이다. 반응형 디자인을 구현할 때 핵심적으로 쓰인다.

4. 오토레이아웃(Auto Layout)이란?

오토레이아웃은 요소들 사이의 간격과 방향을 자동으로 정렬해주는 기능이다.

버튼 안의 텍스트가 길어지면 버튼 크기가 자동으로 늘어나고, 목록에 항목을 추가하면 간격을 유지하면서 자동으로 밀려난다.

개발로 치면 CSS의 Flexbox와 거의 동일한 개념으로, 방향(가로/세로), 간격(gap), 정렬(align)을 설정할 수 있다.

컨스트레인트와 헷갈릴 수 있는데 아래와 같이 구분하면 쉽다.

컨스트레인트 → 프레임 기준으로 요소의 위치를 고정 *오토레이아웃 → *요소들끼리의 간격과 정렬을 자동으로 유지

5. 서비스 디자인 기획 실습

운동도 공부도 해야 한다는 건 안다. 근데 막상 시작이 안 되고, 미루고, 결국 벼락치기를 반복한다. 이 사이클이 반복되는 이유가 뭔지 알고 싶었다.

_기존 습관 앱은 전부 "오늘도 성공!" 에만 집중한다. _

그래서 기획한 서비스가 작심삼일 해부소다. 실패를 기록하고, 패턴을 분석하고, 내가 무너지는 순간을 데이터로 보여주는 사이트이다.

6. 페르소나 만들기

서비스 기획에 이어 피그마로 페르소나도 직접 만들어봤다. 꾸준함을 원하지만 매번 같은 패턴으로 실패하는 26세 직장인 김지현을 설정했다.

마무리

툴 사용법을 익히는 것도 중요하지만, "무엇을 만들 것인가"가 더 중요하다는 걸 느꼈다.

작심삼일 해부소는 그냥 실습 과제가 아니라 진짜 만들어보고 싶은 서비스다. 앞으로 배우는 것들을 하나씩 적용해서 직접 완성해보는 게 목표다.

CX는 단순한 화면 디자인이 아니라 사용자가 서비스를 경험하는 모든 순간을 설계하는 것이다. UI/UX는 CX의 하위 개념이다.

💡 핵심은 계속 쓰게 만드는 것이다. 사용자가 앱을 다시 열고 싶게 만드는 경험 설계가 최우선이다.

온보딩의 중요성

첫 경험이 전부다. 온보딩을 어떻게 설계하느냐에 따라 사용자의 재방문율이 크게 달라진다.
가이드와 튜토리얼을 충실히 설계하자.

모바일 vs 웹 배치는 다르다

모바일과 웹은 화면 크기뿐 아니라 사용 맥락, 인터랙션 방식, 정보 우선순위 배치가 완전히 다르다.
각각의 기기에 맞는 설계가 필요하다.

2. 색(Color) 설계

색의 역할

• 브랜드 아이덴티티 각인 - 서비스를 기억하게 만드는 시각적 각인
• 마케팅 관점에서 클릭 유도 - 할인 정보, 프로모션 배너 등
• 방향 제시 - 구매하기 버튼, 다음 단계 안내 등

키 컬러는 생각보다 적게 쓴다

키 컬러(Primary Color)는 포인트로만 사용한다. 스타벅스나 이마트도 매장에서 초록색·노란색이 넘쳐나지 않는다. 로고, 간판, 핵심 CTA 버튼 등 꼭 필요한 곳에만 집중 배치하기 때문에 오히려 눈에 잘 띄는 것이다.

색의 종류

알아두면 좋은 것들

1. 검은색은 검은색이 아니다 : 그림자와 오버레이에 순수한 #000000 대신 브랜드 컬러가 살짝 섞인 어두운 색을 사용하면 훨씬 자연스럽고 세련된 결과가 나온다. 2. 그림자에 다양한 색을 시도해보자 : 검정 그림자 외에도 보라, 파랑 등 다른 색을 써보면 깊이감과 개성을 줄 수 있다. 3. 돈 관련 프로젝트는 보수적으로 : 금융 서비스에서는 화려한 색보다 신뢰감 있는 중립적 색상 설계가 더 중요하다.

3. 사용성 (Usability)

좋은 사용성이란 사용자가 기대하는 동작을 그대로 구현하는 것이다.

• 엔터키로 로그인 - 버튼 클릭 없이도 동작해야 한다
• 정보를 모두 입력한 후 다음 단계로 - 필수 입력값이 빠진 상태에서 다음 단계로 넘어가지 않도록
• 스켈레톤 UI - 로딩 중에도 레이아웃을 유지해 사용자의 불안감을 줄여준다

4. 디자인 시스템

디자인 시스템 장점 4가지 ⭐

1. 시각적 일관성 : 동일한 형태로 제작, 유사한 모양의 구성 요소들이 일관된 시각적 패턴을 형성
2. 기능적 일관성 : 같은 동작은 항상 같은 방식으로 작동
3. 내부 일관성 : 서비스 내부에서 서로 다른 영역 간의 통일성
4. 외부 일관성 : 타 서비스나 플랫폼 관습에 맞춰 사용자 기대를 충족

디자인 시스템의 구조 ⭐

1. 개요 (Overview) : 일련의 디자인 원칙(Design Principles)을 문서화
2. 파운데이션 (Foundation) : 가장 기초가 되는 디자인 요소의 모음 (아이콘, 폰트 크기, 색상, 폰트)
3. 컴포넌트 (Component) : 디자인 시스템에서 재사용 가능한 구성 요소
4. 패턴 (Pattern) : 사용자가 목표를 달성하려고 사용하는 방법의 모범 사례
5. 기타 : 기업에 따라 커뮤니티를 구성하거나 자료를 공유하는 링크 제공

5. 아토믹 디자인 (Atomic Design) ⭐

브래드 프로스트(Brad Frost)가 고안한 디자인 시스템으로, 디자이너와 개발자 사이의 협업이 용이하도록 UI를 원자 단위부터 계층적으로 구성한다.

원자(Atom) → 분자(Molecule) → 유기체(Organism) → 템플릿(Template) → 페이지(Page)

• 원자 : 버튼, 인풋, 아이콘 등 더 이상 쪼갤 수 없는 최소 단위
• 분자 : 원자가 모여 하나의 역할을 하는 단위 (ex. 검색창 = 인풋 + 버튼)
• 유기체 : 분자가 모여 독립적인 영역을 이루는 단위 (ex. 헤더, 카드 리스트)
• 템플릿 : 유기체를 배치한 페이지 레이아웃
• 페이지 : 실제 콘텐츠가 채워진 최종 화면

6. 디자인 프로세스 방법론

더블 다이아몬드 (Double Diamond) ⭐

문제를 발산과 수렴 두 단계로 반복하며 접근하는 방법론이다.

애자일 프로세스 (Agile Process) ⭐

사용자(이때의 사용자는 진짜 사용자가 아닌 해당 제품을 요구한 회사)의 요구사항을 끊임없이 반영하고 점진적으로 제품을 업데이트하여 서비스가 추구하는 가치를 구현하는 프로세스

린 프로세스 (Lean Process) ⭐

기업이 가정한 시장 상황을 테스트하기 위해 프로토타입을 만들고, 일반 사용자의 피드백을 받아 빠르게 발전시키는 프로세스

📝 차이 포인트: 애자일의 '사용자'는 클라이언트(요청 기업), 린의 '사용자'는 실제 최종 사용자다.

7. 와이어프레임 (Wireframe) ⭐

디자인의 뼈대를 잡는 단계로, 색상이나 비주얼 없이 레이아웃과 구조, 정보 우선순위를 결정한다.
실제 개발 전에 방향을 확인하고 수정 비용을 줄이는 데 핵심적인 역할을 한다.

마치며

오늘 수업이 꽤 흥미로웠다. 디자인이 단순히 예쁜 것을 만드는 게 아니라, 사용자가 편하게 쓸 수 있어야 한다는 것. 그리고 색상도 그냥 쓰는 게 아니라 Primary, Semantic 등 역할이 정해져 있다는 게 신기했다. 앞으로 프로젝트할 때 디자인을 어떻게 접근해야 할지 감이 좀 잡힌 것 같다.

포롱은 팝업스토어 정보를 한 곳에서 탐색하고, 예약·리뷰·키링 수집까지 할 수 있는 웹 서비스이다. 팝업스토어 정보를 인스타그램이나 각종 SNS에서 일일이 찾아야 하는 불편함을 해소하고자 기획했다.

• 슬로건: 찾고, 모으고, 포롱.
• 팀: 이주현 · 고유정 · 서지현 (유레카 4기)
• GitHub: https://github.com/Po-Rong

내가 맡은 기능

• 로그인 / 회원가입
• 관리자(판매자) 페이지
  • 대시보드 요약 카드 (이번달 예약 수 · 평균 별점 · 총 리뷰)
  • 팝업스토어 등록 · 수정 · 삭제
  • 내 팝업스토어 목록 조회
  • 팝업별 후기 탭 조회
  • 예약 고객 조회 · 예약 취소 (날짜별 페이징)

구현 방법

1. 진입 제한 - 판매자만 접근 가능

관리자 페이지는 seller 권한을 가진 사용자만 접근할 수 있어야 했다. 페이지 로드 시 로컬스토리지에서 로그인 정보를 꺼내 권한을 확인하고, 조건에 맞지 않으면 즉시 메인 페이지로 튕겨낸다.

const user = JSON.parse(localStorage.getItem("loginUser"));

if (!user || user.role !== "seller") {
    alert("판매자만 접근 가능합니다.");
    location.href = "/index.html";
}

로그인하지 않은 경우(!user)와 일반 사용자인 경우 모두 같은 로직으로 처리했다.

2. 대시보드 요약 카드

판매자가 페이지에 들어오면 이번달 예약 수, 평균 별점, 총 리뷰 수를 한눈에 볼 수 있도록 요약 카드를 구현했다. API 한 번 호출로 3가지 데이터를 한 번에 받아서 각 카드에 뿌렸다.

function loadSummary() {
    fetch(`${API}/admin/summary?seller_id=${user.userId}`)
        .then((res) => res.json())
        .then((data) => {
            document.getElementById("statMonthlyReservation").textContent = data.monthlyReservationCount;
            document.getElementById("statAverageRating").textContent = data.averageRating;
            document.getElementById("statTotalReview").textContent = data.totalReviewCount;
        });
}

3. 팝업스토어 목록 - 수정/삭제 이벤트 분리

팝업 카드 전체를 클릭하면 상세 페이지로 이동하는데, 카드 안에 수정/삭제 버튼도 함께 있었다. 버튼 클릭 시 카드 클릭 이벤트도 같이 실행되는 문제가 있어서 event.stopPropagation()으로 이벤트 버블링을 막았다.

div.innerHTML = `
    <button onclick="event.stopPropagation(); location.href='/pages/popup-edit.html?id=${popup.id}'">수정</button>
    <button onclick="event.stopPropagation(); deletePopup(${popup.id})">삭제</button>
`;

삭제 후에는 페이지 전체를 reload하지 않고 loadPopupList()만 다시 호출해서 목록을 갱신하였다.

function deletePopup(popupId) {
    if (!confirm("정말 삭제하시겠습니까?")) return;

    fetch(`${API}/popups/${popupId}?seller_id=${user.userId}`, {
        method: "DELETE",
    })
        .then((res) => res.json().then((data) => ({ ok: res.ok, data })))
        .then(({ ok, data }) => {
            if (ok) {
                alert(data.message);
                loadPopupList();
            }
        });
}

4. 이미지 저장 - 로컬 업로드 방식

팝업 등록·수정 시 이미지를 어떻게 저장하고 불러올지가 가장 큰 고민이었다. 배포 환경이 아니다 보니 S3 같은 클라우드 스토리지를 쓸 수 없었고, DB에 직접 저장하는 것도 부담이었다.

백엔드 프로젝트 루트의 /uploads 폴더에 이미지를 저장하고, 해당 파일의 URL을 DB에 저장하는 방식으로 구현했다. 파일명은 UUID로 중복을 방지하고, 쿼리스트링이 포함된 파일명은 전처리로 제거했다.

private String saveImage(MultipartFile file) {
    try {
        String uploadDir = System.getProperty("user.dir") + "/uploads/";

        File dir = new File(uploadDir);
        if (!dir.exists()) {
            dir.mkdirs();
        }

        // 쿼리스트링 제거
        String originalFilename = file.getOriginalFilename();
        if (originalFilename != null && originalFilename.contains("?")) {
            originalFilename = originalFilename.split("\\?")[0];
        }

        String fileName = UUID.randomUUID() + "_" + originalFilename;
        file.transferTo(new File(uploadDir + fileName));

        return "http://localhost:8080/uploads/" + fileName;
    } catch (IOException e) {
        throw new RuntimeException("이미지 저장 실패", e);
    }
}

5. 후기 목록 - 팝업별 그룹화 + 탭

전체 후기를 팝업별로 탭으로 나눠서 볼 수 있도록 구현했다. API에서 받은 전체 후기를 popupTitle 기준으로 객체에 그룹화한 뒤, 탭을 동적으로 생성했다.

// 팝업별로 그룹화
const grouped = {};
data.forEach((review) => {
    const key = review.popupTitle;
    if (!grouped[key]) {
        grouped[key] = { popupTitle: review.popupTitle, reviews: [] };
    }
    grouped[key].reviews.push(review);
});

// 전체 탭
const allTab = document.createElement("button");
allTab.textContent = `전체 (${data.length})`;
allTab.addEventListener("click", () => renderReviewCards(data, "all"));

// 팝업별 탭
groups.forEach((group, groupIndex) => {
    const tab = document.createElement("button");
    tab.textContent = `${group.popupTitle} (${group.reviews.length})`;
    tab.addEventListener("click", () => renderReviewCards(group.reviews, groupIndex));
});

탭 클릭 시 renderReviewCards()에 해당 후기 배열만 넘겨서 다시 렌더링하는 방식이다.

6. 예약 목록 - 날짜별 그룹 + 더보기 페이징

예약 목록을 전부 불러오면 데이터가 너무 많아 UX가 나빠질 것 같았다. 일반적인 row 단위 페이징 대신 날짜 단위 페이징으로 구현했다.

백엔드에서 DISTINCT DATE(reserve_date)로 날짜 목록만 페이징해서 가져오고, 각 날짜별 예약자 목록을 따로 조회해서 묶는 방식이다. 더보기 버튼은 hasNext 값으로 다음 데이터가 있는지 판단해서 표시 여부를 결정한다.

function loadReservationList(page = 0) {
    fetch(`${API}/reservations?seller_id=${user.userId}&year=${selectedYear}&month=${selectedMonth}&page=${page}&size=2`)
        .then((res) => res.json())
        .then((data) => {
            if (page === 0) reservationList.innerHTML = ""; // 첫 페이지면 초기화

            data.content.forEach(({ date, reservations }) => {
                const group = document.createElement("div");
                group.innerHTML = `<p class="date-label">${formatFullDate(date)}</p>`;
                // 날짜별 예약 카드 렌더링
            });

            if (data.hasNext) {
                const btn = document.createElement("button");
                btn.textContent = "더보기";
                btn.onclick = () => {
                    reservationPage++;
                    loadReservationList(reservationPage);
                };
                reservationList.appendChild(btn);
            }
        });
}

page === 0일 때만 목록을 초기화해서 더보기를 눌렀을 때 기존 목록 아래에 자연스럽게 추가되도록 했다.

7. 드래그 스크롤

가로 스크롤 카드 리스트에서 마우스로 드래그해서 스크롤할 수 있도록 구현했다. 핵심은 드래그 중에 카드 클릭 이벤트가 실행되지 않도록 막는 부분이다.

function initDragScroll(containerId) {
    const container = document.getElementById(containerId);
    let isDown = false;
    let isDragging = false;
    let startX, scrollLeft;

    container.addEventListener("mousedown", (e) => {
        isDown = true;
        isDragging = false;
        startX = e.pageX - container.offsetLeft;
        scrollLeft = container.scrollLeft;
    });

    container.addEventListener("mousemove", (e) => {
        if (!isDown) return;
        isDragging = true;
        const walk = (e.pageX - container.offsetLeft - startX) * 1.5;
        container.scrollLeft = scrollLeft - walk;
    });

    // 드래그 중 클릭 방지
    container.addEventListener("click", (e) => {
        if (isDragging) {
            e.stopPropagation();
            isDragging = false;
        }
    }, true);
}

isDragging 플래그로 드래그 여부를 추적하고, 드래그 중일 때는 click 이벤트를 stopPropagation()으로 막았다.

회고

잘한 점

기획부터 개발, 디자인까지 팀원 셋이 역할 구분 없이 다 직접 해냈다. 생각보다 많은 기능을 구현할 수 있었고, 끝까지 완성했다는 것 자체가 잘한 것 같다.

아쉬운 점

이번 프로젝트를 하면서 AI 의존도가 많이 높았던 것 같다. 모르는 게 생기면 스스로 찾아보기보다 AI한테 먼저 물어보는 습관이 생긴 것 같아서 아쉽다. 앞으로는 충분히 공부해서 내가 방향을 먼저 제안하고, AI를 도구로 활용하는 방식으로 발전해 나가야겠다.

그래도 AI 덕분에 이전이라면 구현하는 데 오래 걸렸을 것들을 빠르게 만들어낼 수 있었고, 그 시간을 사용자 경험 개선에 더 쏟을 수 있었던 건 분명한 장점이었다.

배운 점

개발은 기능 구현으로 끝나지 않는다는 걸 배웠다. 다 만들었다고 생각했는데 테스트하면서 새로운 버그가 나오고, 사용자 입장에서 보면 고칠 부분이 계속 생겼다. 좋은 서비스는 끊임없는 개선에서 나온다는 걸 몸소 느꼈다.

1. 카카오 앱 생성 및 설정

1. https://developers.kakao.com/ 사이트 접속 > 로그인 > 앱 > 앱 생성

2. 생성한 앱 클릭 > 카카오맵 클릭 > 사용 설정 활성화

3. 플랫폼 키 선택 > JavaScript 키 추가 버튼 클릭

4. 키 이름 입력 > JavaScript SDK 도메인 입력 후 저장

도메인은 http://127.0.0.1:5500 으로 입력했다. 카카오 맵 API는 등록된 도메인에서만 동작하기 때문에 반드시 입력해야 한다. 로컬 개발 환경에서는 VS Code의 Live Server 확장을 사용했는데, Live Server가 기본적으로 127.0.0.1:5500 포트로 실행되기 때문에 해당 주소를 등록했다.

5. 생성된 키 값 복사

2. 지도에 주소 마킹하기

발급받은 JavaScript 키를 appkey 파라미터에 넣고, 원하는 좌표에 커스텀 마커를 표시하는 예제다.

<!doctype html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>빵집 마커 띄우기</title>
    </head>
    <body>
        <div id="map" style="width: 100%; height: 500px"></div>

        <!-- 카카오 맵 SDK 로드 (appkey에 발급받은 JavaScript 키 입력) -->
        <script
            type="text/javascript"
            src="//dapi.kakao.com/v2/maps/sdk.js?appkey=발급받은_JavaScript_키"
        ></script>

        <script>
            // 지도를 표시할 div와 옵션 설정
            var mapContainer = document.getElementById("map"),
                mapOption = {
                    center: new kakao.maps.LatLng(37.566826, 126.9786567), // 서울시청 기준
                    level: 4, // 지도 확대 레벨 (숫자가 작을수록 확대)
                };

            // 지도 생성
            var map = new kakao.maps.Map(mapContainer, mapOption);

            // 1. 마커 이미지 경로, 크기, 기준점 설정
            var imageSrc = "/assets/images/bakery.png",
                imageSize = new kakao.maps.Size(64, 64), // 마커 이미지 크기 (가로 64, 세로 64)
                // ⭐ 가로 정중앙(32), 세로 바닥(64)을 지도의 좌표점과 일치시킴
                imageOption = { offset: new kakao.maps.Point(32, 64) };

            // 2. 마커 이미지 객체 생성
            var markerImage = new kakao.maps.MarkerImage(
                    imageSrc,
                    imageSize,
                    imageOption,
                ),
                markerPosition = new kakao.maps.LatLng(37.566826, 126.9786567);

            // 3. 마커 생성 후 지도에 표시
            var marker = new kakao.maps.Marker({
                position: markerPosition,
                image: markerImage,
            });

            marker.setMap(map);
        </script>
    </body>
</html>

3. 실행 결과

4. 느낀 점

생각보다 초기 설정이 간단하고 공식 문서도 잘 정리되어 있어서 도입 난이도는 낮을 것 같다. 다만 JavaScript 키가 소스코드에 그대로 노출된다는 점이 신경 쓰였다. 순수 HTML/JS 환경에서는 Vite나 Webpack 같은 번들러가 없기 때문에 환경변수로 키를 숨기는 것이 불가능하다. 대신 아래 두 가지 방법을 조합해서 최소한의 보안을 유지할 수 있다.

1. *도메인 허용 설정으로 제한 * 카카오 디벨로퍼스에서 허용 도메인을 엄격하게 설정하면, 키가 노출되더라도 등록되지 않은 도메인에서는 사용할 수 없다.
2. config.js 분리 + .gitignore 등록 키를 별도 파일로 분리하고 .gitignore에 추가해 깃헙에 올라가지 않도록 막는다.

미니 프로젝트 수준에서는 이 두 가지 조합으로 충분할 것 같다.

이 글에서 다룰 내용

1. 프로젝트 구조 설명
2. 회원가입 백엔드
   • DB 테이블 생성
   • MemberVO
   • DTO 생성 (Request / Response)
   • MemberMapper
   • MemberService
   • MemberController
3. 회원가입 프론트
4. 로그인 백엔드
   • MemberService
   • MemberController
5. 로그인 프론트
6. 공통 기능 (common.js)
7. 동작 확인

1. 프로젝트 구조 설명

백엔드

pizza-shop/
├── src/main/java/
│   └── com.pizzashop/
│       ├── controller/
│       │   ├── MenuController.java
│       │   └── MemberController.java
│       ├── dto/
│       │   ├── request/
│       │   │   ├── MemberRegisterRequest.java
│       │   │   └── MemberLoginRequest.java
│       │   └── response/
│       │       ├── ApiResponse.java
│       │       ├── MemberLoginResponse.java
│       ├── mapper/
│       │   ├── MenuMapper.java
│       │   └── MemberMapper.java
│       ├── service/
│       │   ├── MenuService.java
│       │   └── MemberService.java
│       └── vo/
│           ├── MenuVO.java
│           └── MemberVO.java

Controller → Service → Mapper → DB 순서로 요청이 흘러간다.

프론트엔드

PIZZA-SHOP/
├── css/
│   ├── style.css
│   └── auth.css
├── js/
│   ├── common.js
│   ├── menu.js
│   └── auth.js
├── index.html
├── login.html
└── register.html

2. 회원가입 백엔드

요청 흐름은 다음과 같다.

클라이언트 → Controller → Service → Mapper → DB

DB 테이블 생성

회원 정보를 저장할 members 테이블을 먼저 생성한다.

CREATE TABLE IF NOT EXISTS members (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(100) NOT NULL,
    name VARCHAR(50) NOT NULL,
    role VARCHAR(20) DEFAULT 'USER',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

MemberVO

DB 테이블과 1:1로 매핑되는 데이터 객체다.

@Data
@NoArgsConstructor
@AllArgsConstructor
public class MemberVO {
    private int id;           // 고유번호
    private String username;  // 로그인 아이디
    private String password;  // 비밀번호 (실무에서는 암호화 필요)
    private String name;      // 닉네임
    private String role;      // 권한 (USER / ADMIN)
    private String createdAt; // 가입일
}

DTO 생성

클라이언트와 주고받는 데이터를 명확하게 분리하기 위해 DTO를 사용한다.

VO를 그대로 사용하면 클라이언트가 role 같은 민감한 필드를 임의로 넘길 수 있어 보안에 취약하다. DTO를 사용하면 필요한 필드만 주고받을 수 있다.

MemberRegisterRequest - 회원가입 요청 데이터

@Data
@NoArgsConstructor
@AllArgsConstructor
public class MemberRegisterRequest {
    private String username;
    private String password;
    private String name;
}

MemberLoginRequest - 로그인 요청 데이터

@Data
@NoArgsConstructor
@AllArgsConstructor
public class MemberLoginRequest {
    private String username;
    private String password;
}

ApiResponse - 공통 응답 데이터

@Data
@NoArgsConstructor
@AllArgsConstructor
public class ApiResponse {
    private String result;  // "ok" 또는 "fail"
    private String message; // 성공 또는 실패 메시지
}

MemberLoginResponse - 로그인 응답 데이터

@Data
@NoArgsConstructor
@AllArgsConstructor
public class MemberLoginResponse {
    private String result;   // 실행 결과
    private String name;     // 사용자 이름
    private String role;     // 사용자 역할 (USER / ADMIN)
    private String username; // 사용자 아이디
}

로그인 응답에 password는 절대 포함하면 안 된다.

MemberMapper

@Mapper
public interface MemberMapper {

    // 아이디 중복 체크 / 로그인 시 회원 조회
    @Select("SELECT * FROM members WHERE username = #{username}")
    MemberVO findByUsername(String username);

    // 회원가입 INSERT
    // id, role, created_at은 DB에서 자동 생성되므로 쿼리에서 제외
    @Insert("INSERT INTO members(username, password, name) "
            + "VALUES (#{username}, #{password}, #{name})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    int insert(MemberVO member);
}

@Options(useGeneratedKeys = true, keyProperty = "id") 는 INSERT 후 자동 생성된 id 값을 MemberVO.id에 다시 넣어준다.

MemberService - 회원가입

@Service
public class MemberService {

    @Autowired
    private MemberMapper memberMapper;

    // 1. 같은 아이디가 DB에 존재하는지 조회
    // 2. 있으면 false 반환 -> Controller에서 "중복 아이디" 응답
    // 3. 없으면 INSERT 실행 -> 성공 시 true 반환
    public boolean register(MemberRegisterRequest request) {
        MemberVO existing = memberMapper.findByUsername(request.getUsername());
        if (existing != null) {
            return false; // 중복 아이디 -> 가입 거절
        }

        // Request -> VO 변환
        MemberVO member = new MemberVO();
        member.setUsername(request.getUsername());
        member.setPassword(request.getPassword());
        member.setName(request.getName());

        return memberMapper.insert(member) > 0;
    }
}

role과 created_at은 DB에서 자동으로 설정되므로 따로 넣지 않아도 된다.

MemberController - 회원가입

@RestController
@RequestMapping("/api/member")
@CrossOrigin(origins = "*")
public class MemberController {

    @Autowired
    private MemberService memberService;

    // POST /api/member/register
    // 요청 Body : {"username": "hong", "password": "1234", "name": "홍길동"}
    // 응답 : {"result": "ok", "message": "회원가입 완료"}
    @PostMapping("/register")
    public ApiResponse register(@RequestBody MemberRegisterRequest request) {
        boolean ok = memberService.register(request);
        if (ok) {
            return new ApiResponse("ok", "회원가입 완료");
        } else {
            return new ApiResponse("fail", "이미 사용 중인 아이디입니다.");
        }
    }
}

3. 회원가입 프론트

register.html

<div class="auth-container">
    <div class="auth-box">
        <h2>회원가입</h2>
        <div class="form-group">
            <label>아이디</label>
            <input type="text" id="regId" placeholder="아이디를 입력하세요" />
        </div>
        <div class="form-group">
            <label>비밀번호</label>
            <input type="password" id="regPw" placeholder="비밀번호를 입력하세요" />
        </div>
        <div class="form-group">
            <label>이름</label>
            <input type="text" id="regName" placeholder="이름을 입력하세요" />
        </div>
        <button class="btn-submit" onclick="register()">회원가입</button>
        <p class="auth-link">
            이미 계정이 있으신가요? <a href="login.html">로그인</a>
        </p>
    </div>
</div>

auth.js - 회원가입

const AUTH_API = "http://localhost:8080/api/member";

function register() {
    const id = document.getElementById("regId").value.trim();
    const pw = document.getElementById("regPw").value.trim();
    const name = document.getElementById("regName").value.trim();

    if (!id || !pw || !name) {
        alert("모든 항목을 입력해 주세요.");
        return;
    }

    fetch(`${AUTH_API}/register`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ username: id, password: pw, name: name }),
    })
        .then((res) => res.json())
        .then((data) => {
            if (data.result === "ok") {
                alert("가입 완료! 로그인 페이지로 이동합니다.");
                setTimeout(() => {
                    location.href = "login.html";
                }, 1500);
            } else {
                alert("가입 실패 : 아이디를 확인해 주세요.");
            }
        })
        .catch(() => alert("서버 오류"));
}

4. 로그인 백엔드

MemberService - 로그인

// 1. 아이디로 회원 조회
// 2. 비밀번호 일치하면 MemberVO 반환 (로그인 성공)
// 3. 아이디가 없거나 비밀번호 틀리면 null 반환 (로그인 실패)
public MemberVO login(String username, String password) {
    MemberVO member = memberMapper.findByUsername(username);
    if (member != null && member.getPassword().equals(password)) {
        return member;
    }
    return null;
}

MemberController - 로그인

// POST /api/member/login
// 요청 Body : {"username": "hong", "password": "1234"}
// 응답(성공) : {"result": "ok", "name": "홍길동", "role": "USER", "username": "hong"}
// 응답(실패) : {"result": "fail", "name": null, "role": null, "username": null}
@PostMapping("/login")
public MemberLoginResponse login(@RequestBody MemberLoginRequest request) {
    MemberVO member = memberService.login(request.getUsername(), request.getPassword());
    if (member != null) {
        return new MemberLoginResponse("ok", member.getName(), member.getRole(), member.getUsername());
    } else {
        return new MemberLoginResponse("fail", null, null, null);
    }
}

5. 로그인 프론트

login.html

<div class="auth-container">
    <div class="auth-box">
        <h2>로그인</h2>
        <div class="form-group">
            <label>아이디</label>
            <input type="text" id="loginId" placeholder="아이디를 입력하세요" />
        </div>
        <div class="form-group">
            <label>비밀번호</label>
            <input type="password" id="loginPw" placeholder="비밀번호를 입력하세요" />
        </div>
        <button class="btn-submit" onclick="login()">로그인</button>
        <p class="auth-link">
            계정이 없으신가요? <a href="register.html">회원가입</a>
        </p>
    </div>
</div>

auth.js - 로그인

function login() {
    const id = document.getElementById("loginId").value.trim();
    const pw = document.getElementById("loginPw").value.trim();

    if (!id || !pw) {
        alert("아이디와 비밀번호를 입력해 주세요.");
        return;
    }

    fetch(`${AUTH_API}/login`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ username: id, password: pw }),
    })
        .then((res) => res.json())
        .then((data) => {
            if (data.result === "ok") {
                localStorage.setItem("loginUser", data.name);
                localStorage.setItem("loginRole", data.role);
                localStorage.setItem("loginUserId", data.username);
                alert(`${data.name}님 환영합니다😊`);
                setTimeout(() => {
                    location.href = "index.html";
                }, 1500);
            } else {
                alert("아이디 또는 비밀번호가 틀렸습니다.");
            }
        })
        .catch(() => alert("서버 오류"));
}

로그인 성공 시 localStorage에 사용자 정보를 저장해두면 다른 페이지에서도 로그인 상태를 유지할 수 있다.

6. 공통 기능 (common.js)

// nav 업데이트
function updateNav() {
    const isLoggedIn = localStorage.getItem("loginUser");
    const loginRole = localStorage.getItem("loginRole");
    const navArea = document.getElementById("navArea");

    if (isLoggedIn) {
        const adminMenu = loginRole === "ADMIN" ? `<a href="admin.html">메뉴 관리</a>` : "";
        const cartMenu = loginRole === "USER" ? `<a href="cart.html">장바구니</a>` : "";

        navArea.innerHTML = `
            <a href="index.html">메뉴</a>
            ${adminMenu}
            ${cartMenu}
            <a href="#" onclick="logout()">로그아웃</a>
        `;
    }
}

// 로그아웃
function logout() {
    localStorage.clear();
    location.href = "login.html";
}

로그인 상태면 역할에 따라 nav가 동적으로 바뀐다. ADMIN이면 메뉴 관리, USER면 장바구니가 추가된다.

7. 동작 확인

📸 [스크린샷 - 회원가입 화면] 아이디, 비밀번호, 이름을 입력하고 회원가입 버튼을 클릭하면 가입 완료 알림이 뜨고 자동으로 로그인 페이지로 이동한다.

📸 *[스크린샷 - 로그인 화면]
*아이디와 비밀번호를 입력하고 로그인 버튼을 클릭하면 환영 메시지가 뜨고 메인 페이지로 이동한다.

📸 [스크린샷 - 로그인 성공 후 nav 변경된 화면] 로그인 성공 시 localStorage에 사용자 정보가 저장되고, nav가 역할에 따라 동적으로 변경된다. USER면 장바구니, ADMIN이면 메뉴 관리 링크가 추가된다.

마치며

이번 글에서는 회원가입과 로그인 기능을 백엔드와 프론트엔드로 나눠서 구현해봤다.

• DTO로 요청/응답 데이터를 명확하게 분리
• MyBatis로 DB 연동
• localStorage로 로그인 상태 유지

다음 편에서는 관리자 페이지에서 메뉴 CRUD 기능을 구현할 예정이다.

1. 프로젝트 구조 설명
2. index.html 생성
3. style.css 생성
4. menu.js 생성
5. CRUD 기능 구현
   • 전체 메뉴 조회 (GET)

1. 프로젝트 구조 설명

PIZZA-SHOP/
├── css/
│   └── style.css
├── js/
│   └── menu.js
└── index.html

2. index.html 생성

• index.html은 피자 메뉴 목록을 보여주는 메인 페이지다.

<!doctype html>
<html lang="ko">
    <head>
        <meta charset="UTF-8" />
        <title>PIZZA</title>
        <link rel="stylesheet" href="css/style.css" />
    </head>
    <body>
        <!-- 메뉴 목록 화면 -->
        <header>
            <h1>PIZZA SHOP</h1>
            <nav id="navArea">
                <a href="index.html">메뉴</a>
                <a href="login.html">로그인</a>
                <a href="register.html">회원가입</a>
            </nav>
        </header>

        <div class="hero">
            <h2>오늘의 피자 한 입 🍕</h2>
            <p>맛있는 피자를 즐겨보세요.</p>
        </div>

        <div class="filter">
            <button class="active" onclick="filterMenu('전체', this)">전체</button>
            <button onclick="filterMenu('클래식', this)">클래식</button>
            <button onclick="filterMenu('프리미엄', this)">프리미엄</button>
            <button onclick="filterMenu('사이드', this)">사이드</button>
        </div>

        <div class="menu-grid" id="menuGrid"></div>

        <footer>2026 Pizza Shop. All rights reserved.</footer>
        <script src="js/menu.js"></script>
    </body>
</html>

<div class="menu-grid" id="menuGrid"> 는 비어있는 상태로 시작하고 menu.js에서 API를 호출해 동적으로 메뉴 카드를 채워준다.

3. style.css 생성

style.css는 피자 쇼핑몰의 전체 디자인을 담당한다.

/* 공통 스타일 */
:root {
    --color-bg: #fffdf0;
    --color-dark: #2b1f1d;
    --color-primary: #ff5252;
    --color-accent: #ffb74d;
    --color-light: #ffffff;
    --color-border: #f0e6db;
    --color-text: #4a3b32;
    --color-muted: #a1887f;
    --font-main: "Ansungtangmyeon", "Comic Sans MS", "Apple SD Gothic Neo", sans-serif;
    --radius: 20px;
    --shadow: 0 8px 24px rgba(235, 190, 160, 0.2);
    --transition: 0.25s cubic-bezier(0.175, 0.885, 0.32, 1.275);
}

CSS 변수(:root)를 사용하면 색상, 그림자, 애니메이션 등을 한 곳에서 관리할 수 있어 유지보수가 편리하다.

헤더 / 네비게이션

header {
    background: var(--color-bg);
    padding: 20px 40px;
    display: flex;
    justify-content: space-between;
    align-items: center;
}

nav a {
    color: var(--color-primary);
    text-decoration: none;
    margin-left: 20px;
    font-size: 15px;
    font-weight: bold;
}

display: flex + justify-content: space-between으로 로고는 왼쪽, 네비게이션은 오른쪽에 배치한다.

필터 버튼

.filter {
    display: flex;
    justify-content: center;
    gap: 10px;
    padding: 30px 20px 10px;
}

.filter button {
    padding: 8px 20px;
    border: 2px solid var(--color-accent);
    border-radius: 20px;
    background: var(--color-bg);
    color: var(--color-accent);
    cursor: pointer;
}

.filter button:hover,
.filter button.active {
    background: var(--color-accent);
    color: var(--color-bg);
}

메뉴 그리드

.menu-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(230px, 1fr));
    gap: 24px;
    padding: 20px 40px 60px;
    max-width: 1100px;
    margin: 0 auto;
}

repeat(auto-fill, minmax(230px, 1fr))를 사용하면 별도의 미디어 쿼리 없이도 화면 크기에 따라 자동으로 열 수가 조정되는 반응형 그리드가 완성된다.

메뉴 카드

.menu-card {
    background: var(--color-light);
    border-radius: 12px;
    overflow: hidden;
    box-shadow: var(--shadow);
    transition: var(--transition);
}

.menu-card:hover {
    transform: translateY(-4px);
}

.menu-card .img-area {
    background: var(--color-light);
    height: 160px;
    overflow: hidden;
    text-align: center;
    line-height: 160px;
    font-size: 60px;
}

4. menu.js 생성

menu.js는 API를 호출해 메뉴 데이터를 받아오고, 화면에 카드를 동적으로 렌더링하는 역할을 한다.

const API = "http://localhost:8080/api/menu";
let allMenus = []; // 전체 메뉴 캐시

window.onload = function () {
    loadMenus();
    updateNav();
};

allMenus에 전체 메뉴를 캐싱해두면 카테고리 필터링 시 API를 다시 호출하지 않아도 된다.

전체 메뉴 불러오기

function loadMenus() {
    fetch(API)
        .then((res) => res.json())
        .then((data) => {
            allMenus = data;
            renderMenus(data);
        })
        .catch((err) => console.error("메뉴 불러오기 실패: ", err));
}

카드 렌더링

function renderMenus(menus) {
    const grid = document.getElementById("menuGrid");
    grid.innerHTML = "";

    if (menus.length === 0) {
        grid.innerHTML = '<p style="text-align:center; color:#999; padding:40px;">메뉴가 없습니다.</p>';
        return;
    }

    menus.forEach((menu) => {
        const card = document.createElement("div");
        card.className = "menu-card";

        const imgContent = menu.imgUrl
            ? `<img src="${menu.imgUrl}" alt="${menu.name}" style="width:100%; height:160px; object-fit:contain; display:block;">`
            : getCategoryEmoji(menu.category);

        card.innerHTML = `
            <div class="img-area">${imgContent}</div>
            <div class="info">
                <div class="category">${menu.category}</div>
                <h3>${menu.name}</h3>
                <div class="price">${menu.price.toLocaleString()}원</div>
                <div class="btn-group">
                    <button onclick="order('${menu.name}', ${menu.price})">주문하기</button>
                    <button onclick="addToCart(${menu.id}, '${menu.name}', ${menu.price})">장바구니 담기</button>
                </div>
            </div>
        `;
        grid.appendChild(card);
    });
}

imgUrl이 있으면 이미지를, 없으면 카테고리별 이모지를 대신 보여준다.

function getCategoryEmoji(category) {
    if (category == "클래식") return "⭐";
    if (category == "프리미엄") return "👑";
    if (category == "사이드") return "🍟";
}

카테고리 필터링

function filterMenu(category, event) {
    document.querySelectorAll(".filter button").forEach((btn) => {
        btn.classList.remove("active");
    });
    event.target.classList.add("active");

    if (category === "전체") {
        renderMenus(allMenus);
    } else {
        const filtered = allMenus.filter((m) => m.category === category);
        renderMenus(filtered);
    }
}

5. CRUD 기능 구현 - ① 전체 메뉴 조회 (GET)

전체 메뉴 조회 (GET)

페이지가 로드되면 자동으로 API를 호출해 전체 메뉴를 가져온다.

카테고리 버튼을 클릭하면 해당 카테고리만 필터링되어 보여진다.

마치며

이번 글에서는 피자 쇼핑몰 프론트엔드의 기본 구조를 만들어봤다.

• index.html로 화면 구조 잡기
• style.css로 디자인 입히기
• menu.js로 API 연동 및 동적 렌더링

다음 편에서는 로그인/회원가입 기능을 구현할 예정이다.

학원에서 위 이미지와 같이 Spring Boot로 coffee shop 페이지를 만들어 보았다.
배운 내용을 제대로 익히기 위해 복습 겸 피자 가게 페이지를 직접 만들어보려 한다.

이 글에서 다룰 내용

• 피자 메뉴 전체 조회
• 메뉴 단건 조회
• 메뉴 등록
• 메뉴 수정
• 메뉴 삭제

사용 기술 스택

• Spring Boot
• MySQL
• Lombok
• Postman
• MyBatis

1. MySQL 에서 DB 생성 및 테이블 생성

1. 쿼리 작성 및 실행

-- pizza_db 생성
create database if not exists pizza_db default character set utf8mb4;

-- pizza_db 사용
use pizza_db;

-- menu 테이블 생성
create table menu(
    id int auto_increment primary key,
    name varchar(100) not null,
    size varchar(10) not null,
    price int not null,
    category varchar(50) not null,
    img_url varchar(255)
)

2. pizza_db의 menu 테이블 생성 완료

2. application.properties 설정 (DB 연결, MyBatis)

# 프로젝트 이름
spring.application.name=pizza-shop

# DB 연결 설정
# url - 어떤 DB에 연결할지 (localhost:3306 = 내 컴퓨터의 MySql_db = 사용 할 DB 이름)
spring.datasource.url=jdbc:mysql://localhost:3306/pizza_db?useSSL=false&serverTimezone=Asia/Seoul

# username/password = MySql 로그인 정보
spring.datasource.username=<username>
spring.datasource.password=<password>

# driver = Mysql 전용 드라이버 클래스 (Mysql 8.x 버전용)
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# Mybatis 설정
# VO 클래스가 있는 패키지 등록 -> 쿼리 결과를 VO 객체로 자동 변환해줌
mybatis.type-aliases-package=com.example.demo.vo
# DB 컬럼명 (img_url)을 Java 필드명(imgUrl)으로 자동 변환 (언더스코어 -> 카멜케이스)
mybatis.configuration.map-underscore-to-camel-case=true

3. 프로젝트 생성 및 패키지 생성

1. controller - 클라이언트 요청을 받고 응답을 반환
2. service - 비즈니스 로직 담당
3. vo - 데이터를 담는 객체 (DB 테이블과 매핑)
4. mapper - DB에 접근해서 쿼리 실행

4. MenuVO 클래스 생성

• DB 테이블과 매핑되는 데이터 객체

  package com.pizzashop.vo;
  

import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor;

@Data @NoArgsConstructor @AllArgsConstructor public class MenuVO {

private int id; // 고유 아이디
private String name; // 메뉴명
private String size; // 피자 사이즈 
private int price; // 가격
private String category; // 카테고리
private String imgUrl; // 이미지 URL

}

| 어노테이션 | 기능 |
|-----------|------|
| `@Data` | getter, setter, toString 등을 자동 생성 |
| `@NoArgsConstructor` | 기본 생성자 자동 생성 (매개변수 없음) |
| `@AllArgsConstructor` | 전체 필드 생성자 자동 생성 (모든 필드 포함) |

#### @Data
```java
// 이걸 직접 안 써도 됨
public String getName() { return name; }
public void setName(String name) { this.name = name; }

@NoArgsConstructor

// 이걸 자동 생성
public MenuVO() {}

@AllArgsConstructor

// 이걸 자동 생성
public MenuVO(int id, String name, String size, int price, String category, String imgUrl) {}

5. MenuMapper 인터페이스 생성

Mapper를 인터페이스로 생성하는 이유

직접 구현 코드를 작성하지 않아도 MyBatis가 자동으로 구현체를 만들어주기 때문이다. 개발자는 어떤 쿼리를 실행할지만 정의하면 된다.

@Mapper

MyBatis에게 "이 인터페이스가 Mapper입니다" 라고 알려주는 어노테이션이다. Spring이 자동으로 구현체를 생성하고 Bean으로 등록해준다.

@Options(useGeneratedKeys = true, keyProperty = "id")

INSERT 후 DB에서 자동 생성된 id 값을 MenuVO 객체에 자동으로 담아주는 옵션이다.

package com.pizzashop.mapper;

import java.util.List;

import org.apache.ibatis.annotations.Delete;
import org.apache.ibatis.annotations.Insert;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Options;
import org.apache.ibatis.annotations.Select;
import org.apache.ibatis.annotations.Update;

import com.pizzashop.vo.MenuVO;

@Mapper
public interface MenuMapper {

//    메뉴 전체 조회
    @Select("SELECT * FROM menu ORDER BY id ASC")
    List<MenuVO> findAll();

//    메뉴 단건 조회
    @Select("SELECT * FROM menu WHERE id = #{id}")
    MenuVO findById(int id);

//    메뉴 등록
    @Insert("INSERT INTO menu (name, size, price, category, img_url) VALUES (#{name}, #{size}, #{price}, #{category}, #{imgUrl})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    boolean insert(MenuVO menu);

//    메뉴 수정
    @Update("UPDATE menu SET name=#{name}, size=#{size}, price=#{price}, category=#{category}, img_url=#{imgUrl} WHERE id=#{id}")
    boolean update(MenuVO menu);

//    메뉴 삭제
    @Delete("DELETE FROM menu WHERE id=#{id}")
    boolean delete(int id);

}

6. MenuService 클래스 생성

Service 클래스란?

Controller와 Mapper 사이에서 비즈니스 로직을 처리하는 계층이다. Controller는 요청/응답만 담당하고, 실제 처리 로직은 Service에서 담당한다.

클라이언트 → Controller → Service → Mapper → DB

@Autowired

Spring이 자동으로 객체(Bean)를 찾아서 주입해주는 어노테이션이다. 직접 new로 객체를 생성할 필요 없이 Spring이 알아서 넣어준다.

// @Autowired 없으면 직접 생성해야 함
MenuMapper menuMapper = new MenuMapper();

// @Autowired 있으면 Spring이 알아서 주입
@Autowired
private MenuMapper menuMapper;

@Service

Spring에게 "이 클래스가 Service입니다" 라고 알려주는 어노테이션이다. 자동으로 Bean으로 등록되어 @Autowired로 주입받을 수 있다.

package com.pizzashop.service;

import java.util.List;

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

import com.pizzashop.mapper.MenuMapper;
import com.pizzashop.vo.MenuVO;

@Service
public class MenuService {
// @Autowired = Spring이 알아서 MenuMapper 객체를 여기에 주입해줌(직접 new를 할 필요 없음)
        @Autowired
        private MenuMapper menuMapper;

//        전체 메뉴 조회
        public List<MenuVO> getAll() {return menuMapper.findAll();}

//        단건 메뉴 조회
        public MenuVO getById(int id) {return menuMapper.findById(id);}

//        메뉴 등록 / 수정 / 삭제
//        insert 결과가 1이상이면 true(성공), 0이면 false(실패)
        public boolean add(MenuVO menu) {return menuMapper.insert(menu);}
        public boolean update(MenuVO menu) {return menuMapper.update(menu);}
        public boolean delete(int id) {return menuMapper.delete(id);}

}

7. MenuConroller 클래스 생성

package com.pizzashop.controller;

import java.util.List;
import java.util.Map;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.pizzashop.service.MenuService;
import com.pizzashop.vo.MenuVO;

@RestController
@RequestMapping("/api/menu")
@CrossOrigin(origins="*")
public class MenuController {

    @Autowired
    private MenuService menuService;

//    메뉴 조회
    @GetMapping
    public List<MenuVO> getAll() {
        return menuService.getAll();
    }

//    단건 조회
    @GetMapping("/{id}")
    public MenuVO getById(@PathVariable("id") int id) {
        return menuService.getById(id);
    }

//    메뉴 등록
    @PostMapping
    public Map<String, Object> add(@RequestBody MenuVO menu) {
        boolean success = menuService.add(menu);
        if(success) return Map.of("result", "ok", "message", "등록 완료");
        return Map.of("result", "fail", "message", "등록 실패");
    }

//    메뉴 수정
    @PutMapping("/{id}")
    public Map<String, Object> update(@PathVariable("id") int id, @RequestBody MenuVO menu) {
        menu.setId(id);
        boolean success = menuService.update(menu);
        if(success) return Map.of("result", "ok", "message", "수정 완료");
        return Map.of("result", "fail", "message", "수정 실패");
    }

//    메뉴 삭제
    @DeleteMapping("/{id}")
    public Map<String, Object> delete(@PathVariable("id") int id) {
        boolean success = menuService.delete(id);
        if(success) return Map.of("result", "ok", "message", "삭제 완료");
        return Map.of("result", "fail", "message", "삭제 실패");
    }
}

8. Postman으로 API 실행해보기

1. 메뉴 등록 (이미지 URL은 피자스쿨의 이미지 URL 사용)

2. 전체 메뉴 조회 3. 단건 메뉴 조회 4. 메뉴 수정

5. 메뉴 삭제

마무리

이번 글에서는 피자 가게 메뉴 CRUD를 직접 구현해봤다.

학원에서 배운 내용을 다시 만들어보니 전체적인 흐름이 더 명확하게 이해됐다.

클라이언트 → Controller → Service → Mapper → DB

VO, Mapper, Service, Controller 각각의 역할을 이해하고 나니 Spring Boot의 구조가 훨씬 익숙하게 느껴졌다.

다음 글에서는 피자 가게 프론트 연동을 해볼 예정이다.

1. JDK (JDK 17-LTS 버전) 설치

1. 아래 사이트 접속 > Other Downloads 클릭 https://adoptium.net/

2. JDK 17-LTS 탭 클릭 > 운영체제에 맞는 JDK 설치

2. 스프링부트 설치

1. 아래 사이트 접속 > ECLIPSE 탭 선택 > 운영체제에 맞는 프로그램 설치 https://spring.io/tools

2. 압축 풀고 → 경로 설정 - Launch

3. 롬복 설치

1. 아래 사이트 접속 > 파일 다운로드 https://projectlombok.org/download

2. Specify locatio...버튼 클릭 > 이전에 설치한 SpringToolsForEclipse.exe 파일 선택 > instaal / Up... 버튼 클릭 > Quit Inst... 버튼 클릭

   
   ## ⚠️ 롬복 설치 시 아래와 같은 에러가 난다면? 

3. 관리자 권한으로 cmd창 열기 > lombok.jar가 있는 디렉토리로 이동

4. java -jar lombok.jar 명령어 실행 > 설치 재시도

4. MySQL 설치

1. 아래 사이트 접속 > 다운로드 버튼 클릭 https://dev.mysql.com/downloads/installer/

2. Custom > Next 클릭

3. 왼쪽 Available Products에서 오른쪽으로 이동 > Next ✅ MySQL Server 8.0.46 - X64 ✅ MySQL Workbench 8.0.47 - X64

4. 설치 완료 후 > Execute 클릭

5. root 계정의 비밀번호를 설정 (이 비밀번호는 나중에 DB 접속 시 반드시 필요하므로 반드시 기억/기록해두기)

6. 이후 나오는 화면들은 모두 기본값 유지 후 Next 클릭

   
   

⚠️ MySQL 삭제 후 재설치 시 주의사항

단순히 프로그램만 제거하면 재설치 시 오류가 발생할 수 있다. 아래 순서대로 완전히 삭제 후 재설치

1. 프로그램 제거

제어판 → 프로그램 추가/제거에서 아래 항목을 모두 제거

• MySQL Server
• MySQL Workbench
• MySQL Installer

2. 잔여 파일 삭제

C:\Program Files\MySQL
C:\ProgramData\MySQL

💡 ProgramData는 숨김 폴더 탐색기 상단 보기 → 숨긴 항목 체크 후 접근

3. 재부팅 후 재설치 진행 ✅

5. Postman 설치

1. 아래 사이트 접속 > 다운로드 > 로그인 후 실행 https://www.postman.com/downloads/
   ## ⚠️ Postman 삭제 후 재설치 시 주의사항

단순히 프로그램만 제거하면 재설치 시 오류가 발생할 수 있다. 아래 순서대로 완전히 삭제 후 재설치

1. 프로그램 제거

제어판 → 프로그램 추가/제거에서 아래 항목을 제거

• Postman

2. 잔여 파일 삭제

C:\Users\[사용자명]\AppData\Roaming\Postman
C:\Users\[사용자명]\AppData\Local\Postman

💡 AppData는 숨김 폴더! 탐색기 상단 보기 → 숨긴 항목 체크 후 접근

3. 재설치 진행 ✅

백트래킹(Backtracking)은 가능한 모든 경우를 탐색하되, 조건에 맞지 않으면 되돌아가서 다른 경우를 시도하는 알고리즘이다.

쉽게 말하면 이렇다.

"일단 해봐. 안 되면 되돌아와서 다른 거 해봐."

재귀 함수로 구현하며, 선택 → 재귀 → 선택 취소 패턴이 핵심이다.

선택      →    재귀 호출    →    선택 취소 (백트래킹)
visited[i] = true → permutation(...) → visited[i] = false

부분집합 vs 순열 vs 조합

예시 {1, 2, 3} 에서 2개 뽑기

순열

• 가짓수 : 6개
• 예시 : {1,2}, {1,3}, {2,1}, {2,3}, {3,1}, {3,2}

조합

• 가짓수 : 3개
• 예시 : {1,2}, {1,3}, {2,3}

한 줄 요약

• 부분집합 : 각 원소를 포함할지 말지 결정하며 나올 수 있는 모든 집합 (빈 집합 포함!)
• 순열 : r개의 원소를 나열 (순서 중요!)
• 조합 : r개의 원소를 선택 (순서는 중요하지 않음)

부분집합 (Subset)

개념

{1, 2, 3} 의 모든 부분집합은 다음과 같다.

{}, {1}, {2}, {3}, {1,2}, {1,3}, {2,3}, {1,2,3}  → 총 8가지 (2^3)

각 원소에 대해 포함 / 미포함 두 가지 선택만 한다.

동작 흐름

1 포함 여부 결정
├── 포함 O → 2 포함 여부 결정
│           ├── 포함 O → 3 포함 여부 결정 → {1,2,3} 출력
│           └── 포함 X → 3 포함 여부 결정 → {1,2} 출력
└── 포함 X → 2 포함 여부 결정
            ├── 포함 O → 3 포함 여부 결정 → {1,3} 출력
            └── 포함 X → ...

코드

static int[] arr = {1, 2, 3};
static boolean[] selected = new boolean[arr.length];
static int count = 0;

static void printSubset() {
    count = 0;
    subset(0);
    System.out.println("\n총 " + count + " 가지");
}

static void subset(int depth) {
    // 기저 조건 : 모든 원소에 대해 선택 여부를 결정했으면 출력
    if (depth == arr.length) {
        count++;
        System.out.print("{ ");
        for (int i = 0; i < arr.length; i++) {
            if (selected[i]) System.out.print(arr[i] + " ");
        }
        System.out.println("}");
        return;
    }

    // 현재 원소를 포함하는 경우
    selected[depth] = true;
    subset(depth + 1);

    // 현재 원소를 포함하지 않는 경우 (백트래킹)
    selected[depth] = false;
    subset(depth + 1);
}

핵심 포인트

• visited 없이 selected 배열만으로 포함 여부를 결정
• depth가 arr.length에 도달하면 하나의 부분집합 완성
• 포함 O / 포함 X 두 갈래로 재귀 → 총 2^n 가지

순열 (Permutation)

개념

{1, 2, 3} 에서 2개를 뽑아 순서 있게 나열한다.

{1,2}, {1,3}, {2,1}, {2,3}, {3,1}, {3,2}  → 총 6가지 (3P2)

순서가 다르면 다른 경우다. {1,2} 와 {2,1} 은 다르다.

동작 흐름

depth=0 선택       depth=1 선택        결과
─────────────────────────────────────────
1 선택     ──→     2 선택    ──→   {1,2} ✅
           ──→     3 선택    ──→   {1,3} ✅
2 선택     ──→     1 선택    ──→   {2,1} ✅
           ──→     3 선택    ──→   {2,3} ✅
3 선택     ──→     1 선택    ──→   {3,1} ✅
           ──→     2 선택    ──→   {3,2} ✅

코드

static int count = 0;

// 편의 함수 : 배열과 r값만 넘기면 순열 실행
static void printPermutation(int[] arr, int r) {
    int[] result = new int[r];
    boolean[] visited = new boolean[arr.length];
    count = 0;

    permutation(arr, result, visited, 0, r);
    System.out.println("\n총 " + count + " 가지");
}

static void permutation(int[] arr, int[] result, boolean[] visited, int depth, int r) {
    // 기저 조건 : r개를 모두 선택했으면 출력
    if (depth == r) {
        count++;
        for (int i = 0; i < r; i++) {
            System.out.print(result[i] + " ");
        }
        System.out.println();
        return;
    }

    // 원본 배열의 원소를 하나씩 시도
    for (int i = 0; i < arr.length; i++) {
        // 이미 선택된 원소는 건너뜀
        if (visited[i]) continue;

        // arr[i]를 선택 : result에 넣고 visited 표시
        visited[i] = true;
        result[depth] = arr[i];

        // 다음 깊이로 재귀 호출
        permutation(arr, result, visited, depth + 1, r);

        // 선택 취소 (백트래킹)
        visited[i] = false;
    }
}

핵심 포인트

• visited 배열로 같은 원소를 두 번 쓰는 것을 방지
• depth == r 이 되면 r개 선택 완료 → 출력
• 재귀 후 visited[i] = false 로 되돌려야 다른 경우 탐색 가능

조합 (Combination)

개념

{1, 2, 3} 에서 2개를 뽑는다. 순서는 상관없다.

{1,2}, {1,3}, {2,3}  → 총 3가지 (3C2)

순서가 달라도 같은 경우다. {1,2} 와 {2,1} 은 같다.

순열과의 차이점

순열은 모든 원소를 매번 처음부터 탐색하지만, 조합은 이미 선택한 원소보다 뒤에 있는 원소만 탐색한다.

순열 : 1 선택 후 → {2, 3} 탐색 / 2 선택 후 → {1, 3} 탐색  (앞으로도 감)
조합 : 1 선택 후 → {2, 3} 탐색 / 2 선택 후 → {3} 탐색     (앞으로 안 감)

이게 핵심이다. start 변수로 탐색 시작 위치를 앞으로 당기지 않는다.

동작 흐름

depth=0 선택       depth=1 선택        결과
─────────────────────────────────────────
1 선택(start=1) ──→  2 선택  ──→   {1,2} ✅
               ──→  3 선택  ──→   {1,3} ✅
2 선택(start=2) ──→  3 선택  ──→   {2,3} ✅
3 선택(start=3) ──→  (탐색할 원소 없음, 종료)

코드

static int count = 0;

// 편의 함수 : 배열과 r값만 넘기면 조합 실행
static void printCombination(int[] arr, int r) {
    int[] result = new int[r];
    count = 0;

    combination(arr, result, 0, 0, r);
    System.out.println("\n총 " + count + " 가지");
}

static void combination(int[] arr, int[] result, int start, int depth, int r) {
    // 기저 조건 : r개를 모두 선택했으면 출력
    if (depth == r) {
        count++;
        for (int i = 0; i < r; i++) {
            System.out.print(result[i] + " ");
        }
        System.out.println();
        return;
    }

    // start부터 탐색 (이전 원소는 다시 보지 않음)
    for (int i = start; i < arr.length; i++) {
        result[depth] = arr[i];

        // 다음 탐색은 i+1부터 (중복 방지)
        combination(arr, result, i + 1, depth + 1, r);
    }
}

핵심 포인트

• visited 배열이 필요 없음 → start로 탐색 범위를 제한
• 재귀 호출 시 i + 1 을 넘겨서 현재 원소보다 뒤만 탐색
• 백트래킹은 자동으로 됨 (result 덮어쓰기 방식)

세 가지 비교 정리

마무리

백트래킹의 핵심은 선택 → 재귀 → 선택 취소 패턴이다.

세 가지 모두 같은 뼈대를 가지고 있고, 차이는 어떻게 중복을 방지하느냐다.

• 부분집합 : 포함/미포함 두 갈래로 나눔
• 순열 : visited로 이미 쓴 원소 막음
• 조합 : start로 탐색 범위를 앞으로 당기지 않음

이 패턴에 익숙해지면 백트래킹 문제의 대부분을 풀 수 있다.