눈으로 개발하는 블로그

[19] Frontend 개발 - Capacitor, Geolocation, Google Map

carrotweb — Fri, 7 Aug 2026 17:02:53 +0900

앱에 위치 기반 기능을 추가해보겠습니다.

@capacitor/geolocation 설치
(https://capacitorjs.com/docs/apis/geolocation)

위치 기반 기능 사용

1. geolocation 설치 (터미널에서 실행합니다.)

npm install @capacitor/geolocation --save

2. src\views\LunchMenu에 LunchMenuMapView.vue 파일을 생성합니다.

<template>
    <div>
        <h1>GeoLocation</h1>
        <p>나의 위치:</p>
        <p>위도: {{ loc.lat }}</p>
        <p>경도: {{ loc.lng }}</p>
        <button @click="getCurrentPosition">현 위치</button>
    </div>
</template>

<script>
import { ref } from 'vue';
import { Geolocation } from '@capacitor/geolocation';

export default {
    name : 'LunchMenuMapView',
    setup() {
        const loc = ref({
            lat: 0,
            lng: 0,
        });

    const getCurrentPosition = async () => {
      const pos = await Geolocation.getCurrentPosition();
      loc.value = {
        lat: pos.coords.latitude,
        lng: pos.coords.longitude,
      };
    };

    return {
        getCurrentPosition,
        loc
    };
  }
}
</script>

3. src\router\index.js 파일을 수정합니다.

:
import LunchMenuMapView from '@/views/LunchMenu/LunchMenuMapView.vue'
:

const routes = [
  :
  {
    path: '/lunchmenumap',
    name: 'lunchmenumap',
    component: LunchMenuMapView
  },
  :
]

:

4. src\App.vue 파일을 수정합니다.

<template>
  <div class="header">
        <div class="topline">
            <div class="headmenu">
                <div v-if="isLogin()">
                    {{greetingMessage}}
                    <span @click="Logout()">로그아웃</span>
                </div>
                <div v-else>
                    <router-link :to="{ name: 'Login' }">로그인</router-link>
                </div>
            </div>
        </div>
    <nav>
      <router-link to="/">Home</router-link> |
      <router-link to="/about">About</router-link> |
      <router-link to="/lunchmenu/list">LunchMenu</router-link> |
      <router-link to="/lunchmenumap">LunchMenuMap</router-link>
    </nav>
  </div>
  <router-view/>
</template>

:

5. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenumap)

[현 위치] 버튼 클릭합니다. 권한 요청에서 [이번에만 허용 선택]을 선택합니다.

Google Map 연동

vue3-google-map 설치
(https://vue3-google-map.com/)

1. vue3-google-map 설치 (터미널에서 실행합니다.)

npm install vue3-google-map --save

2. src\views\LunchMenu\LunchMenuMapView.vue 파일에 GoogleMap를 추가합니다.

<template>
    <div>
        <h1>GeoLocation</h1>
        <p>나의 위치:</p>
        <p>위도: {{ loc.lat }}</p>
        <p>경도: {{ loc.lng }}</p>
        <button @click="getCurrentPosition">현 위치</button>
        <GoogleMap
          api-key="YOUR_GOOGLE_MAPS_API_KEY"
          style="width: 100%; height: 400px"
          :center="loc"
          :zoom="15"
          language="kor"
          >
            <Marker :options="{ position: loc }" />
          </GoogleMap>
    </div>
</template>

<script>
import { ref } from 'vue';
import { Geolocation } from '@capacitor/geolocation';
import { GoogleMap, Marker } from 'vue3-google-map';

export default {
  name : 'LunchMenuMapView',
  components: {
    GoogleMap,
    Marker
  },
  setup() {
    const loc = ref({
        lat: 0,
        lng: 0,
    });

    const getCurrentPosition = async () => {
      const pos = await Geolocation.getCurrentPosition();
      loc.value = {
        lat: pos.coords.latitude,
        lng: pos.coords.longitude,
      };
    };

    return {
        getCurrentPosition,
        loc
    };
  }
}
</script>

3. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenumap)

[현 위치] 버튼 클릭을 누릅니다.

Android 권한 설정 추가
(https://capacitorjs.com/docs/apis/geolocation)

1. lunchapp\android\app\src\main\AndroidManifest.xml 파일에 권한을 추가합니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    :

    <!-- Permissions -->

    <uses-permission android:name="android.permission.INTERNET" />

    <!-- Geolocation Plugin -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-feature android:name="android.hardware.location.gps" />
</manifest>

모바일 앱 배포

1. Vue 빌드 (터미널에서 실행합니다.)

npm run build

2. Android / iOS 동기화 (터미널에서 실행합니다.)

npx cap sync

3. Android 프로젝트 오픈

npx cap open android

Android 스튜디오에서 직접 권한 설정을 추가하기 위해서 app\manifests\AndroidManifest.xml 파일에 권한을 추가합니다.

4. 실행(Run) 버튼을 눌러 실행합니다. (Emulator가 실행됩니다.)

[현 위치] 버튼 클릭을 누릅니다.

[18] Frontend 개발 - Capacitor, Vue + Android

carrotweb — Fri, 7 Aug 2026 16:37:10 +0900

Capacitor를 사용하여 쉽게 앱을 개발해 보도록 하겠습니다.

Capacitor
(https://capacitorjs.com)

Web App에 Capacitor 추가
(https://capacitorjs.com/docs/getting-started#add-capacitor-to-your-web-app)

1. capacitor 설치 (터미널에서 실행합니다.)

npm install @capacitor/core @capacitor/cli --save

2. Capacitor 초기화 (터미널에서 실행합니다.)

npx cap init

App Name : 앱 이름 (변경하지 않으려면 그냥 엔터 키를 누릅니다. 변경하려면 입력합니다.)

Package ID : 앱의 패키지 아이디 (변경하지 않으려면 그냥 엔터 키를 누릅니다. 변경하려면 입력합니다.)

Ionic 계정 생성

계정을 생성하지 않겠습니다. n를 입력하고 엔터 키를 누릅니다.

3. Android / iOS Platforms 설치 (터미널에서 실행합니다.)

npm install @capacitor/android @capacitor/ios --save

4. Android / iOS Platforms 추가 (터미널에서 실행합니다.)

npx cap add android
npx cap add ios

Android / iOS가 구성됩니다.

Android / iOS Platforms 추가

1. Vue 빌드 (터미널에서 실행합니다.)

npm run build

2. Android / iOS 동기화 (터미널에서 실행합니다.)

npx cap sync

Android 프로젝트 오픈
(https://capacitorjs.com/docs/android#opening-the-android-project)

3. Android 프로젝트 오픈

npx cap open android

Android Studio가 실행됩니다.

[Trust Project] 버튼을 누릅니다.

4. 실행(Run) 버튼을 눌러 실행합니다. (Emulator가 실행됩니다.)

Android 설치 - Hello Android 실행

carrotweb — Fri, 7 Aug 2026 16:20:33 +0900

Android Studio 다운로드

1. Android Developer (https://developer.android.com/?hl=ko) 사이트로 이동합니다.

2. [Android 스튜디오 다운로드]를 클릭합니다.

3. 약관를 아래로 스크롤한 후 동의를 체크하고 하고 [다운로드]를 누릅니다.

현재는 Android Studio Quail 2 입니다.

4. Android Studio가 다운로드 됩니다.

Android Studio 설치

1. [Next] 버튼을 누릅니다.

2. 설치할 컴퍼넌트를 선택하고 [Next] 버튼을 누릅니다.

3. 설치 경로를 설정하고 [Next] 버튼을 누릅니다.

4. 설치 이름을 설정하고 [Next] 버튼을 누릅니다.

5. 설치가 진행됩니다.

6. 설치가 완료되면 [Finish] 버튼을 누릅니다.

Android Studio 실행

1. 개선에 도움을 주실거면 [Send usage statistics to Google] 버튼을 누릅니다.

2. [Next] 버튼을 누릅니다.

3. 설치 타입을 [Standard]를 선택하고 [Next] 버튼을 누릅니다.

4. 설치 정보가 나타납니다. [Next] 버튼을 누릅니다.

5. 라이센스에 동의(Accept)를 선택하고 [Next] 버튼을 누릅니다.

6. 설치가 진행됩니다.

7. 설치가 완료되면 [Finish] 버튼을 누릅니다.

Android Studio 프로젝트 실행

1. [New Project]를 선택합니다.

2. 실행될 환경과 프로젝트 UI 구성을 선택합니다. [Empty Activity]를 선택합니다.

3. 프로젝트 이름과 패키지 이름, 저장 경로, SDK를 선택하고 [Finish] 버튼을 누릅니다.

4. 기본 소스 코드를 확인합니다.

UI 없이 인사말인 "Hello Android"가 출력되는 코드입니다.

5. 처음에는 실행(Run) 버튼이 비활성화 되어 있습니다. 실행(Run) 버튼 왼쪽에 있는 [Add Configuration]를 클릭하여 가상 환경을 설정합니다.

6. 실행(Run) 버튼을 누르면 Emulator가 실행됩니다.

7. Emulator가 실행된 후 앱이 앱이 실행됩니다.

간단하게 "Hello Android"가 출력됩니다.

8. 중지(Stop) 버튼을 눌러 앱 실행을 종료합니다.

[17] Frontend 개발 - Store State 유지, Cookies, localStorage, Pinia Plugin Persistedstate

carrotweb — Wed, 5 Aug 2026 19:28:38 +0900

페이지 새로고침 문제점

웹 브라우저에서 새로고침을 하면 Vue가 초기화 되면서 Store가 초기화 됩니다.

페이지 새로고침 문제점 해결

Store에 있는 State를 유지하기 위해서는 state의 정보를 저장하고 초기화되면 다시 읽어 들어 유지하게 하면 됩니다.

State의 정보를 저장하고 유지하기 위해 다음과 같이 세 가지 방법이 있습니다.

Cookie(쿠키)를 사용하는 방법
Storage(스토리지)를 사용하는 방법
Pinia Plugin Persistedstate를 사용하는 방법

Store State 유지 - Cookie(쿠키) 사용

웹 브라우저에서 F12키를 누르면 개발자 툴이 나타납니다.

여기서 Application를 클릭하고 Cookies를 클릭합니다.

Cookie 구성

Name : 쿠키 이름
Value : 쿠키 값
Domain : 도메인 (쿠키를 수신하도록 허용된 호스트)
Path : 경로 (쿠키 헤더를 보내기 위해 요청된 URL)
Expires / Max-Age : 쿠키 만료 기간 / 쿠키 최대 사용기간
Size : 쿠키 크기(byte)
HTTP : HTTP 사용 여부 - true / false (true 이면 HTTP를 통해서만 쿠키를 서버로 보낼 수 있음)
Secure : HTTPS 사용 여부 - true / false (true 이면 HTTPS를 통해서만 쿠키를 서버로 보낼 수 있음)
SameSite : 사이트 제한 설정 - none, strict(기본값), lax로 설정 (쿠키를 자사(http://www.home.com) 또는 동일 사이트(dev.home.com) 컨텍스트로 제한해야 하는지를 선언할 수 있습니다. CSRF(Cross-Site Request Forgery - 교차 사이트 요청 위조) 공격을 방지하기 위해 HTTP 쿠키에서 설정할 수 있는 속성입니다.)
- none : 모든 도메인에 쿠키가 전송
- strict : 동일한 사이트 내의 요청에만 전송
- lax : 동일한 사이트 내의 요청 또는 "안전한" HTTP 메서드를 사용하는 최상위 경로(/)인 경우 전송
SameParty : 동일 사이트 사용 여부 - true / false (true 이면 동일한 사이트 내의 요청에서 최상위 경로(/)인 경우 쿠키를 설정하거나 전송할 수 있음)
Priority : 우선순위 - low, medium(기본값), high로 설정

Cookie 함수

Cookies에 저장하기

cookies.set(keyName: string, value: string, expireTimes?: string | number | Date, path?: string, domain?: string, secure?: boolean, sameSite?: string)

Cookies의 set() 메서드는 Cookies에 keyName으로 value를 저장합니다.

Cookies의 set() 메서드에서 만료 기간을 지정하지 않으면 현재 시간에서 하루(1d)가 추가되어 설정됩니다.

그리고 경로(Path)도 설정하지 않았기 때문에 최상위 경로(/)로 설정됩니다.

Cookies에서 가져오기

cookies.get(keyName: string)

Cookies의 get() 메서드는 Cookies에서 keyName으로 검색하여 저장된 쿠키를 가져옵니다.

Cookies에서 제거하기

cookies.remove(keyName: string, path?: string, domain?: string)

Cookies의 remove() 메서드는 Cookies에서 keyName으로 검색하여 저장된 쿠키를 제거합니다.

1. vue3-cookies 설치하기 (터미널에서 실행합니다.)

npm install vue3-cookies --save

2. src\stores\useLoginStore.js 파일을 수정합니다. - Storage에 State를 저장시키는 함수를 추가합니다.

:
import { useCookies } from "vue3-cookies";


export const useLoginStore = defineStore('login', () => {
    :
   const { cookies } = useCookies();
    :

    // Storage에서 state를 저장합니다.
    function saveStateToStorage() {
        const state = {
            access_token : access_token.value,
            refresh_token :  refresh_token.value,
            member_id : member_id.value,
            member_name : member_name.value
        }
        cookies.set("lunchapp.login", JSON.stringify(state));
    }

    :
});

3. src\stores\useLoginStore.js 파일을 수정합니다. - 로그인 함수에 추가합니다.

:

export const useLoginStore = defineStore('login', () => {
    :

    // 로그인합니다.
    async function doLogin(memberInfo) {
        :

        try {
            const res = await axios.post("http://127.0.0.1:9000/api/v1/member/login", memberInfo);
            if (res.data.code == 200) {
                :
                // Storage에서 state를 저장합니다.
                saveStateToStorage();
                result = true;
            }
        }
        :
    }

    :

4. 웹 브라우저에서 확인하기 (http://localhost:8080)

로그인을 하면 Application의 Cookies에 lunchapp.login이 저장되는 것을 확인할 수 있습니다.

Application의 Cookies에 저장된 lunchapp.login의 내용은 다음과 같습니다.

Name : lunchapp.login

Value : %7B%22access_token%22%3A%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoi7YWM7Iqk7Yq4MSIsInJvbGVzIjoiUk9MRV9VU0VSIiwidHlwIjoiQmVhcmVyIiwic2NvcGUiOiJwcm9maWxlIGx1bmNobWVudS5hbGwiLCJpYXQiOjE3NDQwMTU2NzgsImV4cCI6MTc0NDAxNTczOCwiYXVkIjoibHVuY2htZW51QXBwIiwiaXNzIjoiYXBpc2VydmVyLmV4YW1wbGUuY29tIiwic3ViIjoidGVzdDEiLCJqdGkiOiI5Nzk0NzBkNWE0NmM0MGMyOWM3YWE0NzVhNTg5MDFhMSJ9.v1sxBNVVlKT0rUQzbbmFnvT-lwZApyICxfgMIh_rEjM%22%2C%22refresh_token%22%3A%22eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJSZWZyZXNoIiwic2NvcGUiOiJwcm9maWxlIHNjb3BlcyIsImlhdCI6MTc0NDAxNTY3OCwiZXhwIjoxNzQ0MDE1Nzk4LCJhdWQiOiJsdW5jaG1lbnVBcHAiLCJpc3MiOiJhcGlzZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWIiOiJ0ZXN0MSIsImp0aSI6ImI2ODkxNjEyYzNmOTRlNDNiMzE4YTNjYmZhYmNjZTU1In0.m99wsch3Uz2_Q0BpsPEmLpsN6Qo10XV0IU8BAj25QoA%22%2C%22member_id%22%3A%22test1%22%2C%22member_name%22%3A%22%ED%85%8C%EC%8A%A4%ED%8A%B81%22%7D

Domain : localhost

Path : /

Expires / Max-Age : 2025-04-08T08:47:58.398Z

Size : 876

HTTP :

Secure :

SameSite : Lax

SameParty :

Priority : Medium

5. 웹 브라우저를 새로고침(F5)하면 Cookie에는 값은 있지만 로그인이 유지되지 않습니다.

6. src\stores\useLoginStore.js 파일을 수정합니다. - Storage에서 State를 읽어오는 함수를 추가합니다.

export const useLoginStore = defineStore('login', () => {
    :

    // Storage에서 state를 읽어옵니다.
    function readStateFromStorage() {
        if (cookies.get("testvue.login") != null) {
            const state = cookies.get("testvue.login");
            if (state.access_token != null) {
                access_token.value = state.access_token;
            }
            if (state.refresh_token != null) {
                refresh_token.value = state.refresh_token;
            }
            if (state.member_id != null) {
                member_id.value = state.member_id;
            }
            if (state.member_name != null) {
                member_name.value = state.member_name;
            }
        }
    }

    return {
        :
        doLogout,
        readStateFromStorage
    }
});

Cookies의 get() 메서드로 JSON 객체를 가져올 때는 자동으로 JSON 객체로 변환됩니다. JSON.parse() 메서드를 사용하지 않아도 됩니다.

7. src\App.vue 파일을 수정합니다. - onMounted()를 추가하여 Storage에 있는 State를 읽어오게 합니다.

<script>
import { computed, onMounted } from 'vue';
:

export default {
    name: 'AppView',
    setup() {
        :

        onMounted(()=> {
            loginStore.readStateFromStorage();
        });

        :
    }
}
</script>

8. 웹 브라우저를 새로고침(F5)하면 Cookie에 있는 값을 로그인을 유지하는 것을 확인할 수 있습니다.

9. src\stores\useLoginStore.js 파일을 수정합니다. - 로그아웃이 되면 쿠키가 삭제되게 합니다.

export const useLoginStore = defineStore('login', () => {
    :

    // 로그아웃합니다.
    async function doLogout() {
        console.log("로그아웃되었습니다.");
        access_token.value = "";
        refresh_token.value = "";
        member_id.value = "";
        member_name.value = "";
        cookies.remove("lunchapp.login");
    }

    :
});

10. 로그아웃을 하면 Cookie가 삭제되는 것을 확인할 수 있습니다.

Store State 유지 - Storage(스토리지) 사용

1. 개발자 툴에서 Application를 클릭하고 Local storage를 클릭합니다.

Storage 구성

Storage는 키(key)와 값(value)으로 구성되어 저장되고 키(key)로 조회됩니다.
Storage는 Local Storage(로컬 스토리지)와 Session Storage(섹션 스토리지)가 있습니다.
- Local Storage(로컬 스토리지)는 영구적으로 저장됩니다. (삭제하지 않는 한 계속 유지됩니다.)
- Session Storage(섹션 스토리지)는 임시적으로 저장됩니다. (웹 브라우저가 종료되면 사라집니다.)

Storage 함수

Local storage에 저장하기

localStorage.setItem(key: string, value: string)

localStorage의 setItem() 메서드는 Local storage에 key로 value를 저장합니다.

Local storage에서 가져오기

localStorage.getItem(key: string)

localStorage의 getItem() 메서드는 Local storage에서 key로 검색하여 저장된 값을 가져옵니다.

Local storage에서 제거하기

localStorage.removeItem(key: string)

localStorage의 removeItem() 메서드는 Local storage에서 key로 검색하여 저장된 값을 제거합니다.

1. src\stores\useLoginStore.js 파일을 수정합니다. - Cookies를 제거하고 localStorage로 변경합니다.

:
//import { useCookies } from "vue3-cookies";


export const useLoginStore = defineStore('login', () => {
    :
   //const { cookies } = useCookies();
    :

    // Storage에서 state를 저장합니다.
    function saveStateToStorage() {
        const state = {
            access_token : access_token.value,
            refresh_token :  refresh_token.value,
            member_id : member_id.value,
            member_name : member_name.value
        }
        //cookies.set("lunchapp.login", JSON.stringify(state));
        localStorage.setItem("lunchapp.login", JSON.stringify(state));
    }

    :
});

2. src\stores\useLoginStore.js 파일을 수정합니다. - Cookies를 제거하고 localStorage로 변경합니다.

export const useLoginStore = defineStore('login', () => {
    :

    // Storage에서 state를 읽어옵니다.
    function readStateFromStorage() {
        //if (cookies.get("lunchapp.login") != null) {
        //    const state = cookies.get("lunchapp.login");
        if (localStorage.getItem("lunchapp.login") != null) {
            const state =  JSON.parse(localStorage.getItem("lunchapp.login"));
            if (state.access_token != null) {
                access_token.value = state.access_token;
            }
            if (state.refresh_token != null) {
                refresh_token.value = state.refresh_token;
            }
            if (state.member_id != null) {
                member_id.value = state.member_id;
            }
            if (state.member_name != null) {
                member_name.value = state.member_name;
            }
        }
    }

    :
});

JSON.parse() 메서드를 사용하여 JSON 객체로 변환해야 합니다.

3. src\stores\useLoginStore.js 파일을 수정합니다. - Cookies를 제거하고 localStorage로 변경합니다.

export const useLoginStore = defineStore('login', () => {
    :

    // 로그아웃합니다.
    async function doLogout() {
        console.log("로그아웃되었습니다.");
        access_token.value = "";
        refresh_token.value = "";
        member_id.value = "";
        member_name.value = "";
        //cookies.remove("lunchapp.login");
        localStorage.removeItem("lunchapp.login");
    }

    :
});

4. 로그인을 하면 Application의 Local storage에 lunchapp.login이 저장되는 것을 확인할 수 있습니다.

Application의 Local storage에 저장된 lunchapp.login의 내용은 다음과 같습니다.

Key : lunchapp.login
Value : {"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoi7YWM7Iqk7Yq4MSIsInJvbGVzIjoiUk9MRV9VU0VSIiwidHlwIjoiQmVhcmVyIiwic2NvcGUiOiJwcm9maWxlIGx1bmNobWVudS5hbGwiLCJpYXQiOjE3NDQwMzUyMzAsImV4cCI6MTc0NDAzNTI5MCwiYXVkIjoibHVuY2htZW51QXBwIiwiaXNzIjoiYXBpc2VydmVyLmV4YW1wbGUuY29tIiwic3ViIjoidGVzdDEiLCJqdGkiOiIwMWMzNWE1YWVlMmE0YjA1YjM0ZGQ4OWI1MmEwZDZhNiJ9.Smocyex5QHHNigkYh6OTbhqRUK2EtLzKT1oO8Mat3tU","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJSZWZyZXNoIiwic2NvcGUiOiJwcm9maWxlIHNjb3BlcyIsImlhdCI6MTc0NDAzNTIzMCwiZXhwIjoxNzQ0MDM1MzUwLCJhdWQiOiJsdW5jaG1lbnVBcHAiLCJpc3MiOiJhcGlzZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWIiOiJ0ZXN0MSIsImp0aSI6IjdhYWYyMzU0MTIzZDQxNGE5ZTU1YzdjZmQ4MmQyMzQzIn0.P8pc8rT52XZZCzGrB-WUC6pVRt5hMcZ_qD2A6XKkEB0","member_id":"test1","member_name":"테스트1"}

5. 로그아웃을 하면 Local storage에 있는 lunchapp.login이 삭제되는 것을 확인할 수 있습니다.

Pinia Plugin Persistedstate 사용

Pinia Plugin Persistedstate (피니아 플러그인 퍼시스트드스테이트)
(https://prazdevs.github.io/pinia-plugin-persistedstate/)

1. pinia-plugin-persistedstate 설치하기 (터미널에서 실행합니다.)

npm install pinia-plugin-persistedstate --save

2. src\main.js 파일을 수정합니다. - pinia plugin를 추가합니다.

import { createApp } from 'vue';
import { ref } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';
import router from './router';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';

const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);
const app = createApp(App);

:

3. src\App.vue 파일을 수정합니다. - Storage를 제거합니다.

<script>
import { computed } from 'vue';
:

export default {
    name: 'AppView',
    setup() {
        :

        /*
        onMounted(()=> {
            loginStore.readStateFromStorage();
        });
        */

        :
    }
}
</script>

onMounted를 삭제합니다.

4. src\stores\useLoginStore.js 파일을 수정합니다. - Storage를 제거합니다.

:

export const useLoginStore = defineStore('login', () => {
    :

    // 로그인합니다.
    async function doLogin(memberInfo) {
        :

        try {
            const res = await axios.post("http://127.0.0.1:9000/api/v1/member/login", memberInfo);
            if (res.data.code == 200) {
                :
                // Storage에서 state를 저장합니다.
                //saveStateToStorage();
                result = true;
            }
        }
        :
    }
    :

    // 로그아웃합니다.
    async function doLogout() {
        console.log("로그아웃되었습니다.");
        access_token.value = "";
        refresh_token.value = "";
        member_id.value = "";
        member_name.value = "";
        //localStorage.removeItem("lunchapp.login");
    }

    /*
    // Storage에서 state를 저장합니다.
    function saveStateToStorage() {
        const state = {
            access_token : access_token.value,
            refresh_token :  refresh_token.value,
            member_id : member_id.value,
            member_name : member_name.value
        }
        localStorage.setItem("lunchapp.login", JSON.stringify(state));
    }

    // Storage에서 state를 읽어옵니다.
    function readStateFromStorage() {
        if (localStorage.getItem("lunchapp.login") != null) {
            const state =  JSON.parse(localStorage.getItem("lunchapp.login"));
            if (state.access_token != null) {
                access_token.value = state.access_token;
            }
            if (state.refresh_token != null) {
                refresh_token.value = state.refresh_token;
            }
            if (state.member_id != null) {
                member_id.value = state.member_id;
            }

            if (state.member_name != null) {
                member_name.value = state.member_name;
            }
        }
    }
    */

    return {
        access_token,
        refresh_token,
        member_id,
        member_name,
        isLogin,
        doLogin,
        isAccessTokenExpire,
        doRefreshToken,
        doLogout
        //readStateFromStorage
    }
});

5. src\stores\useLoginStore.js 파일을 수정합니다. - 3번째 파라미터에 { persist:true }를 추가합니다.

import { defineStore } from 'pinia';
import { ref } from 'vue';
import axios from 'axios';

export const useLoginStore = defineStore('login', () => {
    :
}, { persist:true });

6. 로그인을 하면 Application의 Local storage에 login으로 저장되는 것을 확인할 수 있습니다.

Application의 Local storage에 저장된 login의 내용은 다음과 같습니다.

Key : login
Value : {"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoi7YWM7Iqk7Yq4MSIsInJvbGVzIjoiUk9MRV9VU0VSIiwidHlwIjoiQmVhcmVyIiwic2NvcGUiOiJwcm9maWxlIGx1bmNobWVudS5hbGwiLCJpYXQiOjE3NDQwMzUyMzAsImV4cCI6MTc0NDAzNTI5MCwiYXVkIjoibHVuY2htZW51QXBwIiwiaXNzIjoiYXBpc2VydmVyLmV4YW1wbGUuY29tIiwic3ViIjoidGVzdDEiLCJqdGkiOiIwMWMzNWE1YWVlMmE0YjA1YjM0ZGQ4OWI1MmEwZDZhNiJ9.Smocyex5QHHNigkYh6OTbhqRUK2EtLzKT1oO8Mat3tU","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJSZWZyZXNoIiwic2NvcGUiOiJwcm9maWxlIHNjb3BlcyIsImlhdCI6MTc0NDAzNTIzMCwiZXhwIjoxNzQ0MDM1MzUwLCJhdWQiOiJsdW5jaG1lbnVBcHAiLCJpc3MiOiJhcGlzZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWIiOiJ0ZXN0MSIsImp0aSI6IjdhYWYyMzU0MTIzZDQxNGE5ZTU1YzdjZmQ4MmQyMzQzIn0.P8pc8rT52XZZCzGrB-WUC6pVRt5hMcZ_qD2A6XKkEB0","member_id":"test1","member_name":"테스트1"}

Key는 Store의 ID입니다.

Value는 Store의 State의 값으로 JSON 객체를 만들어 저장합니다.

export const useLoginStore = defineStore('login', () => {
    const access_token = ref("");
    const refresh_token = ref("");
    const member_id = ref("");
    const member_name = ref("");
    :
}, { persist:true });

7. 로그아웃을 하면 Local storage에 있는 login에 저장된 JSON 객체의 값이 제거되는 것을 확인할 수 있습니다.

Pinia Plugin Persistedstate 구성

key : Storage의 key를 설정합니다. (기본값: store.$id)
storage : 저장소(localStorage, sessionStorage)를 설정합니다. (기본값: localStorage)
serializer : 저장하기전에 직렬화하고 가져올 때 역직렬화를 설정합니다. (기본값: JSON.stringify/destr)
pick : 선택적으로 저장할 state를 선택합니다. (기본값: 없음, 전체 state가 저장됩니다.)
omit : 선택적으로 생략할 state를 선택합니다. (기본값: 없음)
beforeHydrate : Storage에서 가져오기 전에 호출되는 Callback 함수를 설정합니다. (기본값: 없음)
afterHydrate : Storage에서 가져온 후에 호출되는 Callback 함수를 설정합니다. (기본값: 없음)

1. src\stores\useLoginStore.js 파일을 수정합니다. - 3번째 파라미터에 persist를 구성하여 추가합니다.

import { defineStore } from 'pinia';
import { ref } from 'vue';
import axios from 'axios';

export const useLoginStore = defineStore('login', () => {
    :
}, { persist: {
        key: 'lunchapp.login',
        storage: localStorage,
        pick: ['access_token'],
        beforeHydrate:(ctx => console.log(`about to hydrate ${ctx.store.$id}`)),
        afterHydrate:(ctx => console.log(`just hydrated ${ctx.store.$id}`))
    }
});

localStorage에 lunchapp.login이란 Key로 access_token만 저장합니다.

Storage에서 가져오기 전과 후에 콘솔로 로그를 출력합니다.

2. 로그인을 하면 Application의 Local storage에 lunchapp.login으로 저장되는 것을 확인할 수 있습니다.

3. Application의 Local storage에 저장된 lunchapp.login의 내용은 다음과 같습니다.

테스트로 access_token만 저장되기 때문에 로그인이 유지되지 않습니다.

[17] Frontend 개발 - Login 관리, 모듈화

carrotweb — Wed, 5 Aug 2026 18:50:22 +0900

모듈화

Axios Instance (엑시오스 인터셉터)
(https://axios-http.com/kr/docs/instance)

1. src\apis\axiosInterceptor.js 파일을 수정합니다.

import axios from 'axios';
import { useLoginStore } from '@/stores/useLoginStore';
import { useRouter } from 'vue-router';

export const createAxiosInstance = (baseURL, timeout) => {
    const loginStore = useLoginStore();
    
    const router = useRouter();

    const axiosInstance = axios.create({
        baseURL : baseURL,
        timeout : timeout
    });
    :

baseURL은 기본 URL입니다. baseURL이 설정되어 있으면 메소드의 url과 합쳐집니다.

timeout은 요청에 대한 응답이 길어질 경우 중단을 하기 위한 시간입니다. (timeout 시간을 짧게 하면 서버 timeout(응답 코드 408, timeout)) 전에도 중단할 수 있습니다.)

2. src\apis에 lunchmenuApi.js 파일을 생성합니다.

import { createAxiosInstance } from './axiosInterceptor';

let axiosInstance = null;

// LunchmenuApi를 위한 Axios 인스턴스 생성
function createLunchmenuApi() {
    if (axiosInstance == null) {
        axiosInstance = createAxiosInstance("http://127.0.0.1:9000", 60);
    }
    return axiosInstance;
}

// 전체 점심 메뉴 리스트를 가져옵니다.
export function getLunchMenuList() {
    return createLunchmenuApi().get("/api/v1/lunchmenus/");
}

// 점심 메뉴 번호로 검색하여 점심 메뉴를 가져옵니다.
export function getLunchMenuItem(seq) {
    return createLunchmenuApi().get("/api/v1/lunchmenus/" + seq);
}

// 점심 메뉴를 추가합니다.
export function addLunchMenuItem(lunchMenuItem) {
    return createLunchmenuApi().post("/api/v1/lunchmenus/", lunchMenuItem);
}

// 점심 메뉴를 수정합니다.
export function editLunchMenuItem(seq, lunchMenuItem) {
    return createLunchmenuApi().put("/api/v1/lunchmenus/" + seq, lunchMenuItem);
}

// 점심 메뉴를 삭제합니다.
export async function removeLunchMenuItem(seq) {
    return createLunchmenuApi().delete("/api/v1/lunchmenus/" + seq);
}

3. src\views\LunchMenu\LunchMenuListView.vue 파일을 수정합니다.

<script>
:
// import { createAxiosInstance } from '@/apis/axiosInterceptor';
import * as lunchmenuApi from '@/apis/lunchmenuApi';
:

export default {
    name : 'LunchMenuListView',
    setup() {
        :
        //const loginStore = useLoginStore();
        :

         async function getLunchMenuList() {
            try {
                //const res = await createAxiosInstance("http://127.0.0.1:9000").get("/api/v1/lunchmenus/");
                const res = await lunchmenuApi.getLunchMenuList();
                console.log(res);
                lunchMenuList.value = res.data.data;
            } catch(err) {
                console.log(err);
            }
        }
        :

4. src\views\LunchMenu\LunchMenuAddView.vue 파일을 수정합니다.

<script>
:
//import axios from 'axios';
import * as lunchmenuApi from '@/apis/lunchmenuApi';
:

export default {
    name : 'LunchMenuAddView',
    setup() {
        :
        function addClick() {
            const lunchMenuItem = { menuName : state.lunchMenuName };
            //axios.post("http://127.0.0.1:9000/api/v1/lunchmenus/", lunchMenuItem).then(() => {
            lunchmenuApi.addLunchMenuItem(lunchMenuItem).then(() => {
                router.replace({name : 'lunchmenulist'});
            }).catch((err) => {
                console.log(err);
            });
        }

        function getLunchMenuItem() {
            //axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/" + route.query.seq).then((res) => {
            lunchmenuApi.getLunchMenuItem(route.query.seq).then((res) => {
                state.lunchMenuName = res.data.data.menu_name;
            }).catch((err) => {
                console.log(err);
            });
        }

        function editClick() {
            if (state.lunchMenuName == "") {
                alert("점심 메뉴 명을 입력하세요.");
                lunchMenuNameInput.value.focus();
                return;
            }
            var result = confirm("수정하시겠습니까?");
            if (result) {
                const lunchMenuItem = { menuName : state.lunchMenuName };
                //axios.put("http://127.0.0.1:9000/api/v1/lunchmenus/"+ route.query.seq, lunchMenuItem).then(() => {
                lunchmenuApi.editLunchMenuItem(route.query.seq, lunchMenuItem).then(() => {
                    router.replace({name : 'lunchmenuread', query : {seq : route.query.seq}});
                }).catch((err) => {
                    console.log(err);
                });
            }
        }
        :

5. src\views\LunchMenu\LunchMenuReadView.vue 파일을 수정합니다.

<script>
:
//import axios from 'axios';
import * as lunchmenuApi from '@/apis/lunchmenuApi';
:

export default {
    name : 'LunchMenuReadView',
    setup() {
        :
         function getLunchMenuItem() {
            //axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/" + route.query.seq).then((res) => {
            lunchmenuApi.getLunchMenuItem(route.query.seq).then((res) => {
                console.log(res);
                lunchMenuItem.value = res.data.data;
            }).catch((err) => {
                console.log(err);
            });
        }
        :

        async function deleteClick() {
            var result = confirm("삭제하시겠습니까?");
            if (result) {
                try {
                    //const res = await axios.delete("http://127.0.0.1:9000/api/v1/lunchmenus/" + route.query.seq);
                    const res = await lunchmenuApi.removeLunchMenuItem(route.query.seq);
                    console.log(res);
                    if (res.data.code == 200) {
                        alert("삭제되었습니다.");
                        router.push({name : 'lunchmenulist'});
                    } else {
                        alert("삭제되지 않았습니다.");
                    }
                } catch(err) {
                    console.log(err);
                }
            }
        }
        :

로그인 /로그아웃, 로그인 여부 확인

1. src\stores\useLoginStore.js 파일을 수정합니다.

import { defineStore } from 'pinia';
import { ref } from 'vue';
import axios from 'axios';

export const useLoginStore = defineStore('login', () => {
    const access_token = ref("");
    const refresh_token = ref("");
    const member_id = ref("");
    const member_name = ref("");

    // 로그인 여부를 가져옵니다.
    /*
    const isLogin = computed(() => {
        return refresh_token.value == "" ? false : true;
    });
    */
    function isLogin() {
        let login = false;
        if (refresh_token.value != "") {
            // refresh_token에서 .(도트)로 분리하여 payload를 가져옵니다.
            let base64Payload = refresh_token.value.split('.')[1];
            // URL과 호환되지 않는 문자를 base64 표준 문자로 교체합니다.
            base64Payload = base64Payload.replace(/-/g, '+').replace(/_/g, '/');
            // atob() 메소드로 복호화합니다.
            base64Payload = atob(base64Payload);
            // JSON 객체로 변환합니다.
            const payloadObject = JSON.parse(base64Payload);
            // refresh_token의 만료 시간을 확인합니다.
            const currentDate = new Date().getTime() / 1000;
            if (payloadObject.exp <= currentDate) {
                console.log("token expired");
            } else {
                console.log("token valid");
                login = true;
            }
        }
        return login;
    }

    // 로그인합니다.
    async function doLogin(memberInfo) {
        let result = false;
        let resultErr = null;

        try {
            const res = await axios.post("http://127.0.0.1:9000/api/v1/member/login", memberInfo);
            if (res.data.code == 200) {
                console.log("로그인되었습니다.");
                access_token.value = res.data.access_token;
                refresh_token.value = res.data.refresh_token;
                // access_token에서 .(도트)로 분리하여 payload를 가져옵니다.
                let base64Payload = access_token.value.split('.')[1];
                // URL과 호환되지 않는 문자를 base64 표준 문자로 교체합니다.
                base64Payload = base64Payload.replace(/-/g, '+').replace(/_/g, '/');
                // atob() 메소드로 복호화합니다.
                base64Payload = atob(base64Payload);
                // JSON 객체로 변환합니다.
                const payloadObject = JSON.parse(base64Payload);
                member_id.value = payloadObject.sub;
                member_name.value = decodeURIComponent(escape(payloadObject.name));
                result = true;
            }
        } catch(err) {
            :

    // 로그아웃합니다.
    async function doLogout() {
        console.log("로그아웃되었습니다.");
        access_token.value = "";
        refresh_token.value = "";
        member_id.value = "";
        member_name.value = "";
    }

    return {
        access_token,
        refresh_token,
        member_id,
        member_name,
        isLogin,
        doLogin,
        isAccessTokenExpire,
        doRefreshToken,
        doLogout
    }
    :

computed를 삭제합니다.

2. src\router\index.js 파일을 수정합니다.

:

const Authentication = () => (to, from, next) => {
  const loginStore = useLoginStore();
  if (to.name.startsWith("lunchmenu")) {
    if (!loginStore.isLogin()) {
      next({path: '/login', query: { returnUrl: to.fullPath }});
    } else {
      next();
    }
  } else {
    next();
  }
};

:

3. src\App.vue 파일을 수정합니다.

<template>
  <div class="header">
        <div class="topline">
            <div class="headmenu">
                <div v-if="isLogin()">
                    {{greetingMessage}}
                    <span @click="Logout()">로그아웃</span>
                </div>
                <div v-else>
                    <router-link :to="{ name: 'Login' }">로그인</router-link>
                </div>
            </div>
        </div>
        <nav>
            <router-link to="/">Home</router-link> |
            <router-link to="/about">About</router-link> |
            <router-link to="/lunchmenu/list">LunchMenu</router-link>
        </nav>
  </div>
  <router-view/>
</template>

<script>
import { computed } from 'vue';
import { useLoginStore } from '@/stores/useLoginStore';
import { useRouter } from 'vue-router';

export default {
  name: 'AppView',
  setup() {
    const loginStore = useLoginStore();
    const router = useRouter();

    // 로그인 여부를 가져옵니다.
    function isLogin() {
      return loginStore.isLogin();
    }

    // 로그아웃합니다
    function Logout() {
      loginStore.doLogout();
      router.replace({name : 'home'});
    }

    // 환영 메시지를 가져옵니다.
    const greetingMessage = computed(() => {
      return `${loginStore.member_name}님, 안녕하세요.`;
    });

    return {
      isLogin,
      Logout,
      greetingMessage
    }
  }
}
</script>

<style>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
}
nav {
  padding: 30px;
}
nav a {
  font-weight: bold;
  color: #2c3e50;
}
nav a.router-link-exact-active {
  color: #42b983;
}
.header {
  position:relative;
}
.header .topline {
  position:relative;
  height:30px;
  margin:0 10px;
}
.header .topline .headmenu {
  position:absolute;
  right:0;
  top:4px;
}
.header .topline .headmenu a {
  font-weight:bold;
  color:#2c3e50;
}
.header .topline .headmenu span {
  font-weight:bold;
  color:#2c3e50;
  cursor:pointer;
  text-decoration:underline;
}
</style>

4. 웹 브라우저에서 확인하기 (http://localhost:8080) ← 로그인 전

5. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) ← 로그인 후

[16] Frontend 개발 - Login 관리, Axios Interceptor

carrotweb — Wed, 5 Aug 2026 18:29:16 +0900

Axios Interceptor (엑시오스 인터셉터)를 사용하여 Access Token 재발급(갱신)

Axios Interceptor (엑시오스 인터셉터)
(https://axios-http.com/kr/docs/interceptors)

Axios 요청 전이나 Axios 응답 후 처리는 Axios Interceptor (엑시오스 인터셉터)을 사용하여 가로챌 수 있습니다.

Axios Interceptor (엑시오스 인터셉터) 기본 구조입니다.

// 요청 인터셉터
axios.interceptors.request.use(function (config) {
    // Do something before request is sent
    // 요청이 전달되기 전에 처리
    return config;
  }, function (error) {
    // Do something with request error
    // 요청 오류에 대한 처리
    return Promise.reject(error);
  });

// 응답 인터셉터
axios.interceptors.response.use(function (response) {
    // Any status code that lie within the range of 2xx cause this function to trigger
    // 응답 상태코드가 2xx 범위안에 있으면 트리거됩니다.
    // Do something with response data
    // 응답 데이터로 처리
    return response;
  }, function (error) {
    // Any status codes that falls outside the range of 2xx cause this function to trigger
    // 응답 상태코드가 2xx 범위를 벗어나면 트리거됩니다.
    // Do something with response error
    // 응답 오류에 대한 처리
    return Promise.reject(error);
  });

1. src에 apis 디렉터리를 생성하고 axiosInterceptor.js 파일을 생성합니다.

import axios from 'axios';

const axiosInstance = axios.create();

// 요청 인터셉터
axiosInstance.interceptors.request.use(function (config) {
    console.log("axios.interceptors.request");
    return config;
  }, function (error) {
    console.log("axios.interceptors.request.error");
    console.log(error);
    return Promise.reject(error);
  });

// 응답 인터셉터
axiosInstance.interceptors.response.use(function (response) {
    console.log("axios.interceptors.response");
    return response;
  }, function (error) {
    console.log("axios.interceptors.response.error");
    console.log(error);
    return Promise.reject(error);
  });

  export default axiosInstance;

2. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list)

3. src\apis\axiosInterceptor.js 파일을 수정합니다.

import axios from 'axios';
import { useLoginStore } from '@/stores/useLoginStore';

export const createAxiosInstance = () => {
    const loginStore = useLoginStore();
    
    const axiosInstance = axios.create();

    // 요청 인터셉터
    axiosInstance.interceptors.request.use(async function (config) {
        console.log("axios.interceptors.request");
        console.log(loginStore.access_token);
        return config;
    }, function (error) {
        console.log("axios.interceptors.request.error");
        console.log(error);
        return Promise.reject(error);
    });

    // 응답 인터셉터
    axiosInstance.interceptors.response.use(function (response) {
        console.log("axios.interceptors.response");
        return response;
    }, function (error) {
        console.log("axios.interceptors.response.error");
        console.log(error);
        return Promise.reject(error);
    });

    return axiosInstance;
};

Store를 사용하기 위해서 함수로 변경해야 합니다.

4. src\views\LunchMenu\LunchMenuListView.vue 파일을 수정합니다.

<script>
:
//import axios from 'axios';
import { createAxiosInstance } from '@/apis/axiosInterceptor';
:

export default {
    name : 'LunchMenuListView',
    setup() {
        const router = useRouter();
        const route = useRoute();
        :

        async function getLunchMenuList() {
            console.log(loginStore.access_token);
            :

            try {
                const res = await createAxiosInstance().get("http://127.0.0.1:9000/api/v1/lunchmenus/", {
                    headers: {
                        "Authorization" : "Bearer " + loginStore.access_token
                    }
                });
                console.log(res);
                lunchMenuList.value = res.data.data;
            } catch(err) {
                console.log(err);
            }
            :

5. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list)

Axios Interceptor (엑시오스 인터셉터) 사용 - Axios 요청 전 적용

Access Token의 만료 확인 시점

요청하기 전에 Access Token이 만료되었는지 확인하기 위해서는 Axios Interceptor (엑시오스 인터셉터)을 사용합니다.

Access Token의 payload에 있는 exp(expiration, 만료 시간)를 확인하여 만료되었는지 확인 후 Refresh Token를 사용하여 Access Token를 재발급합니다. → 매번 Access Token를 확인

1. src\apis\axiosInterceptor.js 파일을 수정합니다.

:
import { useRouter } from 'vue-router';

export const createAxiosInstance = () => {
    :
    const router = useRouter();
    :

    // 요청 인터셉터
    axiosInstance.interceptors.request.use(async function (config) {
        console.log("axios.interceptors.request");
        console.log(loginStore.access_token);
        if (loginStore.isAccessTokenExpire()) {
            console.log("Access Token이 만료되었습니다.");
            try {
                await loginStore.doRefreshToken();
            } catch(err) {
                console.log(err);
                alert("인증이 만료되었습니다.\n다시 로그인 해주시기 바랍니다.");
                router.replace({name : 'Login'});
            }
        }
        return config;
    }, function (error) {
        console.log("axios.interceptors.request.error");
        console.log(error);
        return Promise.reject(error);
    });
    :

2. src\views\LunchMenu\LunchMenuListView.vue 파일을 수정합니다.

<script>
:
import { useRouter } from 'vue-router';
:

export default {
    name : 'LunchMenuListView',
    setup() {
        :
        // const route = useRoute();
        :

        async function getLunchMenuList() {
            console.log(loginStore.access_token);
            /*
            if (loginStore.isAccessTokenExpire()) {
                console.log("Access Token이 만료되었습니다.");
                try {
                    await loginStore.doRefreshToken();
                } catch(err) {
                    console.log(err);
                    alert("인증이 만료되었습니다.\n다시 로그인 해주시기 바랍니다.");
                    router.replace({path: '/login', query: { returnUrl: route.fullPath }});
                    return;
                }
            }
            */

            :

useRoute를 삭제하고 Access Token 만료 처리를 부분을 주석처리하거나 삭제합니다.

3. src\views\Account\LoginView.vue 파일을 수정합니다.

<script>
:

export default {
    name : 'LoginView',
    setup() {
        :
        function loginClick() {
            :

            const memberInfo = { id: state.memberId, password: state.memberPassword };
            loginStore.doLogin(memberInfo).then(() => {
                const returnUrl = route.query.returnUrl;
                if (returnUrl == null || returnUrl == "") {
                    router.replace({name : 'home'});
                } else {
                    router.replace({path : returnUrl});
                }
            }).catch((err) => {
                state.errorMessage = err.message;
            });
        }
        :

returnUrl이 없으면 홈으로 이동되게 처리합니다.

4. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (10분 후) → Access Token 재발급(갱신)

5. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (15분 후) → Refresh Token 만료 → 재발급(갱신) 불가 → 로그인 → 홈

Axios Interceptor (엑시오스 인터셉터) 사용 - Axios 응답 후 적용

Access Token의 만료 확인 시점

요청 후 응답에서 Access Token이 만료되었는지 확인하기 위해서는 Axios Interceptor (엑시오스 인터셉터)을 사용합니다.

요청 후 응답에서 Access Token이 만료되었다는 응답 코드(401, Unauthorized)와 응답 메시지(“토큰이 만료되었습니다.”)가 오면 Refresh Token를 사용하여 Access Token를 재발급하고 다시 요청을 보냅니다. → 요청에 대한 응답이 실패일 경우만 처리

1. src\apis\axiosInterceptor.js 파일을 수정합니다.

:

export const createAxiosInstance = () => {
    :

    // 요청 인터셉터
    axiosInstance.interceptors.request.use(async function (config) {
        console.log("axios.interceptors.request");
        console.log(loginStore.access_token);

        config.headers['Content-Type'] = 'application/json';
        config.headers['Authorization'] = `Bearer ${loginStore.access_token}`;

        /*
        if (loginStore.isAccessTokenExpire()) {
            console.log("Access Token이 만료되었습니다.");
            try {
                await loginStore.doRefreshToken();
            } catch(err) {
                console.log(err);
                alert("인증이 만료되었습니다.\n다시 로그인 해주시기 바랍니다.");
                router.replace({name : 'Login'});
            }
        }
        */

        return config;
    }, function (error) {
        :

Request Header에 Authorization를 추가하고 Access Token 만료 처리 부분을 주석처리하거나 삭제합니다.

2. src\views\LunchMenu\LunchMenuListView.vue 파일을 수정합니다.

<script>
:
//import { useLoginStore } from '@/stores/useLoginStore';
:

export default {
    name : 'LunchMenuListView',
    setup() {
        :
        //const loginStore = useLoginStore();
        :

        async function getLunchMenuList() {
            //console.log(loginStore.access_token);

            try {
            	/*
                const res = await createAxiosInstance().get("http://127.0.0.1:9000/api/v1/lunchmenus/", {
                    headers: {
                        "Authorization" : "Bearer " + loginStore.access_token
                    }
                });
                */
                const res = await createAxiosInstance().get("http://127.0.0.1:9000/api/v1/lunchmenus/");
                console.log(res);
                lunchMenuList.value = res.data.data;
            } catch(err) {
                console.log(err);
            }
        }
        :

Header를 삭제합니다.

3. src\apis\axiosInterceptor.js 파일을 수정합니다.

:

export const createAxiosInstance = () => {
    :

    // 응답 인터셉터
    axiosInstance.interceptors.response.use(function (response) {
        console.log("axios.interceptors.response");
        return response;
    }, async function (error) {
        console.log("axios.interceptors.response.error");
        console.log(error);
        var axiosRequest = error.config;
        if (error.response && !axiosRequest._retry) {
            axiosRequest._retry = true;
            // 응답코드가 401이면 처리합니다.
            if (error.response.status == 401) {
                if (loginStore.isAccessTokenExpire()) {
                    console.log("Access Token이 만료되었습니다.");
                    try {
                        // Access Token 재발급 요청
                        await loginStore.doRefreshToken();

                        // 재발급된 Access Token으로 header를 수정합니다.
                        axiosRequest.headers = {
                            'Content-Type': 'application/json',
                            Authorization: `Bearer ${loginStore.access_token}`
                          };
                        // 다시 요청(request)합니다.
                        const response = await axios.request(axiosRequest);
                        return response;
                    } catch(err) {
                        console.log(err);
                        alert("인증이 만료되었습니다.\n다시 로그인 해주시기 바랍니다.");
                        router.replace({name : 'Login'});
                    }
                }
            }
        }
        return Promise.reject(error);
    });
    :

재요청이 실패하면 계속 반복되기 때문에 반복을 방지하기 위해서 요청 정보(config)에 _retry를 사용하여 한 번만 처리되게 합니다.

응답 상태코드가 401이고 Access Token 만료되어 있으면 Access Token를 재발급하고 요청 정보(config)를 사용하여 다시 요청합니다.

4. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (10분 후) → Access Token 재발급(갱신)

5. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (15분 후) → Refresh Token 만료 → 재발급(갱신) 불가 → 로그인 → 홈

[15] Frontend 개발 - Login 관리, Access Token, Refresh Token

carrotweb — Wed, 5 Aug 2026 18:12:47 +0900

Access Token, Refresh Token (액세스 토큰, 리프레시 토큰)

1. src\stores\useLoginStore.js 파일을 수정합니다.

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

export const useLoginStore = defineStore('login', () => {
    const access_token = ref("");
    const refresh_token = ref("");

    // 로그인 여부를 가져옵니다.
    const isLogin = computed(() => {
        return refresh_token.value == "" ? false : true;
    });

    // 로그인합니다.
    async function doLogin(memberInfo) {
        let result = false;
        let resultErr = null;

        try {
            const res = await axios.post("http://127.0.0.1:9000/api/v1/member/login", memberInfo);
            if (res.data.code == 200) {
                console.log("로그인되었습니다.");
                access_token.value = res.data.access_token;
                refresh_token.value = res.data.refresh_token;
                result = true;
            }
        } catch(err) {
            // 400, 401, 500 에러 처리
            console.log(err);
            if (!err.response) {
                err.response = {
                    data:{"result":"fail", "code":401, "message":"사용자가 없습니다.", access_token: "", refresh_token: ""}
                };
            }
            resultErr = err.response.data;
        }

        return new Promise((resolve, reject) => {
            if (result) {
                resolve();
            } else {
                reject(resultErr);
            }
        });
    }
  
    return {
        access_token,
        refresh_token,
        isLogin,
        doLogin
    }
});

2. src\views\LunchMenu\LunchMenuListView.vue 파일을 수정합니다.

<script>
:

export default {
    name : 'LunchMenuListView',
    setup() {
        :

        function getLunchMenuList() {
            console.log(loginStore.access_token);
            axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/", {
                headers: {
                    "Authorization" : "Bearer " + loginStore.access_token
                }
            }).then((res) => {
                console.log(res);
                lunchMenuList.value = res.data.data;
            }).catch((err) => {
                console.log(err);
            });
        }
        :
    }
};
</script>

3. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list)

JWT 확인

iat(Issued At Time, 발급된 시간)

exp(Expiration Time, 만료 시간)

Access Token 재발급(갱신)

1. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (10분 후)

Access Token의 만료 확인 시점

Access Token을 사용할 경우

요청하기 전에 Access Token이 만료되었는지 확인 후 Refresh Token를 사용하여 Access Token이 재발급 → Access Token의 payload에 있는 exp(expiration, 만료 시간)로 확인 → 매번 확인

요청 후 응답에서 Access Token이 만료되었는지 확인 후 Refresh Token를 사용하여 Access Token이 재발급 → 응답 코드와 응답 메시지로 확인 → 실패일 경우만 처리

1. src\stores\useLoginStore.js 파일을 수정합니다. - Access Token 만료 확인과 재발급(갱신) 함수 추가

:
    // Access Token이 만료되었는지 확인합니다.
    function isAccessTokenExpire() {
        let expire = false;
        if (access_token.value != "") {
            // access_token에서 .(도트)로 분리하여 payload를 가져옵니다.
            let base64Payload = access_token.value.split('.')[1];

            // URL과 호환되지 않는 문자를 base64 표준 문자로 교체합니다.
            base64Payload = base64Payload.replace(/-/g, '+').replace(/_/g, '/');
            
            // atob() 메소드로 복호화합니다.
            base64Payload = atob(base64Payload);
            
            // JSON 객체로 변환합니다.
            var payloadObject = JSON.parse(base64Payload);

            // access_token의 만료 시간을 확인합니다.
            var currentDate = new Date().getTime() / 1000;
            if (payloadObject.exp <= currentDate) {
                console.log("token expired");
                expire = true;
            } else {
                console.log("token valid");
            }
        }
        return expire;
    }

2. src\stores\useLoginStore.js 파일을 수정합니다.

    // Access Token를 갱신합니다.
    async function doRefreshToken() {
        let result = false;
        let resultErr = null;

        if (access_token.value != "" && refresh_token.value != "") {
            try {
                const tokenInfo = { refresh_token: refresh_token.value };
                const res = await axios.post("http://127.0.0.1:9000/api/v1/member/refresh", tokenInfo);
                if (res.data.code == 200) {
                    console.log("Access Token을 재발급(갱신)하였습니다.");
                    console.log(res.data);
                    access_token.value = res.data.access_token;
                    refresh_token.value = res.data.refresh_token;
                    result = true;
                }
            } catch(err) {
                // 400, 401, 500 에러 처리
                console.log(err);
                if (!err.response) {
                    err.response = {
                        data: {"result":"fail", "code":401, "message":"Access Token을 재발급(갱신)할 수 없습니다.", access_token: "", refresh_token: ""}
                    };
                }
            }
        } else {
            resultErr = {"result":"fail", "code":401, "message":"Access Token이 없습니다.", access_token: "", refresh_token: ""}
        }

        return new Promise((resolve, reject) => {
            if (result) {
                resolve();
            } else {
                reject(resultErr);
            }
        });
    }
  
    return {
        access_token,
        refresh_token,
        isLogin,
        doLogin,
        isAccessTokenExpire,
        doRefreshToken
    }
    :

3. src\views\LunchMenu\LunchMenuListView.vue 파일을 수정합니다.

<script>
:
import { useRouter, useRoute } from 'vue-router';
:

export default {
    name : 'LunchMenuListView',
    setup() {
        const router = useRouter();
        const route = useRoute();
        :

        async function getLunchMenuList() {
            console.log(loginStore.access_token);
            if (loginStore.isAccessTokenExpire()) {
                console.log("Access Token이 만료되었습니다.");
                try {
                    await loginStore.doRefreshToken();
                } catch(err) {
                    console.log(err);
                    alert("인증이 만료되었습니다.\n다시 로그인 해주시기 바랍니다.");
                    router.replace({path: '/login', query: { returnUrl: route.fullPath }});
                    return;
                }
            }

            try {
                const res = await axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/", {
                    headers: {
                        "Authorization" : "Bearer " + loginStore.access_token
                    }
                });
                console.log(res);
                lunchMenuList.value = res.data.data;
            } catch(err) {
                console.log(err);
            }
        }
        :

4. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (10분 후) → Access Token 재발급(갱신)

5. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (15분 후) → Refresh Token 만료 → 재발급(갱신) 불가

6. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list) → Access Token 만료 (15분 후) → Refresh Token 만료 → 재발급(갱신) 불가 → 로그인

[14] Backend 개발 - 사용자 API 개발, 라우트 별 인증 처리, 인가 처리

carrotweb — Wed, 5 Aug 2026 16:27:53 +0900

라우트 별로 인증 처리

1. index.js 파일 수정

const express = require('express');
const cookieParser = require('cookie-parser');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

:

// Cookie 설정
app.use(cookieParser());

// 인증 설정
//app.use('/api/v1/lunchmenus', require('./src/api/v1/authMiddleware'));
// 점심 메뉴 연결
app.use('/api/v1/lunchmenus', require('./src/api/v1/lunchmenu'));
// 사용자 연결
app.use('/api/v1/member', require('./src/api/v1/member'));

app.listen(port, () => {
    console.log(`APIServer started on port ${port}`);
});

전체 lunchmenu에 대한 인증 설정을 주석 처리하거나 삭제합니다.

2. src\api\v1\lunchmenu.js 파일 수정 - 점심 메뉴 등록, 수정, 삭제일 때만 인증/인가가 처리되게 하겠습니다.

:
const authMiddleware = require('./authMiddleware');

:
// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    :
});

// 점심 메뉴 번호로 검색하여 점심 메뉴를 리턴합니다.
router.get('/:no', async function(req, res, next) {
    :
});

// 점심 메뉴를 등록합니다.
router.post('/', authMiddleware, async function(req, res, next) {
    :
});

// 점심 메뉴를 수정합니다.
router.put('/:no', authMiddleware, async function(req, res, next) {
   :
});

// 점심 메뉴를 삭제합니다.
router.delete('/:no', authMiddleware, async function(req, res, next) {
    :
});

사용자 API 테스트 (POSTMAN에서 확인)
1. 사용자 로그인

2. 전체 점심 메뉴 등록 - 인증 확인

인증 처리를 통한 등록 (등록자 컬럼 추가)

테이블 수정 쿼리 실행, 데이터 업데이트 쿼리 실행

use lunchdb;

-- tb_lunch_menu table에 mbr_id 컬럼 추가
ALTER TABLE tb_lunch_menu ADD mbr_id varchar(50) NOT NULL COMMENT '사용자 ID' AFTER menu_name;

-- tb_lunch_menu table에 모든 mbr_id의 값을 'system'으로 등록
UPDATE tb_lunch_menu SET mbr_id='system';

사용자 API 테스트 (POSTMAN에서 확인)

전체 점심 메뉴 조회

1. src\db\mappers\mariadb\lunchmenu\lunchmenu-sql.xml 파일을 수정합니다.

    :

     <insert id="insertLunchMenuItem">
        INSERT INTO tb_lunch_menu
            (
                menu_name,
                mbr_id
            )
            VALUES
            (
                #{menuName},
                #{memberID}
            )
    </insert>

    :

2. src\api\v1\lunchmenu.js 파일 수정 - 사용자 ID를 토큰에 있는 sub로 처리

:
// 점심 메뉴를 등록합니다.
router.post('/', authMiddleware, async function(req, res, next) {
    :

    const params = {
        menuName : req.body.menuName,
        memberID : req.tokenData.sub
    };

    //const query = "INSERT INTO tb_lunch_menu (menu_name, mbr_id) VALUES(?, ?)";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'insertLunchMenuItem', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.menuName, req.tokenData.sub]);
        data = await conn.query(query);
        // OkPacket { affectedRows: 1, insertId: 4n, warningStatus: 0 }
        if (data.affectedRows == 1) {
            result.message = "데이터가 등록되었습니다.";
        } else {
            result.message = "데이터가 등록되지 않았습니다.";
        }
    } catch (error) {
        :

사용자 API 테스트 (POSTMAN에서 확인)

전체 점심 메뉴 등록

전체 점심 메뉴 조회

인증 처리를 통한 수정/삭제 (등록자 비교)

1. src\api\v1\lunchmenu.js 파일 수정

:
// 점심 메뉴를 수정합니다.
router.put('/:no', authMiddleware, async function(req, res, next) {
    :

    //const query = "SELECT * FROM tb_lunch_menu WHERE seq = ?";
    const querySelect = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'selectLunchMenuItem', params, format);

    //const query = "UPDATE tb_lunch_menu SET menu_name = ? WHERE seq = ?";
    const queryUpdate = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'updateLunchMenuItem', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.params.no]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            if (data[0].mbr_id == req.tokenData.sub) {
                // data = await conn.query(query, [req.body.menuName, req.params.no]);
                data = await conn.query(querySelect);
                // OkPacket { affectedRows: 1, insertId: 0n, warningStatus: 0 }
                if (data.affectedRows == 1) {
                    result.message = "데이터가 수정되었습니다.";
                } else {
                    result.message = "데이터가 수정되지 않았습니다.";
                }
            } else {
                result.result = "fail";
                result.code = 403;
                result.message = "id가 동일하지 않습니다.";
            }
        }
    }
    :

사용자 API 테스트 (POSTMAN에서 확인)

전체 점심 메뉴 수정 - 사용자 ID 비교

이전에 등록된 모든 점심 메뉴의 mbr_id를 'system'으로 등록하였기 때문에 id가 일치하지 않습니다.

2. src\api\v1\lunchmenu.js 파일 수정

:
// 점심 메뉴를 삭제합니다.
router.delete('/:no', authMiddleware, async function(req, res, next) {
    :

    //const query = "SELECT * FROM tb_lunch_menu WHERE seq = ?";
    const querySelect = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'selectLunchMenuItem', params, format);
    
    //const query = "DELETE FROM tb_lunch_menu WHERE seq = ?";
    const queryDelete = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'deleteLunchMenuItem', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.params.no]);
        data = await conn.query(querySelect);
        if (data.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            if (data[0].mbr_id == req.tokenData.sub) {
                // data = await conn.query(query, [req.params.no]);
                data = await conn.query(queryDelete);
                // OkPacket { affectedRows: 1, insertId: 0n, warningStatus: 0 }
                if (data.affectedRows == 1) {
                    result.message = "데이터가 삭제되었습니다.";
                } else {
                    result.message = "데이터가 삭제되지 않았습니다.";
                }
            } else {
                result.result = "fail";
                result.code = 403;
                result.message = "id가 동일하지 않습니다.";
            }
        }
    }
    :

사용자 API 테스트 (POSTMAN에서 확인)

전체 점심 메뉴 삭제 - 사용자 ID 비교

이전에 등록된 모든 점심 메뉴의 mbr_id를 'system'으로 등록하였기 때문에 id가 일치하지 않습니다.

Scope를 통한 인가(접근 권한 확인) 처리

1. src\api\v1\lunchmenu.js 파일 수정

:
// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', authMiddleware, async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    const searchInfo = search(req);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: [],
        pagination: {}
    };

    // Scope로 접근 권한 확인
    const scopes = req.tokenData.scope.split(" ");
    if (scopes.findIndex((element) => element === "lunchmenu.all" || element === "lunchmenu.read") < 0) {        
        result.result = "fail";
        result.code = 403;
        result.message = "접근 권한이 없습니다."
        res.status(result.code).json(result);
        return;
    }

    :
});

:
// 점심 메뉴 번호로 검색하여 점심 메뉴를 리턴합니다.
router.get('/:no', authMiddleware, async function(req, res, next) {
    console.log(`REST API Get Method - Read Lunch Menu ${req.params.no}.`);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    };

    // Scope로 접근 권한 확인
    const scopes = req.tokenData.scope.split(" ");
    if (scopes.findIndex((element) => element === "lunchmenu.all" || element === "lunchmenu.read") < 0) {        
        result.result = "fail";
        result.code = 403;
        result.message = "접근 권한이 없습니다."
        res.status(result.code).json(result);
        return;
    }

    :
});

:
// 점심 메뉴를 등록합니다.
router.post('/', authMiddleware, async function(req, res, next) {
    console.log("REST API Post Method - Create Lunch Menu.");

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    };

    // Scope로 접근 권한 확인
    const scopes = req.tokenData.scope.split(" ");
    if (scopes.findIndex((element) => element === "lunchmenu.all" || element === "lunchmenu.write") < 0) {        
        result.result = "fail";
        result.code = 403;
        result.message = "접근 권한이 없습니다."
        res.status(result.code).json(result);
        return;
    }

    :
});

:
// 점심 메뉴를 수정합니다.
router.put('/:no', authMiddleware, async function(req, res, next) {
    console.log(`REST API Put Method - Update Lunch Menu ${req.params.no}.`);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    }

    // Scope로 접근 권한 확인
    const scopes = req.tokenData.scope.split(" ");
    if (scopes.findIndex((element) => element === "lunchmenu.all" || element === "lunchmenu.write") < 0) {        
        result.result = "fail";
        result.code = 403;
        result.message = "접근 권한이 없습니다."
        res.status(result.code).json(result);
        return;
    }

    :
});

:
// 점심 메뉴를 삭제합니다.
router.delete('/:no', authMiddleware, async function(req, res, next) {
    console.log(`REST API Delete Method - Delete Lunch Menu ${req.params.no}.`);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    }

    // Scope로 접근 권한 확인
    const scopes = req.tokenData.scope.split(" ");
    if (scopes.findIndex((element) => element === "lunchmenu.all" || element === "lunchmenu.delete") < 0) {        
        result.result = "fail";
        result.code = 403;
        result.message = "접근 권한이 없습니다."
        res.status(result.code).json(result);
        return;
    }

    :
});

사용자 API 테스트 (POSTMAN에서 확인)

전체 점심 메뉴 등록 - 사용자 Scope 비교

로그인된 사용자의 scope가 profile lunchmenu.read이기 때문에 읽기만 됩니다.

사용자의 scope를 lunchmenu.all 이나 lunchmenu.write로 수정하면 등록이 됩니다.

[13] Backend 개발 - 사용자 API 개발, Access Token, Refresh Token

carrotweb — Wed, 5 Aug 2026 15:36:04 +0900

기존 ID Token 생성 부분을 함수로 분리

ID Token 생성

1. src\api\v1\member.js 파일 수정 – ID Token 생성 함수로 분리합니다.

// ID Token을 생성합니다.
async function generateIDToken(memberID, memberName, memberRoles) {
    const result = {
        result: 'success',
        message: '',
        token: ''
    };

    // 토큰 발급 시간
    const issuedAt = new Date().toLocaleString();
    const iat = Date.parse(issuedAt) / 1000;

    // ID Token - JWT
    const uuid = uuidv4().toString();
    const jwtid = uuid.replace(/-/gi, '');
    try {
        const idToken = await new Promise((resolve, reject) => {
            jwt.sign({
                    name : memberName,
                    roles : memberRoles,
                    typ : "ID",
                    iat : iat
                },
                secret,
                {
                    algorithm: "HS256",
                    issuer : "https://apiserver.example.com",
                    subject : memberID,
                    audience : "lunchmenuApp",
                    expiresIn : "1d",
                    jwtid : jwtid
                },
                (err, token) => {
                    if (err) {
                        reject(err);
                    } else {
                        resolve(token);
                    }
                });
        });
        result.token = idToken;
    } catch(err) {
        console.log(err);
        result.result = "fail";
        result.message = "ID Token 생성이 실패하였습니다.";
    }

    return result;
}

type으로 추가하여 Token을 구분하였습니다.

2. src\api\v1\member.js 파일 수정 – login 라우트를 수정합니다.

:
// JWT - 암호
const secret = "005c9780fe7c11eb89b4e39719de58a5";

// 사용자 ID로 검색하여 사용자를 인증하고 토큰을 리턴합니다.
router.post('/login', async function(req, res, next) {
    console.log("REST API Post Method - Member Login.");

    const result = {
        result: 'fail',
        code: 401,
        message: '',
        id_token: ''
    };

    if (req.body.id == undefined || req.body.id == "") {
        result.code = 400;
        result.message = "id가 없습니다.";
        res.status(result.code).json(result);
        return;
    } else if (req.body.password == undefined || req.body.password == "") {
        result.code = 400;
        result.message = "password가 없습니다.";
        res.status(result.code).json(result);
        return;
    }

    const params = {
        id : req.body.id,
        password : req.body.password
    };

    //const query = "SELECT * FROM tb_member WHERE mbr_id = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu.member', 
        'selectMember', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.id]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.message = "사용자가 없습니다.";
        } else {
            if (data[0].mbr_pw != params.password) {
                result.message = "비밀번호가 동일하지 않습니다."
            } else {
                result.message = "사용자가 인증되었습니다.";

                // ID Token을 생성합니다.
                const resultIDToken = await generateIDToken(data[0].mbr_id, data[0].mbr_name, data[0].mbr_roles);
                if (resultIDToken.result == "success") {
                    result.id_token = resultIDToken.token;
                }
            }

            if (result.id_token != "") {
                result.result = "success";
                result.code = 200;
            } else {
                result.code = 500;
                result.id_token = "";
                result.message = "토큰 생성이 실패하였습니다.";
            }
        }
    } catch (error) {
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

동일한 암호키로 토큰을 생성하기 위해 JWT 암호를 위로 이동시킵니다.

기존 idtoken를 id_token으로 변경하였습니다.

사용자 API 테스트 (POSTMAN에서 확인)
사용자 로그인

JWT 확인

ID Token의 문제점

ID Token은 사용자를 인증하고 인증된 사용자에 대한 정보를 취득할 수 있지만 토큰의 유효 기간이 길게 설정되기 때문에 토큰이 탈취 당할 경우 보안이 취약해집니다.

Access Token을 사용해야 하는 이유?

토큰의 유효 기간을 짧게 설정하여 토큰이 탈취되어도 토큰의 유효 기간이 짧기 때문에 보안 문제를 최소화 할 수 있습니다.

그러나 Access Token의 유효 기간이 짧기 때문에 매번 사용자를 다시 인증해야 하는 문제가 발생합니다.

Refresh Token을 사용해야 하는 이유?
Access Token이 만료되었을 때 사용자를 확인하는 인증 절차를 거치지 않고 Access Token을 재발급할 수 있게 처리해주는 토큰을 생성합니다.

Access Token, Refresh Token (액세스 토큰, 리프레시 토큰)

사용자가 로그인하면 서버에서 사용자를 확인하여 토큰(Access Token과 Refresh Token)을 생성한 후 클라이언트에게 토큰(Access Token과 Refresh Token)을 전달하는 방식입니다. 클라이언트는 요청을 보낼 때 Authorization Header에 토큰(Access Token)을 포함하여 전달하면 서버는 전달 받은 토큰을 검증하여 인증된 사용자인지 확인합니다.

토큰(Access Token, Refresh Token)은 JSON Web Token (JWT, JSON 웹 토큰)입니다.

Access Token은 인증된 사용자에 대한 정보(claim(클레임))과 서버 리소스에 접근할 수 있는 권한(scope(스코프))이 포함되어 있습니다.

Refresh Token은 Access Token을 재발급하는데 사용되는 토큰입니다.

장점

클라이언트에서 토큰을 관리하기 때문에 서버에 부하가 낮아집니다.

단점

토큰이 탈취 당할 수 있습니다. → 보안성이 취약함
(HTTPS로 보안할 수 있습니다. 단, 클라이언트 해킹은 차단할 수 없습니다.)
모든 자원을 접근할 수 있습니다. → 별도의 접근 권한 처리 필요

Access Token, Refresh Token Process (Access / Refresh 토큰 생성 프로세스)

Access Token, Refresh Token Process (Access Token 만료 시 프로세스)

Access / Refresh Token 생성

1. src\api\v1\member.js 파일 수정 - Access Token 생성 함수를 추가합니다.

// Access Token을 생성합니다.
async function generateAccessToken(memberID, memberName, memberRoles) {
    const result = {
        result: 'success',
        message: '',
        token: ''
    };

    // 토큰 발급 시간
    const issuedAt = new Date().toLocaleString();
    const iat = Date.parse(issuedAt) / 1000;

    // Access Token - JWT
    const uuid = uuidv4().toString();
    const jwtid = uuid.replace(/-/gi, '');
    try {
        const accessToken = await new Promise((resolve, reject) => {
            jwt.sign({
                    name : memberName,
                    roles : memberRoles,
                    typ : "Bearer",
                    scope: "profile lunchmenu.all",
                    iat : iat
                },
                secret,
                {
                    algorithm: "HS256",
                    issuer : "apiserver.example.com",
                    subject : memberID,
                    audience : "lunchmenuApp",
                    expiresIn : "10m",
                    jwtid : jwtid
                },
                (err, token) => {
                    if (err) {
                        reject(err);
                    } else {
                        resolve(token);
                    }
                });
        });
        result.token = accessToken;
    } catch(err) {
        console.log(err);
        result.result = "fail";
        result.message = "Refresh Token 생성이 실패하였습니다.";
    }

    return result;
}

Type으로 Token 구분 : Bearer

Scope로 서버 리소스에 접근할 수 있는 권한 설정 : profile lunchmenu.all

2. src\api\v1\member.js 파일 수정 - Refresh Token 생성 함수를 추가합니다.

// Refresh Token을 생성합니다.
async function generateRefreshToken(memberID) {
    const result = {
        result: 'success',
        message: '',
        token: ''
    };

    // 토큰 발급 시간
    const issuedAt = new Date().toLocaleString();
    const iat = Date.parse(issuedAt) / 1000;

    // Refresh Token - JWT
    const uuid = uuidv4().toString();
    const jwtid = uuid.replace(/-/gi, '');
    try {
        const refreshToken = await new Promise((resolve, reject) => {
            jwt.sign({
                    typ : "Refresh",
                    scope: "profile scopes",
                    iat : iat
                },
                secret,
                {
                    algorithm: "HS256",
                    issuer : "apiserver.example.com",
                    subject : memberID,
                    audience : "lunchmenuApp",
                    expiresIn : "15m",
                    jwtid : jwtid
                },
                (err, token) => {
                    if (err) {
                        reject(err);
                    } else {
                        resolve(token);
                    }
                });
        });
        result.token = refreshToken;
    } catch(err) {
        console.log(err);
        result.result = "fail";
        result.message = "Refresh Token 생성이 실패하였습니다.";
    }

    return result;
}

Type으로 Token 구분 : Refresh

Scope로 서버 리소스에 접근할 수 있는 권한 설정 : profile scopes

3. src\api\v1\member.js 파일 수정 - login 라우트를 수정합니다.

:
// 사용자 ID로 검색하여 사용자를 인증하고 토큰을 리턴합니다.
router.post('/login', async function(req, res, next) {
    console.log("REST API Post Method - Member Login.");

    const result = {
        result: 'fail',
        code: 401,
        message: '',
        access_token: '',
        refresh_token: ''
    };

    if (req.body.id == undefined || req.body.id == "") {
        result.code = 400;
        result.message = "id가 없습니다.";
        res.status(result.code).json(result);
        return;
    } else if (req.body.password == undefined || req.body.password == "") {
        result.code = 400;
        result.message = "password가 없습니다.";
        res.status(result.code).json(result);
        return;
    }

    const params = {
        id : req.body.id,
        password : req.body.password
    };

    //const query = "SELECT * FROM tb_member WHERE mbr_id = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu.member', 
        'selectMember', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.id]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.message = "사용자가 없습니다.";
        } else {
            if (data[0].mbr_pw != params.password) {
                result.message = "비밀번호가 동일하지 않습니다."
            } else {
                result.message = "사용자가 인증되었습니다.";

                // Access Token을 생성합니다.
                const resultAccessToken = await generateAccessToken(data[0].mbr_id, data[0].mbr_name, data[0].mbr_roles);
                if (resultAccessToken.result == "success") {
                    result.access_token = resultAccessToken.token;
                }

                // Refresh Token을 생성합니다.
                const resultRefreshToken = await generateRefreshToken(data[0].mbr_id);
                if (resultRefreshToken.result == "success") {
                    result.refresh_token = resultRefreshToken.token;
                }
            }

            if (result.access_token != "" && result.refresh_token != "") {
                result.result = "success";
                result.code = 200;
            } else {
                result.code = 500;
                result.access_token = "";
                result.refresh_token = "";
                result.message = "토큰 생성이 실패하였습니다.";
            }
        }
    } catch (error) {
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

id_token를 지우고 access_token, refresh_token를 추가합니다.

기존 ID Token 생성을 주석 처리하거나 삭제합니다.

4. src\api\v1\authMiddleware.js 파일 수정

// Token 방식 (Access Token, Refresh Token)
const jwt = require('jsonwebtoken');

const authMiddleware = async (req, res, next) => {
    let authorization = req.header('Authorization');

    const result = {
        result: 'fail',
        code: 401,
        message: '인증이 실패하였습니다.',
        data: {}
    };

    if (authorization == undefined || authorization == "") {
        result.code = 400;
        res.status(result.code).json(result);
    } else {
        authorization = authorization.replace("Bearer ","");
        try {
            const secret = "005c9780fe7c11eb89b4e39719de58a5";
            const tokenData = await new Promise((resolve, reject) => {
                jwt.verify(authorization, secret, 
                    (err, decoded) => {
                        if (err) {
                            reject(err);
                        } else {
                            resolve(decoded);
                        }
                    });
            });
            if (tokenData.typ == "Bearer") {
                req.tokenData = tokenData;
                next();
            }
        } catch(err) {
            if (err instanceof jwt.TokenExpiredError) {
                // 토큰 만료 - 401(Unauthorized), 498(Invalid token)
                result.message = "토큰이 만료되었습니다.";
            } else if (err instanceof jwt.JsonWebTokenError) {
                // 토큰 에러 - Invalid token
                result.message = "토큰이 유효하지 않습니다.";
            } else {
                result.message = "토큰이 유효하지 않습니다.";
            }
            res.status(result.code).json(result);
        }
    }
}

module.exports = authMiddleware;

Type이 Bearer일 때만 next()를 호출합니다.

사용자 API 테스트 (POSTMAN에서 확인)

사용자 로그인

Access Token 확인

Refresh Token 확인

Refresh Token Rotation

Access Token과 Refresh Token 둘 다 탈취가 될 경우 문제가 발생할 수 있습니다.

그래서 Access Token이 재발급될 때 Refresh Token도 같이 재발급되게 하여 보안 문제를 최소화 할 수 있습니다.

1. src\api\v1\member.js 파일 수정 - refresh 라우트를 추가합니다.

// Refresh Token으로 Access Token를 재발급(갱신)합니다.
// Refresh Token도 재발급합니다.
router.post('/refresh', async function(req, res, next) {
    console.log("REST API Post Method - Token Refresh.");

    const result = {
        result: 'fail',
        code: 401,
        message: '',
        access_token: '',
        refresh_token: ''
    };

    if (req.body.refresh_token == undefined || req.body.refresh_token == "") {
        result.code = 400;
        result.message = "Refresh Token이 없습니다.";
        res.status(result.code).json(result);
        return;
    }

    const refreshToken = req.body.refresh_token;

    // 토큰 검증
    let tokenData = {};
    try {
        tokenData = await new Promise((resolve, reject) => {
            jwt.verify(refreshToken, secret, 
                (err, decoded) => {
                    if (err) {
                        reject(err);
                    } else {
                        resolve(decoded);
                    }
                });
        });
    } catch(err) {
        if (err instanceof jwt.TokenExpiredError) {
            // 토큰 만료 - 401(Unauthorized), 498(Invalid token)
            result.message = "Refresh Token이 만료되어 Access Token을 재발급(갱신)할 수 없습니다.";
        } else if (err instanceof jwt.JsonWebTokenError) {
            // 토큰 에러 - Invalid token
            result.message = "Refresh Token이 유효하지 않습니다.";
        } else {
            result.message = "Refresh Token이 유효하지 않습니다.";
        }
        res.status(result.code).json(result);
        return;
    }

    const params = {
        id : tokenData.sub
    };

    //const query = "SELECT * FROM tb_member WHERE mbr_id = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu.member', 
        'selectMember', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [tokenData.sub]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.message = "사용자가 없어 Access Token을 재발급(갱신)할 수 없습니다.";
        } else {
            // Access Token을 생성합니다.
            const resultAccessToken = await generateAccessToken(data[0].mbr_id, data[0].mbr_name, data[0].mbr_roles);
            if (resultAccessToken.result == "success") {
                result.access_token = resultAccessToken.token;
            }

            // Refresh Token을 생성합니다.
            const resultRefreshToken = await generateRefreshToken(data[0].mbr_id);
            if (resultRefreshToken.result == "success") {
                result.refresh_token = resultRefreshToken.token;
            }

            if (result.access_token != "" && result.refresh_token != "") {
                result.result = "success";
                result.code = 200;
                result.message = "Access Token을 재발급(갱신)하였습니다.";
            } else {
                result.code = 500;
                result.access_token = "";
                result.refresh_token = "";
                result.message = "Access Token을 재발급(갱신)할 수 없습니다.";
            }
        }
    } catch (error) {
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없어 Access Token을 재발급(갱신)할 수 없습니다.";
        } else {
            result.message = "서버 오류가 발생하여 Access Token을 재발급(갱신)할 수 없습니다.";
        }
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

사용자 API 테스트 (POSTMAN에서 확인)

전체 점심 메뉴 조회 - Access Token 만료

Access Token 재발급(갱신)

Access Token 확인

[12] Frontend 개발 - 상태 관리, Login 관리, ID Token

carrotweb — Tue, 4 Aug 2026 17:44:45 +0900

로그인뷰 생성하기

1. src에 Account 디렉터리를 생성하고 LoginView.vue 파일을 생성합니다.

<template>
    <div class="login">
        <form class="loginform">
            <p>
                <label for="memberIdInput">아이디</label>
                <input type="text" id="memberIdInput" class="input_text" ref="memberIdInput" v-model.trim="memberId" placeholder="아이디를 입력하세요." />
            </p>
            <p>
                <label for="memberPasswordInput">패스워드</label>
                <input type="password" id="memberPasswordInput" class="input_text" ref="memberPasswordInput" v-model.trim="memberPassword" placeholder="패스워드를 입력하세요." />
            </p>
            <p class="buttons">
                <button @click.prevent="loginClick" class="button blue">로그인</button>
                <button @click.prevent="cancelClick" class="button">취소</button>
            </p>
        </form>
        <p>{{ errorMessage }}</p>
    </div>
</template>

<script>
import { reactive, toRefs, onMounted, ref } from 'vue';
import { useRouter } from 'vue-router';

export default {
    name : 'LoginView',
    setup() {
        const router = useRouter();

        const state = reactive({
            memberId: "",
            memberPassword: "",
            errorMessage: ""
        });

        const memberIdInput = ref(null);
        const memberPasswordInput = ref(null);

        function loginClick() {
            if (state.memberId == "") {
                alert("아이디를 입력하세요.");
                memberIdInput.value.focus();
                return;
            } else if (state.memberPassword == "") {
                alert("패스워드를 입력하세요.");
                memberPasswordInput.value.focus();
                return;
            }
        }
        function cancelClick() {
            router.back();
        }

        onMounted(()=>{
            memberIdInput.value.focus();
        });

        return {
            ...toRefs(state),
            loginClick,
            cancelClick,
            memberIdInput,
            memberPasswordInput
        }
    }
};
</script>

<style scoped>
.login { width:800px; margin:20px auto; }
.loginform { width:400px; margin:auto; }
.loginform p > label { display:inline-block; width:100px; font-size:14px; padding-right:10px; }
.loginform p > .input_text { width:200px; font-size:14px; height:32px; }
.buttons { position:relative; height:32px; margin-top:20px; }
.buttons > .button { overflow:visible; cursor:pointer; min-width:125px; height:32px; margin:0 2px; padding:0 15px; line-height:32px; font-size:14px; border:1px solid #dfdfdf; background:#fff; border-radius:10px; }
.buttons > .button.blue { color:#fff; border-color:#0099d2 !important; background:#0099d2 !important; }
</style>

2. src\router\index.js에서 로그인을 추가합니다.

import LoginView from '@/views/Account/LoginView.vue'

:
const routes = [
  :
  {
    path: '/login',
    name: 'Login',
    component: LoginView
  }
]
:

3. 웹 브라우저에서 확인하기 (http://localhost:8080/login)

Login Store(로그인 스토어) 생성

1. src\stores에 useLoginStore.js 파일을 생성합니다.

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

export const useLoginStore = defineStore('login', () => {
    const idToken = ref("");

    // 로그인 여부를 가져옵니다.
    const isLogin = computed(() => {
        return idToken.value == "" ? false : true;
    });

    // 로그인합니다.
    async function doLogin(memberInfo) {
        let result = false;
        let resultErr = null;

        try {
            const res = await axios.post("http://127.0.0.1:9000/api/v1/member/login", memberInfo);
            if (res.data.code == 200) {
                console.log("로그인되었습니다.");
                idToken.value = res.data.idtoken;
                result = true;
            }
        } catch(err) {
            // 400, 401, 500 에러 처리
            console.log(err);
            if (!err.response) {
                err.response = {
                    data:{"result":"fail", "code":401, "message":"사용자가 없습니다.", idtoken: ""}
                };
            }
            resultErr = err.response.data;
        }

        return new Promise((resolve, reject) => {
            if (result) {
                resolve();
            } else {
                reject(resultErr);
            }
        });
    }
  
    return {
        idToken,
        isLogin,
        doLogin
    }
});

2. src\Account\LoginView.vue 파일을 수정합니다.

<script>
:
import { useLoginStore } from '@/stores/useLoginStore';

export default {
    name : 'LoginView',
    setup() {
        :

        const loginStore = useLoginStore();

        function loginClick() {
            :

            const memberInfo = { id: state.memberId, password: state.memberPassword };
            loginStore.doLogin(memberInfo).then(() => {
                router.replace({name : 'home'});
            }).catch((err) => {
                state.errorMessage = err.message;
            });
        }
        :

    }
};
</script>

3. 웹 브라우저에서 확인하기 (http://localhost:8080/login) - 로그인 실패 테스트

Navigation Guards (내비게이션 가드)
(https://router.vuejs.kr/guide/advanced/navigation-guards.html)

Navigation Guards (내비게이션 가드)로 처리

1. src\router\index.js에서 로그인을 위한 내비게이션 가드를 추가합니다.

[라우트 전역 처리]

import { useLoginStore } from '@/stores/useLoginStore'

:

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes
})

router.beforeEach((to, from, next) => {
  const loginStore = useLoginStore();
  if (to.name.startsWith("lunchmenu")) {
    if (!loginStore.isLogin) {
      next({path: '/login', query: { returnUrl: to.fullPath }});
      //next('/login?returnUrl=' + to.fullPath);
    } else {
      next();
    }
  } else {
    next();
  }
});

export default router

export 전에 router.beforeEach를 추가합니다.

to는 이동할 URL에 대한 객체
form은 현재 URL에 대한 객체
next는 이동하기 위한 메서드

이름이 "lunchmenu"로 시작하고 로그인이 되지 않은 상태일 때만 로그인이 적용되게 하합니다.

returnUrl로 이동할 URL의 경로를 전달합니다.

[라우트 별 처리]

import { useLoginStore } from '@/stores/useLoginStore'

:
const routes = [
  :
  {
    path: '/lunchmenu',
    component: LunchMenuView,
    beforeEnter : (to, from, next) => {
      const loginStore = useLoginStore();
      if (to.name.startsWith("lunchmenu")) {
        if (!loginStore.isLogin) {
          next({path: '/login', query: { returnUrl: to.fullPath }});
        } else {
          next();
        }
      } else {
        next();
      }
    },
    children : [
      :
    ]
]
:

[메서드를 생성하고 라우트 별 처리]

import { useLoginStore } from '@/stores/useLoginStore'

:
const Authentication = () => (to, from, next) => {
  const loginStore = useLoginStore();
  if (to.name.startsWith("lunchmenu")) {
    if (!loginStore.isLogin) {
      next({path: '/login', query: { returnUrl: to.fullPath }});
    } else {
      next();
    }
  } else {
    next();
  }
};

const routes = [
  :
  {
    path: '/lunchmenu',
    component: LunchMenuView,
    beforeEnter: Authentication(),
    children : [
      :
    ]
]
:

2. src\Account\LoginView.vue 파일을 수정합니다.

<script>
:
import { useRouter, useRoute } from 'vue-router';
:

export default {
    name : 'LoginView',
    setup() {
        const router = useRouter();
        const route = useRoute();

        function loginClick() {
            :

            const memberInfo = { id: state.memberId, password: state.memberPassword };
            loginStore.doLogin(memberInfo).then(() => {
                //router.replace({name : 'home'});
                const returnUrl = route.query.returnUrl;
                router.replace({path : returnUrl});
            }).catch((err) => {
                state.errorMessage = err.message;
            });
        }
        :
    }
};
</script>

3. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list → http://localhost:8080/login?returnUrl=/lunchmenu/list)

4. src\Account\LunchMenu\LunchMenuListView.vue 파일을 수정합니다.

<script>
:
import { useLoginStore } from '@/stores/useLoginStore';
:

export default {
    name : 'LunchMenuListView',
    setup() {
        :
        const loginStore = useLoginStore();

        function getLunchMenuList() {
            console.log(loginStore.idToken);
            axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/", {
                headers: {
                    "Authorization" : "Bearer " + loginStore.idToken
                }
            }).then((res) => {
                console.log(res);
                lunchMenuList.value = res.data.data;
            }).catch((err) => {
                console.log(err);
            });
        }
        :
    }
};
</script>

5. 웹 브라우저에서 확인하기 (http://localhost:8080/lunchmenu/list)

[11] Frontend 개발 - 상태 관리, Store – Pinia

carrotweb — Tue, 4 Aug 2026 17:21:11 +0900

Store를 사용해야 하는 이유

Store는 애플리케이션 전반에서 접근할 수 있는 데이터를 포함해야 합니다.

여러 컴포넌트에서 사용되는 데이터(사용자 정보, 네비게이션 정보, 전역 정보)와 컴포넌트에서 보존되어야 하는 데이터(Form 데이터)가 포함됩니다.

Store는 state와 비즈니스 로직을 보유하는 독립체(entity)로 컴포넌트 트리에 묶여 있지 않습니다.

→ 전역 state로 모든 컴포넌트가 읽고 쓸 수 있습니다.

Computed (계산된 속성) 사용

반응형 데이터를 계산하는 코드가 <template> 내에 있거나 반복되면 <template>이 복잡해 보일 수 있습니다.

그래서 계산하는 코드를 분리하고 반응되도록 computered() 함수로 처리합니다.

<template>
    <div>리스트가 {{ lunchMenuList.value.length > 0 ? "있습니다" : "없습니다" }} </div>
</template>

<script setup>
    import { ref } from 'vue'
    const lunchMenuList = ref([]);

    return {
        lunchMenuList
    }
</setup>

<template>
    <div>리스트가 {{ isLunchMenu }} </div>
</template>

<script setup>
    import { ref, computed } from 'vue'
    const lunchMenuList = ref([]);

    // 계산된 ref
    const isLunchMenu = computed(() => {
        return lunchMenuList.value.length > 0 ? "있습니다" : "없습니다";
    });

    return {
        lunchMenuList,
        isLunchMenu
    }
</setup>

1. src\views\LunchMenu\LunchMenuListView.vue에 computed을 추가하고 사용합니다.

<template>
    <div>{{ appTitle }} - {{ lunchmenuTitle }} 리스트가 {{  isLunchMenu }}
        <button @click="countStore.incrementByRandom()">{{ countStore.count }}</button>
    </div>
    :
</template>

<script>
import { ref, computed } from 'vue';
:

export default {
    setup() {
        :
        // 계산된 ref
        const isLunchMenu = computed(() => {
            return lunchMenuList.value.length > 0 ? "있습니다" : "없습니다";
        });

        return {
            :
            isLunchMenu
        }
    },
    :
}
</script>

2. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/list)

상태 관리 - pinia
(https://ko.vuejs.org/guide/scaling-up/state-management.html#pinia)

Pinia(피니아)
(https://pinia.vuejs.kr/)

1. 상태 관리를 사용하기 위해 Pinia 설치 (터미널에서 실행합니다.)

npm install pinia --save

2. src\main.js에 pinia 인스턴스(루트 Store)를 추가합니다.

import { createApp } from 'vue';
import { ref } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';
import router from './router';

const pinia = createPinia();
const app = createApp(App);

app.use(pinia);

app.provide('appTitle', '점심 메뉴 앱');

const greetingMessage = ref('즐거운 점심 시간되세요!');
const likeCount = ref(0);

function likeUp() {
    this.likeCount++;
}

app.provide('useCommonStore', {
    greetingMessage,
    likeCount,
    likeUp
});

app.use(router).mount('#app');

Store(스토어) 정의

Store는 defineStore()를 사용하여 정의합니다.

import { defineStore } from 'pinia';

export const useMyStore = defineStore('my', {
    state: () => ({
        :
    }),
    getters: {
        :
    },
    actions: {
        :
    },
});

Store에서는 data는 state로, computed는 getters로, methods는 actions로 생각하면 됩니다.

"use"로 시작해 "Store"로 끝나는 Store의 이름을 사용하는 것이 좋습니다.

state에 정의된 프로퍼티만 접근할 수 있습니다.

getters, actions은 this를 통해 state에 정의된 프로퍼티에 접근할 수 있습니다.

actions은 비동기라 API를 호출할 경우 async await로 처리해야 합니다.

1. src\stores에 useLikeStore.js 파일을 생성합니다.

Options API로 개발하면 다음과 같습니다.

import { defineStore } from 'pinia';

export const useLikeStore = defineStore('like', {
    state: () => {
        return {
            likeCount: 0
        }
    },
    getters: {
        getLikeMessage: ((state) => {
            return "좋아요가 " + state.likeCount + "개 있습니다.";
        })
    },
    actions: {
        // Like를 증가시킵니다.
        increment() {
            this.likeCount++
        }
    }
});

Options API 대신 Composition API로 개발하시기 바랍니다.

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

export const useLikeStore = defineStore('like', () => {
    const likeCount = ref(0);

    const getLikeMessage = computed(() => {
        return "좋아요가 " + likeCount.value + "개 있습니다.";
    });

    // Like를 증가시킵니다.
    function increment() {
        likeCount.value++;
    }
  
    return {
        likeCount,
        getLikeMessage,
        increment
    }
});

ref()는 state 프로퍼티, computed()는 getters 프로퍼티, function()은 actions 프로퍼티가 됩니다.

2. src\views\LunchMenu\LunchMenuListView.vue에 useLikeStore를 추가하고 사용합니다.

<template>
    :
    <div>
        <span>{{ greetingMessage }}</span>
        <button @click="likeStore.increment()">{{ likeStore.getLikeMessage }}</button>
    </div>
    :
</template>

<script>
import { useLikeStore } from '@/stores/useLikeStore';
:

export default {
    setup() {
        :
        const likeStore = useLikeStore();

        return {
            :
            likeStore
        }
    },
    :
}
</script>

3. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/list)

[10] Frontend 개발 - 상태 관리

carrotweb — Tue, 4 Aug 2026 17:03:00 +0900

상태 관리

여러 하위 컴포넌트들이 동일한 데이터를 사용해야 할 경우
→ 상위 컴포넌트에서 하위 컴포넌트로 데이터를 전달해야 할 때 props를 사용합니다.

깊은 계층 구조를 가진 컴포넌트 트리에서 비효율적입니다. → Prop Drillin

Prop Drilling (프랍(프롭) 드릴링)

자식 컴포넌트는 부모 컴포넌트로부터 데이터를 전달 받기 위해 <script>에 props(프랍스, property, 프라퍼티)에 속성 명과 타입을 설정합니다.

부모 컴포넌트는 <template>에서 자식 HTML 태그 안에 넘겨줄 prop을 설정합니다.

RootComp.vue

<template>
    <h1>Hello, Vue!</h1>
    <FooterComp userID="testid" />
</template>

<script>
import FooterComp from './FooterComp.vue'

export default {
    name : 'RootComp',
    components : {
        FooterComp
    }
}
</script>

FooterComp.vue

<template>
    <DeepChildComp :userID=useID />
</template>

<script>
import DeepChildComp from './DeepChildComp.vue'

export default {
    name : 'FooterComp',
    components : {
        DeepChildComp
    },
    props: ['userID']
}
</script>

Footer에는 사용하지 않지만 자식 컴포넌트인 DeepChild가 사용하기 때문에 prop를 설정해야 합니다.

DeepChildComp.vue

<template>
    <h2>{{ userID }}, Have a good time</h2>
</template>

<script>
export default {
    name : 'DeepChildComp',
    props: ['userID']
}
</script>

Provide(제공) / Inject(주입) 사용 ← Prop Drilling 해결

상위 컴포넌트는 하위 모든 컴포넌트에 대한 의존성 제공자 역할을 할 수 있습니다.

하위 모든 컴포넌트는 깊이에 관계없이 상위 체인의 컴포넌트에서 제공(provide)하는 의존성을 주입(inject)할 수 있습니다.

하위 모든 컴포넌트에 데이터를 제공하려면 provide() 함수를 사용
상위 컴포넌트에서 제공하는 데이터를 주입하려면 inject() 함수를 사용

하위 모든 컴포넌트에 데이터를 제공하기 위해서 provide() 함수 또는 provide 옵션을 사용합니다.

import { provide } from 'vue'

export default {
  setup() {
    provide('message', '안녕!')
  }
}

상위 컴포넌트에서 제공하는 데이터를 주입하려면 inject() 함수 또는 inject 옵션을 사용합니다.

import { inject } from 'vue'

export default {
  setup() {
    const message = inject('message')
    return {
      message
    }
  }
}

Composition API 대신 Options API로 하면 개발하면 다음과 같습니다.

export default {
  provide: {
    message: '안녕!'
  }
}

export default {
  inject: ['message'],
  data() {
    return {
      fullMessage: this.message
    }
  }
}

Provide / Inject 사용

1. src\main.js에 provide(프로바이드, 제공) 함수를 추가합니다. → App-level Provide

import { createApp } from 'vue';
import { ref } from 'vue';
import App from './App.vue';
import router from './router';

const app = createApp(App);

app.provide('appTitle', '점심 메뉴 앱');

const greetingMessage = ref('즐거운 점심 시간되세요!');
const likeCount = ref(0);

function likeUp() {
    this.likeCount++;
}

app.provide('useCommonStore', {
    greetingMessage,
    likeCount,
    likeUp
});

app.use(router).mount('#app');

Provide할 때 반응형 데이터와 상태 변경에 대한 함수가 같이 있는 것이 좋습니다.
"use"로 시작해 "Store"로 끝나는 Store의 이름을 사용하는 것이 좋습니다.

2. src\views\LunchMenu\LunchMenuView.vue에 provide(프로바이드, 제공) 함수를 추가합니다. → Component Provide

<template>
    <div class="lunch-menu">점심 메뉴</div>
    <div class="lunch-view">
        <router-view />
    </div>
</template>

<script>
import { provide } from 'vue';

export default {
    setup() {
        provide('lunchmenuTitle', '점심 메뉴’);
    }
}
</script>

3. src\views\LunchMenu\LunchMenuListView.vue에 Injext(인젝트, 주입) 함수를 추가하고 사용합니다.

<template>
    <div>{{ appTitle }} - {{ lunchmenuTitle }} 리스트</div>
    <div>
        <span>{{ greetingMessage }} </span>
        <button @click="likeUp">좋아요 - {{ likeCount }}</button>
    </div>
    :
</template>

<script>
:
import { inject } from 'vue';

export default {
    setup() {
        :
        const appTitle = inject('appTitle');
        const { greetingMessage, likeCount, likeUp } = inject('useCommonStore');
        const lunchmenuTitle = inject('lunchmenuTitle');
        :
        return {
            :
            appTitle,
            greetingMessage,
            likeCount,
            likeUp,
            lunchmenuTitle
        }
    },
    :
}
</script>

4. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/list)

"좋아요"버튼을 누르면 카운트가 증가합니다.

반응형 객체로 상태 관리

상태 관리
(https://ko.vuejs.org/guide/scaling-up/state-management.html)

1. src에 stores 디렉터리를 생성하고 useCountStore.js 파일을 생성합니다.

import { reactive } from 'vue';

export const useCountStore = reactive({
    // 카운트
    count: 0,
    // 카운트를 증가시킵니다.
    increment() {
        this.count++;
    },
    // 카운트를 감소시킵니다.
    decrement() {
        this.count--;
    },
    // 카운트를 랜덤으로 증가시킵니다.
    incrementByRandom() {
        const random = Math.floor(Math.random() * 5);
        this.count += random;
    }
});

reactive()를 사용하여 반응형 객체를 만듭니다.

반응형 데이터와 상태 변경에 대한 함수가 같이 있는 것이 좋습니다.

2. src\views\LunchMenu\LunchMenuView.vue에 useCountStore을 추가하고 사용합니다.

<template>
    <div class="lunch-menu">점심 메뉴
        <button @click="countStore.incrementByRandom()">{{ countStore.count }}</button>
    </div>
    <div class="lunch-view">
        <router-view />
    </div>
</template>

<script>
import { provide } from 'vue';
import { useCountStore } from '@/stores/useCountStore.js'

export default {
    setup() {
        provide('lunchmenuTitle', '점심 메뉴');

        const countStore = useCountStore;

        return {
            countStore
        }
    }
}
</script>

:

3. src\views\LunchMenu\LunchMenuListView.vue에 useCountStore을 추가하고 사용합니다.

<template>
    <div>{{ appTitle }} - {{ lunchmenuTitle }} 리스트
        <button @click="countStore.incrementByRandom()">{{ countStore.count }}</button>
    </div>
    :
</template>

<script>
:
import { useCountStore } from '@/stores/useCountStore.js'

export default {
    setup() {
        :
        const countStore = useCountStore;

        return {
            :
            countStore
        }
    },
    :
}
</script>

4. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/list)

[9] Backend 개발 - 사용자 API 개발, 인증 처리, ID Token

carrotweb — Tue, 4 Aug 2026 16:05:33 +0900

ID Token

사용자가 로그인하면 서버에서 사용자를 확인하여 사용자 정보로 토큰을 생성한 후 응답 데이터로 클라이언트에게 토큰을 전달하는 방식입니다.

클라이언트는 요청을 보낼 때 Authorization HTTP Header에 토큰을 포함하여 전달하면 서버는 전달 받은 토큰을 검증하여 인증된 사용자인지 확인합니다.

ID 토큰은 JSON Web Token (JWT, JSON 웹 토큰)입니다.

ID 토큰에는 인증된 사용자에 대한 정보(claim(클레임))가 포함되어 있습니다.

장점

클라이언트에서 토큰을 관리하기 때문에 서버에 부하가 낮아집니다.
접근 권한을 적용할 수 있습니다.

단점

토큰이 탈취 당할 수 있습니다. → 보안성이 취약함 (HTTPS로 보안할 수 있습니다. 단, 클라이언트 해킹은 차단할 수 없습니다.)
모든 자원을 접근할 수 있습니다. → 별도의 접근 권한 처리 필요

ID Token Process (ID 토큰 프로세스)

ID Token으로 JSON Web Token를 사용하겠습니다.

JWT(JSON Web Token - JSON 웹 토큰)
(https://datatracker.ietf.org/doc/html/rfc7519)

JWT(JSON Web Token - JSON 웹 토큰)
(https://jwt.io/)

JSON 웹 토큰을 디코딩, 검증 그리고 생성합니다. 두 집단 간에 안전하게 클레임(정보)을 표현하기 위한 개방형 산업 표준 RFC 7519 방식입니다.

사용자 보호를 위해 모든 JWT 디버깅과 유효성 검사는 브라우저에서 수행됩니다. JWT는 리소스에 대한 액세스 권한을 부여하는 자격 증명을 나타낼 수 있으므로 JWT를 붙여 넣거나 공유할 때 주의하세요.

JWT는 header(헤더).payload(페이로드, 전송되는 데이터).signature(시그니처, 서명)로 구성되어 있습니다.
도트(.)로 구분되어 있습니다. (Self-Contained Token)

JWT는 header.payload.signature로 구성되어 있습니다.

header(헤더)

algorithm(alg, 서명에 사용된 알고리즘)과 token type(typ, 토큰 타입) 정보를 가지고 있습니다.

payload(페이로드, 전송되는 데이터)

저장되는 정보를 claim(클레임)이라고 부르고 name : value로 구성됩니다. 여러 claim 세트로 구성됩니다. (payload는 암호화되지 않기 때문에 개인정보는 사용하지 않아야 합니다.)

signature(시그니처, 서명)

JWT의 무결성을 보장하기 위한 서명입니다.

sign(header + "." + payload, private_key)

각각의 JSON은 base64UrlEncode()로 인코딩합니다.

JWT Claims

Registered Claim Names (등록된 클레임 이름)

이름이 이미 정의된 클레임입니다.

iss (issuer, 이슈어, 발급자) : JWT 발급자 (JWT를 발급한 주체), 도메인을 사용합니다.

Ex) "iss" : "auth.example.com", "iss" : "https://auth.example.com"

sub (subject, 서브젝트, 제목) : JWT 제목

Ex) "sub" : "authcode"

aud (audience, 오디언스, 청취자) : JWT 대상자 (JWT를 받는 수신자), JWT를 요청한 클라이언트의 ID나 고유 식별 값을 사용합니다.

Ex) "aud" : "lunchmenuApp"

exp (expiration time, 엑스퍼레이션 타임, 만료 시간) : JWT 만료 시간, 시간 이후에는 JWT에 대한 처리가 수락되어서는 안됩니다.

Ex) "exp": 1629535586

nbf (not before, 낫 비포, 이전 아님) : 시간 이전에는 JWT에 대한 처리가 수락되어서는 안됩니다.

Ex) "nbf": 1629535596

iat (Issued at, 이슈드 엣, 발급 시간) : JWT 발급 시간

Ex) "iat": 1629449186

jti (JWT ID) : JWT에 대한 고유 식별자, 발급자가 생성한 값 간의 충돌을 방지하기 위해 사용됩니다.

Ex) "jti": "c56e9bf321b8406d9dac956652ec9aef"

Public Claim Names (공개 클레임 이름)

원하는 이름으로 클레임 이름을 정의할 수 있습니다. 새로운 클레임 이름은 충돌을 방지하기 위해 충돌 방지 이름(Collision-Resistant Name, 컬리전 리지스턴트 네임)이 포함되어 있어야 합니다. 그래서 네임스페이스나 URI 형식으로 정의하는 것이 좋습니다.

Ex) "cohttp://m.example.auth.api.v1.member.userid" : "test1"

Ex) "http://auth.example.com/api/v1/member/userid" : "test1"

Private Claim Names (비공개 클레임 이름)

JWT 생산자(JWT 발급자)와 소비자(JWT를 요청한 클라이언트)는 합의하에 비공개 클레임 이름을 정의하고 사용할 수 있습니다.

Ex) "name" : "kang byung joon", "given_name" : "byung joon“, "family_name" : "kang"

Ex) "nickname" : "carrotweb"

Libraries for Token Signing/Verification
(https://jwt.io/libraries)

jsonwebtoken
(https://www.npmjs.com/package/jsonwebtoken)

1. JSON 토큰을 사용하기 위해 jsonwebtoken 설치 (터미널에서 실행합니다.)

npm install jsonwebtoken --save

uuid

(https://www.npmjs.com/package/uuid)

2. UUID를 사용하기 위해 uuid 설치 (터미널에서 실행합니다.)

npm install uuid --save

JWT Sign

jwt.sign(payload, secret, options, [callback])

payload

JWT에 저장되는 정보로 key : value로 구성됩니다.

여기서는 로그인 사용자를 구분하기 위해 아이디(sub), JWT 발급 시간(iat), JWT 만료 시간(exp), JWT 대상자(aud), JWT 발급자(iss), JWT에 대한 고유 식별자(jti), 이름(name), 권한(roles)을 저장합니다.

secret

서명을 만들 때 사용되는 암호 문자열입니다.

여기서는 UUID를 암호 문자열로 사용했습니다.

options

JWT를 생성할 때 사용되는 옵션입니다.

algorithm은 암호화 알고리즘으로 HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 등을 사용할 수 있습니다. 기본값으로 HS256를 사용합니다.

expiresIn(exp)는 JWT 만료 시간으로 초 단위 또는 시간 범위 문자열로 설정합니다.

년 단위 : "1y", 일 단위 : "1 days", "1d", 시간 단위 : "2.5 hrs", "2h", 분 단위 : "1m", 초 단위 : "5s“ (단위 문자가 포함되지 않으면 초 단위로 설정됩니다.)

notbefore(nbf)는 JWT를 처리하지 않는 시간으로 초 단위 또는 시간 범위 문자열로 설정합니다.

expiresIn와 동일한 표기법을 사용합니다.

audience(aud)는 JWT 대상자(JWT를 받는 수신자)입니다. JWT를 요청한 클라이언트의 ID나 고유 식별 값을 사용합니다.

issuer(iss)는 JWT 발급자(JWT를 발급한 주체)입니다. 도메인을 사용합니다.

subject(sub)는 JWT 제목(claim의 주제)입니다. 인증에서는 사용자 ID를 사용합니다.

jwtid는 JWT 식별자입니다.

[callback]

JWT가 생성된 후 호출되는 funcation입니다. 생성된 토큰(token)이나 에러(err)를 인자로 줍니다.

3. src\api\v1\member.js 파일 전체 수정

const express = require('express');
const router = express.Router();
const getDBConnection = require('../../db/mariadb/connection');
const mybatisMapper = require('mybatis-mapper');
const { v4: uuidv4 } = require('uuid');
const jwt = require('jsonwebtoken');

// XML 파일 경로는 상대 경로가 아닌 절대 경로(Root 경로)로 './' 또는 '/' 없이 입력해야 합니다.
mybatisMapper.createMapper(['./src/db/mappers/mariadb/lunchmenu/member-sql.xml']);

// SQL 언어 형식과 들여쓰기를 설정
const format = {language: 'mariadb', indent: '  '};

// 사용자 ID로 검색하여 사용자를 인증하고 리턴합니다.
router.post('/login', async function(req, res, next) {
    console.log(`REST API Post Method - Member Login.`);

    const result = {
        result: 'fail',
        code: 401,
        message: '',
        idtoken: ''
    };

    if (req.body.id == undefined || req.body.id == "") {
        result.code = 400;
        result.message = "id가 없습니다."
        res.status(result.code).json(result);
        return;
    } else if (req.body.password == undefined || req.body.password == "") {
        result.code = 400;
        result.message = "password가 없습니다."
        res.status(result.code).json(result);
        return;
    }

    const params = {
        id : req.body.id,
        password : req.body.password
    };

    //const query = "SELECT * FROM tb_member WHERE mbr_id = ? AND mbr_pw = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu.member', 
        'selectMember', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.id, req.body.password]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.message = "사용자가 없습니다.";
        } else {
            if (data[0].mbr_pw != params.password) {
                result.message = "비밀번호가 동일하지 않습니다."
            } else {
                result.message = "사용자가 인증되었습니다.";
                const uuid = uuidv4().toString();
                const jwtid = uuid.replace(/-/gi, '');
                const secret = "005c9780fe7c11eb89b4e39719de58a5";
                try {
                    const issuedAt = new Date().toLocaleString();
                    const iat = Date.parse(issuedAt) / 1000;
                    const idToken = await new Promise((resolve, reject) => {
                        jwt.sign({
                                name : data[0].mbr_name,
                                roles : data[0].mbr_roles,
                                iat : iat
                            },
                            secret,
                            {
                                algorithm: "HS256",
                                issuer : "apiserver.example.com",
                                subject : data[0].mbr_id,
                                audience : "lunchmenuApp",
                                expiresIn : "1d",
                                jwtid : jwtid
                            },
                            (err, token) => {
                                if (err) {
                                    reject(err);
                                } else {
                                    resolve(token);
                                }
                            });
                    });
                    result.result = "success";
                    result.code = 200;
                    result.idtoken = idToken;
                } catch(err) {
                    console.log(err);
                    result.code = 500;
                    result.message = "ID 토큰 생성이 실패하였습니다.";
                }
            }
        }
    } catch (error) {
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

module.exports = router;

JWT Verify

jwt.verify(token, secretOrPublicKey, [options, callback])

token

jwt.sign() 메서드로 생성된 JWT입니다.

secretOrPublicKey

서명을 만들 때 사용된 암호 문자열입니다.

[callback]

JWT가 검증(확인)된 후 호출되는 funcation입니다.

payload 값(decode)이나 에러(err)를 인자로 줍니다.

4. src\api\v1\authMiddleware.js 파일 전체 수정

const jwt = require('jsonwebtoken');

const authMiddleware = async (req, res, next) => {
    let authorization = req.header('Authorization');

    const result = {
        result: 'fail',
        code: 401,
        message: '인증이 실패하였습니다.',
        data: {}
    };

    if (authorization == undefined || authorization == "") {
        result.code = 400;
        res.status(result.code).json(result);
    } else {
        authorization = authorization.replace("Bearer ","");
        try {
            const secret = "005c9780fe7c11eb89b4e39719de58a5";
            const idToken = await new Promise((resolve, reject) => {
                jwt.verify(authorization, secret, 
                    (err, decoded) => {
                        if (err) {
                            reject(err);
                        } else {
                            resolve(decoded);
                        }
                    });
            });
            req.idToken = idToken;
            next();
        } catch(err) {
            res.status(result.code).json(result);
        }
    }
}

module.exports = authMiddleware;

5. index.js 파일 수정 (쿠키, 세션 주석 처리)

const express = require('express');
//const cookieParser = require('cookie-parser');
//const session = require('express-session');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

:

// Cookie 설정
//app.use(cookieParser());

// 세션 설정
//app.use(session({
//    secret: "test", // 세션 ID 쿠키에 서명하는데 사용되는 비밀번호입니다.
//    resave: false, // 세션을 세션 저장소에 다시 저장하도록 강제합니다.
//    saveUninitialized: true, // "초기화되지 않은" 세션을 강제로 저장소에 저장합니다.
//    name: "sessionid" // 응답에 설정할 세션 ID 쿠키의 이름입니다.
//}));

// 인증 설정
app.use('/api/v1/lunchmenus', require('./src/api/v1/authMiddleware'));
:

사용자 API 테스트 (POSTMAN에서 확인)
1. 기존 쿠키 삭제

2. 전체 점심 메뉴 조회

3. 사용자 로그인

4. JWT 확인

5. 전체 점심 메뉴 조회

CORS 처리

Cross Origin Resource Sharing (교차 출처 리소스 공유)

1. index.js 파일 수정 (기존 CORS 처리에 Headers에 Authorization 추가, OPTIONS 처리 추가)

// 모든 리소스에 접근 허용 - CORS(Cross-origin resource sharing, 교차 출처 리소스 공유) 문제 해결
// GET, POST, PUT, DELETE 메서드 사용 허용
// Content-type, Authorization 요청 허용
app.use(function (req, res, next) {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
    res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    if (req.method === 'OPTIONS') {
        res.sendStatus(200);
    } else {
        next();
    }
});

Response to preflight request doesn't pass access control check: It does not have HTTP ok status.

Preflight 요청에 대한 응답이 액세스 제어 검사를 통과하지 못했습니다. HTTP 확인 상태가 아닙니다.

OPTIONS으로 요청이 들어오면 상태 코드 200으로 응답하면 됩니다.

CORS(Cross Origin Resource Sharing, 교차 출처 리소스 공유)
(https://expressjs.com/en/resources/middleware/cors.html)

1. cors를 사용하기 위해 cors 설치 (터미널에서 실행합니다.)

npm install cors --save

2. index.js 파일 수정 (CORS 추가, 기존 CORS 주석 처리)

const express = require('express');
//const cookieParser = require('cookie-parser');
//const session = require('express-session');
const cors = require('cors');
const app = express();
const port = 9000;

app.use(cors());

:

// 모든 리소스에 접근 허용 - CORS(Cross-origin resource sharing, 교차 출처 리소스 공유) 문제 해결
// GET, POST, PUT, DELETE 메서드 사용 허용
// Content-type, Authorization 요청 허용
//app.use(function (req, res, next) {
//	res.header('Access-Control-Allow-Origin', '*');
//	res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
//	res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
//	if (req.method === 'OPTIONS') {
//		res.sendStatus(200);
//	} else {
//		next();
//	}
//});

:

[8] Backend 개발 - 사용자 API 개발, 인증 처리, Session + HTTP Cookie

carrotweb — Tue, 4 Aug 2026 15:28:12 +0900

인증 처리를 위한 사용자 API 개발

사용자 인증 처리를 위한 테이블을 생성합니다.

Table 생성

테이블 생성 쿼리 실행

use lunchdb;

-- tb_member table이 있으면 삭제
DROP TABLE IF EXISTS tb_member;

-- tb_member table 생성
CREATE TABLE tb_member (
    seq int NOT NULL AUTO_INCREMENT COMMENT '사용자 일련번호',
    mbr_id varchar(50) NOT NULL COMMENT '사용자 ID',
    mbr_pw varchar(125) NOT NULL COMMENT '사용자 비밀번호',
    mbr_name varchar(50) NOT NULL COMMENT '사용자 이름',
    mbr_roles varchar(250) NOT NULL COMMENT '사용자 롤',
    reg_dtm datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '등록일',
    CONSTRAINT tb_member_pk PRIMARY KEY (seq)
)
ENGINE=InnoDB
DEFAULT CHARSET=utf8mb4
COLLATE=utf8mb4_general_ci
COMMENT='사용자';

초기 데이터 등록 쿼리 실행

INSERT INTO tb_member (mbr_id, mbr_pw, mbr_name, mbr_roles, reg_dtm) VALUES('test1', 'test1', '테스트1', 'ROLE_USER', '2025-03-06 14:12:00.000');

사용자 API 개발

1. src\db\mappers\mariadb\lunchmenu에 member-sql.xml 파일을 생성합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="apiserver.db.mappers.mariadb.lunchmenu.member">
    <select id="selectMember">
        SELECT *
          FROM tb_member
         WHERE mbr_id = #{id}
    </select>
</mapper>

2. src\api\v1에 member.js 파일 생성

const express = require('express');
const router = express.Router();
const getDBConnection = require('../../db/mariadb/connection');
const mybatisMapper = require('mybatis-mapper');

// XML 파일 경로는 상대 경로가 아닌 절대 경로(Root 경로)로 './' 또는 '/' 없이 입력해야 합니다.
mybatisMapper.createMapper(['./src/db/mappers/mariadb/lunchmenu/member-sql.xml']);

// SQL 언어 형식과 들여쓰기를 설정
const format = {language: 'mariadb', indent: '  '};

// 사용자 ID로 검색하여 사용자를 인증하고 리턴합니다.
router.post('/login', async function(req, res, next) {
    console.log(`REST API Post Method - Member Login.`);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    };

    if (req.body.id == undefined || req.body.id == "") {
        result.result = "fail";
        result.code = 400;
        result.message = "id가 없습니다."
        res.status(result.code).json(result);
        return;
    } else if (req.body.password == undefined || req.body.password == "") {
        result.result = "fail";
        result.code = 400;
        result.message = "password가 없습니다."
        res.status(result.code).json(result);
        return;
    }

    const params = {
        id : req.body.id,
        password : req.body.password
    };

    //const query = "SELECT * FROM tb_member WHERE mbr_id = ? AND mbr_pw = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu.member', 
        'selectMember', params, format);

    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.id, req.body.password]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.result = "fail";
            result.code = 401;
            result.message = "사용자가 없습니다.";
        } else {
            if (data[0].mbr_pw != params.password) {
                result.result = "fail";
                result.code = 401;
                result.message = "비밀번호가 동일하지 않습니다."
            } else {
                result.message = "사용자가 인증되었습니다.";
            }
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

module.exports = router;

3. index.js 파일에 BODY를 JSON 데이터로 변환, URL 인코딩, 요청 리소스 허용 처리

const express = require('express');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

:

// 점심 메뉴 연결
app.use('/api/v1/lunchmenus', require('./src/api/v1/lunchmenu'));
// 사용자 연결
app.use('/api/v1/member', require('./src/api/v1/member'));

app.listen(port, () => {
    console.log(`APIServer started on port ${port}`);
});

사용자 API 테스트 (POSTMAN에서 확인)
사용자 로그인

인증 처리

HTTP Cookie (쿠키)

사용자가 로그인하면 서버에서 사용자를 확인하여 쿠키를 생성하고 응답 HTTP Header에 쿠키를 포함시켜 클라이언트에게 전달하는 방식입니다. (Set-Cookie: <cookie-name>=<cookie-value>)

클라이언트는 요청을 보낼 때 요청 HTTP Header에 쿠키를 포함하여 전달하면 서버는 전달 받은 쿠키에서 세션을 가져와서 검증하고 인증된 사용자인지 확인합니다. (Cookie: <cookie-name>=<cookie-value>)

장점

클라이언트에 정보를 저장하기 때문에 서버에 부하가 낮아집니다.

단점

쿠키의 사이즈가 4KB이어서 많은 정보를 담을 수 없습니다.
일반적으로 쿠키 값은 암호화 되지 않기 때문에 안전하지 않습니다.
쿠키가 탈취 당할 수 있습니다.  보안성이 취약함

HTTP Cookie Process (쿠키 프로세스)

cookie-parser

(https://expressjs.com/en/resources/middleware/cookie-parser.html)

1. 쿠키 파서를 사용하기 위해 cookie-parser 설치 (터미널에서 실행합니다.)

npm install cookie-parser --save

2. index.js 파일 수정

const express = require('express');
const cookieParser = require('cookie-parser');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

:

// Cookie 설정
app.use(cookieParser());

// 점심 메뉴 연결
app.use('/api/v1/lunchmenus', require('./src/api/v1/lunchmenu'));
// 사용자 연결
app.use('/api/v1/member', require('./src/api/v1/member'));

app.listen(port, () => {
    console.log(`APIServer started on port ${port}`);
});

3. src\api\v1\member.js 파일 수정

    :
    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.id, req.body.password]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.code = 401;
            result.message = "사용자가 없습니다.";
        } else {
            if (data[0].mbr_pw != params.password) {
                result.result = "fail";
                result.code = 401;
                result.message = "비밀번호가 동일하지 않습니다."
            } else {
                result.message = "사용자가 인증되었습니다.";
                res.cookie("id", params.id);
                res.cookie("password", params.password);
            }
        }
    } catch (error) {
    :

res.cookie로 정보를 쿠키에 저장합니다.

그러면 응답 HTTP Header에 쿠키를 포함시켜 클라이언트에게 전달됩니다.

res.appendHeader(
    "Set-Cookie", ["id=" + params.id, "password=" + params.password]
);

사용자 API 테스트 (POSTMAN에서 확인)
사용자 로그인

인증 미들웨어(Middleware) 생성

1. src\api\v1에 authMiddleware.js 파일 생성

const getDBConnection = require('../../db/mariadb/connection');
const mybatisMapper = require('mybatis-mapper');

// XML 파일 경로는 상대 경로가 아닌 절대 경로(Root 경로)로 './' 또는 '/' 없이 입력해야 합니다.
mybatisMapper.createMapper(['./src/db/mappers/mariadb/lunchmenu/member-sql.xml']);

// SQL 언어 형식과 들여쓰기를 설정
const format = {language: 'mariadb', indent: '  '};

const authMiddleware = async (req, res, next) => {
    const id = req.cookies.id;
    const password = req.cookies.password;

    const result = {
        result: 'fail',
        code: 400,
        message: '인증이 실패하였습니다.',
        data: {}
    };

    if ((id == undefined || id == "") || (password == undefined || password == "")) {
        res.status(result.code).json(result);
    } else {
        const params = {
            id : id,
            password : password
        };

        const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu.member', 
            'selectMember', params, format);

        let conn;
        try {
            conn = await getDBConnection();
            data = await conn.query(query);
            if (data.length == 1) {
                if (data[0].mbr_pw == params.password) {
                    next();
                }
            }
        } catch (error) {
            result.code = 500;
            if (error.code == "ER_NO_SUCH_TABLE") {
                result.message = "테이블이 없습니다.";
            } else {
                result.message = "서버 오류가 발생하였습니다.";
            }
            res.status(result.code).json(result);
        } finally {
            if (conn) {
                conn.release();
            }
        }
    }
}

module.exports = authMiddleware;

2. index.js 파일 수정

const express = require('express');
const cookieParser = require('cookie-parser');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

:

// Cookie 설정
app.use(cookieParser());

// 인증 설정
app.use('/api/v1/lunchmenus', require('./src/api/v1/authMiddleware'));
// 점심 메뉴 연결
app.use('/api/v1/lunchmenus', require('./src/api/v1/lunchmenu'));
// 사용자 연결
app.use('/api/v1/member', require('./src/api/v1/member'));

app.listen(port, () => {
    console.log(`APIServer started on port ${port}`);
});

사용자 API 테스트 (POSTMAN에서 확인)

1. 기존 쿠키 삭제

2. 전체 점심 메뉴 조회

3. 사용자 로그인

4. 전체 점심 메뉴 조회

Session + HTTP Cookie(세션 + 쿠키)

사용자가 로그인하면 서버에서 사용자를 확인하여 세션을 생성하고 사용자 정보를 세션에 저장한 후 응답 HTTP Header에 쿠키를 포함시켜 클라이언트에게 전달하는 방식입니다.

클라이언트는 요청을 보낼 때 Cookie HTTP Header에 세션을 포함하여 전달하면 서버는 전달 받은 쿠키에서 세션을 가져와서 검증하고 인증된 사용자인지 확인합니다.

장점

서버에서 세션을 관리하기 때문에 안전합니다. → 보안성이 높음

단점

세션 정보를 관리하기 위해 서버 메모리가 많이 사용됩니다.
서버를 확장할 경우 세션 관리가 어려워집니다. → 서버 이중화를 위해 (In-Memory)DB를 사용
쿠키가 탈취 당할 수 있습니다. → 보안성이 취약함
모든 자원을 접근할 수 있습니다. → 별도의 접근 권한 처리 필요

Session + HTTP Cookie Process (세션 + 쿠키 프로세스)

express-session
(https://expressjs.com/en/resources/middleware/session.html)

1. 섹션을 사용하기 위해 express-session 설치 (터미널에서 실행합니다.)

npm install express-session --save

2. index.js 파일 수정

const express = require('express');
const cookieParser = require('cookie-parser');
const session = require('express-session');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

:

// Cookie 설정
app.use(cookieParser());

// 세션 설정
app.use(session({
    secret: "test", // 세션 ID 쿠키에 서명하는데 사용되는 비밀번호입니다.
    resave: false, // 세션을 세션 저장소에 다시 저장하도록 강제합니다.
    saveUninitialized: true, // "초기화되지 않은" 세션을 강제로 저장소에 저장합니다.
    name: "sessionid" // 응답에 설정할 세션 ID 쿠키의 이름입니다.
}));

// 인증 설정
app.use('/api/v1/lunchmenus', require('./src/api/v1/authMiddleware'));
:
});

3. src\api\v1\member.js 파일 수정

    :
    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.id, req.body.password]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.code = 401;
            result.message = "사용자가 없습니다.";
        } else {
            if (data[0].mbr_pw != params.password) {
                result.result = "fail";
                result.code = 401;
                result.message = "비밀번호가 동일하지 않습니다."
            } else {
                result.message = "사용자가 인증되었습니다.";
                req.session.userid = params.id;
                req.session.userpassword = params.password;
            }
        }
    } catch (error) {
    :

req.session로 정보를 세션에 저장합니다.

4. src\api\v1\authMiddleware.js 파일 수정

const getDBConnection = require('../../db/mariadb/connection');
const mybatisMapper = require('mybatis-mapper');

// XML 파일 경로는 상대 경로가 아닌 절대 경로(Root 경로)로 './' 또는 '/' 없이 입력해야 합니다.
mybatisMapper.createMapper(['./src/db/mappers/mariadb/lunchmenu/member-sql.xml']);

// SQL 언어 형식과 들여쓰기를 설정
const format = {language: 'mariadb', indent: '  '};

const authMiddleware = async (req, res, next) => {
    const id = req.session.userid;
    const password = req.session.userpassword;

    const result = {
        result: 'fail',
        code: 400,
        message: '인증이 실패하였습니다.',
        data: {}
    };
   :
}

사용자 API 테스트 (POSTMAN에서 확인)
1. 기존 쿠키 삭제

2. 전체 점심 메뉴 조회

3. 사용자 로그인

4. 전체 점심 메뉴 조회

사용자 id와 password 대신 데이터로 저장

1. src\api\v1\member.js 파일 수정

    :
    let conn;
    try {
        conn = await getDBConnection();
        //data = await conn.query(query, [req.body.id, req.body.password]);
        data = await conn.query(query);
        if (data.length == 0) {
            result.code = 401;
            result.message = "사용자가 없습니다.";
        } else {
            if (data[0].mbr_pw != params.password) {
                result.result = "fail";
                result.code = 401;
                result.message = "비밀번호가 동일하지 않습니다."
            } else {
                result.message = "사용자가 인증되었습니다.";
                req.session.member = data[0];
            }
        }
    } catch (error) {
    :

2. src\api\v1\authMiddleware.js 파일 전체 수정

const authMiddleware = async (req, res, next) => {
    const member = req.session.member;

    const result = {
        result: 'fail',
        code: 400,
        message: '인증이 실패하였습니다.',
        data: {}
    };

    if (member == undefined || member == "") {
        res.status(result.code).json(result);
    } else {
        next();
    }
}

module.exports = authMiddleware;

[7] Frontend 개발 - 읽기 뷰 (ReadView), 수정, 삭제 생성

carrotweb — Mon, 3 Aug 2026 16:29:23 +0900

읽기 뷰 (ReadView) 생성

1. src\views\LunchMenu에서 LunchMenuReadView.vue 파일을 생성합니다.

<template>
    <div>점심 메뉴 보기</div>
</template>

<script>
export default {
    setup() {
    }
}
</script>

2. src\router\index.js에서 LunchMenuReadView.vue를 import하고 children(칠드런)에 추가합니다.

:
import LunchMenuReadView from '@/views/LunchMenu/LunchMenuReadView.vue'

const routes = [
  :
  {
    path: '/lunchmenu',
    component: LunchMenuView,
    children : [
      :
      {
        path: ':seq',
        name: 'lunchmenuread',
        component: LunchMenuReadView
      }
    ]
  }
]
:

:seq는 웹 경로에 있는 파라미터입니다.

파라미터는 콜론 :으로 표시됩니다.

/lunchmenu/1

웹 경로에 있는 파라미터(동적 세그먼트)를 사용한 동적으로 라우팅하게 합니다. → 파라미터를 사용한 동적 라우트 매칭 (https://router.vuejs.kr/guide/essentials/dynamic-matching.html)

2. src\views\LunchMenu\LunchMenuListView.vue 파일에서 <li>가 클릭되면 함수(핸들러)가 호출되도록 @click(v-on:click)를 사용합니다.

<template>
    <div>점심 메뉴 리스트</div>
    <div class="buttons">
        <div class="right">
            <router-link :to="{ name: 'lunchmenuadd' }" class="button blue">
                <span>등록</span>
            </router-link>
        </div>
    </div>
    <div v-if="lunchMenuList.length == 0">
        점심 메뉴가 없습니다.
    </div>
    <div v-else>
        점심 메뉴가 {{ lunchMenuList.length }} 개 있습니다.
        <ul class="menu-list">
            <li class="menu-item" v-for="(lunchMenuItem, index) in lunchMenuList" :key="index"
                @click="gotoLunchMenuRead(lunchMenuItem)">{{ lunchMenuItem.menu_name }}
            </li>
        </ul>
    </div>
</template>

3. setup()에 <li>가 클릭되면 읽기 뷰 컴포넌트로 이동하기 위해서 라우터 인스턴스를 받고 router.push() 함수를 사용합니다. → Router 프로그램 방식

<script>
:
import { useRouter } from 'vue-router';

export default {
    name : 'LunchMenuListView',
    setup() {
        const router = useRouter();
        :
        function gotoLunchMenuRead(lunchMenuItem) {
            router.push({name : 'lunchmenuread', params : {seq : lunchMenuItem.seq}});
        }

        return {
            :
            gotoLunchMenuRead
        }
    },
}
</script>

name에는 route(라우트)를 생성할 때 부여한 이름을 사용합니다.

params에는 웹 경로에 있는 파라미터(콜론(:)으로 표시)인 :seq에 전달할 lunchMenuItem의 seq입니다.

router.push() 함수를 사용하면 routers에 등록되어 있는 router를 찾아 이동하게 됩니다.
(https://router.vuejs.kr/guide/essentials/navigation.html#Navigate-to-a-different-location)

4. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/1)

5. src\views\LunchMenu\LunchMenuListView.vue 파일에서 <li>에 있는 점심 메뉴 명을 클릭되면 이동하도록 router-link를 추가합니다. → Router 선언적 방식

<template>
    <div>점심 메뉴 리스트</div>
    <div class="buttons">
        <div class="right">
            <router-link :to="{ name: 'lunchmenuadd' }" class="button blue">
                <span>등록</span>
            </router-link>
        </div>
    </div>
    <div v-if="lunchMenuList.length == 0">
        점심 메뉴가 없습니다.
    </div>
    <div v-else>
        점심 메뉴가 {{ lunchMenuList.length }} 개 있습니다.
        <ul class="menu-list">
            <li class="menu-item" v-for="(lunchMenuItem, index) in lunchMenuList" :key="index">
                <router-link :to="{name : 'lunchmenuread', params : {seq: lunchMenuItem.seq}}">
                    {{ lunchMenuItem.menu_name }}
                </router-link>
            </li>
        </ul>
    </div>
</template>

name에는 route(라우트)를 생성할 때 부여한 이름을 사용합니다.

params에는 웹 경로에 있는 파라미터(콜론(:)으로 표시)인 :seq에 전달할 lunchMenuItem의 seq입니다.

6. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/)

LunchMenuListView.vue 파일에 있는 <style>에 menu-item를 추가했습니다.

<style>
.menu-item a {
    color: white;
}
</style>

7. src\views\LunchMenu\LunchMenuReadView.vue 파일을 수정합니다.

<template>
    <div>점심 메뉴 보기 {{ $route.params.seq }}</div>
    {{ lunchMenuItem.menu_name }}
</template>

<script>
import { ref } from 'vue';
import { useRoute } from 'vue-router'
import axios from 'axios';

export default {
    setup() {
        const route = useRoute();

        const lunchMenuItem = ref({});

        function getLunchMenuItem() {
            axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/" + route.params.seq).then((res) => {
                console.log(res);
                lunchMenuItem.value = res.data.data;
            }).catch((err) => {
                console.log(err);
            });
        }

        return {
            lunchMenuItem,
            getLunchMenuItem
        }
    },
    mounted() {
        this.getLunchMenuItem();
    }
}
</script>

현재 라우트는 템플릿에서 $route로 접근할 수 있습니다.

라우트가 매칭되면 파라미터의 값은 컴포넌트에서 route.params로 노출됩니다

/lunchmenu/:seq → /lunchmenu/1

useRoute() 함수는 현재 라우트를 반환 합니다.

8. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/1)

9. 목록 버튼을 추가하고 버튼이 클릭되면 점심 메뉴 리스트로 이동하도록 함수를 생성하고 리턴합니다.

<template>
    :
    <div class="buttons">
        <div class="right">
            <button class="button" @click="listClick">목록</button>
        </div>
    </div>
</template>

<script>
import { useRoute, useRouter } from 'vue-router'

export default {
    setup() {
        :
        const router = useRouter();
        :
        function listClick() {
            router.back();
        }

        return {
            :
            listClick
        }
    },
    :
}
</script>

10. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/1)

수정 생성 – 등록 뷰 (AddView) 재사용

1. src\router\index.js에서 수정 라우트를 children(칠드런)에 추가합니다.

:
const routes = [
  :
  {
    path: '/lunchmenu',
    component: LunchMenuView,
    children : [
      :
      {
        path: ':seq/edit',
        name: 'lunchmenuedit',
        component: LunchMenuAddView
       }
    ]
  }
]
:

/lunchmenu/1/edit

컴포넌트는 등록 컴포넌트를 사용합니다.

2. 수정 버튼을 추가하고 버튼이 클릭되면 점심 메뉴 수정으로 이동하도록 함수를 생성하고 리턴합니다.

<template>
    :
    <div class="buttons">
        <div class="left">
            <button class="button" @click="editClick">수정</button>
        </div>
        :
    </div>
</template>

<script>
:
export default {
    setup() {
        :
        function editClick() {
            var result = confirm("수정하시겠습니까?");
            if (result) {
                router.push({name : 'lunchmenuedit', params : {seq : route.params.seq}});
            }
        }
    return {
            :
            editClick
        }
    },
    :
    
    }
</script>

<style>
.buttons > div.left {
    position:absolute;
    height:32px;
    left:0;
}
</style>

3. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/1)

4. src\views\LunchMenu\LunchMenuAddView.vue 파일에서 $route.name으로 등록인지 수정인지 확인하여 메지지를 변경하고 버튼을 교체합니다.

<template>
    <div>점심 메뉴 {{ $route.name == 'lunchmenuedit' ? '수정' : '등록' }}</div>
    <form class="lunchMenuForm">
        <div>
            <label for="lunchMenuName">점심 메뉴 명 :</label>
            <input type="text" id="lunchMenuName" 
                placeholder="점심 메뉴 명을 입력하세요."
                v-model="lunchMenuName"/>
        </div>
    </form>
    <div class="buttons">
        <div class="right">
            <button v-if="$route.name == 'lunchmenuedit'" class="button blue" @click="editClick">수정</button>
            <button v-else class="button blue" @click="addClick">등록</button>
            <button class="button" @click="cancelClick">취소</button>
        </div>
    </div>
</template>

수정 버튼이 클릭되면 axios의 put() 함수를 사용하여 APIServer에 점심 메뉴가 수정되도록 합니다.

<script>
import { reactive, toRefs, onMounted } from 'vue';
import { useRouter, useRoute } from 'vue-router';
:

export default {
    setup() {
        :
        const route = useRoute();
        :
        function editClick() {
            if (state.lunchMenuName == "") {
                alert("점심 메뉴 명을 입력하세요.");
                lunchMenuNameInput.value.focus();
                return;
            }
            var result = confirm("수정하시겠습니까?");
            if (result) {
                const lunchMenuItem = { menuName : state.lunchMenuName };
                axios.put("http://127.0.0.1:9000/api/v1/lunchmenus/"+ route.params.seq, lunchMenuItem).then(() => {
                    router.replace({name : 'lunchmenuread', params : {seq: route.params.seq}};
                }).catch((err) => {
                    console.log(err);
                });
            }
        }

onMounted()에 콜백으로 getLunchMenuItem() 함수를 등록하여 APIServer에서 점심 메뉴를 가져오도록 합니다.

        function getLunchMenuItem() {
            axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/" + route.params.seq).then((res) => {
                state.lunchMenuName = res.data.data.menu_name;
            }).catch((err) => {
                console.log(err);
            });
        }
        :
        onMounted(()=>{
            if (route.name == "lunchmenuedit") {
                getLunchMenuItem();
            }
        });
        return {
            :
            editClick
        }
    }
}

5. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/1/edit)

6. 마운트 된 후 점심 메뉴 명 입력란으로 포커스가 가기 위해서 <template>를 참조하여 처리해야 합니다.

<template>
    :
            <input type="text" id="lunchMenuName" placeholder="점심 메뉴 명을 입력하세요."
                v-model="lunchMenuName"
                ref="lunchMenuNameInput"/>
    :
</template>

<script>
import { …, ref } from 'vue';

export default {
    setup() {
        :
        const lunchMenuNameInput = ref(null);
        :
        onMounted(()=>{
            :
            lunchMenuNameInput.value.focus();
        });
        
        return {
            :
            lunchMenuNameInput
        }
    }
}
</script>

DOM에 접근하기 위해서 ref란 특수 속성을 사용합니다.

ref 속성 값과 일치하는 이름으로 ref를 선언해야 합니다.

초기값은 null 이어야 합니다. 마운트 된 후 DOM객체로 변경됩니다.

focus() 함수로 input에 포커스가 이동됩니다.

템플릿 참조에 대한 설명을 참고하세요. (https://ko.vuejs.org/guide/essentials/template-refs.html)

삭제 – 읽기 뷰 (ReadView) 사용

1. 삭제 버튼을 추가하고 버튼이 클릭되면 점심 메뉴가 삭제되도록 함수를 생성하고 리턴합니다.

<template>
    :
    <div class="buttons">
        <div class="left">
            <button class="button" @click="editClick">수정</button>
            <button class="button" @click="deleteClick">삭제</button>
        </div>
        :
    </div>
</template>

<script>
:

export default {
    setup() {
        :
        async function deleteClick() {
            var result = confirm("삭제하시겠습니까?");
            if (result) {
                try {
                    const res = await axios.delete("http://127.0.0.1:9000/api/v1/lunchmenus/" + route.params.seq);
                    if (res.data.code == 200) {
                        alert("삭제되었습니다.");
                        router.push({name : 'lunchmenulist’});
                    } else {
                        alert("삭제되지 않았습니다.");
                    }
                } catch(err) {
                    console.log(err);
                }
            }
        }

        return {
            :
            deleteClick
        }
    },
    :
}
</script>

2. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/4)

라우터와 현재 라우트에 접근하기

라우터와 현재 라우트에 대한 접근 방법을 참고하세요.
(https://router.vuejs.kr/guide/#Accessing-the-router-and-current-route)

변수와 함수 사용

[6] Frontend 개발 - 등록 뷰 (AddView) 생성

carrotweb — Mon, 3 Aug 2026 15:51:05 +0900

등록 뷰 (AddView) 생성

1. src\views\LunchMenu에서 LunchMenuAddView.vue 파일을 생성합니다.

<template>
    <div>점심 메뉴 등록</div>
</template>

<script>
export default {
    setup() {
    }
}
</script>

2. src\router\index.js에서 LunchMenuAddView.vue를 import하고 routes에 route를 추가합니다.

:
import LunchMenuAddView from '@/views/LunchMenu/LunchMenuAddView.vue'

const routes = [
  :
  {
    path: '/lunchmenu/',
    name: 'lunchmenulist',
    component: LunchMenuListView
  },
  {
    path: '/lunchmenu/add',
    name: 'lunchmenuadd',
    component: LunchMenuAddView
  }
]
:

중첩된 라우트

/lunchmenu/와 /lunchmenu/add를 App.vue에 있는 router-view 컴포넌트가 아닌 /lunchmenu에서 Vue 컴포넌트를 생성하고 자체적인 router-view 컴포넌트에서 처리할 수 있습니다.

/ → app.vue
+- <router-view/>
+- /lunchmenu/ → LunchMenuListView.vue
+- /lunchmenu/add → LunchMenuAddView.vue

App.vue에 있는 router-view에서 변경됨

/ → app.vue
+- <router-view/>
    +- /lunchmenu → LunchMenuView.vue
        +- <router-view/>
            +- / → LunchMenuListView.vue
            +- /add → LunchMenuAddView.vue

LunchMenuView에 있는 router-view에서 변경됨

중첩된 라우트에 연결된 Vue 컴포넌트에는 반드시 router-view 컴포넌트가 있어야 합니다.

App UI는 컴포넌트가 중첩되게 구성되어 있습니다.

웹 경로(URL)를 세그먼트(segment, 부분)하면 컴포넌트를 중첩 시킬 수 있습니다.

중첩된 라우트에 대한 설명을 참고하세요.
(https://router.vuejs.kr/guide/essentials/nested-routes.html)

3. src\views\LunchMenu에서 LunchMenuView.vue 파일을 생성합니다.

<template>
    <div class="lunch-menu">점심 메뉴</div>
    <div class="lunch-view">
        <router-view/>
    </div>
</template>

<style>
.lunch-menu {
    width: 540px;
    margin: 10px auto;
}
.lunch-view {
    background-color: #dddddd;
    width: 540px;
    padding: 12px 0px;
    margin: auto auto;
}
</style>

4. src\router\index.js에서 LunchMenuView.vue를 import하고 중첩된 웹 경로(부모 경로)를 분리하여 route에 추가하고 중첩되지 않는 웹 경로(자식 경로)는 children(칠드런)에 추가합니다.

:
import LunchMenuView from '@/views/LunchMenu/LunchMenuView.vue'

const routes = [
  :
  {
    path: '/lunchmenu’,
    component: LunchMenuView,
    children : [
      {
        path: '',
        name: 'lunchmenulist',
        component: LunchMenuListView
      },
      {
        path: 'add',
        name: 'lunchmenuadd',
        component: LunchMenuAddView
      }
    ]
  }
]
:

5. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/)

6. src\views\LunchMenu\LunchMenuListView.vue 파일에 등록 뷰 컴포넌트로 이동하기 위해 router-link를 추가합니다. <style>에 있는 menu-list를 수정합니다.

<template>
    <div>점심 메뉴 리스트</div>
    <div class="buttons">
        <div class="right">
            <router-link :to="{ name: 'lunchmenuadd' }" class="button blue">
                <span>등록</span>
            </router-link>
        </div>
    </div>
    :
</template>

<style>
.menu-list {
    margin: 10px 10px;
    padding: 0;
}
:
</style>

to 속성에 path(웹 경로) 대신 route(라우트) 이름을 사용하기 위해서는 :to 속성을 사용해야 합니다.
:to는 v-bind:to를 단축한 겁니다. v-bind는 속성 값에 데이터를 바인딩해줍니다.
name에는 route(라우트)를 생성할 때 부여한 이름을 사용합니다.
/lunchmenu/add로 링크가 생성됩니다.

네임드 라우트

router-link 컴포넌트는 path 대신 route(라우트)를 생성할 때 부여한 이름으로 사용할 수 있습니다.
네임드 라우트 (https://router.vuejs.kr/guide/essentials/named-routes.html)

to 속성에 path(웹 경로)를 사용 → route(라우트)를 생성할 때 등록한 path를 사용

v3.x

<router-link to="/lunchmenu/add">등록</router-link>
<router-link :to="{ path: '/lunchmenu/add' }">등록</RouterLink>

v4.x

<RouterLink to="/lunchmenu/add">등록</RouterLink>
<RouterLink :to="{ path: '/lunchmenu/add' }">등록</RouterLink>

:to(v-bind:to) 속성에 name(이름)을 사용 → route(라우트)를 생성할 때 부여한 이름을 사용

v3.x

<router-link :to="{ name: 'lunchmenuadd' }">등록</router-link>

v4.x

<RouterLink :to="{ name: 'lunchmenuadd' }">등록</RouterLink>

7. public에 css 디렉터리를 생성하고 default.css 파일을 생성합니다. 공통으로 사용할 버튼 CSS를 추가합니다.

.buttons {
    position: relative;
    width: 500px; 
    height: 32px;
    margin-bottom: 20px;
    margin: auto auto;
}
.buttons > div.right {
    position: absolute;
    height: 32px;
    right: 0;
}
.buttons > div > a.button {
    display: inline-block;
    min-width: 95px;
    height: 32px;
    line-height: 32px;
    vertical-align: middle;
    font-size: 13px;
    text-align: center;
    text-decoration: none;
    border-radius: 20px;
    cursor: pointer;
}
.buttons > div > .button.blue {
    color: #fff; 
    border-color: #0099d2 !important; 
    background: #0099d2 !important;
}

8. link로 스타일시트를 추가합니다.

<!DOCTYPE html>
<html lang="">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <link rel="icon" href="<%= BASE_URL %>favicon.ico">
    <link rel="stylesheet" href="<%= BASE_URL %>css/default.css">
    <title><%= htmlWebpackPlugin.options.title %></title>
  </head>
  <body>
    <noscript>
      <strong>We're sorry but <%= htmlWebpackPlugin.options.title %> doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
    </noscript>
    <div id="app"></div>
    <!-- built files will be auto injected -->
  </body>
</html>

<%= BASE_URL %> 대신 /를 사용해도 됩니다. → <link rel="stylesheet" href="/css/default.css">
vue.config.js에서 module.exports에 publicPath가 없으면 <%= BASE_URL %>은 /입니다.

BASE_URL 변경 방법

vue.config.js에서 module.exports에 publicPath로 경로를 추가하고 다시 시작(npm run serve)하면 BASE_URL이 publicPath로 변경됩니다.

9. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/)

10. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/add)

11. <template>에 점심 메뉴 입력 폼을 추가하고 이 컴포넌트에서만 사용하는 CSS를 <style>에 추가합니다.

<template>
    <div class="test">점심 메뉴 등록</div>
    <form class="lunchMenuForm">
        <div>
            <label for="lunchMenuName">점심 메뉴 명 :</label>
            <input type="text" id="lunchMenuName" 
                placeholder="점심 메뉴 명을 입력하세요."/>
        </div>
    </form>
    <div class="buttons">
        <div class="right">
            <button class="button blue">등록</button>
            <button class="button">취소</button>
        </div>
    </div>
</template>

<script>
export default {
    setup() {
    }
}
</script>

<style scoped>
.lunchMenuForm {
    margin: 10px 10px; padding: 10px 10px 0px 10px; background-color: white;
}
.lunchMenuForm > div {
    padding-bottom: 10px; display: flex;
}
.lunchMenuForm label {
    flex: 0 0 120px; line-height: 38px;
}
.lunchMenuForm input[type="text"] {
    width: 100%; font-size: 14px;
}
button {
    display: inline-block; padding: 0.375rem 0.75rem; min-width: 95px;
    border: 1px solid #6c757d; border-radius: 0.375rem; margin-left: 10px;
    cursor: pointer;
}
button:first-child {
    margin-left: 0;
}
</style>

12. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/add)

13. setup()에 점심 메뉴 명이 문자열로 저장될 lunchMenuName이 반응형이 되도록 reactive(리엑티브) 함수를 사용합니다. 그리고 <template>에서 사용할 수 있게 리턴합니다.

<script>
import { reactive } from 'vue';

export default {
    setup() {
        const state = reactive({
            lunchMenuName: ""
        });

        state.lunchMenuName = "Hello";

        return {
            state
        }
    }
}
</script>

값이 반응형 상태가 되도록 하는 ref(레프) 함수와 다르게 reactive(리엑티브) 함수는 객체 자체를 반응형으로 처리합니다. (https://ko.vuejs.org/guide/essentials/reactivity-fundamentals#reactive)

14. <template>에서 lunchMenuName과 <input> 태그가 양방향 바인딩되게 v-model 디렉티브를 사용합니다.

<template>
    <div class="test">점심 메뉴 등록</div>
    <form class="lunchMenuForm">
        <div>
            <label for="lunchMenuName">점심 메뉴 명 :</label>
            <input type="text" id="lunchMenuName" 
                placeholder="점심 메뉴 명을 입력하세요."
                v-model="state.lunchMenuName"/>
        </div>
    </form>
    <div class="buttons">
        <div class="right">
            <button class="button blue">등록</button>
            <button class="button">취소</button>
        </div>
    </div>
</template>

Form 입력 바인딩에 대한 설명을 참고하세요.
(https://ko.vuejs.org/guide/essentials/forms.html#form-input-bindings)

15. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/add)

toRef vs toRefs

반응형 객체인 state의 모든 속성에 대해 toRef()로 반환되게 하기 위해서는 toRefs() 함수를 사용합니다.

<script>
import { reactive, toRefs } from 'vue';

export default {
    setup() {
        const state = reactive({
            lunchMenuName: ""
        });

        state.lunchMenuName = "Hello";

        const { lunchMenuName } = toRefs(state);
        lunchMenuName.value = "Hello World!!";

        return {
            lunchMenuName
        }
    }
}
</script>

toRefs()는 반응형 객체의 모든 속성에 대해 ref를 만들어 리턴합니다.
(https://ko.vuejs.org/api/reactivity-utilities.html#torefs)

모든 속성이 분해 할당됩니다. Destructuring(디스트럭처링, 구조 분해 할당)

const { lunchMenuName } = toRefs(state);

반응형 객체인 state의 모든 속성에 대해 toRef()로 반환되게 하기 위해서는 toRefs() 함수를 사용합니다.

<script>
import { reactive, toRefs } from 'vue';

export default {
    setup() {
        const state = reactive({
            lunchMenuName: ""
        });

        state.lunchMenuName = "Hello World!!";

        return {
            ...toRefs(state)
        }
    }
}
</script>

Spread Operator(스프레드 오퍼레이터)를 사용하여 모든 속성을 분해합니다. → 모든 속성들이 ref()로 리턴

웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/add)

16. 버튼이 클릭되면 함수(핸들러)가 호출되도록 @click(v-on:click)를 사용합니다.

<template>
    <div class="test">점심 메뉴 등록</div>
    <form class="lunchMenuForm">
        <div>
            <label for="lunchMenuName">점심 메뉴 명 :</label>
            <input type="text" id="lunchMenuName" 
                placeholder="점심 메뉴 명을 입력하세요."
                v-model="lunchMenuName"/>
        </div>
    </form>
    <div class="buttons">
        <div class="right">
            <button class="button blue" @click="addClick">등록</button>
            <button class="button" @click="cancelClick">취소</button>
        </div>
    </div>
</template>

@는 v-on 디렉티브를 단축한 겁니다.

@이벤트=함수(핸들러)

함수(핸들러)는 setup()에 함수로 정의합니다.

이벤트 핸들링에 대한 설명을 참고하세요.

(https://ko.vuejs.org/guide/essentials/event-handling.html)

v-on에 대한 설명을 참고하세요.

(https://ko.vuejs.org/api/built-in-directives#v-on)

17. setup()에 버튼 클릭에 대한 함수(핸들러)를 정의하고 리턴합니다.

<script>
import { reactive, toRefs } from 'vue';

export default {
    setup() {
        const state = reactive({
            lunchMenuName: ""
        });

        function addClick() {
        }

        function cancelClick() {
        }

        return {
            ...toRefs(state),
            addClick,
            cancelClick
        }
    }
}
</script>

18. 취소 버튼이 클릭되면 이전 경로로 이동하기 위해서 라우터 인스턴스를 받아서 이전 경로로 이동하도록 router.back() 또는 router.go() 함수를 사용합니다. → Router 프로그램 방식

<script>
import { reactive, toRefs } from 'vue';
import { useRouter } from 'vue-router';

export default {
    setup() {
        const router = useRouter();
        :
        function cancelClick() {
            router.back();
        }
        :
    }
}
</script>

router.back();은 router.go(-1);과 같습니다.

특정 히스토리로 이동합니다.

(https://router.vuejs.kr/guide/essentials/navigation.html#Traverse-history)

19. 등록 버튼이 클릭되면 axios(엑시오스)의 post() 함수를 사용하여 APIServer에 점심 메뉴가 추가 되도록 합니다.

<script>
:
import axios from 'axios';

export default {
    setup() {
        :
        const state = reactive({
            lunchMenuName: ""
        }); 

        function addClick() {
            const lunchMenuItem = { menuName : state.lunchMenuName };
            axios.post("http://127.0.0.1:9000/api/v1/lunchmenus/", lunchMenuItem).then((res) => {
                console.log(res);
            }).catch((err) => {
                console.log(err);
            });
        }
        :
    }
}
</script>

20. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu/add)

21. 점심 메뉴가 추가되면 점심 메뉴 리스트로 이동되도록 router.replace() 함수를 사용합니다.

<script>
:

export default {
    setup() {
        const router = useRouter();
        
        const state = reactive({
            lunchMenuName: ""
        }); 

        function addClick() {
            const lunchMenuItem = { menuName : state.lunchMenuName };
            axios.post("http://127.0.0.1:9000/api/v1/lunchmenus/", lunchMenuItem).then(() => {
                router.replace({name : 'lunchmenulist'});
            }).catch((err) => {
                console.log(err);
            });
        }
        :
    }
}
</script>

라우터 이동

router.push() 함수와 router.replace() 함수는 이동할 위치 정보를 이용하여 vue 컴포넌트로 이동합니다.

router.push() (https://router.vuejs.kr/api/interfaces/Router.html#push)
router.replace() (https://router.vuejs.kr/api/interfaces/Router.html#replace)

router.push() 함수를 사용하면 히스토리에 추가됩니다. 웹 브라우저에서 이전 버튼을 클릭하면 현재 링크(등록 뷰 컴포넌트)로 이동합니다.

router.push({name : 'lunchmenulist'});

router.replace() 함수를 사용하면 현재 히스토리가 변경됩니다. 웹 브라우저에서 이전 버튼을 클릭하면 현재 링크(등록 뷰 컴포넌트)의 이전 링크(리스트 뷰 컴포넌트)로 이동합니다.

router.replace({name : 'lunchmenulist'});

21. 웹 브라우저에서 확인하기 (http://127.0.0.1:8080/lunchmenu)

[5] Backend 개발 - API Server 개발, Node.JS + Search

carrotweb — Mon, 3 Aug 2026 15:08:59 +0900

검색(Search)

데이터베이스에 있는 테이블에서 검색 조건에 맞는 데이터만 검색(select) 하기 위해서는 SELECT 할 때 WHERE 절을 사용하면 됩니다.

공통적으로 많이 사용하는 검색 조건은

검색 타입(검색할 테이블의 컬럼)
검색 조건(검색하고자 하는 키워드가 테이블의 컬럼 값과 일치하는지 또는 포함되는지에 대한 조건)
검색 키워드(검색할 테이블의 컬럼에서 검색할 키워드)

WHERE 절을 MyBatis Mapper XML에서 조건에 따라 처리되게 만들기 위해서는 <where>를 사용하면 됩니다.

검색 타입(searchType), 검색 조건(searchCondition), 검색 키워드(searchKeyword)

<select id="selectLunchMenuList">
    SELECT TLM.*
     FROM tb_lunch_menu TLM
    <where>
        <if test='searchKeyword != null and searchKeyword != ""'>
            <choose>
                <when test='searchType != null and searchType == "menuName"'>
                    <choose>
                        <when test='searchCondition != null and searchCondition == "like"'>
                            TLM.menu_name LIKE CONCAT('%',#{searchKeyword},'%')
                        </when>
                        <otherwise>
                            TLM.menu_name = #{searchKeyword}
                        </otherwise>
                    </choose>
                </when>
            </choose>
        </if>
    </where>
     ORDER BY TLM.REG_DTM DESC
     LIMIT ${pageStartRecordNo}, ${countPerPage}
</select>

검색 키워드가 있고 검색 타입이 menuName 이면 검색 조건(포함하면 like, 그렇지 않으면 일치)에 따라 검색

검색 키워드가 없거나 검색 타입이 일치하지 않으면 WHERE 절은 생성되지 않습니다.

점심 메뉴 리스트(selectLunchMenuList)와 점심 메뉴 리스트 수(selectLunchMenuListCount)에서 동일한 WHERE 절을 사용해야 합니다.

Mapper XML에서는 동일하게 사용되는 쿼리문을 분리하여 재사용할 수 있게 <sql>를 지원하고 있습니다.

<sql id="whereLunchMenuList">
    <where>
        <if test='searchKeyword != null and searchKeyword != ""'>
            <choose>
                <when test='searchType != null and searchType == "menuName"'>
                    <choose>
                        <when test='searchCondition != null and searchCondition == "like"'>
                            TLM.menu_name LIKE CONCAT('%',#{searchKeyword},'%')
                        </when>
                        <otherwise>
                            TLM.menu_name = #{searchKeyword}
                        </otherwise>
                    </choose>
                </when>
            </choose>
        </if>
    </where>
</sql>

<select>에서 <sql>를 가져오기 위해서 <include>를 추가하고 <include>의 refid 속성에 <sql>의 id을 입력하면 <sql>에 있는 쿼리문이 포함되게 됩니다.

검색(Search) 모듈 추가

1. src\db\mappers\mariadb\lunchmenu\lunchmenu-sql.xml 파일을 수정합니다.

    :

    <sql id="whereLunchMenuList">
        <where>
            <if test='searchKeyword != null and searchKeyword != ""'>
                <choose>
                    <when test='searchType != null and searchType == "menuName"'>
                        <choose>
                            <when test='searchCondition != null and searchCondition == "like"'>
                                TLM.menu_name LIKE CONCAT('%',#{searchKeyword},'%')
                            </when>
                            <otherwise>
                                TLM.menu_name = #{searchKeyword}
                            </otherwise>
                        </choose>
                    </when>
                </choose>
            </if>
        </where>
    </sql>

    <select id="selectLunchMenuList">
        SELECT TLM.*
          FROM tb_lunch_menu TLM
        <include refid="whereLunchMenuList"/>
         ORDER BY TLM.REG_DTM DESC
         LIMIT ${pageStartRecordNo}, ${countPerPage}
    </select>
    
    
    <select id="selectLunchMenuListCount">
        SELECT count(TLM.seq) AS listCount
          FROM tb_lunch_menu TLM
        <include refid="whereLunchMenuList"/>
    </select>

    :

2. src\api\v1\search.js 파일을 추가합니다.

// 검색
// HTTP 요청 req
const search = function(req) {
    // 검색 타입
    let searchType = req.query.searchtype;
    if (searchType == undefined || typeof searchType == "undefined" || searchType == null) {
        searchType = "";
    }
    // 검색 조건 - 일치(equal), 포함(like)
    let searchCondition = req.query.searchcondition;
    if (searchCondition == undefined || typeof searchCondition == "undefined" || searchCondition == null) {
        searchCondition = "equal";
    }
    // 검색 키워드
    let searchKeyword = req.query.searchkeyword;
    if (searchKeyword == undefined || typeof searchKeyword == "undefined" || searchKeyword == null) {
        searchKeyword = "";
    }

    // 검색 정보
    const searchInfo = {
        searchType : searchType,
        searchCondition : searchCondition,
        searchKeyword : searchKeyword
    }
    return searchInfo;
}

module.exports = search;

3. src\api\v1\lunchmenu.js 파일을 수정합니다.

:
const search = require('./search');
:

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method – Read All Lunch Menu.");

    const searchInfo = search(req);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: [],
        pagination: {}
    };

    let conn;
    try {
        conn = await getDBConnection();

        const params = {
            searchType : searchInfo.searchType,
            searchCondition : searchInfo.searchCondition,
            searchKeyword : searchInfo.searchKeyword
        };

        //const query = "SELECT count(seq) AS listCount FROM tb_lunch_menu";
        let query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
            'selectLunchMenuListCount', params, format);

        // 전체 크기
        const dataCount = await conn.query(query);
        if (dataCount.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            // 결과에 숫자 타입(int(n, N), float(f, F), double(d, D), long(l, L))이 같이 옵니다. [ { listCount: 3n } ]
            const totalCount = parseInt(dataCount[0].listCount);

            // 페이지네이션 정보
            // 전체 레코드 수 totalCount
            // 페이지 크기 req.query.countperpage
            // 페이지 번호 req.query.pageno
            // 페이지 사이즈 req.query.pagesize
            const paginationInfo = pagination(totalCount, req.query.pageno, req.query.countperpage, req.query.pagesize);

            if (totalCount > 0) {
                params.pageStartRecordNo = paginationInfo.pageStartRecordNo;
                params.countPerPage = paginationInfo.countPerPage;

                //const query = "SELECT * FROM tb_lunch_menu ORDER BY REG_DTM DESC";
                query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
                    'selectLunchMenuList', params, format);

                const data = await conn.query(query);
                if (data.length == 0) {
                    result.message = "데이터가 없습니다.";
                } else {
                    result.message = "데이터가 조회되었습니다.";
                    result.data = data;
                }
            } else {
                result.message = "데이터가 없습니다.";
            }

            // 페이지네이션 정보
            result.pagination = paginationInfo;
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
        console.log(error);
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

점심 메뉴 API 테스트 (POSTMAN에서 확인)
1. 전체 점심 메뉴 조회

http://127.0.0.1:9000/api/v1/lunchmenus?searchtype=menuName&searchcondition=like&searchkeyword=%EB%B3%B6
%EB%B3%B6 → 볶
문자열 디코딩(https://dencode.com/)

{
    "result": "success",
    "code": 200,
    "message": "데이터가 조회되었습니다.",
    "data": [
        {
            "seq": 3,
            "menu_name": "볶음밥",
            "reg_dtm": "2025-01-17 13:37:26"
        }
    ],
    "pagination": {
        "totalCount": 1,
        "countPerPage": 10,
        "pageSize": 10,
        "startPageNo": 1,
        "endPageNo": 1,
        "lastPageNo": 1,
        "pageNo": 1,
        "pageStartRecordNo": 0,
        "pageEndRecordNo": 0
    }
}

[4] Backend 개발 - API Server 개발, Node.JS + Paging

carrotweb — Mon, 3 Aug 2026 14:59:35 +0900

페이징(Paging), 페이지(Page)

데이터베이스에서 페이징(Paging) 없이 데이터를 가져오면 전체 데이터를 반환하면 서버 부하(데이터베이스 부하, 네트워크 트래픽 부하)가 발생합니다. 그래서 데이터를 가져오기 전에 한 번에 가져올 데이터의 크기를 정해서 가져오게 해야 합니다.

이렇게 일정한 크기로 데이터를 가져오는 것을 페이징(Paging)이라고 하고 일정한 크기를 가진 데이터를 페이지(Page)라고 합니다.

Query String(쿼리 스트링)으로 URL 주소 뒤에 붙여서 사용합니다.

페이지 크기(countperpage) : 가져올 ROW 수
페이지 번호(pageno) : 가져올 페이지 번호

http://127.0.0.1:9000/api/v1/lunchmenus?countperpage=10&pageno=1
1번부터 10번까지 점심 메뉴를 가져옵니다.

http://127.0.0.1:9000/api/v1/lunchmenus?countperpage=5&pageno=2
6번부터 10번까지 점심 메뉴를 가져옵니다.

페이징(Paging) 기능 추가

1. src\api\v1\lunchmenu.js 파일을 수정합니다.

점심 메뉴 조회에 페이지 크기(countperpage), 페이지 번호(pageno)를 추가합니다.

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    // 페이지 크기
    let countPerPage = req.query.countperpage;
    // 페이지 번호
    let pageNo = req.query.pageno;

    // 페이지 크기가 없으면 10으로 설정
    if (countPerPage == undefined || typeof countPerPage == "undefined" || countPerPage == null) {
        countPerPage = 10;
    } else {
        countPerPage = parseInt(countPerPage);
    }
    // 페이지 번호가 없으면 1로 설정
    if (pageNo == undefined || typeof pageNo == "undefined" || pageNo == null) {
        pageNo = 1;
    } else {
        pageNo = parseInt(pageNo);
    }

    :
}

2. src\db\mappers\mariadb\lunchmenu\lunchmenu-sql.xml 파일을 수정합니다.

페이지 크기(countperpage)와 페이지 번호(pageno)를 사용하여 로우 시작 번호와 끝 번호를 계산하기 위해서 전체 크기를 가져와야 합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="apiserver.db.mappers.mariadb.lunchmenu">  
    <select id="selectLunchMenuList">
        SELECT *
          FROM tb_lunch_menu
         ORDER BY REG_DTM DESC
    </select>

    <select id="selectLunchMenuListCount">
        SELECT count(seq) AS listCount
          FROM tb_lunch_menu
    </select>

    :

쿼리문에 페이징(Paging)을 처리하기 위해 LIMIT를 추가합니다. (https://mariadb.com/kb/en/limit/)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="apiserver.db.mappers.mariadb.lunchmenu">  
    <select id="selectLunchMenuList">
        SELECT *
          FROM tb_lunch_menu
         ORDER BY REG_DTM DESC
         LIMIT ${pageStartRecordNo}, ${countPerPage}
    </select>

    :

ROW 시작 번호부터 가져올 ROW 수만큼 ROW를 가져옵니다.

Oracle에서는 ROW_NUMBER를 사용하여 ROW의 번호를 부여하고 WHERE 절에서 BETWEEN으로 가져옵니다.

<select id="selectLunchMenuList">
    SELECT   *
              , RNUM
     FROM (
               SELECT   *
                         , ROW_NUMBER() OVER(ORDER BY REG_DTM) AS RNUM
                FROM tb_lunch_menu
              )
    WHERE RNUM BETWEEN ${pageStartRecordNo} AND ${pageEndRecordNo}
</select>

3. src\api\v1\lunchmenu.js 파일을 수정합니다.

페이지 크기(countperpage)와 페이지 번호(pageno)를 사용하여 로우 시작 번호와 끝 번호를 계산합니다.

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    :

    let conn;
    try {
        conn = await getDBConnection();

        //const query = "SELECT count(seq) AS listCount FROM tb_lunch_menu";
        let query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
            'selectLunchMenuListCount', {}, format);

        // 전체 크기
        const dataCount = await conn.query(query);
        if (dataCount.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            // 결과에 숫자 타입(int(n, N), float(f, F), double(d, D), long(l, L))이 같이 옵니다. [ { listCount: 3n } ]
            const totalCount = parseInt(dataCount[0].listCount);

            // 시작 번호
            let pageStartRecordNo = ((pageNo - 1) * countPerPage);
            // 전체 크기가 0이면
            if (totalCount == 0) {
                pageStartRecordNo = 0;
            }
            // 종료 번호
            let pageEndRecordNo = (pageNo * countPerPage) - 1;
            // 전체 크기가 0이면
            if (totalCount == 0) {
                pageEndRecordNo = 0;
            } else if (pageEndRecordNo > (totalCount - 1)) {
                // 종료 번호가 전체 크기보다 크면 전체 크기로 변경
                pageEndRecordNo = totalCount - 1;
            }

            const params = {
                pageStartRecordNo : pageStartRecordNo,
                countPerPage : countPerPage
            };

            //const query = "SELECT * FROM tb_lunch_menu ORDER BY REG_DTM DESC";
            query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
                'selectLunchMenuList', params, format);

            const data = await conn.query(query);
            if (data.length == 0) {
                result.message = "데이터가 없습니다.";
            } else {
                result.message = "데이터가 조회되었습니다.";
                result.data = data;
            }
        }
    }

    :

점심 메뉴 API 테스트 (POSTMAN에서 확인)

1. 전체 점심 메뉴 조회

페이지네이션(Pagination)

나누어진 Page(페이지)를 이전 페이지나 다음 페이지 또는 특정 페이지로 이동할 수 있게 처리하는 것을 Pagination(페이지네이션)이라고 합니다.

페이지 사이즈(pageSize)
전체 마지막 페이지 번호(lastPageNo)
시작 페이지 번호(startPageNo)
종료 페이지 번호(endPageNo)
이전 페이지 번호 = 시작 페이지 번호(startPageNo) - 1
다음 페이지 번호 = 종료 페이지 번호(endPageNo) + 1

페이지네이션(Pagination) 정보 추가

1. src\api\v1\lunchmenu.js 파일을 수정합니다.

페이지 사이즈(pagesize)를 추가합니다.

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    :
    // 페이지 사이즈
    let pageSize = req.query.pagesize;

    :
    // 페이지 사이즈가 없으면 10으로 설정
    if (pageSize == undefined || typeof pageSize == "undefined" || pageSize == null) {
        pageSize = 10;
    } else {
        pageSize = parseInt(pageSize);
    }

    :
}

Query String(쿼리 스트링)으로 URL 주소 뒤에 붙여서 사용합니다.

http://127.0.0.1:9000/api/v1/lunchmenus?pagesize=5&countperpage=5&pageno=3
11번부터 15번까지 점심 메뉴를 가져옵니다.

전체 마지막 페이지 번호(lastPageNo)를 계산합니다. 전체 크기(totalCount)를 페이지 크기(countPerPage)로 나누고 나머지가 있으면 1을 더합니다.

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    :
        // 전체 크기
        const dataCount = await conn.query(query);
        if (dataCount.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            // 결과에 숫자 타입(int(n, N), float(f, F), double(d, D), long(l, L))이 같이 옵니다. [ { listCount: 3n } ]
            const totalCount = parseInt(dataCount[0].listCount);

            // 전체 마지막 페이지 번호
            const lastPageNo = Math.floor(totalCount / countPerPage) + (totalCount % countPerPage == 0 ? 0 : 1);

    :
}

시작 페이지 번호(startPageNo)를 계산합니다.

페이지 사이즈(pageSize)에서 페이지 번호(pageNo)를 나누고 나머지가 없으면 1을 뺍니다.

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    :

            // 결과에 숫자 타입(int(n, N), float(f, F), double(d, D), long(l, L))이 같이 옵니다. [ { listCount: 3n } ]
            const totalCount = parseInt(dataCount[0].listCount);

            // 전체 마지막 페이지 번호
            const lastPageNo = Math.floor(totalCount / countPerPage) + (totalCount % countPerPage == 0 ? 0 : 1);
            // 시작 페이지 번호
            let startPageNo = 1;
            // 페이지 사이즈로 페이지 번호를 나눈 몫만큼 페이지 시작 번호 변경
            let start = Math.floor(pageNo / pageSize);
            if (start >= 1) {
                // 그렇지만 나머지가 없으면 현재 페이지 번호가 마지막 페이지 번호와 같아 감소
                if (pageNo % pageSize == 0) {
                    start--;
                }
                startPageNo = (start * pageSize) + 1;
            }
    :
}

페이지 번호가 10이면 start가 1이 됩니다. 그러면 시작 페이지 번호가 11이 됩니다. 그래서 페이지 사이즈의 배수(즉 나머지가 없으면)이면 start에서 1을 뺍니다. 그러면 시작 페이지 번호가 1이 됩니다.

종료 페이지 번호(endPageNo)를 계산합니다.

시작 페이지 번호(startPageNo)에서 1을 빼고 페이지 사이즈(pageSize)를 더하면 됩니다.

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    :

            // 시작 페이지 번호
            let startPageNo = 1;
            :
            // 종료 페이지 번호
            let endPageNo = (startPageNo - 1) + pageSize;
            // 그렇지만 종료 페이지 번호가 마지막 페이지 번호보다 크면 마지막 페이지 번호로 변경
            if (endPageNo > lastPageNo) {
                endPageNo = lastPageNo;
            }
    :
}

페이지네이션(endPageNo)을 추가합니다.

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    :

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: [],
        pagination: {}
    };

            :

            // 페이지네이션 정보
            result.pagination.totalCount = totalCount;
            result.pagination.countPerPage = countPerPage;
            result.pagination.pageSize = pageSize;
            result.pagination.startPageNo = startPageNo;
            result.pagination.endPageNo = endPageNo;
            result.pagination.lastPageNo = lastPageNo;
            result.pagination.pageNo = pageNo;
            :
}

점심 메뉴 API 테스트 (POSTMAN에서 확인)

1. 전체 점심 메뉴 조회

{
    "result": "success",
    "code": 200,
    "message": "데이터가 조회되었습니다.",
    "data": [
        {
            "seq": 1,
            "menu_name": "짜장면",
            "reg_dtm": "2025-01-17 13:37:00"
        }
    ],
    "pagination": {
        "totalCount": 3,
        "countPerPage": 2,
        "pageSize": 10,
        "startPageNo": 1,
        "endPageNo": 2,
        "lastPageNo": 2,
        "pageNo": 2
    }
}

페이지네이션(Pagination) 모듈로 처리

1. src\api\v1\pagination.js 파일을 추가합니다.

// 페이지네이션
// 전체 레코드 수 totalCount
// 페이지 번호 pageNo
// 페이지 크기 countPerPage
// 페이지 사이즈 pageSize
const pagination = function(totalCount, pageNo, countPerPage, pageSize) {
    // 페이지 번호가 없으면 1로 설정
    if (pageNo == undefined || typeof pageNo == "undefined" || pageNo == null) {
        pageNo = 1;
    } else {
        pageNo = parseInt(pageNo);
    }
    // 페이지 크기가 없으면 10으로 설정
    if (countPerPage == undefined || typeof countPerPage == "undefined" || countPerPage == null) {
        countPerPage = 10;
    } else {
        countPerPage = parseInt(countPerPage);
    }
    // 페이지 사이즈가 없으면 10으로 설정
    if (pageSize == undefined || typeof pageSize == "undefined" || pageSize == null) {
        pageSize = 10;
    } else {
        pageSize = parseInt(pageSize);
    }

    // 전체 마지막 페이지 번호
    const lastPageNo = Math.floor(totalCount / countPerPage) + (totalCount % countPerPage == 0 ? 0 : 1);

    // 시작 페이지 번호
    let startPageNo = 1;
    // 페이지 사이즈로 페이지 번호를 나눈 몫만큼 페이지 시작 번호 변경
    let start = Math.floor(pageNo / pageSize);
    if (start >= 1) {
        // 그렇지만 나머지가 없으면 현재 페이지 번호가 마지막 페이지 번호와 같아 감소
        if (pageNo % pageSize == 0) {
            start--;
        }
        startPageNo = (start * pageSize) + 1;
    }

    // 종료 페이지 번호
    let endPageNo = (startPageNo - 1) + pageSize;
    // 그렇지만 종료 페이지 번호가 마지막 페이지 번호보다 크면 마지막 페이지 번호로 변경
    if (endPageNo > lastPageNo) {
         endPageNo = lastPageNo;
    }

    // 시작 번호
    let pageStartRecordNo = ((pageNo - 1) * countPerPage);
    // 전체 크기가 0이면
    if (totalCount == 0) {
        pageStartRecordNo = 0;
    }
    
    // 종료 번호
    let pageEndRecordNo = (pageNo * countPerPage) - 1;
    // 전체 크기가 0이면
    if (totalCount == 0) {
        pageEndRecordNo = 0;
    } else if (pageEndRecordNo > (totalCount - 1)) {
        // 종료 번호가 전체 크기보다 크면 전체 크기로 변경
         pageEndRecordNo = totalCount - 1;
    }

    // 페이지네이션 정보
    const paginationInfo = {};
    paginationInfo.totalCount = totalCount;
    paginationInfo.countPerPage = countPerPage;
    paginationInfo.pageSize = pageSize;
    paginationInfo.startPageNo = startPageNo;
    paginationInfo.endPageNo = endPageNo;
    paginationInfo.lastPageNo = lastPageNo;
    paginationInfo.pageNo = pageNo;
    paginationInfo.pageStartRecordNo = pageStartRecordNo;
    paginationInfo.pageEndRecordNo = pageEndRecordNo;
    
    return paginationInfo;
}

module.exports = pagination;

2. src\api\v1\lunchmenu.js 파일을 수정합니다.

:
const pagination = require('./pagination');
:

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: [],
        pagination: {}
    };

    let conn;
    try {
        conn = await getDBConnection();

        //const query = "SELECT count(seq) AS listCount FROM tb_lunch_menu";
        let query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
            'selectLunchMenuListCount', {}, format);

        // 전체 크기
        const dataCount = await conn.query(query);
        if (dataCount.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            // 결과에 숫자 타입(int(n, N), float(f, F), double(d, D), long(l, L))이 같이 옵니다. [ { listCount: 3n } ]
            const totalCount = parseInt(dataCount[0].listCount);

            // 페이지네이션 정보
            // 전체 레코드 수 totalCount
            // 페이지 크기 req.query.countperpage
            // 페이지 번호 req.query.pageno
            // 페이지 사이즈 req.query.pagesize
            const paginationInfo = pagination(totalCount, req.query.pageno, req.query.countperpage, req.query.pagesize);

            if (totalCount > 0) {
                const params = {
                    pageStartRecordNo : paginationInfo.pageStartRecordNo,
                    countPerPage : paginationInfo.countPerPage
                };

                //const query = "SELECT * FROM tb_lunch_menu ORDER BY REG_DTM DESC";
                query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
                    'selectLunchMenuList', params, format);
                console.log(query);
                const data = await conn.query(query);
                if (data.length == 0) {
                    result.message = "데이터가 없습니다.";
                } else {
                    result.message = "데이터가 조회되었습니다.";
                    result.data = data;
                }
            } else {
                result.message = "데이터가 없습니다.";
            }

            // 페이지네이션 정보
            result.pagination = paginationInfo;
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
        console.log(error);
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

[3] Backend 개발 - API Server 개발, Node.JS + MyBatis3

carrotweb — Mon, 3 Aug 2026 14:36:13 +0900

Node.JS에서 MyBatis3 Mapper XML 파일을 이용하기

1. Mybatis Mapper 설치하기 (터미널에서 실행합니다.)

npm install mybatis-mapper --save

2. src\db에 mappers\mariadb\lunchmenu 디렉터리를 생성하고 lunchmenu-sql.xml 파일을 생성합니다.

XML은 MyBatis3 구문과 동일합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="">
</mapper>

<mapper>의 namespace(네임스페이스) 속성은 Mapper XML 파일들을 서로 구분하기 위해서 사용됩니다. 그래서 하나의 Mapper XML 파일만 가리켜야 하기 때문에 중복되지 않아야 합니다.

여기서는 namespace(네임스페이스)를 프로젝트 명과 XML 파일이 있는 경로를 조합하여 사용하겠습니다.

프로젝트 명 : apiserver

XML 파일이 있는 경로 : db\mappers\mariadb\lunchmenu
그래서 mapper namespace는 apiserver.db.mappers.mariadb.lunchmenu입니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="apiserver.db.mappers.mariadb.lunchmenu">  
    <select id="">
    </select>

    <insert id="">
    </insert>

    <update id="">
    </update>

    <delete id="">
    </delete>
</mapper>

<mapper> 안에서는 <select>(SELECT 쿼리문), <insert>(INSERT 쿼리문), <update>(UPDATE 쿼리문), <delete>(DELEETE 쿼리문)를 설정할 수 있습니다.

<select>, <insert>, <update>, <delete>의 id 속성 값은 식별자로 중복되지 않는 이름으로 입력합니다.

id 속성은 mybatisMapper.getStatement() 함수에서 구문을 찾을 때 사용됩니다.

id 속성 값에 대한 접두사(Prefix)와 접미사(suffix)를 이용하여 다음과 같은 명명 규칙(NamingRule)을 정합니다.

DB : Insert, Select, Update, Delete

SELECT 쿼리문으로 여러 로우를 가져오면 select<모델명>List
SELECT 쿼리문으로 로우 수를 가져오면 select<모델명>ListCount
SELECT 쿼리문으로 한 로우만 가져오면 select<모델명>Item
SELECT 쿼리문으로 하나의 값만 가져오면 select<모델명>Value
INSERT 쿼리문은 insert<모델명>Item
UPDATE 쿼리문으로 한 로우만 수정하면 update<모델명>Item
UPDATE 쿼리문으로 여러 로우를 수정하면 update<모델명>List
DELEETE 쿼리문으로 한 로우만 삭제하면 delete<모델명>Item
DELEETE 쿼리문으로 여러 로우를 삭제하면 delete<모델명>List

CRUD : Create, Read, Update, Delete (CRUDL : Create, Read, Update, Delete, List)

SELECT 쿼리문으로 여러 로우를 가져오면 read<모델명>List (list<모델명>)
SELECT 쿼리문으로 로우 수를 가져오면 read<모델명>ListCount (list<모델명>Count)
SELECT 쿼리문으로 한 로우만 가져오면 read<모델명>Item
SELECT 쿼리문으로 하나의 값만 가져오면 read<모델명>Value
INSERT 쿼리문은 create<모델명>Item
UPDATE 쿼리문으로 한 로우만 수정하면 update<모델명>Item
UPDATE 쿼리문으로 여러 로우를 수정하면 update<모델명>List
DELEETE 쿼리문으로 한 로우만 삭제하면 delete<모델명>Item
DELEETE 쿼리문으로 여러 로우를 삭제하면 delete<모델명>List

ABCD : Add, Browse, Change, Delete

SELECT 쿼리문으로 여러 로우를 가져오면 browse<모델명>List
SELECT 쿼리문으로 로우 수를 가져오면 browse<모델명>Count
SELECT 쿼리문으로 한 로우만 가져오면 browse<모델명>Item
SELECT 쿼리문으로 하나의 값만 가져오면 browse<모델명>Value
INSERT 쿼리문은 add<모델명>Item
UPDATE 쿼리문으로 한 로우만 수정하면 change<모델명>Item
UPDATE 쿼리문으로 여러 로우를 수정하면 change<모델명>List
DELEETE 쿼리문으로 한 로우만 삭제하면 delete<모델명>Item
DELEETE 쿼리문으로 여러 로우를 삭제하면 delete<모델명>List

BREAD : Browse, Read, Edit, Add, Delete

SELECT 쿼리문으로 여러 로우를 가져오면 browse<모델명>
SELECT 쿼리문으로 로우 수를 가져오면 browse<모델명>Count
SELECT 쿼리문으로 한 로우만 가져오면 read<모델명>
SELECT 쿼리문으로 하나의 값만 가져오면 read<모델명>Value
INSERT 쿼리문은 add<모델명>Object
UPDATE 쿼리문으로 한 로우만 수정하면 edit<모델명>Object
UPDATE 쿼리문으로 여러 로우를 수정하면 edit<모델명>List
DELEETE 쿼리문으로 한 로우만 삭제하면 delete<모델명>Object
DELEETE 쿼리문으로 여러 로우를 삭제하면 delete<모델명>List

DAVE : Delete, Add, View, Edit

SELECT 쿼리문으로 여러 로우를 가져오면 view<모델명>List
SELECT 쿼리문으로 로우 수를 가져오면 view<모델명>Count
SELECT 쿼리문으로 한 로우만 가져오면 view<모델명>Object
SELECT 쿼리문으로 하나의 값만 가져오면 view<모델명>Value
INSERT 쿼리문은 add<모델명>Object
UPDATE 쿼리문으로 한 로우만 수정하면 edit<모델명>Object
UPDATE 쿼리문으로 여러 로우를 수정하면 edit<모델명>List
DELEETE 쿼리문으로 한 로우만 삭제하면 delete<모델명>Object
DELEETE 쿼리문으로 여러 로우를 삭제하면 delete<모델명>List

GRADE : Get, Remove, Add, Delete, Edit

SELECT 쿼리문으로 여러 로우를 가져오면 get<모델명>List
SELECT 쿼리문으로 로우 수를 가져오면 get<모델명>ListCount
SELECT 쿼리문으로 한 로우만 가져오면 get<모델명>Object
SELECT 쿼리문으로 하나의 값만 가져오면 get<모델명>Value
INSERT 쿼리문은 add<모델명>Object
UPDATE 쿼리문으로 한 로우만 수정하면 edit<모델명>Object
UPDATE 쿼리문으로 여러 로우를 수정하면 edit<모델명>List
UPDATE 쿼리문으로 한 로우만 사용(검색)되지 않게 수정하면 remove<모델명>Object
UPDATE 쿼리문으로 여러 로우가 사용(검색)되지 않게 수정하면 remove<모델명>List
DELEETE 쿼리문으로 한 로우만 삭제하면 delete<모델명>Object
DELEETE 쿼리문으로 여러 로우를 삭제하면 delete<모델명>List

DB 명명 규칙으로 사용하겠습니다.

3. lunchmenu-sql.xml 파일에 src\api\v1\lunchmenu.js 파일에 있는 query를 <select>, <insert>, <update>, <delete> 구문으로 추가합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="apiserver.db.mappers.mariadb.lunchmenu">  
    <select id="selectLunchMenuList">
        SELECT *
          FROM tb_lunch_menu
         ORDER BY REG_DTM DESC
    </select>

    <select id="selectLunchMenuItem">
        SELECT *
          FROM tb_lunch_menu
         WHERE seq = ${seq}
    </select>

    <insert id="insertLunchMenuItem">
        INSERT INTO tb_lunch_menu
            (
                menu_name
            )
            VALUES
            (
                #{menuName}
            )
    </insert>

    <update id="updateLunchMenuItem">
        UPDATE tb_lunch_menu
           SET menu_name = #{menuName}
         WHERE seq = ${seq}
    </update>

    <delete id="deleteLunchMenuItem">
        DELETE
          FROM tb_lunch_menu
         WHERE seq = ${seq}
    </delete>
</mapper>

SQL 문에 있는 #{}, ${}는 전달되는 변수가 들어갈 곳입니다.

#{}은 변수에 들어 갈 값이 따옴표로 묶여 변환됩니다. → 문자열에 사용

${}은 변수 그대로 변환됩니다. → 숫자에 사용

API 수정

1. src\api\v1\lunchmenu.js 파일을 수정합니다.

const express  = require('express');
const router = express.Router();
const getDBConnection = require('../../db/mariadb/connection');
const mybatisMapper = require('mybatis-mapper');

// XML 파일 경로는 상대 경로가 아닌 절대 경로(Root 경로)로 './' 또는 '/' 없이 입력해야 합니다.
mybatisMapper.createMapper(['./src/db/mappers/mariadb/lunchmenu/lunchmenu-sql.xml']);

// SQL 언어 형식과 들여쓰기를 설정
const format = {language: 'mariadb', indent: '  '};

createMapper([XML Files])

[XML Files]은 XML 파일 경로들이 있는 배열입니다.
XML 파일 경로는 상대 경로가 아닌 절대 경로(Root 경로)로 ＇./＇ 또는 ＇/＇ 없이 입력해야 합니다.
- Root에 있다면 ./test.xml, test.xml
- Root의 하위 디렉터리인 src에 있다면 ./src/test.xml, src/test.xml
지정된 xml 파일을 읽고 구문 분석하여 SQL 문을 생성할 준비를 합니다.

format 변수의 language 옵션
(https://github.com/sql-formatter-org/sql-formatter/blob/HEAD/docs/language.md#options)

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    :

    //const query = "SELECT * FROM tb_lunch_menu ORDER BY REG_DTM DESC";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'selectLunchMenuList', {}, format);

    :
        data = await conn.query(query);
    :
});

getStatement(namespace: string, sql: string, param?: mybatisMapper.Params, format?: mybatisMapper.Format)

namespace은 네임스페이스로 XML 파일에 있는 <mapper>의 namespace 속성 값입니다.
sql는 XML 파일에 있는 <select>, <insert>, <update>, <delete>의 id 속성 값입니다.
Parameters는 XML 파일에 있는 SQL 문에 있는 #{}, ${} 변수에 들어갈 값입니다.
format은 옵션입니다. SQL 언어와 들여쓰기를 설정할 수 있습니다. (https://www.npmjs.com/package/sql-formatter)

// 점심 메뉴 번호로 검색하여 점심 메뉴를 리턴합니다.
router.get('/:no', async function(req, res, next) {
    :

    const params = {
        seq : req.params.no
    };

    //const query = "SELECT * FROM tb_lunch_menu WHERE seq = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'selectLunchMenuItem', params, format);

    :
        data = await conn.query(query);
    :
});

// 점심 메뉴를 등록합니다.
router.post('/', async function(req, res, next) {
    :

    const params = {
        menuName : req.body.menuName
    };

    //const query = "INSERT INTO tb_lunch_menu (menu_name) VALUES(?)";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'insertLunchMenuItem', params, format);

    :
         data = await conn.query(query);
    :
});

// 점심 메뉴를 수정합니다.
router.put('/:no', async function(req, res, next) {
    :

    const params = {
        menuName : req.body.menuName,
        seq : req.params.no
    };

    //const query = "UPDATE tb_lunch_menu SET menu_name = ? WHERE seq = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'updateLunchMenuItem', params, format);

    :
        data = await conn.query(query);
    :
});

// 점심 메뉴를 삭제합니다.
router.delete('/:no', async function(req, res, next) {
    :

    const params = {
        seq : req.params.no
    };

    //const query = "DELETE FROM tb_lunch_menu WHERE seq = ?";
    const query = mybatisMapper.getStatement('apiserver.db.mappers.mariadb.lunchmenu', 
        'deleteLunchMenuItem', params, format);

    :
         data = await conn.query(query);
    :
});

[2] Frontend 개발

carrotweb — Sun, 2 Aug 2026 20:19:34 +0900

개발 환경을 구성하기 위해 프로그램 설치

Project Scaffolding(프로젝트 스캐폴딩)

프로젝트를 시작하기 위한 구조와 설정 등을 자동으로 처리해주는 툴입니다. → 애플리케이션의 구조 생성

개발자가 수동으로 설치하고 설정해야 하는 것들을 프로그램이 대신 처리해줌으로써 개발을 빠르게 시작할 수 있도록 도와줍니다.

Vue CLI(Command line interface)

Vue.js 개발을 위한 표준 도구 (빠른 Vue.js 애플리케이션 개발을 위한 시스템을 제공) (https://cli.vuejs.org/)

IDE(Integrated Development Environment, 통합 개발 환경)

VS Code + Vue-Official(extension)

문법 강조 표시, TypeScript 지원, 템플릿 표현식 및 컴포넌트 props에 대한 인텔리센스 제공

Browser Devtools

Vue.js devtools

Vue로 만든 웹의 구조를 파악하거나 데이터 파악하고 디버깅을 할 수 있게 제공

Vue CLI로 Vue 프로젝트 생성

1. Vue CLI 설치 (콘솔에서 실행합니다.)

npm install -g @vue/cli

vue --version

2. Vue CLI로 Vue 프로젝트 생성 (콘솔에서 실행합니다.)

vue create lunchapp

vue 프로젝트를 어떻게 구성할 건지 preset(프리셋 : 사전 설정)합니다. – Default (Vue 3) 선택

babel (바벨, https://babeljs.io) : javascript를 이전 버전과 호환되게 코드를 변환해주는 컴파일러 → 트랜스파일러

eslint (린트/린터, https://eslint.org) : javascript 코드에서 발견되는 문제 패턴들을 식별해주는 정적 분석 도구, 코드 규칙을 이용하 코드 스타일 유지

3. Vue 프로젝트 실행 (콘솔에서 실행합니다.)

cd lunchapp; npm run serve

4. 웹 브라우저에서 확인 (http://localhost:8080/)

5. 웹 경로와 Vue 컴포넌트를 연결하기 위해 Vue Router 설치

Vue Router –웹 경로와 Vue 컴포넌트를 연결해 줍니다.

(https://router.vuejs.kr)

Vue Router Plugin으로 vue-router를 설치하겠습니다.

vue에서는 vue router에 대한 일련의 작업들을 자동으로 처리해 Plugin을 제공합니다.

Vue Router Plugin 설치 (콘솔에서 실행합니다.)

vue add router

설치가 진행되는 중에 "Use history mode for router? (Requires proper server setup for index fallback in production) - 라우터에 히스토리 모드를 사용 하시겠습니까? (프로덕션에서 인덱스 폴백을 위한 적절한 서버 설정 필요합니다.)"라는 컨펌 메시지가 나타납니다. 라우터를 히스토리 모드로 사용하기 위해 "Y"을 입력하고 엔터키를 누릅니다.

Vue Router 디렉터리 구조

6. index.js에 Router(라우터) 인스턴스를 생성

import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '../views/HomeView.vue'

const routes = [
  {
    path: '/',
    name: 'home',
    component: HomeView
  },
  {
    path: '/about',
    name: 'about',
    component: () => import(/* webpackChunkName: "about" */ '../views/AboutView.vue')
  }
]

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes
})

export default router

라우터 인스턴스 생성
(https://router.vuejs.kr/guide/#Registering-the-router-plugin)

7. App.vue에 Router(라우터) 인스턴스를 use() 함수로 등록

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

createApp(App).use(router).mount('#app')

use() 함수는 mount() 함수 이전에 실행되어야 합니다.

라우터 인스턴스 등록
(https://router.vuejs.kr/guide/#Registering-the-router-plugin)

8. 웹 브라우저에서 확인 (http://localhost:8080/)

9. API 서버와 연동하기 위해 Vue Axios(액시오스) 설치

npm install axios --save

Options API vs Composition API

Vue 2 지원은 2023년 12월 31일에 종료
API 스타일에 대한 설명을 참고하세요. (https://ko.vuejs.org/guide/introduction.html#api-styles)

LunchMenuListView 컴포넌트 생성

1. src\views에서 LunchMenu 디렉터리 생성, LunchMenuListView.vue 파일을 생성합니다.

<template>
    <div>점심 메뉴 리스트</div>
</template>

<script>
</script>

<style>
</style>

2. src\router\index.js에서 LunchMenuListView.vue를 import하고 routes에 route를 추가합니다.

:
import LunchMenuListView from '@/views/LunchMenu/LunchMenuListView.vue'

const routes = [
  :
  {
    path: '/lunchmenu/',
    name: 'lunchmenu',
    component: LunchMenuListView
  }
]

:

@는 단축 경로로 "src/*" 경로를 단축한 겁니다.
vue.config.js 파일에 정의되어 있습니다.
"paths": {
"@/*": ["src/*"]
},

3. src\App.vue에서 router-link를 추가합니다.

Router 선언적 방식 (v3.x)

<template>
  <nav>
    <router-link to="/">Home</router-link> |
    <router-link to="/about">About</router-link> |
    <router-link to="/lunchmenu/">LunchMenu</router-link>
  </nav>
  <router-view/>
</template>

링크를 생성하기 위해서 <a>태그가 아닌 router-link 컴포넌트를 사용합니다. → router-link 컴포넌트는 <a>태그로 렌더링 됩니다. (<router-link to=""> → <a href="">)

router-view 컴포넌트는 현재 컴포넌트에서 렌더링할 위치입니다. → 현재 경로에 맞는 컴포넌트가 렌더링 됩니다.

(v4.x)

<template>
  <nav>
    <RouterLink to="/">Home</RouterLink> |
    <RouterLink to="/about">About</RouterLink> |
    <RouterLink to="/lunchmenu/">LunchMenu</RouterLink>
  </nav>
  <RouterView/>
</template>

4. 웹 브라우저에서 확인 (http://localhost:8080/lunchmenu)

LunchMenuListView 컴포넌트 개발

1. setup()에 점심 메뉴들이 리스트로 저장될 lunchMenuList를 선언하고 값이 반응형 상태가 되도록 ref(레프, reference) 함수를 사용합니다. 그리고 <template>에서 사용할 수 있게 리턴합니다.

<template>
    <div>점심 메뉴 리스트</div>
</template>

<script>
import { ref } from 'vue';

export default {
    name : 'LunchMenuListView',
    setup() {
        let lunchMenuList = ref([]);

        return {
            lunchMenuList
        }
    }
}
</script>

let lunchMenuList = []; ← 값이 변동되므로 let로 변수 선언

let lunchMenuList = ref([]); ← 값에 ref() 함수를 적용하여 반응형 상태가 되도록 함

Composition API에서는 반응형 상태를 선언하는 ref() 함수입니다. → 반응성
(https://ko.vuejs.org/guide/essentials/reactivity-fundamentals#ref)

2. <template>에서 lunchMenuList가 있는지 없는지에 따라 블록을 렌더링 합니다.

<template>
    <div>점심 메뉴 리스트</div>
    <div v-if="lunchMenuList.length == 0">
        점심 메뉴가 없습니다.
    </div>
    <div v-else>
        점심 메뉴가 {{ lunchMenuList.length }} 개 있습니다.
    </div>
</template>

Directive(디렉티브) : 지시문으로 <template>에서 v- 접두사가 붙어 사용되는 속성입니다.

v-if는 조건이 true일 때 블록을 렌더링 합니다. → 조건부 렌더링

v-else는 v-if에 대한 else 블록입니다.

블록은 태그입니다. 시작 태그와 종료 태그가 한 블록입니다.

{{ }}(Mustache, 머스테치, 이중 괄호)는 데이터를 DOM에 바인딩합니다. → 보간(Interpolation)법(중간에 무언가를 끼워 넣다)

조건부로 블록을 렌더링합니다.
(https://ko.vuejs.org/guide/essentials/conditional.html)

텍스트 보간법
(https://ko.vuejs.org/guide/essentials/template-syntax#text-interpolation)

3. axios의 get() 함수를 사용하여 APIServer에서 점심 메뉴 리스트를 받아서 lunchMenuList에 적용하는 getLunchMenuList() 함수를 생성하고 컴포넌트에서 사용할 수 있게 리턴합니다.

<script>
import { ref } from 'vue';
import axios from 'axios';

export default {
    name : 'LunchMenuListView',
    setup() {
        let lunchMenuList = ref([]);

        function getLunchMenuList() {
            axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/").then((res) => {
                lunchMenuList.value = res.data.data;
            }).catch((err) => {
                console.log(err);
            });
        }

        return {
            lunchMenuList, getLunchMenuList
        }
    }
}
</script>

setup()안에서 ref() 함수로 작용된 값에 접근할 때는 value로 속성을 사용해야 합니다.

Ref()는 반응형 ref 객체를 반환합니다. Ref 객체 안에는 단일 속성으로 value가 있습니다. value 속성에 값이 있습니다.

axios의 get() 함수는 HTTP GET 메서드로 요청합니다. ← 비동기

then() 메서드는 요청(HTTP Request)에 대한 응답(HTTP Response)이 성공하면 들어오는 메서드로 callback function를 호출합니다. 파라미터는 응답 객체입니다. "response"이나 "res"로 사용합니다.

catch() 메서드는 요청(HTTP Request)에 대한 응답(HTTP Response)이 실패하면 들어오는 메서드로 callback function를 호출합니다. 파라미터는 에러 객체입니다. "error"이나 "err"로 사용합니다.

then() 메서드와 catch() 메서드에서 function를 직접 사용해서 처리하면 됩니다.

then(function(res) {

})

또는 화살표 함수(arrow function)를 사용할 수 있습니다.

then((res) => {

})

비동기 처리

function getLunchMenuList() {
    axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/").then((res) => {
        lunchMenuList.value = res.data.data;
    }).catch((err) => {
        console.log(err);
    });
}

동기 처리

async function getLunchMenuList() {
    try {
        const result = await axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/");
        lunchMenuList.value = result.data.data;
    } catch(err) {
        console.log(err);
    }
}

axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/")의 결과 값

{
    "data": {
        "result": "success",
        "code": 200,
        "message": "데이터가 조회되었습니다.",
        "data": [
            {
                "seq": 3,
                "menu_name": "볶음밥",
                "reg_dtm": "2025-01-17 13:37:26"
            },
            {
                "seq": 2,
                "menu_name": "짬봉",
                "reg_dtm": "2025-01-17 13:37:14"
            },
            {
                "seq": 1,
                "menu_name": "자장면",
                "reg_dtm": "2025-01-17 13:37:00"
            }
        ]
    },
    "status": 200,
    "statusText": "OK",
    "headers": {
        "content-length": "283",
        "content-type": "application/json; charset=utf-8"
    },
    "config": {
        "transitional": {
        "transitional": {
            "silentJSONParsing": true,
            "forcedJSONParsing": true,
            "clarifyTimeoutError": false
        },
        "adapter": [
            "xhr",
            "http",
            "fetch"
        ],
        "transformRequest": [
            null
        ],
        "transformResponse": [
            null
        ],
        "timeout": 0,
        "xsrfCookieName": "XSRF-TOKEN",
        "xsrfHeaderName": "X-XSRF-TOKEN",
        "maxContentLength": -1,
        "maxBodyLength": -1,
        "env": {},
        "headers": {
            "Accept": "application/json, text/plain, */*"
        },
        "method": "get",
        "url": "http://127.0.0.1:9000/api/v1/lunchmenus/"
    },
    "request": {}
}

4. 컴포넌트가 로딩이 완료된 후 점심 메뉴 리스트를 가져오는 함수를 호출하기 위해 <script>에 mounted() 함수를 추가하고 setup에 있는 getLunchMenuList() 함수가 실행되게 합니다.

<script>
import { ref } from 'vue';
import axios from 'axios';

export default {
    setup() {
        :
    },
    mounted() {
        this.getLunchMenuList();
    }
}
</script>

컴포넌트가 마운트 되면 mounted() 훅이 실행됩니다. → 생명주기 훅

setup()에서 리턴 되는 변수는 this(컴포넌트 인스턴스)에 노출됩니다:

생명주기 훅 등록 – mounted 등록
(https://ko.vuejs.org/guide/essentials/lifecycle#registering-lifecycle-hooks)

Composition API (컴포지션 API)에서 setup() 함수를 <script setup>으로 단순화 할 수 있습니다.

<script setup>
import { ref, onMounted } from 'vue';
import axios from 'axios';

let lunchMenuList = ref([]);

function getLunchMenuList() {
    axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/").then((res) => {
        console.log(res);
        lunchMenuList.value = res.data.data;
    }).catch((err) => {
        console.log(err);
    });
}

onMounted(()=>{
    getLunchMenuList();
});
</script>

setup() 밖에서 사용된 mounted를 setup()에서 사용할 수 있습니다. → onMounted()
(https://ko.vuejs.org/api/composition-api-lifecycle#onmounted)

Options API (옵션 API)로 작성할 수 있습니다.

<script>
import axios from 'axios';

export default {
    name : 'LunchMenuListView',
    data() {
        return {
            lunchMenuList : []
        }
    },
    methods : {
        async getLunchMenuList() {
            try {
                const result = await axios.get("http://127.0.0.1:9000/api/v1/lunchmenus/");
                console.log(result);
                this.lunchMenuList = result.data.data;
            } catch(err) {
                console.log(err);
            }
        }
    },
    mounted() {
        this.getLunchMenuList();
    }
}
</script>

setup()에서 사용한 변수와 함수는 Options API에서는 data와 methods로 분리됩니다.

5. lunchMenuList 수 만큼 반복하여 <li>가 생성되게 합니다.

<template>
    <div>점심 메뉴 리스트</div>
    <div v-if="lunchMenuList.length == 0">
        점심 메뉴가 없습니다.
    </div>
    <div v-else>
        점심 메뉴가 {{ lunchMenuList.length }} 개 있습니다.
        <ul class="menu-list">
            <li class="menu-item" v-for="(lunchMenuItem, index) in lunchMenuList" :key="index">
                {{ lunchMenuItem.menu_name }}
            </li>
        </ul>
    </div>
</template>

v-for는 배열을 기반으로 블록을 렌더링 합니다. → 리스트 렌더링

Vue가 각 노드의 ID를 추적하고 기존 엘리먼트를 재사용하고 재정렬할 수 있도록 힌트를 제공하려면 각 항목에 대해 특수 속성 key를 고유한 값으로 제공해야 합니다.

:key는 v-bind:key를 단축한 겁니다. key는 속성입니다. v-bind는 속성 값에 변수를 바인딩해줍니다.  속성 바인딩 (속성에서는 이중 괄호를 사용할 수 없습니다.)

배열을 리스트로 렌더링합니다.
(https://ko.vuejs.org/guide/essentials/list)

6. 스타일을 적용하기 위하여 <style>에 CSS를 추가합니다.

<style>
.menu-list {
    width: 500px;
    margin: 10px auto;
    padding: 0;
}
.menu-item {
    list-style: none;
    padding: 10px 10px;
    background-color: #0a4171;
    color: white;
    margin: 4px 0px;
    cursor: pointer;
}
</style>

7. 웹 브라우저에서 확인 (http://localhost:8080/lunchmenu)

[1] Backend 개발 - API Server 개발

carrotweb — Sun, 2 Aug 2026 19:16:33 +0900

APIServer 프로젝트 생성

1. toyprojects > apiserver 디렉터리 생성 (터미널에서 실행합니다.)

mkdir toyprojects; cd toyprojects; mkdir apiserver; cd apiserver; code .

2. 패키지 초기화 (터미널에서 실행합니다.)

npm init -y

3. Express.js 설치하기 (터미널에서 실행합니다.)

npm install express --save

package.json에서 dependencies 확인

4. Entry Point 파일 생성하기 (index.js 파일 생성, express를 가져와 서버를 생성)

const express = require('express');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.listen(port, () => {
    console.log(`APIServer started on port ${port}`);
});

포트를 9000으로 설정하였습니다.

Express Middleware

(https://expressjs.com/ko/guide/writing-middleware.html)

Express에서 HTTP 요청과 HTTP 응답 사이에서 수행되는 함수입니다.

Middleware는 HTTP 요청이 들어오는 순간부터 순차적으로 실행되고 다음 Middleware가 실행합니다.

(다음 Middleware은 next라는 이름의 변수로 표시됩니다. 현재 처리되는 Middleware에서 next()를 호출하지 않으면 다음 Middleware로 전달되지 않고 중지됩니다.)

Application-level middleware (애플리케이션 레벨 미들웨어)

const express = require('express')
const app = express()

const myLogger = function (req, res, next) { <--함수형 미들웨어
  console.log('LOGGED')
  next()
}

app.use(myLogger) <-- 1

app.get('/', (req, res, next) => { <-- 2
  res.send('Hello World!')
})

app.listen(3000)

5. npm으로 실행하기 위해 Script 추가 (package.json 파일을 오픈하여 "scripts"에 node 실행문을 추가)

"start": "node index.js"

6. npm으로 실행 (터미널에서 실행합니다.)

npm run start

7. 웹 브라우저에서 확인 (http://127.0.0.1:9000)

Mariadb Database, Table 생성

데이터베이스 생성 쿼리 실행

-- lunchdb Database가 있으면 삭제
DROP DATABASE IF EXISTS lunchdb;

-- lunchdb Database가 없으면 생성
CREATE DATABASE IF NOT EXISTS lunchdb;

테이블 생성 쿼리 실행

use lunchdb;

-- tb_lunch_menu table이 있으면 삭제
DROP TABLE IF EXISTS tb_lunch_menu;

-- TEST_TB table 생성
CREATE TABLE IF NOT EXISTS tb_lunch_menu (
  seq int NOT NULL AUTO_INCREMENT COMMENT '점심 메뉴 일련번호',
  menu_name varchar(100) COLLATE utf8mb4_general_ci NOT NULL COMMENT '점심 메뉴 명',
  reg_dtm datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '등록일',
  PRIMARY KEY (`seq`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='점심 메뉴’;

초기 데이터 등록 쿼리 실행

INSERT INTO tb_lunch_menu (menu_name, reg_dtm) VALUES('짜장면', '2025-01-17 13:37:00.000');
INSERT INTO tb_lunch_menu (menu_name, reg_dtm) VALUES('짬봉', '2025-01-17 13:37:14.000');
INSERT INTO tb_lunch_menu (menu_name, reg_dtm) VALUES('볶음밥', '2025-01-17 13:37:26.000');

8. DB 연동을 위한 MariaDB Connector 설치 (터미널에서 실행합니다.)

npm install mariadb --save

Connection Pools with MariaDB Connector/Node.js (Promise API)
(https://mariadb.com/docs/server/connect/programming-languages/nodejs/promise/connection-pools/)

dateStrings를 true로 설정 – 날짜를 문자열로 처리하도록 설정함 → time_zone 문제 해결
(https://mariadb.com/kb/en/node-js-connection-options/)

9. DB Connection Pool 생성 (src\db\mariadb 디렉터리 생성, connection.js 파일 생성, DB Connection Pool 생성)

const mariadb = require('mariadb');

const pool = mariadb.createPool({
    host: "127.0.0.1",
    port: 3306,
    user: "root",
    password: "kiki@2000",
    database: "lunchdb",
    connectionLimit: 10,
    dateStrings: true
});

async function getDBConnection() {
    connection = await pool.getConnection();
    return connection;
}

module.exports = getDBConnection;

password는 Mariadb를 설치할 때 입력한 password로 입력하세요.

10. 점심 메뉴 API 개발 (src 디렉터리에서 api\v1 디렉터리 생성, lunchmenu.js 파일 생성)

const express  = require('express');
const router = express.Router();
const getDBConnection = require('../../db/mariadb/connection');

// 전체 점심 메뉴 리스트를 리턴합니다.
router.get('/', async function(req, res, next) {
    console.log("REST API Get Method - Read All Lunch Menu.");

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: []
    }

    const query = "SELECT * FROM tb_lunch_menu ORDER BY REG_DTM DESC";
    
    let conn;
    try {
        conn = await getDBConnection();
        data = await conn.query(query, []);
        if (data.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            result.message = "데이터가 조회되었습니다.";
            result.data = data;
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
        console.log(error);
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

// 점심 메뉴 번호로 검색하여 점심 메뉴를 리턴합니다.
router.get('/:no', async function(req, res, next) {
    console.log(`REST API Get Method - Read Lunch Menu ${req.params.no}.`);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    }

    const query = "SELECT * FROM tb_lunch_menu WHERE seq = ?";

    let conn;
    try {
        conn = await getDBConnection();
        data = await conn.query(query, [req.params.no]);
        if (data.length == 0) {
            result.message = "데이터가 없습니다.";
        } else {
            result.message = "데이터가 조회되었습니다.";
            result.data = data[0];
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
        console.log(error);
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

// 점심 메뉴를 등록합니다.
router.post('/', async function(req, res, next) {
    console.log("REST API Post Method - Create Lunch Menu.");
    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    }

    if (req.body.menuName == undefined || req.body.menuName == "") {
        result.result = "fail";
        result.code = 400;
        result.message = "menuName이 없습니다."
        res.status(result.code).json(result);
        return;
    }

    const query = "INSERT INTO tb_lunch_menu (menu_name) VALUES(?)";

    let conn;
    try {
        conn = await getDBConnection();
        data = await conn.query(query, [req.body.menuName]);
        // OkPacket { affectedRows: 1, insertId: 4n, warningStatus: 0 }
        if (data.affectedRows == 1) {
            result.message = "데이터가 등록되었습니다.";
        } else {
            result.message = "데이터가 등록되지 않았습니다.";
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
        console.log(error);
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

// 점심 메뉴를 수정합니다.
router.put('/:no', async function(req, res, next) {
    console.log(`REST API Put Method - Update Lunch Menu ${req.params.no}.`);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    }

    if (req.body.menuName == undefined || req.body.menuName == "") {
        result.result = "fail";
        result.code = 400;
        result.message = "menuName이 없습니다."
        res.status(result.code).json(result);
        return;
    }
    const query = "UPDATE tb_lunch_menu SET menu_name = ? WHERE seq = ?";
    
    let conn;
    try {
        conn = await getDBConnection();
        data = await conn.query(query, [req.body.menuName, req.params.no]);
        // OkPacket { affectedRows: 1, insertId: 0n, warningStatus: 0 }
        if (data.affectedRows == 1) {
            result.message = "데이터가 수정되었습니다.";
        } else {
            result.message = "데이터가 수정되지 않았습니다.";
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
        console.log(error);
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

// 점심 메뉴를 삭제제합니다.
router.delete('/:no', async function(req, res, next) {
    console.log(`REST API Delete Method - Delete Lunch Menu ${req.params.no}.`);

    const result = {
        result: 'success',
        code: 200,
        message: '',
        data: {}
    }

    const query = "DELETE FROM tb_lunch_menu WHERE seq = ?";
    
    let conn;
    try {
        conn = await getDBConnection();
        data = await conn.query(query, [req.params.no]);
        // OkPacket { affectedRows: 1, insertId: 0n, warningStatus: 0 }
        if (data.affectedRows == 1) {
            result.message = "데이터가 삭제되었습니다.";
        } else {
            result.message = "데이터가 삭제되지 않았습니다.";
        }
    } catch (error) {
        result.result = "fail";
        result.code = 500;
        if (error.code == "ER_NO_SUCH_TABLE") {
            result.message = "테이블이 없습니다.";
        } else {
            result.message = "서버 오류가 발생하였습니다.";
        }
        console.log(error);
    } finally {
        if (conn) {
            conn.release();
        }
    }

    res.status(result.code).json(result);
});

module.exports = router;

11. index.js 파일에 BODY를 JSON 데이터로 변환, URL 인코딩, 요청 리소스 허용 처리

const express = require('express');
const app = express();
const port = 9000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

// Request의 내용(body)을 JSON 데이터로 변화해서 사용할 수 설정
app.use(express.json());
// express.urlencoded() 메서드를 이용하여 URL를 인코딩 할 수 있게 설정
app.use(express.urlencoded({extended:false}));
// 모든 리소스에 접근 허용 - CORS(Cross-origin resource sharing, 교차 출처 리소스 공유) 문제 해결
// GET, POST, PUT, DELETE 메서드 사용 허용
// content-type 요청 허용
app.use(function (req, res, next) {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
    res.header('Access-Control-Allow-Headers', 'content-type');
    next();
});

// 점심 메뉴 연결
app.use('/api/v1/lunchmenus', require('./src/api/v1/lunchmenu'));

app.listen(port, () => {
    console.log(`APIServer started on port ${port}`);
});

12. 웹 브라우저에서 확인 (http://127.0.0.1:9000/api/v1/lunchmenus)

점심 메뉴 API 테스트 (POSTMAN에서 확인)

1. 전체 점심 메뉴 조회

2. 점심 메뉴 번호로 조회

3. 점심 메뉴 등록

4. 점심 메뉴 번호로 수정

5. 점심 메뉴 번호로 삭제

LangChain – Advanced RAG, Post-Retrieval, Reranker

carrotweb — Thu, 30 Jul 2026 19:47:10 +0900

Reranker (리랭커)

벡터 스토어에서 검색된 문서(청크)가 사용자의 의도를 정확히 반영하지 못하거나 대화의 맥락을 놓칠 수 있기 때문에 사용자 질문과 관련이 높은 문서(청크)로 순위를 재정렬합니다. (프롬프트가 길어지면 중간에 위치한 중요한 정보를 LLM이 제대로 반영하지 못하는 ‘Lost in the Middle’ 현상이 발생할 위험이 있습니다. - https://arxiv.org/pdf/2307.03172)

Retriever (검색) : 벡터 스토어에서 질문과 관련성(유사도 계산) 있는 문서(청크)들을 빠르게 추출합니다.
Reranker (순위 재정렬) : 문서(청크)들을 분석(의미적 분석)하여 순위를 조정합니다.
Compression (압축) : 전체 문서(청크)를 LLM에 전달하면 비용이 많이 드는 문제점을 해결하기 위해서 압축합니다.

장점

정확도 증가 : 질문과 검색된 문서(청크)를 의미적 관계로 분석하여 더 적합한 문서(청크)로 재정렬하여 더 정확한 결과를 제공합니다.

단점

처리 시간 증가 : 복잡한 연산으로 처리 시간이 길어집니다.

Reranking – Cross Encoder Reranker

Bi-Encoder (단일 인코더) vs Cross Encoder (교차 인코더)

Bi-Encoder 방식은 질의와 문서를 각각 독립적으로 임베딩한 후, 두 임베딩 벡터 간의 유사도를 통해 문서를 평가하는 방식입니다.

Cross-Encoder는 모든 질의-문서 쌍을 개별적으로 모델이 계산해야 평가하는 방식입니다. (처리 속도가 느립니다.)

Bi-Encoder 기반의 벡터 검색이 추출한 후보 문서(상위 K개 이하)를 대상으로 2차적으로 리랭킹할 때 사용됩니다.

Cross Encoder Reranker

교차 인코더 모델을 구현한 Hugging Face 모델(예: BAAI/bge-reranker-base)를 사용하여 리트리버에서 리랭커를 구현하는 방법을 보여줍니다.

SagemakerEndpointCrossEncoder를 사용하면 Sagemaker에 로드된 HuggingFace 모델을 사용할 수 있습니다.

Reranking하기

BAAI/bge-reranker-base (https://huggingface.co/BAAI/bge-reranker-base)

bge-m3 모델(BAAI(Beijing Academy of Artificial Intelligence)에서 개발한 최신 임베딩 모델)를 기반으로 한 리랭커 모델입니다.

BAAI/bge-reranker-v2-m3 (https://huggingface.co/BAAI/bge-reranker-v2-m3)

bge-m3 모델(BAAI(Beijing Academy of Artificial Intelligence)에서 개발한 최신 임베딩 모델)를 기반으로 한 다국어 리랭커 모델입니다.

1. project3에 QnA3.ipynb 파일에 크로스 인코더 테스트 코드를 추가합니다.

[Code]
from langchain_community.cross_encoders import HuggingFaceCrossEncoder
 
# Reranker
reranker = HuggingFaceCrossEncoder(
    model_name='BAAI/bge-reranker-v2-m3',
    model_kwargs = {'device': 'cpu'}
)

[Code]
text1 = "중학생의 수학 기초학력 미달률은?"
text2 = "중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며"
text3 = "수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황"

similar_score_1 = reranker.score([text1, text2])
similar_score_2 = reranker.score([text1, text3])
print(similar_score_1, similar_score_2)

2. 크로스 인코더 테스트 코드를 실행합니다.

3. project3에 QnA3.ipynb 파일에 검색 결과 순위 재정렬 코드를 추가합니다.

[Code]
from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import CrossEncoderReranker

compressor = CrossEncoderReranker(model=reranker, top_n=3)

compression_retriever = ContextualCompressionRetriever(
    base_compressor=compressor, base_retriever=retriever
)

question = "중학생의 수학 기초학력 미달률은?"

compressed_docs = compression_retriever.invoke(question)
print(compressed_docs)

4. 검색 결과 순위 재정렬 코드를 실행합니다.

검색 결과 순서 재정렬 결과입니다.

[BAAI/bge-reranker-base를 사용할 경우]

[BAAI/bge-reranker-v2-m3를 사용할 경우]

[Document(id='fb8315b4-483c-4763-b361-af94b8e80ce0', metadata={'source': 'data/test.txt'}, page_content='교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학'), Document(id='6dcbfe08-1013-45d4-8d20-fcdbaae62393', metadata={'source': 'data/test.txt'}, page_content='8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.'), Document(id='2790ef3b-dab5-4a0e-8595-c054b6cdce53', metadata={'source': 'data/test.txt'}, page_content='이번 기획전에서는 AI 수학 학습 플랫폼 ‘매쓰홀릭 T’, AI 영어 학습 솔루션 ‘원아워’, 국어 문해력 학습 프로그램 ‘리드포스쿨’ 등 기초 학력 향상에 특화된 에듀테크')]

한국어 Reranker 사용하기

Dongjin-kr/ko-reranker (https://huggingface.co/Dongjin-kr/ko-reranker)

1. project3에 QnA3.ipynb 파일에 검색 결과 순위 재정렬 코드를 추가합니다.

[Code]
from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import CrossEncoderReranker
from langchain_community.cross_encoders import HuggingFaceCrossEncoder

# 교차 인코더 리랭커
cross_encoder_model = HuggingFaceCrossEncoder(model_name="Dongjin-kr/ko-reranker")

compressor = CrossEncoderReranker(model=cross_encoder_model, top_n=3)

compression_retriever = ContextualCompressionRetriever(
    base_compressor=compressor, base_retriever=retriever
)

question = "중학생의 수학 기초학력 미달률은?"

compressed_docs = compression_retriever.invoke(question)

print(compressed_docs)

2. 검색 결과 순위 재정렬 코드를 실행합니다.

검색 결과 순서 재정렬 결과입니다.

크로스 인코더의 스코어로 사용하여 순서 재정렬하기

1. project3에 QnA3.ipynb 파일에 크로스 인코더의 스코어로 사용하여 리랭커 코드를 추가합니다.

[Code]
question = "중학생의 수학 기초학력 미달률은?"

# 스코어
idx = 0
for text in result_texts:
    similar_score = reranker.score([question, text.page_content])
    text.metadata['score'] = similar_score
    if similar_score < 0.5:
        del result_texts[idx]
    #print(idx, text.metadata['score'], text.page_content)
    idx += 1

# 재정렬 (내림차순)
sorted_result_texts = sorted(result_texts, key=lambda item: item.metadata['score'], reverse=True)

for text in sorted_result_texts:
    print(text.metadata['score'], text.page_content)

2. 크로스 인코더의 스코어로 사용하여 리랭커 코드를 실행합니다.

FlashRank Reranker

FlashRank(프랭크 랭크)는 기존 검색과 리트리벌 파이프라인에 순위 재정렬(Reranking) 기능을 추가하는 초경량 & 초고속 파이썬 라이브러리입니다.

SoTA(State-of-the-Art) 크로스 인코더를 기반으로 합니다.

1. project3에 QnA3.ipynb 파일에 검색 결과 순위 재정렬 코드를 추가합니다.

[Markdown]
검색 결과 재순위(Re-ranking)

[Code]
%pip install flashrank

[Code]
from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import FlashrankRerank

# 플래시 링크
compressor = FlashrankRerank(model="ms-marco-MultiBERT-L-12", top_n=3)

compression_retriever = ContextualCompressionRetriever(
    base_compressor=compressor, base_retriever=retriever
)

question = "중학생의 수학 기초학력 미달률은?"

compressed_docs = compression_retriever.invoke(question)

print(compressed_docs)

2. 첫번째 [Code]를 실행하여 flashrank를 설치합니다.

설치 후 비로 실행하면 오류가 발생합니다. VSCode를 재시작해야 합니다.

3. 검색 결과 순위 재정렬 코드를 실행합니다.

검색 결과 순서 재정렬 결과입니다.

[Document(metadata={'id': 3, 'relevance_score': np.float32(0.9995719), 'source': 'data/test.txt'}, page_content='기초 학력 향상에 특화된 에듀테크 솔루션을 특별 할인가로 제공한다.'), Document(metadata={'id': 4, 'relevance_score': np.float32(0.99949664), 'source': 'data/test.txt'}, page_content='이번 기획전에서는 AI 수학 학습 플랫폼 ‘매쓰홀릭 T’, AI 영어 학습 솔루션 ‘원아워’, 국어 문해력 학습 프로그램 ‘리드포스쿨’ 등 기초 학력 향상에 특화된 에듀테크'), Document(metadata={'id': 2, 'relevance_score': np.float32(0.9993681), 'source': 'data/test.txt'}, page_content='테크빌교육 체더스, 기초학력 부진 해결을 위한 코스웨어 기획전 진행')]

하지만 하위 순위가 더 적합합니다.

[Document(metadata={'id': 0, 'relevance_score': np.float32(0.99928063), 'source': 'data/test.txt'}, page_content='교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학'), Document(metadata={'id': 1, 'relevance_score': np.float32(0.9986457), 'source': 'data/test.txt'}, page_content='8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.')]

검색 결과에 대한 순서 재정렬이 항상 적합하지 않을 수 있습니다.

모델에 따라 다르니 모델 테스트를 통해 사용하시길 바랍니다.

LangChain – Advanced RAG, Post-Retrieval, ContextualCompressionRetriever

carrotweb — Thu, 30 Jul 2026 19:22:25 +0900

질문에 대한 데이터를 검색하면 질문과 관련된 많은 문서(청크)가 검색될 수 있습니다.

유료 LLM를 사용할 경우 검색된 많은 문서(청크)를 그대로 사용하면 많은 비용이 발생하게 됩니다.

그래서 검색된 많은 문서(청크)를 그대로 사용하지 않고 질문의 맥락에 맞게 검색된 문서(청크)를 압축하여 사용하면 비용을 줄 일 수 있습니다.

Advanced RAG – Post-Retrieval

ContextualCompressionRetriever (문맥 압축 검색기)

기본 리트리버를 래핑하고 결과를 압축하는 리트리버입니다.

LLMChainExtractor (LLM 체인 추출기)

LLM 체인을 사용하여 문서(청크)에서 관련 부분을 추출합니다.

project3에 QnA3.ipynb 파일에 검색 결과 압축 코드를 추가합니다.

[Code]
from langchain.retrievers import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import LLMChainExtractor

# LLM 체인 추출기
compressor = LLMChainExtractor.from_llm(model)

# 문맥 압축 검색기
compression_retriever = ContextualCompressionRetriever(
    base_compressor=compressor, base_retriever=retriever
)

compressed_docs = compression_retriever.invoke("중학생의 수학 기초학력 미달률은?")
print(compressed_docs)

검색된 문서(청크)입니다.

교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학
8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.
테크빌교육 체더스, 기초학력 부진 해결을 위한 코스웨어 기획전 진행
기초 학력 향상에 특화된 에듀테크 솔루션을 특별 할인가로 제공한다.이번 기획전에서는 AI 수학 학습 플랫폼 ‘매쓰홀릭 T’, AI 영어 학습 솔루션 ‘원아워’, 국어 문해력 학습 프로그램 ‘리드포스쿨’ 등 기초 학력 향상에 특화된 에듀테크

검색된 문서(청크)를 압축한 결과입니다.

[gpt-4o-mini를 사용한 경우]

[Document(metadata={'source': 'data/test.txt'}, page_content='중학생의 기초학력 미달률은 9.1%, 수학 13.0%였으며'), Document(metadata={'source': 'data/test.txt'}, page_content='수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.')]

[exaone3.5:7.8b를 사용한 경우]

[Document(metadata={'source': 'data/test.txt'}, page_content='중학생의 기초학력 미달률은 9.1%, 수학은 13.0%였습니다. \n\n*Note: The extracted part directly addresses the question regarding the middle school mathematics foundational achievement rate while keeping the provided context intact.*'), Document(metadata={'source': 'data/test.txt'}, page_content='수학 16.6%')]
참고: 발췌한 부분은 제공된 맥락을 그대로 유지하면서 중학교 수학 기초 성취도에 대한 질문을 직접 다루고 있습니다.

한국어 LLM 사용시 ContextualCompressionRetriever 대신 프롬프트를 이용하여 추출하기

1. project3에 QnA3.ipynb 파일에 프롬프트로 추출하는 코드를 추가합니다.

[Code]
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 프롬프트 (한국어)
prompt_template = PromptTemplate.from_template(
"""다음은 입력 문장과 여러 개의 보기 문장입니다.
입력 문장과 의미가 유사하거나 거의 같은 내용을 가진 보기 문장을 **그대로** 추출하세요.  
추론하거나 새로운 문장을 생성하지 말고, 보기 문장 중 유사한 문장을 **있는 그대로** 출력하세요.  

### 입력 문장:
{question}

### 보기 문장:
{context}

### 출력 형식:
보기 문장 그대로 출력하세요.
부가 설명은 추가하지 마세요.
"""
)

texts = "\n\n".join(result_text.page_content for result_text in result_texts)

question = "중학생의 수학 기초학력 미달률은?"

chain = (
    prompt_template
    | model
    | StrOutputParser()
)

response = chain.invoke({"context": texts, "question": question})
print(response)

2. 프롬프트로 추출하는 코드를 실행합니다.

검색 결과 압축 실행 결과입니다.

[exaone3.5:7.8b를 사용한 경우]

교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학 16.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.

LangChain – Advanced RAG, Pre-Retrieval(한국어 LLM 사용)

carrotweb — Thu, 30 Jul 2026 18:23:21 +0900

이번에는 한국어 LLM인 exaone3.5:7.8b를 사용하여 답변을 생성해보고 MultiQueryRetriever에 적용해보겠습니다.

Exaone 3.5 (https://www.lgresearch.ai/exaone)

현배 버전은 4.5입니다.

Ollama에서 Exaone 3.5 다운로드 하기
1. Ollama Models Search (https://ollama.com/search?q=exaone) 에서 Exaone 3.5를 검색합니다.

Exaone 3.5(https://ollama.com/library/exaone3.5)를 클릭하면 다양한 모델이 있습니다.
PC에서 사용할거라 용량이 작은 모델인 Exaone 3.5를 사용할 겁니다.

exaone3.5:7.8b를 클릭하면 모델에 대한 정보를 확인할 수 있습니다.

2. 콘솔에서 ollama pull 명령어를 사용하여 exaone3.5:7.8b를 다운로드합니다.

ollama pull exaone3.5:7.8b

콘솔에서 ollama list 명령어를 사용하여 다운로드된 모델들을 확인할 수 있습니다.

Generation (생성) – LLM (답변 생성)

1. project3에 QnA3.ipynb 파일에 Exaone으로 실행 코드를 추가합니다.

[Code]
from langchain_ollama import ChatOllama

model = ChatOllama(
    model="exaone3.5:7.8b",
    temperature=0
)

[Code]
from langchain import hub

prompt = hub.pull("rlm/rag-prompt")
print(prompt)

[Code]
retriever = loaded_vector_store.as_retriever(search_kwargs={"k": 5})

result_texts = retriever.invoke("중학생의 수학 기초학력 미달률은?")
print(result_texts)

[Code]
from langchain_core.output_parsers import StrOutputParser

texts = "\n\n".join(result_text.page_content for result_text in result_texts)

chain = prompt | model | StrOutputParser()
response = chain.invoke({"context" : texts, "question": "중학생의 수학 기초학력 미달률은?"})
print(response)

2. Exaone으로 실행 코드를 실행합니다.

Ollama 프롬프트 실행 결과입니다.

중학생의 수학 기초학력 미달률은 13.0%입니다. 이는 전체 기초학력 미달률 중 수학 분야에서 가장 높은 비율을 보입니다. 학습 격차 해소를 위한 추가적인 지원이 필요한 상황입니다.

Context가 없을 경우 실행 결과입니다.

제공된 맥락에는 중학생의 수학 기초학력 미달률에 대한 구체적인 통계나 데이터가 포함되어 있지 않습니다. 정확한 비율을 말씀드리기 위해서는 해당 연도와 지역의 공식 교육 통계 자료가 필요합니다. 따라서 현재 정보로는 해당률을 알려드리지 못합니다.

만약, Exaone3.5:32b를 다운로드하여 사용하고자 할 경우에는 시스템 사양이 낮을 경우 응답시간이 느려 사용할 수 없습니다.

용량이 크기 때문에 작동이 되지 않습니다.

그럴 경우, 시스템 속성(Windows + R)에서 가상메모리의 페이징 파일 크기를 변경하시면 사용이 가능합니다.

한국어 LLM 사용시 Multi-Query Retriever의 문제점

한국어 LLM를 Multi-Query Retriever에 사용할 경우에 문제점있습니다.

1. project3에 QnA3.ipynb 파일에 테스트 실행 코드를 추가합니다.

[Code]
question = "대출?"

result_texts = multi_query_retriever.invoke(input=question)
result_texts

2. 테스트 실행 코드를 실행합니다.

Multi-Query Retriever가 생성한 질문이 영문으로 생성되는 문제점있습니다.

INFO:langchain.retrievers.multi_query:Generated queries: ['1. What loan options are available for borrowers with my current financial profile?', '2. Could you recommend details on loan terms and interest rates for similar financial situations?', '3. How do different loan products compare in terms of eligibility criteria and repayment options?']

[번역]

1. 현재 제 재정 상황에 맞는 대출 옵션은 무엇인가요?

2. 비슷한 재정 상황에 맞는 대출 조건과 금리를 자세히 설명해 주시겠어요?

3. 자격 기준과 상환 옵션 측면에서 다양한 대출 상품을 비교하면 어떤가요?

프롬프트를 이용하여 한글 질문 생성하기

1. project3에 QnA3.ipynb 파일에 테스트 실행 코드를 추가합니다.

[Code]
from langchain_core.prompts import PromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# 프롬프트 (영어)
prompt_template = PromptTemplate.from_template(
"""You are an AI language model assistant. 
Your task is to generate three different versions of the given user question to retrieve relevant documents from a vector database. 
By generating multiple perspectives on the user question, your goal is to help the user overcome some of the limitations of the distance-based similarity search. 
Your response should be a list of values separated by new lines

#ORIGINAL QUESTION: 
{question}

#Answer in Korean:
"""
)

question = "대출?"

#chain = prompt | model | StrOutputParser()

#response = chain.invoke({"question": question})
#print(response)

chain = (
    {"question": RunnablePassthrough()}
    | prompt_template
    | model
    | StrOutputParser()
)

response = chain.invoke(question)
response

RunnablePassthrough() 는 데이터를 전달하는 역할을 합니다. invoke() 메서드를 통해 입력된 데이터를 그대로 반환 합니다.

2. 테스트 실행 코드를 실행합니다.

프롬프트가 생성한 결과입니다.

'대출 관련 정보 찾기 \n대출 조건 문의 \n금융 대출 옵션 탐색'

프롬프트가 한글이면 좀 더 나은 질문을 생성할 수 있습니다.

3. 프롬프트를 한글로 변경합니다.

[Code]
from langchain_core.prompts import PromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# 프롬프트 (한국어)
prompt_template = PromptTemplate.from_template(
"""당신은 AI 언어 모델 어시스턴트입니다.
당신의 임무는 주어진 사용자 질문의 세 가지 다른 버전을 생성하여 벡터 데이터베이스에서 관련 문서를 검색하는 것입니다.
사용자 질문에 대한 다양한 관점을 생성함으로써, 사용자가 거리 기반 유사도 검색의 한계를 극복하도록 돕는 것이 당신의 목표입니다.

너의 응답 결과는 줄바꿈으로 구분하여 리스트로 제공합니다.

#원본 질문
{question}
"""
)

question = "대출?"
chain = (
    {"question": RunnablePassthrough()}
    | prompt_template
    | model
    | StrOutputParser()
)
response = chain.invoke(question)
response

4. 테스트 실행 코드를 실행합니다.

프롬프트가 생성한 결과입니다.

'```\n# 버전 1\n대출 조건과 이자율에 대해 자세히 알려주시겠어요?\n\n# 버전 2\n현재 이용 가능한 대출 상품의 종류와 장단점은 무엇인가요?\n\n# 버전 3\n대출 신청 과정과 필요 서류는 무엇인가요? \n```'

LangChain – Advanced RAG, Pre-Retrieval

carrotweb — Thu, 30 Jul 2026 17:07:25 +0900

이전까지 개발한 RAG를 Navie RAG라고 합니다. 지금부터 좀더 업그레이드된 RAG인 Advanced RAG를 개발해보겠습니다.

Advanced RAG(Retrieval-Augmented Generation)

Naive RAG의 검색 기능을 개선하고 텍스트 처리 기술을 도입하여 RAG 성능을 향상시킨 모델입니다.

즉, Retrieve(검색) 품질을 개선하는 것입니다. 검색 품질을 개선하기 위해서 검색 전(Pre-Retrieval)과 검색 후(Post-Retrieval)를 최적화하는 것을 의미합니다.

Pre-Retrieval(사전 검색) 최적화

검색되는 문서(청크)의 질을 높이기 위해 Indexing(인덱싱)를 최적화하고 검색 결과의 질을 높이기 위해 검색 질의(Query)를 재구성(Query Rewrite, Query Expansion)하여 검색을 최적화합니다.

Post-Retrieval(사후 검색) 최적화

검색된 문서(청크)의 순서를 재정렬하여 Context를 최적화합니다. 처리 방법은 검색된 문서(청크)에 대해 의미론적 관계를 다시 계산하여 순위를 재정렬(Reranking)하고 추출한 다음 압축하여 최적화합니다.

“외부 지식”과 “모델 적응” 측면에서 모델 최적화 방법 비교 (https://arxiv.org/pdf/2312.10997)

프롬프트 엔지니어링은 모델과 외부 지식 수정을 최소화하며, LLM 자체의 역량을 활용하는데 중점을 둡니다.
미세 조정은 모델에 대한 추가 학습을 포함합니다.
Naive/Advanced RAG는 모델 수정에 대한 요구가 낮으나 연구가 진행됨에 따라 Modular RAG는 미세 조정 기술과 더욱 통합되었습니다.

Retrieval and Generation (검색과 생성)

Advanced RAG – Pre-Retrieval (사전 검색)

정확하지 않은 질문?

질문의 의도가 정확하지 않는 질문으로 인해 정확지 않은 검색 결과가 나오게 됩니다.

질문이 단순하게 "대출"이라고만 하면 무슨 의도의 질문으로 이해해서 검색을 해야 할까요?

질문이 정확하지 않기 때문에 원하는 결과가 나오지 않을 겁니다.

그렇지만 대부분의 사용자들은 간단한 질문으로 원하는 결과가 나오길 바랍니다.

우문현답(愚問賢答)

(어리석은 질문이라도 현명하게 답변한다)

"개떡같이 말해도 찰떡같이 알아듣는다.“

(자세히 설명하지 않거나, 잘못된 설명을 하여도 어떤 말인지 알아듣는다.)

Query Rewrite (쿼리 재작성)

사용자가 입력한 질문을 바로 임베딩하여 벡터 스토어에 검색하지 않고 질문을 기반으로 다양한 관점으로 질문을 재생성하여 검색하게 합니다.

LLM을 사용하여 여러 개의 유사 질문으로 재생성하여 단일 질문의 한계(부정확한 질문)를 극복하여 더 좋은 검색 결과를 얻을 수 있습니다.

Multi-Query Retriever

MultiQueryRetriever는 LLM을 사용하여 주어진 사용자 입력 쿼리에 대해 다른 관점에서 여러 쿼리를 생성함으로써 프롬프트 튜닝 프로세스를 자동화합니다.
각 쿼리에 대해 관련 있는 문서 집합을 검색하고 모든 쿼리에서 유닉 유니온(UNION과 UNION ALL)을 사용하여 잠재적으로 관련이 있는 더 많이 문서 집합을 얻습니다.
MultiQueryRetriever는 같은 질문에 대해 여러 관점을 생성함으로써 거리 기반 검색의 한계를 완화하고 더욱 풍부한 결과를 얻을 수 있습니다.

1. project3에 QnA3.ipynb 파일을 생성하고 벡터 스토어 멀티 검색 코드를 추가합니다.

[Markdown]
벡터 스토어 멀티 검색 (Faiss)

[Code]
import os
from langchain.chat_models import init_chat_model

os.environ["OPENAI_API_KEY"] = "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"

model = init_chat_model("gpt-4o-mini", model_provider="openai")

[Code]
from langchain_huggingface import HuggingFaceEmbeddings

embeddings_model = HuggingFaceEmbeddings(model_name="intfloat/multilingual-e5-large-instruct")

[Code]
from langchain_community.vectorstores import FAISS

loaded_vector_store = FAISS.load_local(
    folder_path="./faiss_db", # 저장된 디렉토리
    index_name="test_db", # 저장된 인덱스 명
    embeddings=embeddings_model, # 사용할 임베딩 모델
    allow_dangerous_deserialization=True # pickle 파일 역직렬화 허용 
)

[Code]
import logging

logging.basicConfig()
logging.getLogger("langchain.retrievers.multi_query").setLevel(logging.INFO)

[Code]
from langchain.retrievers.multi_query import MultiQueryRetriever

multi_query_retriever = MultiQueryRetriever.from_llm(
    retriever=loaded_vector_store.as_retriever(search_kwargs={"k": 5}),
    llm=model
)

question = "중학생의 수학 기초학력 미달률은?"

result_texts = multi_query_retriever.invoke(input=question)
result_texts

Python 표준 라이브러인 logging 모듈은 프로그램 실행 중 발생하는 이벤트들을 추적(기록)할 수 있도록 해줍니다.

[Code]
import logging

logging.basicConfig()
logging.getLogger("langchain.retrievers.multi_query").setLevel(logging.INFO)

로깅 모듈의 basicConfig() 함수는 루트 로거를 빠르고 편리하게 구성하는 방법을 제공합니다. 애플리케이션의 기본 로깅 기능 설정을 간소화합니다.

로그를 파일에 기록하려면 basicConfig() 함수에 filename 파라미터를 사용하여 로그 파일의 경로를 지정하면 됩니다.

basicConfig()의 기본값 Log Level(로그 레벨)은 logging.WARN 입니다.

Logger(로거)는 직접 인스턴스화해서는 안 되고 함수인 logging.getLogger(name)을 통해 인스턴스화해야 합니다.

name 파라미터에 설정된 네임스페이스(패키지(모듈) 계층 구조)에서 발생하는 이벤트들을 추적합니다.

Log Level(로그 레벨)은 로깅 메시지의 중요도나 심각도를 나타냅니다.

DEBUG(디버그 정보) > INFO(일반 정보) > WARNING(경고 메시지) > ERROR(에러 메시지) > CRITICAL(심각한 오류 메시지)

2. 벡터 스토어 멀티 검색 코드를 실행합니다.

멀티 쿼리 리트리버가 생성한 질문 결과입니다.

INFO:langchain.retrievers.multi_query:Generated queries: ['중학생들의 수학 기초 학력이 부족한 비율은 어떻게 되나요? ', '중학생을 대상으로 한 수학 기초학력 미달률에 대한 통계는 무엇이 있나요? ', '우리나라 중학생 수학 기초학력 미달률에 관한 정보는 무엇인가요?']

벡터 스토어 검색 결과입니다.

[Document(id='fb8315b4-483c-4763-b361-af94b8e80ce0', metadata={'source': 'data/test.txt'}, page_content='교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학'),
Document(id='6dcbfe08-1013-45d4-8d20-fcdbaae62393', metadata={'source': 'data/test.txt'}, page_content='8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.'),
Document(id='babccbd5-7557-4c20-85ff-46534ad2b69b', metadata={'source': 'data/test.txt'}, page_content='기초 학력 향상에 특화된 에듀테크 솔루션을 특별 할인가로 제공한다.'),
Document(id='241efdba-09b4-4e44-a74b-bcbd645eeb1e', metadata={'source': 'data/test.txt'}, page_content='테크빌교육 체더스, 기초학력 부진 해결을 위한 코스웨어 기획전 진행'),
Document(id='32fd32b1-b92d-4dd3-b03a-87d4015ab911', metadata={'source': 'data/test.txt'}, page_content='솔루션을 활용해 학생들 간의 학습 격차를 해소하는 데 도움이 되길 바란다”고 말했다.')]

랭체인 - Chat Prompt Template, LCEL(LangChain Expression Language)

carrotweb — Sun, 26 Jul 2026 18:04:56 +0900

Prompt(프롬프트)란

사용자가 대규모(초거대) 언어 모델(LLM)에게 질문이나 작업을 요청할때 사용되는 입력문입니다.

Prompt Template(프롬프트 템플릿)이란

PromptTemplate를 사용하여 프롬프트(입력문)안에 변수를 포함하여 생성한 후 동적으로 입력받은 변수 값으로 채워 넣어 프롬프트를 생성합니다.

from langchain_core.prompts import PromptTemplate

# 'role' 변수를 사용하는 프롬프트 템플릿을 정의
template = "너는 {role} 전문가로 {role} 질문에 친절하게 답변해 주십시오."

# PromptTemplate 인스턴스를 생성
promptTemplate = PromptTemplate.from_template(template)

# 템플릿에 변수 값을 채워 넣어 프롬프트를 완성
prompt = promptTemplate.format(role="천문학")

너는 천문학 전문가로 천문학 질문에 친절하게 답변해 주십시오.

Chat Prompt Template(챗 프롬프트 템플릿)이란

ChatPromptTemplate를 사용하여 LangChain Message인 SystemMessage와 HumanMessage에 변수를 포함하여 생성한 후 동적으로 입력받은 변수 값으로 채워 넣어 프롬프트를 생성합니다.

(https://python.langchain.com/docs/tutorials/llm_chain/)

Chat Prompt Template 사용하기

1. project3에 qna.py 파일을 생성합니다.

import os
from langchain.chat_models import init_chat_model
from langchain_core.prompts import ChatPromptTemplate

os.environ["OPENAI_API_KEY"] = "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"

model = init_chat_model("gpt-4o", model_provider="openai")

system_template = "너는 천문학 전문가로 천문학 질문에 친절하게 답변해 주십시오."

prompt_template = ChatPromptTemplate.from_messages([
    ("system", system_template),
    ("user", "{text}")
])

prompt = prompt_template.invoke({"text": "태양계에서 가장 큰 행성은 무엇인가요?"})

ai_msg = model.invoke(prompt)
print(ai_msg.content)

Terminal(터미널)에서 명령어를 사용하여 실행합니다.

모델 출력 결과 : 태양계에서 가장 큰 행성은 목성입니다. 목성은 직경과 질량 모두에서 다른 행성들보 다 훨씬 크며, 태양계 전체 행성 질량의 상당 부분을 차지하고 있습니다. 목성은 주로 수소와 헬륨으로 이루어진 가스 행성이며, 그 방대한 크기와 대기 조건 덕분에 여러 독특한 특징을 가지고 있습니다.

chain으로 실행하기

StrOutputParser

StrOutputParser는 모델의 출력 결과를(AIMessage 또는 AIMessageChunk)을 일반 텍스트 문자열로 변환합니다.

모델 출력 결과가 ChatModel 메시지일 경우 StrOutputParser는 메시지의 .content 속성을 추출하여 전달합니다.

(https://reference.langchain.com/python/langchain-core/output_parsers/string/StrOutputParser)

LangChain의 LCEL(LangChain Expression Language)을 사용하기

프롬프트, 언어 모델, 출력 파서를 파이프 기호(|)로 연결해 하나의 실행 가능한 작업 흐름(chain)을 만드는 구문입니다.

chain = prompt_template | model | StrOutputParser()

1. project3에 qna.py 파일을 수정합니다.

import os
from langchain.chat_models import init_chat_model
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

os.environ["OPENAI_API_KEY"] = "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"

model = init_chat_model("gpt-4o", model_provider="openai")

system_template = "너는 천문학 전문가로 천문학 질문에 친절하게 답변해 주십시오."

prompt_template = ChatPromptTemplate.from_messages([
    ("system", system_template),
    ("user", "{text}")
])

chain = prompt_template | model | StrOutputParser()
response = chain.invoke({"text": "태양계에서 가장 큰 행성은 무엇인가요?"})
print(response)

Terminal(터미널)에서 명령어를 사용하여 실행합니다.

모델 출력 결과 : 태양계에서 가장 큰 행성은 목성입니다. 목성은 지름과 부피 모두에서 가장 크고, 질량도 태양계의 다른 모든 행성을 합친 것보다 더 큽니다. 이는 목성이 주로 가스로 이루어져 있기 때문이며, 이에 따라 가스 행성이라고도 불립니다. 목성의 거대한 크기는 많은 위성들과 특유의 대기 현상을 포함한 다양한 특징을 가지고 있습니다.

랭체인 - LangChain Message (SystemMessage, HumanMessage, AIMessage)

carrotweb — Sun, 26 Jul 2026 16:58:14 +0900

LangChain Message에 대해 알아보겠습니다.

대화 메시지를 Role(역활)로 구분해보겠습니다.

첫번쩨 메시지는 Developer(개발자)가 LLM에 역화과 작업을 설명 → Task Description (작업 설명)

두번째 메시지는 User(사용자)가 LLM에게 질문

세번째 메시지는 Assistant(어시스턴트)가 User(사용자)의 질문에 대한 대답

대화 시작전에 Task Description (작업 설명)이 설명되어 있으면 LLM으로부터 좀더 정확한 결과를 받을 수 있습니다.

대화 메시지를 LangChain Message로 구분해보겠습니다.

SystemMessage : 시스템 메시지로 AI의 행동(역할이나 정보를 통한 설정)을 촉진하기 위한 메시지입니다.

HumanMessage : 인간 메시지로 AI 모델에 전달할 메시지입니다.

AIMessage : AI 메시지로 프롬프트에 대한 응답 메시지입니다. (채팅 모델에서 반환)

LangChain Message로 만들기

랭체인 사이트의 튜토리얼을 기반으로 개발하도록 하겠습니다.
작성 당시 버전은 v0.3이였습니다. 현재 v1.3과 다를 수 있습니다.

1. project3에 main.py 파일을 생성합니다.

import os
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage

os.environ["OPENAI_API_KEY"] = "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"

model = init_chat_model("gpt-4o", model_provider="openai")

messages = [
    SystemMessage(
        content="You are a helpful assistant! Your name is Bob."
    ),
    HumanMessage(
        content="What is your name?"
    )
]

ai_msg = model.invoke(messages)
print(ai_msg.content)

또는 OpenAI 모델만 전용으로 클래스인 ChatOpenAI를 사용햐도 됩니다.

import os
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

os.environ["OPENAI_API_KEY"] = "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"

llm = ChatOpenAI(
    model="gpt-4o"
)

messages = [
    SystemMessage(
        content="You are a helpful assistant! Your name is Bob."
    ),
    HumanMessage(
        content="What is your name?"
    )
]

ai_msg = llm.invoke(messages)
print(ai_msg.content)

대화 메시지 처럼 역활과 작업 설명을 해주기 위해서 SystemMessage에 "You are a helpful assistant! Your name is Bob."을 입력하고 사용자의 질문을 위해 HumanMessage에 "What is your name?"을 입력합니다.

실행하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

python main.py

결과를 AIMessage로 "My name is Bob. How can I assist you today?"가 전달됩니다.

LangChain - RAG + Ollama + Hugging Face - llama3-2-Korean

carrotweb — Sat, 25 Jul 2026 00:24:24 +0900

Hugging Face 모델을 다운로드하여 Ollama에서 사용하기

한국어가 포함되어 있는 llama-3.2-Korean Models를 사용해보겠습니다.
(https://huggingface.co/Bllossom/llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M)

1. llama-3.2-Korean Models을 다운로드합니다.
(https://huggingface.co/Bllossom/llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M/tree/main)

2. llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M.gguf 파일을 다운로드합니다.

GGUF : GPT(generative pre-trained transformer) Unified Format

3. 콘솔에서 ollama create 명령어를 사용하여 llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M를 Ollama에서 사용할 수 있게 생성합니다.

ollama create llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M

모델을 Ollama 엡에서 실행하지 않기 때문에 Modelfile은 생성하지 않았습니다.

만약, Ollama 앱에서 사용할 경우에는 다운로드 폴더에 Modelfile 파일을 생성해야 합니다.

FROM llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M.gguf

TEMPLATE """{{- if .System }}
<s>{{ .System }}</s>
{{- end }}
<s>Human:
{{ .Prompt }}</s>
<s>Assistant:
"""

SYSTEM """A chat between a curious user and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the user's questions."""

PARAMETER stop <s>
PARAMETER stop </s>

다운로드 폴더에서 콘설을 실행하여 ollama create 명령어에 Modelfile을 포함하여 실행하면 됩니다.

ollama create llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M -f Modelfile

Generation (생성) – LLM (답변 생성)

1. project3에 QnA2.ipynb 파일에 Ollama로 프롬프트 실행 코드를 수정합니다.

[Code]
from langchain_ollama import ChatOllama
from langchain_core.output_parsers import StrOutputParser

model = ChatOllama(
    model="llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M",
    temperature=0
)

texts = "\n\n".join(result_text.page_content for result_text in result_texts)

chain = prompt | model | StrOutputParser()
response = chain.invoke({"context" : texts, "question": "중학생의 수학 기초학력 미달률은?"})
print(response)

2. Ollama 프롬프트 실행 코드를 실행합니다.

Ollama 프롬프트 실행 결과입니다.

중학생의 수학 기초학력 미달률은 13.0%입니다. 이는 고등학생 수학 기초학력 미달률(16.6%)보다 낮습니다. 수학 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황입니다.

Note: The answer is based on the provided context, which mentions that 13.0% of middle school students have a low basic math level. (참고: 답변은 제공된 맥락을 기반으로 하며, 중학교 학생의 13.0%가 기초 수학 수준이 낮다는 내용을 담고 있습니다.)

Context가 없을 경우 실행 결과입니다.

중학생의 수학 기초학력 미달률은 2019년 기준으로 약 10%에 불과하다. 이는 교육부가 발표한 데이터를 바탕으로 한 것으로, 이 데이터는 2018년부터 2020년까지의 수학 기초학력을 평가한 결과다. 이 미달률은 학생들이 수학 기초 학습을 충분히 하지 못하고 있는 것을 나타낸다.

Note: The answer is based on the provided context and may not be up-to-date or accurate for current information.
If you need more recent data, please let me know. (참고: 답변은 제공된 맥락을 기반으로 하며, 최신 정보와 일치하지 않거나 정확하지 않을 수 있습니다. 더 최신 데이터가 필요하시면 알려주세요.)

LangChain - RAG + Ollama + gemma3

carrotweb — Fri, 24 Jul 2026 18:06:46 +0900

LangChain에서 Ollama 연동하기

LangChain에서 Ollama와 연동하는 방법을 제공하고 있습니다.

(https://docs.langchain.com/oss/python/integrations/providers/ollama)

Ollama를 사용하면 Llama3.1과 같은 오픈 소스 대규모 언어 모델을 로컬에서 실행할 수 있습니다.

Ollama는 모델 가중치, 구성 그리고 데이터를 Modelfile로 정의된 단일 패키지로 묶습니다. GPU 사용량을 포함한 설정 및 구성 세부 정보를 최적화합니다. 지원되는 모델 및 모델 변형의 전체 목록은 Ollama 모델 라이브러리를 참조하세요.

OllamaLLM은 LangChain에서 Ollama 모델과 상호 작용하는 방법을 설명합니다.

(https://docs.langchain.com/oss/python/integrations/llms/ollama)

Ollama 실행하기

1. project3에 QnA2.ipynb 파일에 Ollama 코드를 추가합니다.

[Markdown]
Ollama Gemma3:4b

[Code]
from langchain_community.llms import Ollama
from langchain_core.prompts import ChatPromptTemplate

model = Ollama(model="gemma3:1b")

system_template = "너는 천문학 전문가로 천문학 질문에 친절하게 답변해 주십시오."

prompt_template = ChatPromptTemplate.from_messages([
    ("system", system_template),
    ("user", "{text}")
])

prompt = prompt_template.invoke({"text": "태양계에서 가장 큰 행성은 무엇인가요?"})

response = model.invoke(prompt)
response

2. Ollama 코드를 실행합니다.

Ollama 코드 실행 결과입니다.

'안녕하세요! 천문학 전문가로서 태양계 행성에서 가장 큰 행성은 **목성**입니다. \n\n목성은 태양을 중심으로 하는 역전 운동 시스템의 중력으로 인해 엄청난 크기를 가지고 있습니다. 이는 태양의 중력에 비해 훨씬 크기 때문에, 목성은 태양계의 가장 큰 행성이 됩니다.\n\n혹시 더 궁금한 점이 있으신가요? 예를 들어, 목성의 특징이나 행성 간의 상대적인 크기 등에 대해 더 자세히 알려드릴 수 있습니다.'

Generation (생성) – LLM (답변 생성)

1. project3에 QnA2.ipynb 파일에 Ollama로 프롬프트 실행 코드를 추가합니다.

[Code]
%pip install langchain-ollama

[Code]
from langchain_ollama import ChatOllama
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

model = ChatOllama(
    model="gemma3:1b",
    temperature=0
)

texts = "\n\n".join(result_text.page_content for result_text in result_texts)

chain = prompt | model | StrOutputParser()
response = chain.invoke({"context" : texts, "question": "중학생의 수학 기초학력 미달률은?"})
print(response)

위 방식은 chain 방식입니다.

do_prompt = prompt.invoke({"context" : texts, "question": "중학생의 수학 기초학력 미달률은?"})

ai_msg = model.invoke(do_prompt)
print(ai_msg.content)

2. 첫번째 [Code]를 실행하여 langchain-ollama를 설치합니다.

3. Ollama로 프롬프트 실행 코드를 실행합니다.

Ollama 프롬프트 실행 결과입니다.

The 기초학력 미달률은 9.1%입니다. 특히 수학의 기초학력 부진이 가장 높습니다. 테크빌교육은 기초학력 향상 코스웨어 기획전을 진행하고 있습니다.

Context가 없을 경우 실행 결과입니다.

The provided context does not contain information about the math 기초학력 미달률. (제공된 컨텍스트에는 수학 기초학력 미달률에 대한 정보가 포함되어 있지 않습니다.)

Ollama에서 gemma3n 다운로드 하기
1. Ollama Models Search (https://ollama.com/library/gemma3n)에서 gemma3n를 검색합니다.

2. 콘솔에서 ollama pull 명령어를 사용하여 gemma3n:e4b를 다운로드합니다.

ollama pull gemma3n:e4b

3. project3에 QnA2.ipynb 파일에 Ollama로 프롬프트 실행 코드를 수정합니다.

[Code]
from langchain_ollama import ChatOllama
from langchain_core.output_parsers import StrOutputParser

model = ChatOllama(
    model="gemma3n:e4b",
    temperature=0
)

texts = "\n\n".join(result_text.page_content for result_text in result_texts)

chain = prompt | model | StrOutputParser()
response = chain.invoke({"context" : texts, "question": "중학생의 수학 기초학력 미달률은?"})
print(response)

4. Ollama로 프롬프트 실행 코드를 실행합니다.

Ollama 프롬프트 실행 결과입니다.

교육부의 '2023 국가수준 학업성취도평가' 결과, 중학생의 수학 기초학력 미달률은 13.0%로 나타났습니다. 이는 영어 6.0%보다 높은 수치이며, 특히 수학의 기초학력 부진이 심각한 상황입니다. 따라서 학습 격차 해소를 위한 지원이 필요합니다.

Context가 없을 경우 실행 결과입니다.

I am sorry, but I cannot answer the question about the percentage of middle school students with insufficient basic math skills. The provided context is empty, so I do not have the information needed to answer. Therefore, I don't know the answer. (죄송하지만, 중학생 중 기초 수학 능력이 부족한 학생의 비율에 대한 질문에는 답변해 드릴 수 없습니다. 제공된 정보가 부족하여 답변에 필요한 정보를 얻을 수 없습니다. 따라서 답변을 드릴 수 없습니다.)

Open Source (Local) LLM - Ollama 사용하기

carrotweb — Fri, 24 Jul 2026 17:44:13 +0900

Open Source (Local) LLM 장점과 단점

장점

보안성 : 유료 LLM(대규모(초거대) 언어 모델)를 사용하지 않기 때문에 데이터가 유출될 위험이 없습니다.
접근성 : 내부 망에 서버가 있어 외부 망과 연결하지 않아도 되고 인터넷 연결 없이도 사용이 가능합니다.
빠른 응답 : 내부 서버에서 실행되므로 처리 응답이 빠릅니다. (대기 시간이 짧아집니다.)
비용 절감 : 유료 LLM 사용료가 없습니다.
다양한 모델 사용 : 서버나 서비스에 맞게 다양한 모델을 사용할 수 있습니다.

단점

정확성의 한계 : 모델이 학습된 날짜가 오래될 경우 오래된 정보가 제공되거나 정보가 없을 수도 있습니다. (파인 튜닝 또는 관련 정보 별도 구축 후 연동)
높은 시스템 비용 : 모델에 따라 고성능 GPU와 대용량 메모리가 있는 시스템을 사용할 수 있기 때문에 서버 비용 부담이 증가될 수 있습니다.

유료 LLM(대규모(초거대) 언어 모델)을 대처할 Open Source LLM(대규모(초거대) 언어 모델) 사용

Ollama (올라마)
로컬 머신에서 LLM을 실행시켜주는 프로그램입니다.

Ollama 설치하기

1. Ollama (https://ollama.com) 사이트에 접속합니다.

2. Download Ollama (https://ollama.com/download)에서 Windows를 선택하고 다운로드를 클릭합니다.

3. 다운로드된 OllamaSetup를 실생하여 설치합니다.

Ollama 설치 위치는 C:\Users\{사용자계정}\AppData\Local\Programs\Ollama 입니다.

4. 콘솔에서 ollama를 실행하여 사용방법을 확인할 수 있습니다.

ollama

모델로 Gemma3를 사용하도록 하겠습니다. 현재는 Gemma4입니다.

Gemma (https://deepmind.google/models/gemma/)

Ollama에서 gemma3 다운로드 하기

1. Ollama Models Search (https://ollama.com/search)에서 gemma3를 검색합니다.

gemma3(https://ollama.com/library/gemma3)를 클릭하면 다양한 모델이 있습니다.

PC에서 사용할거라 용량이 작은 모델인 gemma3:1b를 사용할 겁니다.

gemma3:1b를 클릭하면 모델에 대한 정보를 확인할 수 있습니다.

2. 콘솔에서 ollama pull 명령어를 사용하여 gemma3:1b를 다운로드합니다.

ollama pull gemma3:1b

3. 콘솔에서 ollama list 명령어를 사용하여 다운로드된 모델들을 확인할 수 있습니다.

ollama list

다운로드된 모델들은 C:\Users\{사용자계정}\.ollama\models\에 저장됩니다.

Ollama에서 gemma3:1b 실행하기

1. 콘솔에서 ollama run 명령어를 사용하여 gemma3:1b를 실행합니다.

ollama run gemma3:1b

2. 다음과 같이 질문을 해보면 답을 잘 해 줍니다.

너는 천문학 전문가로 천문학 질문에 친절하게 답변해 주십시오. 태양계에서 가장 큰 행성은 무엇인가요?

Ctrl + D를 누르면 Ollama가 종료됩니다.

Ollama 실행 확인하고 종료하기

1. 콘솔에서 ollama ps 명령어를 사용하면 실행중인 모델들이 나타납니다.

ollama ps

2.콘솔에서 ollama stop 명령어를 사용하면 실행중인 모델을 중지됩니다.

ollama stop gemma3:1b

Ollama 앱 실행하기

1. 윈도우 "시작" 버튼을 클릭하고 "Ollama"를 입력하고 앱을 클릭합니다.

2. Ollama에서 gemma3:1b를 선택하고 질문하면 됩니다.

RAG App 개발 - Open Source 모델 사용

carrotweb — Thu, 23 Jul 2026 17:44:24 +0900

기존 소스에서 OpenAI 모델 대신 Hugging Face (허깅 페이스)에 있는 intfloat/multilingual-e5-large-instruct을 사용하여 임베딩을 하겠습니다.

Indexing (인덱싱) – Embed (임베드, 임베딩 모델)

1. project3에 QnA1.ipynb 파일에 텍스트 문서 임베딩 코드를 변경합니다.

[Markdown]
일반 텍스트 문서 임베딩 (huggingface)

[Code]
%pip install langchain-huggingface

[Code]
%pip install sentence-transformers

[Code]
from langchain_huggingface import HuggingFaceEmbeddings

embeddings_model = HuggingFaceEmbeddings(model_name="intfloat/multilingual-e5-large-instruct")

#embeddings = embeddings_model.embed_documents([text.page_content for text in texts])

#len(embeddings)

2. 첫번째 [Code]를 실행하여 langchain-huggingface를 설치합니다.

3. 두번째 [Code]를 실행하여 sentence-transformers를 설치합니다.

4. 텍스트 문서 임베딩 코드를 실행합니다.

모듈 저장 위치 : C:\Users\{사용자계정}\.cache\huggingface\hub

Indexing (인덱싱) – Store (저장)

이번에는 Chroma 대신 Faiss를 사용해보도록 하겠습니다.

Faiss (https://ai.meta.com/tools/faiss/)

Facebook AI Research에 의해 개발된 라이브러리로, 대규모 벡터 데이터셋에서 유사도 검색을 빠르고 효율적으로 수행할 수 있게 해줍니다. 메모리 사용량을 최소화하면서도 검색 속도를 극대화하는 특징이 있습니다.

Vector Stores (https://python.langchain.com/docs/how_to/vectorstores/)

1. project3에 QnA1.ipynb 파일에 벡터 스토어 저장 코드를 변경합니다. 벡터 스토어가 저장될 faiss_db 폴더를 생성합니다.

[Markdown]
벡터 스토어 저장 (Faiss)

[Code]
%pip install faiss-cpu

[Code]
from langchain_community.vectorstores import FAISS

vector_store = FAISS.from_documents(
    documents=texts,# 분할된 Document 객체 리스트
    embedding=embeddings_model # 사용할 임베딩 모델
)

# 저장될 디렉토리, 인덱스 명
vector_store.save_local("./faiss_db", "test_db")

2. 첫번째 [Code]를 실행하여 faiss-cpu를 설치합니다.

3. 벡터 스토어 저장 코드를 실행합니다. faiss_db 폴더에 벡터 스토어가 생성됩니다.

4. 벡터 스토어 쿼리 코드를 실행합니다.

Retrieval (검색) – Search (검색)

Faiss (https://python.langchain.com/docs/integrations/vectorstores/faiss/)

1. project3에 QnA2.ipynb 파일을 생성하고 벡터 스토어 검색 코드를 추가합니다.

[Markdown]
벡터 스토어 검색 (Faiss)

[Code]
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_community.vectorstores import FAISS

embeddings_model = HuggingFaceEmbeddings(model_name="intfloat/multilingual-e5-large-instruct")

loaded_vector_store = FAISS.load_local(
    folder_path="./faiss_db", # 저장된 디렉토리
    index_name="test_db", # 저장된 인덱스 명
    embeddings=embeddings_model, # 사용할 임베딩 모델
    allow_dangerous_deserialization=True # pickle 파일 역직렬화 허용 
)

retriever = loaded_vector_store.as_retriever(search_kwargs={"k": 5})

result_texts = retriever.invoke("중학생의 수학 기초학력 미달률은?")
result_texts

2. 벡터 스토어 검색 코드를 실행합니다.

벡터 스토어 검색 결과입니다.

[Document(id='fb8315b4-483c-4763-b361-af94b8e80ce0', metadata={'source': 'data/test.txt'}, page_content='교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학'),
 Document(id='6dcbfe08-1013-45d4-8d20-fcdbaae62393', metadata={'source': 'data/test.txt'}, page_content='8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.'),
 Document(id='241efdba-09b4-4e44-a74b-bcbd645eeb1e', metadata={'source': 'data/test.txt'}, page_content='테크빌교육 체더스, 기초학력 부진 해결을 위한 코스웨어 기획전 진행'),
 Document(id='babccbd5-7557-4c20-85ff-46534ad2b69b', metadata={'source': 'data/test.txt'}, page_content='기초 학력 향상에 특화된 에듀테크 솔루션을 특별 할인가로 제공한다.'),
 Document(id='2790ef3b-dab5-4a0e-8595-c054b6cdce53', metadata={'source': 'data/test.txt'}, page_content='이번 기획전에서는 AI 수학 학습 플랫폼 ‘매쓰홀릭 T’, AI 영어 학습 솔루션 ‘원아워’, 국어 문해력 학습 프로그램 ‘리드포스쿨’ 등 기초 학력 향상에 특화된 에듀테크')]

Generation (생성) – LLM (답변 생성)

1. 프롬프트 실행 코드를 실행합니다.

프롬프트를 여러번 실행한 결과입니다.

중학생의 수학 기초학력 미달률은 13.0%입니다. 이는 다른 과목에 비해 가장 높은 수치로, 학습 격차 해소를 위한 지원이 필요하다는 점이 강조되고 있습니다.

중학생의 수학 기초학력 미달률은 13.0%입니다. 이는 고등학생의 수학 기초학력 미달률인 16.6%보다 낮지만, 여전히 학습 격차 해소를 위한 지원이 필요합니다.

LangChain – RAG + Open Source AI

carrotweb — Thu, 23 Jul 2026 17:09:55 +0900

Open Source Embedding Model

유료 Embedding Model (임베딩 모델) 대처할 Open Source Embedding Model (임베딩 모델)

Hugging Face (허깅 페이스)
머신 러닝 커뮤니티로 모델, 데이터 세트 그리고 애플리케이션을 협업하는 플랫폼입니다.
기계 학습 모델을 구축, 배포 및 교육하기 위한 도구와 리소스를 개발하는 프랑스계 미국 회사이자 오픈 소스 커뮤니티이다.

Hugging Face (https://huggingface.co/)

LangChain은 Hugging Face 임베딩 모델을 사용하는 다양한 방법을 지원하고 있습니다. 그 중에서 Local inference(로컬 추론 방식)을 사용해보겠습니다.

Local inference은 모델을 다운로드하고 Sentence Transformers를 사용하여 프로세스 내에서 실행합니다.

로컬에서 생성하고 처음 실행할 때 모델 가중치가 다운로드됩니다.

Embed Text (https://docs.langchain.com/oss/python/integrations/embeddings/huggingfacehub)

Hugging Face (허깅 페이스)에서 무료로 사용할 모델을 검색하겠습니다.

Search – sentence-transformers/all-mpnet-base-v2
(https://huggingface.co/models?library=transformers&sort=trending&search=sentence)

sentence-transformers/all-mpnet-base-v2 모델을 확인해 보겠습니다.

sentence-transformers/all-mpnet-base-v2 (https://huggingface.co/sentence-transformers/all-mpnet-base-v2)

LangChain에서 Hugging Face (허깅 페이스)를 사용하기 위해서 langchain-huggingface를 설치해야 합니다.

pip install -U langchain-huggingface

Hugging Face (허깅 페이스) 모델을 사용하여 임베딩(인코딩)하여 사용할 수 있습니다.

모델의 성능을 확인할 수 있습니다. 오픈 소스라 성능은 높지 않습니다. 그렇지만 무료이기 때문에 적절하게 사용한다면 좋습니다.

https://www.sbert.net/docs/sentence_transformer/pretrained_models.html

다국어 임베딩 모델 (Multilingual Embedding Model)

Hugging Face (허깅 페이스)에서 많이 사용되는 Multilingual Embedding Model (멀티링구얼 임베딩 모델, 다국어 임베딩 모델)에 대해 알아보겠습니다.

sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

이 모델은 50개 언어를 지원합니다.

intfloat/multilingual-e5-large-instruct

이 모델은 xlm-roberta에서 제공하는 100개 언어를 지원합니다. (xlm-roberta-large에서 초기화되었고 다양한 다국어 데이터셋을 사용하여 지속적으로 학습되었습니다.)

snunlp/KR-SBERT-V40K-klueNLI-augSTS

이 모델은 서울대학교 컴퓨터언어학 연구실에서 개발한 모델입니다.

KLUE-NLI 데이터 세트와 증강된 KorSTS 데이터 세트를 추가하여 SBERT 모델을 미세 조정하였습니다.

dragonkue/snowflake-arctic-embed-l-v2.0-ko

이 모델은 Snowflake/snowflake-arctic-embed-l-v2.0 모델에 한국어 검색의 성능을 향상시키기 위해 한국어 데이터를 추가 학습하여 미세 조정하였습니다.

한국어 임베딩 모델을 비교하고 평가하는 리더보드입니다.

최신의 정보는 https://github.com/OnAnd0n/ko-embedding-leaderboard에서 확인하실 수 있습니다.

multilingual 모델 검색하기
(https://huggingface.co/models?pipeline_tag=sentence-similarity&library=transformers&sort=trending&search=multilingual)

sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

(https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2)

intfloat/multilingual-e5-large-instruct

(https://huggingface.co/intfloat/multilingual-e5-large-instruct)

이 모델은 xlm-roberta-large에서 초기화되었고 다양한 다국어 데이터셋을 사용하여 지속적으로 학습됩니다. xlm-roberta에서 제공하는 100개 언어를 지원하지만, 리소스가 부족한 언어는 성능 저하가 발생할 수 있습니다.

XLM-RoBERTa 모델은 100개 언어가 포함된 2.5TB의 필터링된 CommonCrawl 데이터를 기반으로 사전 학습되었습니다.

Embedding Leaderboard – Multilingual (https://huggingface.co/spaces/mteb/leaderboard)

KR 모델 검색하기
(https://huggingface.co/models?pipeline_tag=sentence-similarity&library=transformers&sort=trending&search=KR)

snunlp/KR-SBERT-V40K-klueNLI-augSTS

(https://huggingface.co/snunlp/KR-SBERT-V40K-klueNLI-augSTS)

snunlp/KR-SBERT

(https://github.com/snunlp/KR-SBERT)

서울대학교 컴퓨터언어학 연구실에서 개발한 사전 학습된 한국어 특정 Sentence-BERT model(닐스 라이머스와 이리나 구레비치 2019)

Sentence-BERT(센텐스버트, SBERT)는 기본적으로 BERT의 문장 임베딩의 성능을 우수하게 개선시킨 모델입니다. SBERT는 BERT의 문장 임베딩을 응용하여 BERT를 파인 튜닝하였습니다.

KLUE-NLI 데이터셋과 증강 KorSTS 데이터셋을 기반으로 SBERT 모델을 파인 튜닝하였습니다.

dragonkue/snowflake-arctic-embed-l-v2.0-ko

(https://huggingface.co/dragonkue/snowflake-arctic-embed-l-v2.0-ko)

RAG App 개발 2 - Retrieval and Generation (검색과 생성) 하기

carrotweb — Thu, 23 Jul 2026 00:22:29 +0900

Retrieval and Generation (검색과 생성)

임베딩 모델을 생성합니다.
벡터 스토어에서 상위 5개만 검색되게 매개변수를 지정하여 리트리버를 인스턴스화합니다.
사용자 질문을 리트리버를 사용하여 벡터 스토어에서 데이터(청크)를 검색하여 가져옵니다.
검색된 데이터(청크)와 사용자 질문으로 프롬프트를 생성합니다.
LLM에 사용하여 결과를 생성합니다.

Retrieval and Generation (검색과 생성) 순서대로 진행하겠습니다.

Retrieval (검색) – Search (검색)

Chroma (https://python.langchain.com/docs/integrations/vectorstores/chroma/)

Retrieval (https://python.langchain.com/docs/how_to/vectorstore_retriever/)

1. project3에 QnA2.ipynb 파일을 생성하고 벡터 스토어 검색 코드를 추가합니다.

[Markdown]
벡터 스토어 검색

[Code]
import os
from langchain_openai import OpenAIEmbeddings
from langchain_chroma import Chroma

os.environ["OPENAI_API_KEY"] = "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"

embeddings_model = OpenAIEmbeddings(model="text-embedding-3-large")

loaded_vector_store = Chroma(
    embedding_function=embeddings_model, # 사용할 임베딩 모델
    persist_directory="./chroma_db", # 디렉토리
    collection_name="test_db"
)

retriever = loaded_vector_store.as_retriever(search_kwargs={"k": 5})

result_texts = retriever.invoke("중학생의 수학 기초학력 미달률은?")
result_texts

2. 벡터 스토어 검색 코드를 실행합니다.

벡터 스토어 검색 결과입니다.

[Document(id='12c21365-cdea-4ba7-8876-eea93aa5a419', metadata={'source': 'data/test.txt'}, page_content='교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학'),
 Document(id='7cd4b316-9aed-43dd-84c5-f5f8ac59157b', metadata={'source': 'data/test.txt'}, page_content='8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.'),
 Document(id='6e29f2ff-6892-43da-8206-88c58c0dbe9b', metadata={'source': 'data/test.txt'}, page_content='테크빌교육 체더스, 기초학력 부진 해결을 위한 코스웨어 기획전 진행'),
 Document(id='40f8cf3a-7a78-4f1f-96b1-1ae2db207855', metadata={'source': 'data/test.txt'}, page_content='정지혜 체더스사업부 부서장은 "학기말부터 여름방학은 기초학력을 높일 수 있는 중요한 시기”라며 “이번 기획전을 통해 선생님들이 효과가 검증된 솔루션을 활용해 학생들 간의 학습'),
 Document(id='7ab223ae-8e2a-4335-ae59-6ac3004231c7', metadata={'source': 'data/test.txt'}, page_content='이번 기획전에서는 AI 수학 학습 플랫폼 ‘매쓰홀릭 T’, AI 영어 학습 솔루션 ‘원아워’, 국어 문해력 학습 프로그램 ‘리드포스쿨’ 등 기초 학력 향상에 특화된 에듀테크')]

Retrieval (검색) – Prompt (프롬프트)

Prompt Hub (https://python.langchain.com/docs/tutorials/rag/#orchestration)

1. project3에 QnA2.ipynb 파일에 프롬프트 가져오기 코드를 추가합니다.

[Markdown]
프롬프트 가져오기

[Code]
from langchain import hub

prompt = hub.pull("rlm/rag-prompt")

print(prompt)

2. 프롬프트 가져오기 코드를 실행합니다.

프롬프트 가져오기 결과입니다.

c:\workspaces\projects\project3\myenv\Lib\site-packages\langsmith\client.py:272: LangSmithMissingAPIKeyWarning: API key must be provided when using hosted LangSmith API
  warnings.warn(
input_variables=['context', 'question'] input_types={} partial_variables={} metadata={'lc_hub_owner': 'rlm', 'lc_hub_repo': 'rag-prompt', 'lc_hub_commit_hash': '50442af133e61576e74536c6556cefe1fac147cad032f4377b60c436e6cdcb6e'} messages=[HumanMessagePromptTemplate(prompt=PromptTemplate(input_variables=['context', 'question'], input_types={}, partial_variables={}, template="You are an assistant for question-answering tasks. Use the following pieces of retrieved context to answer the question. If you don't know the answer, just say that you don't know. Use three sentences maximum and keep the answer concise.\nQuestion: {question} \nContext: {context} \nAnswer:"), additional_kwargs={})]

Generation (생성) – LLM (답변 생성)

1. project3에 QnA2.ipynb 파일에 프롬프트 실행 코드를 추가합니다.

[Markdown]
프롬프트 실행

[Code]
from langchain.chat_models import init_chat_model

model = init_chat_model("gpt-4o-mini", model_provider="openai")

texts = "\n\n".join(result_text.page_content for result_text in result_texts)

do_prompt = prompt.invoke({"context" : texts, "question": "중학생의 수학 기초학력 미달률은?"})

ai_msg = model.invoke(do_prompt)
print(ai_msg.content)

생성된 프롬프트입니다.

ChatPromptValue(messages=[HumanMessage(content='You are an assistant for question-answering tasks. Use the following pieces of retrieved context to answer the question. If you don\'t know the answer, just say that you don\'t know. Use three sentences maximum and keep the answer concise.\nQuestion: 중학생의 수학 기초학력 미달률은? \nContext: 교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학\n\n8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다.\n\n테크빌교육 체더스, 기초학력 부진 해결을 위한 코스웨어 기획전 진행\n\n정지혜 체더스사업부 부서장은 "학기말부터 여름방학은 기초학력을 높일 수 있는 중요한 시기”라며 “이번 기획전을 통해 선생님들이 효과가 검증된 솔루션을 활용해 학생들 간의 학습\n\n이번 기획전에서는 AI 수학 학습 플랫폼 ‘매쓰홀릭 T’, AI 영어 학습 솔루션 ‘원아워’, 국어 문해력 학습 프로그램 ‘리드포스쿨’ 등 기초 학력 향상에 특화된 에듀테크 \nAnswer:', additional_kwargs={}, response_metadata={})])

2. 프롬프트 실행 코드를 실행합니다.

프롬프트를 여러번 실행한 결과입니다.

중학생의 수학 기초학력 미달률은 13.0%로 보고되었습니다. 이 수치는 고등학생의 수학 미달률 16.6%와 비교할 때 여전히 높은 편입니다. 따라서 학습 격차 해소를 위한 지원이 필요하다고 판단됩니다.

중학생의 수학 기초학력 미달률은 13.0%입니다. 이는 영어 6.0%와 다른 과목들에 비해 가장 높은 수치로, 학습 격차 해소를 위한 지원이 필요합니다.

중학생의 수학 기초학력 미달률은 13.0%입니다. 이 수치는 기초학력 부진이 상대적으로 높은 것을 보여줍니다. 따라서 학습 격차 해소를 위한 지원이 필요합니다.

RAG App 개발 1 - Indexing (인덱싱) 하기

carrotweb — Thu, 23 Jul 2026 00:00:53 +0900

개발 환경 설정

RAG App를 Jupyter로 개발하기 위해서 VSCode에 Extension으로 Jupyter 설치합니다.

Jupyter

Jupyter는 파이썬과 R 언어를 위해 인터렉티브한 컴퓨팅 환경을 제공하기 위해 개발되어 무료로 제공되고 있는 웹 기반의 소프트웨어이다. Jupyter Notebook은 셀이라는 블럭의 집합으로 코드를 작성할 수 있도록 해주며, 각 셀은 따로 수정하고 실행할 수도 있습니다.

VSCode에서 Jupyter Notebook 단축키를 사용할 수 있도록 해주는 확장 프로그램입니다. 이 확장 프로그램을 설치하면 Jupyter Notebook에서 사용하던 단축키를 VS Code에서도 동일하게 사용할 수 있습니다.

RAG App 개발

랭체인 사이트의 튜토리얼을 기반으로 설명하겠습니다.

더 자세한 내용 랭체인 사이트를 참고하시기 바랍니다.

(https://python.langchain.com/docs/tutorials/rag/)

Q&A App 개발

Indexing (인덱싱) 하기

텍스트 문서 파일을 텍스트 로더로 로드합니다.
텍스트 스플리터로 텍스트를 청크 사이즈로 분할합니다.
임베딩 모델을 생성합니다. (청크를 벡터 값 변환)
분할된 청크들을 임베딩 모델을 사용하여 벡터로 변환하고 벡터 스토어에 저장합니다.

Indexing (인덱싱) 순서대로 진행하겠습니다.

Indexing (인덱싱) – Load (읽기)

1. project3에 data 폴더를 만들고 test.txt 파일을 생성합니다.

데이터인 test.txt 파일은 회사 관련 뉴스입니다.

테크빌교육 체더스, 기초학력 부진 해결을 위한 코스웨어 기획전 진행

테크빌교육(대표 이형세)이 운영하는 에듀테크 마켓 플레이스 ‘체더스’가 여름방학을 앞두고 학생의 국·영·수 기초학력 부진 해소를 위한 ‘코스웨어 기획전’을 진행한다고 25일 밝혔다. 

교육부의 ‘2023 국가수준 학업성취도평가’에 따르면 중학생의 기초학력 미달률은 9.1%, 영어 6.0%, 수학 13.0%였으며 고등학생은 국어 8.6%, 영어 8.7%, 수학 16.6%로 집계됐다. 특히 수학의 기초학력 부진이 가장 높아 학습 격차 해소를 위한 지원이 필요한 상황이다. 

이번 기획전에서는 AI 수학 학습 플랫폼 ‘매쓰홀릭 T’, AI 영어 학습 솔루션 ‘원아워’, 국어 문해력 학습 프로그램 ‘리드포스쿨’ 등 기초 학력 향상에 특화된 에듀테크 솔루션을 특별 할인가로 제공한다. 

체더스는 에듀테크 제품 판매에서 나아가 교육 현장에서의 활용도를 높이기 위한 다양한 지원 프로그램도 운영 중이다. 국내외 33종 에듀테크 제품의 무료 체험과 함께 초등과 중·고등으로 세분화된 ‘체더스 부트캠프’, 전국 교사 대상의 웨비나를 연 20회씩 진행하며 에듀테크 도입과 실제 수업 적용 사례를 확산하고 있다. 

최근에는 ‘체더스 디지털 배지’ 시스템을 도입했다. 이 배지는 에듀테크 등급 배지(공교육에서 신뢰할 수 있는 품질과 가치를 제공하는 에듀테크)와 학교 실증 배지(실제 교육 현장에서 활용 돼 교육적·기술적 효과를 입증한 에듀테크)의 2종으로 구성돼 있다. 

올해부터 에듀테크 선도학교 예산 축소에 따라 ‘최저가 보장 이달의 에듀테크 특가전’도 진행하고 있다. 노션(Notion), 굿노트(GoodNotes), 카훗(Kahoot), 카미(Kami), 니어팟(Nearpod) 북크리에이터(Book Creator) 등 해외 주요 에듀테크 솔루션을 최저가로 판매하고 국내 에듀테크 기업들과의 협업으로 할인 혜택도 확대할 계획이다. 

정지혜 체더스사업부 부서장은 "학기말부터 여름방학은 기초학력을 높일 수 있는 중요한 시기”라며 “이번 기획전을 통해 선생님들이 효과가 검증된 솔루션을 활용해 학생들 간의 학습 격차를 해소하는 데 도움이 되길 바란다”고 말했다. 

한편 체더스는 지난 5월 체더스에서 에듀테크 제품을 구매한 학교를 대상으로 ‘간식어택 이벤트’를 진행했다. 그 결과 이벤트에 선정된 8개교에 피자 및 간식 박스를 전달했으며 1등으로 당첨된 의정부신곡초등학교에는 지난 24일 ‘찾아가는 간식차’를 보내 디지털 교육에 앞장서고 있는 교육 현장을 직접 응원했다.

2. project3에 QnA1.ipynb 파일을 생성합니다.

텍스트 파일을 읽기(LOAD)하기 위해서 langchain-community에 있는Text Loader를 사용하겠습니다.

langchain-community (https://python.langchain.com/api_reference/community/index.html) – Third-party module (서드파티 모듈)

Document Loader > Text Loader (https://python.langchain.com/api_reference/community/document_loaders/langchain_ community.document_loaders.text.TextLoader.html)

3. project3에 QnA1.ipynb 파일에 텍스트 문서 로드 코드를 추가합니다.

[Markdown]
일반 텍스트 문서 로드

[Code]
%pip install langchain-community

[Code]
from langchain_community.document_loaders import TextLoader

file_path = "data/test.txt"

# 텍스트 로더 생성
loader = TextLoader(file_path, encoding="utf-8")

# 문서 로드
docs = loader.load()

print(f"문서의 수: {len(docs)}\n")
docs

4. 첫번째 [Code]를 실행하여 langchain-community를 설치합니다.

5. 일반 텍스트 문서 로드 코드를 실행합니다.

Indexing (인덱싱) – Split (분할)

Splitting Document (https://python.langchain.com/docs/tutorials/rag/#splitting-documents)

Recursive Text Splitter (https://python.langchain.com/docs/how_to/recursive_text_splitter/)

1. project3에 QnA1.ipynb 파일에 텍스트 문서 분할 코드를 추가합니다.

[Markdown]
일반 텍스트 문서 분할

[Code]
from langchain_text_splitters import RecursiveCharacterTextSplitter

text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=100,
    chunk_overlap=20
)
texts = text_splitter.split_documents(docs)
len(texts)

2. 문서 분할 코드를 실행합니다.

Indexing (인덱싱) – Embed (임베드, 임베딩 모델)

OpenAI에서 제공하는 임베딩 서비스입니다.
텍스트를 효율적으로 벡터로 변환합니다. 하지만 비용이 발생합니다.

Embed Text (https://python.langchain.com/docs/how_to/embed_text/)

Vector embeddings (https://platform.openai.com/docs/guides/embeddings)

1. project3에 QnA1.ipynb 파일에 텍스트 문서 임베딩 코드를 추가합니다.

[Markdown]
일반 텍스트 문서 임베딩

[Code]
import os
from langchain_openai import OpenAIEmbeddings

os.environ["OPENAI_API_KEY"] = "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"

embeddings_model = OpenAIEmbeddings(model="text-embedding-3-large")

embeddings = embeddings_model.embed_documents([text.page_content for text in texts])

len(embeddings)

2. 텍스트 문서 임베딩 코드를 실행합니다.

문서 임베딩 코드를 실행 결과입니다.

Indexing (인덱싱) – Store (저장)

Store 중 대표적인 2개를 소개합니다.

Chroma (https://www.trychroma.com/)

임베딩 벡터를 저장하기 위한 오픈소스 소프트웨어로, LLM App 구축을 용이하게 하는 핵심 기능을 수행합니다.

Faiss (https://ai.meta.com/tools/faiss/)

여기서는 Chroma를 Store로 사용하겠습니다.

langchain-chroma (https://python.langchain.com/api_reference/chroma/index.html)

Vector Stores (https://python.langchain.com/docs/how_to/vectorstores/)

1. project3에 QnA1.ipynb 파일에 벡터 스토어 저장 코드를 추가합니다. 벡터 스토어가 저장될 chroma_db 폴더를 생성합니다.

[Markdown]
벡터 스토어 저장

[Code]
%pip install langchain-chroma

[Code]
from langchain_chroma import Chroma

vector_store = Chroma.from_documents(
    documents=texts, # 분할된 Document 객체 리스트
    embedding=embeddings_model, # 사용할 임베딩 모델
    persist_directory="./chroma_db", # 저장될 디렉토리
    collection_name="test_db"
)

2. 첫번째 [Code]를 실행하여 langchain-chroma를 설치합니다.

3. 벡터 스토어 저장 코드를 실행합니다. chroma_db 폴더에 벡터 스토어가 생성됩니다.

4. project3에 QnA1.ipynb 파일에 벡터 스토어 쿼리 코드를 추가합니다.

[Code]
query = "중학생의 수학 기초학력 미달률은?"
docs = vector_store.similarity_search(query)
print(docs[0].page_content)

5. 벡터 스토어 쿼리 코드를 실행합니다.

이어서, Retrieval and Generation (검색과 생성)을 진행하도록 하겠습니다.

RAG(Retrieval-Augmented Generation)

carrotweb — Wed, 22 Jul 2026 20:32:22 +0900

RAG(Retrieval-Augmented Generation)

LLM(대규모(초거대) 언어 모델)의 출력을 최적화하여 답변을 생성하기 전에 학습 데이터 소스를 외부의 신뢰할 수 있는 지식 베이스를 참조하도록 하는 프로세스입니다.

RAG 장점

최신 정보 : 최신 정보로 답변할 수 있습니다.

정확한 정보 : 특정 도메인에 대한 정확한 정보로 답변할 수 있습니다. → Hallucination(할루시네이션, 환각) 방지, 신뢰 강화

RAG 단점

답변 지연 : In-Context Learning (ICL, 인-컨텍스트 학습)으로 인한 답변 시간이 지연될 수 있습니다.

보안 문제 : In-Context Learning (ICL, 인-컨텍스트 학습)으로 인한 민감한 정보가 외부로 노출될 수 있습니다.

RAG 프로세스

1. Indexing (인덱싱)

소스에서 데이터를 수집하고 인덱싱하는 파이프라인입니다.

일반적으로 오프라인에서 수행됩니다.

Load (로드) : 문서 로더를 사용하여 데이터를 로드합니다.
Split (분할) : 큰 문서를 작은 청크로 나눕니다. (이는 데이터 인덱싱과 모델 전달 모두에 유용합니다. 큰 청크는 검색하기 어렵고 모델의 한정된 컨텍스트 길이에 맞지 않기 때문입니다.)
Embed (임베드) : 청크를 벡터 값으로 생성합니다. (Embedding Model (임베딩 모델)을 사용)
Store (저장) : 유사도 검색을 할 수 있도록 벡터 값(분할 데이터)를 저장합니다. (VectorStore)

Embedding(임베딩)이란?

텍스트나 이미지, 오디오 등을 Embedding Model(임베딩 모델)을 사용하여 Vector(벡터, 숫자들로 구성된 배열)로 변환하는 과정을 의미합니다.

Embedding Model(임베딩 모델)은 데이터를 벡터로 변환할 수 있도록 학습된 모델을 의미합니다.

잠깐 수학적 데이터 표현 단위를 확인해보겠습니다.

Scalar(스칼라)는 크기로만 설명되는 물리량입니다. 즉, 스칼라는 숫자 값만으로 표현되는 양입니다.
Vector(벡터)는 숫자의 배열(크기와 방향을 가지고 있는 값)입니다. 숫자는 순서대로 배열되어 있으며 해당 순서의 색인을 통해 각 개별 숫자를 식별할 수 있습니다. 벡터는 공간의 점을 식별하는 것으로 생각할 수 있으며, 각 요소는 서로 다른 축을 따라 좌표를 제공합니다.
Matrice(매트릭스, 행렬)는 숫자가 행과 열로 배열(스칼라 값을 2차원 형태로 배열)됩니다.
Tensor(텐서)는 n-차원의 배열입니다. n-차원 공간에서 값을 나타내며, 여러 차원으로 구성된다.

2. Retrieval and Generation (검색과 생성)

사용자 질문을 받아 저장소에서 관련 데이터를 검색한 다음 질문과 데이터를 모델에 전달합니다.

Retrieve (검색) : 사용자 입력이 주어지면, 검색기를 사용하여 임베딩(벡터 값으로 생성)하고 저장소에서 데이터(청크)를 검색합니다.

Generate (생성) : 질문과 검색된 데이터를 모두 포함하는 프롬프트를 사용하여 LLM을 통한 답변을 생성합니다.

LLM 한계 및 해결방법

carrotweb — Wed, 22 Jul 2026 17:23:09 +0900

LMM 한계

정보의 한계

LLM(대규모(초거대) 언어 모델)은 선행 학습된 데이터(학습 시점의 데이터)에만 제한됩니다. 그래서 최신 정보가 부족합니다.
그리고 특정 도메인에 대한 정보가 부족하거나 없을 수 있습니다.

ChatGPT를 통해 정보의 한계를 확인해보겠습니다.

중학생의 수학 기초학력 미달율을 물어보겠습니다.

ChatGPT는 학습된 정보가 없을 경우 웹에서 검색을 합니다.

ChatGPT가 웹에서 검색한 내용을 정리하여 보여줍니다.

질의할때가 2025년 7월인데 ChatGPT에 데이터도 없고 웹 검색에서도 2023년를 기준으로 가져왔습니다.

이처럼 최신 데이터를 기대하고 물어보면 없거나 과거 데이터를 가져올 수 밖에 없습니다.

정확성의 한계

오래된 정보가 제공되거나 일반적인 정보가 제공될 수 있어 부정확한 답변이 제공될 수 있습니다.

용어 혼동(동일한 용어로 인하)으로 인해 다른 내용으로 답변 생성
신뢰할 수 없는 출처로부터 답변 생성
사실과 다른(존재하지 않는) 정보를 사실인 것처럼 답변 생성 → Hallucination(할루시네이션, 환각)

LLM 한계점 해결 방법

Fine-tuning (파인 튜닝, 미세 조정)

특정 도메인에 대한 높은 정확성을 제공하기 위해, 이미 훈련된 대규모 언어 모델에 특정 데이터셋을 사용하여 추가적인 학습을 수행하는 작업을 말합니다.

파인 튜닝의 한계점

Overtraining, Overfitting (과적합, 과대적합, 오버피팅) : 학습 모델이 학습 데이터에 지나치게 잘 맞춰져 일반화하는 능력이 떨어지는 현상을 말한다.
Catastrophic Forgetting (파멸적 망각) : LLM에 새로운 정보를 학습할 때 이전에 학습한 정보를 급격하게 잊어버리는 현상을 의미한다.
높은 시스템 비용 : 재 학습을 위한 고성능 GPU와 대용량 메모리가 있는 시스템을 사용하기 위한 비용 부담과 재 학습 시간이 필요합니다. 추가 학습을 위한 Labeling(라벨링)과 Supervised Learning(지도학습) 과정에 많은 시간과 작업량을 필요합니다.

Few-Shot Learning (FSL, 퓨샷 학습)

0개에서 n개의 예제를 학습하여 예측을 수행하는 방법을 학습한 후 답변이 출력되도록 합니다.

예제를 통해 모델이 질문에 대한 의도를 좀더 정확하게 이해하게 되고 답변을 예제 형식에 맞게 처리하게 됩니다.

제한된 양의 학습 데이터만을 사용하여 새로운 작업을 수행할 수 있게 하는 학습 방식입니다.

Zero-Shot Learning (제로샷 학습) : 모델에 학습할 수 있는 예제를 제공하지 않는 방식입니다.

One-Shot Learning (원샷 학습) : 모델에 학습할 수 있는 하나의 예제를 제공하는 방식입니다.

Few-Shot Learning (퓨샷 학습) : 모델에 학습할 수 있는 여러 예제를 제공하는 방식입니다.

Chain-of-Thought (CoT, 생각의 사슬)

예제로 문제와 함께 문제를 해결하기 위한 논리적 단계를 포함하여 프롬프트를 구성합니다. 이를 통해 모델은 유사한 추론 라인을 따르도록 유도하여 좀더 정확한 답변을 할 수 있도록 해줍니다.

수학 문제, 복잡한 이해 문제, 주어진 데이터로부터 추론을 요구하는 문제와 같이 여러 단계나 추론의 레이어가 필요한 문제에 특히 유용합니다.

예를 들어, 수학 문제와 결과 값을 묻는 예제 대신에 결과 값에 계산 방식을 설명하여 모델이 수학 계산 과정에 반영하도록 유도할 수 있습니다.

In-Context Learning (ICL, 인-컨텍스트 학습)

별도의 모델 학습과정 없이 프롬프트에 Context(문맥)를 제공하고 Context(문맥)를 기반으로 모델을 학습시켜 답변이 출력되도록 합니다.

프롬프트 구성 요소

지시(Instruction) – 모델이 수행할 특정 작업 또는 지시 (Task Description, Persona, Role)
문맥(Context) – 더 나은 답변을 위해 모델을 조종할 수 있는 외부 정보나 추가 문맥 (Information, Input Indicator, Example)
입력 데이터(Input Data) – 답변 받고자 하는 입력이나 질문 (User Input, Question)
출력 지시자(Output Indicator) – 출력의 유형이나 형식 (Output Indicator, Format)

인-컨텍스트 학습의 한계점

Context 길이 제한 : LLM이 처리할 수 있는 컨텍스트에 길이 제한이 있습니다. 그래서 긴 컨텍스트는 처리할 수 없습니다.
제공되는 Context가 너무 적거나 정보의 품질이 낮으면 모델 성능이 저하될 수 있습니다.
Context가 추론이나 복잡한 논리적 사고를 요구할 경우 LLM이 정보를 처리하는데 제약이 있을 수 있습니다.

우리가 LangChain으로 만들 RAG(Retrieval-Augmented Generation, 검색 증강 생성)는 LLM(대규모(초거대) 언어 모델)에 외부 데이터를 참고하여 답변하도록 In-Context Learning (ICL, 인-컨텍스트 학습)을 활용하여 만들겁니다.

우선 LangChain Hub에서 In-Context Learning (ICL, 인-컨텍스트 학습) 방식으로 사용될 프롬프트를 검색하여 사용해보도록 하겠습니다. 이 프롬프트는 다음에 개발할 RAG에서 사용됩니다.

LangChain Hub (https://smith.langchain.com/hub/)

rag로 검색한 후 rlm/rag-prompt를 클릭합니다. 검색 후 Top Favorited를 클릭하면 상단에 나옵니다.

You are an assistant for question-answering tasks.
Use the following pieces of retrieved context to answer the question.
If you don't know the answer, just say that you don't know.
Use three sentences maximum and keep the answer concise.
Question: {question} 
Context: {context} 
Answer:

당신은 질의응답 작업에 대한 어시스턴트입니다.
다음 문맥을 참고하여 질문에 답을 하세요.
답을 모르면 모른다고만 말씀해 주세요.
최대 세 문장으로 간결하게 답변해 주십시오.
질문: {question}
문맥: {context}
답:

정확한 결과를 얻기 위해서 프롬프트에 모델의 역할을 설정해주고 작업에 대한 지시사항을 설정합니다. 그리고 프롬프트에 질문과 관련된 Context(문맥)를 제공하고 Context(문맥)를 기반으로 모델을 학습시켜 답변이 출력되도록 합니다.

In-Context Learning (ICL, 인-컨텍스트 학습)으로 할 경우 다음과 같이 고려할 사항이 있습니다.

프롬프트에 질문과 관련된 데이터는 어디에 있고 어떻게 가져와야 하는가?
질문에 맞게 프롬프트의 역할을 어떻게 설정해야 하는가?
프롬프트에서 문맥 관리는 어떻게 해야 하는가?

다음에는 고려사항을 답을 찾아가 보도록하겠습니다.

랭체인 - LangChain

carrotweb — Mon, 8 Jun 2026 19:46:38 +0900

LangChain(랭체인) - https://www.langchain.com/

LangChain(랭체인)은 대규모(초거대) 언어 모델(LLM)을 기반으로 애플리케이션을 개발하기 위한 프레임워크입니다.

2025년에 사내 개발자 교육을 위해 만들어진 내용으로 작성되었습니다.

작성 당시 버전은 v0.3이였습니다. 현재 v1.3과 다를 수 있습니다.

링크는 현재 사이트에 맞게 수정하였습니다. 현재와 다르니 클릭해서 확인해보시기 바랍니다.

랭체인 사이트의 튜토리얼을 기반으로 설명하겠습니다.

더 자세한 내용 랭체인 사이트를 참고하시기 바랍니다.

(https://docs.langchain.com/oss/python/langchain/overview)

프로젝트 및 가상 환경 생성

1. 프로젝트 폴더를 생성합니다. (저는 C:\workspaces\projects\project3 폴더를 생성하였습니다.)

2. Visual Studio Code의 메뉴 File(파일) > Open Folder...(폴더 열기)를 클릭하여 "C:\workspaces\projects\project3" 폴더로 이동하고 "폴더 선택" 버튼을 누르면 폴더가 오픈됩니다.
보안을 위해 Trust(신뢰) 확인 창이 나타납니다. "Yes, I Trust the authors" 버튼을 누릅니다. 그리고 Welcome 창은 닫습니다.

3. Visual Studio Code의 메뉴 Terminal(터미널) > New Terminal(새 터미널)를 클릭합니다. 그리고 가상 환경을 생성하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

python -m venv {가상 환경 이름 또는 경로를 포함한 가상 환경 이름}

저는 가상 환경 이름을 myenv(my environments)라고 하였습니다.

python -m venv myenv

4. 생성된 가상 환경을 활성화하기 위해서는 myenv의 Scripts 폴더에 있는 activate를 Terminal(터미널)에서 실행해야 합니다.

cd myenv\Scripts
/activate

LangChain 설치

더 자세한 내용 랭체인 사이트를 참고하시기 바랍니다.

(https://docs.langchain.com/oss/python/langchain/install)

현재 가상 환경에 LangChain(랭체인)을 설치하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

pip install langchain

LangChain(랭체인)이 설치됩니다.

가상 환경 폴더(myenv)의 Lib\site-packages 폴더를 보면 LangChain(랭체인) 관련 모듈들이 설치되어 있는 것을 확인할 수 있습니다.

LangChain(랭체인)에서 openAI 모델을 사용하기 위해서 openAI 모델의 통합 패키지인 langchain-openai를 설치해야 합니다.

langchain-openai 설치

더 자세한 내용 랭체인 사이트를 참고하시기 바랍니다.

(https://docs.langchain.com/oss/python/langchain/install)

현재 가상 환경에 langchain-openai를 설치하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

pip install langchain-openai

langchain-openai가 설치됩니다.

가상 환경 폴더(myenv)의 Lib\site-packages 폴더를 보면 langchain-openai 관련 모듈들이 설치되어 있는 것을 확인할 수 있습니다.

간단한 채팅 만들기

더 자세한 내용 랭체인 사이트를 참고하시기 바랍니다.

(https://docs.langchain.com/oss/python/langchain/quickstart)

현재 v1.3에는 Agent로 되어있습니다. v0.3이라 설명이 다릅니다.

init_chat_model (통합 모델 초기화)

통합 인터페이스를 사용하여 지원되는 모든 제공업체의 채팅 모델을 초기화합니다.

(https://reference.langchain.com/python/langchain/chat_models/base/init_chat_model)

init_chat_model(
  model: str | None = None,
  model_provider: str | None = None,
);

model : 사용할 모델 명 (openAI 모델을 사용할 것이기 때문에 gpt-로 시작하는 모델명을 입력합니다. 비용을 고려해서 gpt-4o-mini로 사용했습니다.)

model_provider : 모델을 제공하는 업체 명 (openAI 모델을 사용할 것이기 때문에 openai를 입력합니다.)

코드 내에서 API Key를 현경 변수로 직접 적용하기 위해서 os.environ를 사용합니다.

os.environ["OPENAI_API_KEY"] = "{API Key}"

변수명은 "OPENAI_API_KEY"로 값은 openAI에서 생성한 Key를 입력합니다.

텍스트 프롬프트를 채팅 모델로 호출하여 응답을 AIMessage 객체로 받아옵니다.

ai_msg = model.invoke({message})

message : 메시지 프롬프트를 입력합니다. 간단하게 텍스트로 입력합니다.

응답 결과을 출력하기 위해 AIMessage 객체에서 content로 결과를 가져옵니다.

print(ai_msg.content)

project3에 main.py 파일을 생성합니다.

import os
from langchain.chat_models import init_chat_model

os.environ["OPENAI_API_KEY"] = "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"

model = init_chat_model("gpt-4o-mini", model_provider="openai")

ai_msg = model.invoke("Hello, world!")
print(ai_msg.content)

실행하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

python main.py

openAI의 gpt-4o-mini 모델을 이용한 응답 결과가 출력됩니다.

입력 메시지 : Hello, world! (4 token)
응답 메시지 : Hello! How can I assist you today? (9 token)

content='Hello! How can I assist you today?' additional_kwargs={'refusal': None} response_metadata={'token_usage': {'completion_tokens': 9, 'prompt_tokens': 27, 'total_tokens': 36, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}}, 'model_name': 'gpt-4o-2024-08-06', 'system_fingerprint': 'fp_a288987b44', 'id': 'chatcmpl-BqFjFY82nFOkuR2XNQte8UD9zGs6A', 'service_tier': 'default', 'finish_reason': 'stop', 'logprobs': None} id='run--e8c00ef2-1f2c-4c5c-b203-8570c3b0c5e0-0' usage_metadata={'input_tokens': 27, 'output_tokens': 9, 'total_tokens': 36, 'input_token_details': {'audio': 0, 'cache_read': 0}, 'output_token_details': {'audio': 0, 'reasoning': 0}}

OpanAI 사용내역

OpenAI Platform에서 사용량을 확인할 수 있습니다.

(https://platform.openai.com/usage)

추가로

할당량이 초과될 경우 다음과 같은 에러 메시지가 출력됩니다.

에러 메시지 : You exceeded your current quota, please check your plan and billing details.
현재 할당량을 초과했습니다. 요금제 및 청구 세부 정보를 확인하세요.

잘못된 API 키를 사용할 경우에는 다음과 같은 에러 메시지가 출력됩니다.

에러 메시지 : Incorrect API key provided
잘못된 API 키가 제공되었습니다.

API 키는 https://platform.openai.com/account/api-keys에서 찾을 수 있습니다.

파이썬 장고 사이트 국제화, 시간 설정 - LANGUAGE_CODE, TIME_ZONE, USE_I18N, USE_TZ

carrotweb — Mon, 4 Nov 2024 02:51:36 +0900

장고를 처음 실행하면 영어로 사이트가 보입니다.

사이트에 표시되는 언어를 영어에서 한국어로 변경하고 싶을 경우에는 LANGUAGE_CODE(언어 코드)를 변경하면 됩니다.

Internationalization(국제화) 설정

config 폴더에 있는 settings.py 파일에서 internationalization(국제화) 영역에 있는 LANGUAGE_CODE를 'en-us'에서 'ko-kr'로 변경하면 됩니다.

# 언어 - 한국어
LANGUAGE_CODE = 'ko-kr'

그러면 사이트가 한국어로 표시됩니다.

장고가 제공하는 메인 페이지는 myenv(가상환경) > Lib > site-packages > django > views > templates 폴더에 있는 default_urlconf.html 파일입니다.

메인 페이지(default_urlconf.html)를 보면 상단에 load 템플릿 태그가 있습니다.

{% load i18n %}

이는 internationalization(국제화)를 로드하여 템플릿 페이지에서 번역된 문장열을 사용하겠다는 것입니다.

여기서, i18(또는 대문자로 I18N)이 무슨 단어이기에 국제화라는 걸까요?

i18n은 internationalization의 첫 번째 단어 i부터 끝단어 n사이에 18개의 문자가 있는 것을 합처서 i18n으로 약어를 만든 겁니다.

i nternationalizatio n
  ------------------
                  18

i18n

반대로 localization(지역화 또는 현지화)는 무슨 단어일까요?

네, 예상하신 대로 l10n(또는 대문자로 L10N)입니다.

l ocalizatio n
  ----------
          10

l10n

템플릿 페이지에서 internationalization(국제화)로 번역된 문자열을 사용하고 싶을 때는 translate 템플릿 태그를 사용하면 됩니다.

메인 페이지(default_urlconf.html)처럼 번역된 문자열을 사용하고 싶은 문자열마다 translate 템플릿 태그를 사용하면 됩니다.

<title>{% translate "The install worked successfully! Congratulations!" %}</title>

그럼 번역된 문자열들은 어디에 있을까요?

번역된 문자열들은 myenv(가상환경) > Lib > site-packages > django > conf > locale 폴더에 언어 코드별로 있습니다.

한국어로 번역된 문자열들은 myenv(가상환경) > Lib > site-packages > django > conf > locale > ko > LC_MESSAGES 폴더에 있는 django.po 파일입니다.

원문과 번역문은 msgid와 msgstr로 구성되어 있습니다.

msgid "The install worked successfully! Congratulations!"
msgstr "성공적으로 설치되었습니다! 축하합니다!"

msgid는 translate 템플릿 태그에 있는 문자열입니다.

{% translate "The install worked successfully! Congratulations!" %}
              -------------------------------------------------
                                                          msgid

msgstr은 번역된 문자열입니다.

만약, 국제화를 사용하고 싶지 않을 경우에는 config 폴더에 있는 settings.py 파일에서 internationalization(국제화) 영역에 있는 USE_I18N를 False로 하면 됩니다.

# 국제화를 사용하지 않음
USE_I18N = False

이러면 템플릿 페이지에 있는 문장이 그대로 나옵니다.

우리는 관리자 페이지를 한국어로 표시할 것이기 때문에 USE_I18N은 True로 변경하지 않을 것입니다.

국제화와 번역에 대한 더 자세한 내용 장고 문서 사이트를 참고하시기 바랍니다. (https://docs.djangoproject.com/en/5.1/topics/i18n/, https://docs.djangoproject.com/en/5.1/topics/i18n/translation/)

템플릿 페이지에서 사용할 국제화 생성에 대해서 다음에 앱을 만들고 템플릿 페이지를 만들 때 다시 설명하도록 하겠습니다.

시간 설정

장고는 기본적으로 TIME_ZONE은 UTC(Universal Time Coordinated, 협정 세계시)으로 되어 있습니다.

config 폴더에 있는 settings.py 파일에서 internationalization(국제화) 영역에 있는 TIME_ZONE이 UTC으로 설정되어 있습니다.

TIME_ZONE = 'UTC'

그럼 한국 시간으로 표시하려면 어떻게 해야 할까요?

TIME_ZONE를 Asia/Seoul로 변경하면 됩니다.

# 시간 - 한국
TIME_ZONE = 'Asia/Seoul'

그럼 한국 시간으로 시간이 표시됩니다.

여기서 주의할 점!

데이터베이스에 저장될 때는 UTC로 저장되는 겁니다.

단지 데이터베이스에서 데이터를 가져올 때만 한국 시간으로 변형되는 겁니다.

다음처럼, 현재 한국 시간이 2024년 11월 3일 오후 7시 39분 34초라면 데이터베이스에 저장될 때는 UTC로 변형되어 저장됩니다.

UTC로 저장되는 시간
datetime.datetime(2024, 11, 3, 10, 39, 34, tzinfo=datetime.timezone.utc)

한국 시간으로 처리된 시간
datetime.datetime(2024, 11, 3, 19, 39, 34, tzinfo=<DstTzInfo 'Asia/Seoul' LMT+9:00:00 STD>)

그렇기 때문에 데이터베이스에 저장된 시간은 한국 시간 기준보다 9시간이 느리게 저장이 됩니다.

UTC
Asia/Seoul = UTC + 9

그래서 시스템(서버) 시간이 한국 시간 기준일 경우 데이터베이스에 저장된 시간과 맞지 않아서 서버 프로그램에 개발에 문제가 될 수 도 있습니다.

그럼 데이터베이스에 저장되는 시간을 시스템 시간(한국 시간 기준)으로 하려면 어떻게 해야 할까요?

TIME_ZONE를 사용하지 않으면 됩니다. 그래서 USE_TZ를 False로 변경하면 됩니다.

# TIME_ZONE를 사용하지 않음
USE_TZ = False

TIME_ZONE를 사용하지 않기 때문에 데이터베이스에 저장된 시간은 시스템 시간(한국 시간 기준)이 됩니다.

USE_TZ = True --> UTC 시간으로 저장됩니다.
USE_TZ = False --> 시스템 시간으로 저장됩니다.

만약, 국제화를 사용하지 않고 시스템 시간(한국 시간 기준)을 기준으로 하고 싶을 경우에는 USE_I18N과 USE_TZ를 False로 설정하면 됩니다.

# 국제화를 사용하지 않음
USE_I18N = False

# TIME_ZONE를 사용하지 않음
USE_TZ = False

우리는 시스템 시간(한국 시간 기준)으로 저장할 것이 때문에 USE_TZ를 False로 설정합니다.

파이썬 장고 마이그레이션 - makemigrations, migrate, reversing migrations

carrotweb — Sun, 27 Oct 2024 22:21:31 +0900

장고 기반 프로젝트를 처음 실행하면 터미널(Terminal)에 다음과 같이 붉은색으로 마이그레이션(Migration)에 대한 경고를 보여줍니다.

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.

번역하면 적용되지 않은 마이그레이션이 18개 있습니다. 당신의 프로젝트가 앱(admin, auth, contenttypes, sessions)에 대한 마이그레이션을 할 때까지 제대로 작동하지 않을 수 있습니다.

적용하려면 'python manage.py migrate'을 실행하세요.

경고가 발생한 이유는 장고 기반 프로젝트는 기본적으로 관리자 기능이 함께 제공되기 때문입니다. 그래서 관리자 앱(App)에 있는 모델(Model)들과 연동되는 테이블(Table)이 데이터베이스(Database)에 있어야 합니다.

장고 관리자 앱(admin, auth, contenttypes, sessions)은 어디에 있나요?

config 폴더에 있는 settings.py 파일에서 INSTALLED_APPS에 설정되어 있습니다.

관리자 앱들은 myenv(가상환경) > Lib > site-packages > django > contrib 폴더에 있습니다.

그리고 모델(model)들은 앱(admin, auth, contenttypes, sessions) 폴더에 있는 models.py 파일에 있습니다. (messages, staticfiles 앱에는 모델이 없습니다.)

4개의 앱에 있는 모델 클래스가 18개 있습니다. 그래서 마이그레이션 대상이 18개가 있다고 한 겁니다.

마이그레이션에 대한 내용 아래에서 자세히 다루겠습니다.

그럼 데이터베이스는 어디서 설정해야 할까요?

데이터베이스에 대한 설정은 config 폴더에 있는 settings.py 파일에서 DATABASES에 SQLite3로 설정되어 있습니다.

왼쪽 EXPLORER를 보면 db.sqlite3 파일이 추가된 것을 확인할 수 있습니다.

이 추가된 db.sqlite3 파일이 데이터베이스로 사용될 파일입니다.

SQLite3는 Python에 포함되어 있어 별도로 설치할 필요가 없습니다. 그래서 개발할 때 편리하게 사용할 수 있습니다.

만약, 데이터베이스를 MariaDB, MySQL, PostgreSQL로 변경하실 경우에는 settings.py 파일에서 DATABASES를 변경하고 싶은 데이터베이스로 변경하시면 됩니다.

그럼 마이그레이션을 통해 데이터베이스에 관리자 테이블들을 생성해 보겠습니다.

마이그레이션을 하기 위해서는 마이그레이션 파일(마이그레이션 클래스가 있는 파일)을 생성해야 합니다.

마이그레이션 클래스는 앱(app)에 모델(model)이 추가되거나 변경되었을 때 데이터베이스에 테이블을 추가, 수정, 삭제하거나 테이블의 컬럼을 추가, 수정, 삭제할 수 있게 해 줍니다.

모델이 추가되면 migrations.CreateModel
모델이 수정되면 migrations.AlterModelTable
모델이 삭제되면 migrations.DeleteModel
모델에 필드가 추가되면 migrations.AddField
모델에 필드가 수정되면 migrations.AlterField
모델에 필드가 삭제되면 migrations.RemoveField

마이그레이션 클래스에 대한 더 자세한 내용 장고 문서 사이트를 참고하시기 바랍니다. (https://docs.djangoproject.com/en/5.1/ref/migration-operations/)

예를 들어, 모델이 추가되면 마이그레이션 클래스의 오퍼레이션에 migrations.CreateModel 클래스로 테이블과 테이블의 필드를 추가할 수 있습니다. (admin의 LogEntry 모델에 대한 마이그레이션 파일입니다.)

예를 들어, 모델이 수정되면 마이그레이션 클래스의 오퍼레이션에 migrations. AlterField 클래스로 테이블의 필드를 수정할 수 있습니다. (auth의 Permission모델에 대한 마이그레이션 파일입니다.)

앱(App)에 모델(Model)이 있으면 반드시 모델에 대한 마이그레이션 클래스가 있어야 합니다.

하나의 마이그레이션 파일에는 앱에 있는 모델 수만큼 마이그레이션 클래스가 있어야 합니다.

그럼 마이그레이션 클래스를 직접 만들어야 할까요?

아닙니다. 직접 만들 수 있지만 장고에서는 마이그레이션 클래스를 자동으로 생성해 주는 makemigrations 명령어를 지원하고 있습니다.

makemigrations(메이크 마이그레이션)

마이그레이션 클래스를 생성해 주는 명령어인 makemigrations를 터미널(Terminal)에서 실행합니다.

python manage.py makemigrations {앱 이름}

(앱 이름}은 모델이 변경된 앱의 이름입니다.

(앱 이름}이 있으면 해당 앱에서만 추가되거나 변경된 모델이 있는지 확인해서 마이그레이션 클래스를 생성해 줍니다.

(앱 이름}이 없으면 전체 앱을 대상으로 추가되거나 변경된 모델이 있는지 확인해서 마이그레이션 클래스를 생성해 줍니다.

장고 관리자의 앱(admin, auth, contenttypes, sessions)에 대해 하나씩 실행할 수 있지만 전체 앱을 대상으로 실행하겠습니다.

python manage.py makemigrations

makemigrations를 실행하면 터미널(Terminal)에 No changes detected (감지된 변경이 없습니다.)라고 나옵니다.

왜 장고 관리지 앱에 대해 마이그레이션 클래스가 있는 파일이 생성되지 않았을까요?

마이그레이션 파일을 생성한 적이 없는 왜 변경된 게 없다고 할까요?

그 이유는 이미 장고 관리자 앱에는 마이그레이션 클래스가 있는 파일이 생성되어 있고 우리가 관리자 앱에 있는 모델을 수정한 적이 없기 때문입니다.

위에서 마이그레이션 클래스를 설명할 때 예시로 보여드린 화면을 보시면 django의 auth 앱에 migrations 폴더에서 마이그레이션 파일들이 있는 것을 볼 수 있습니다.

다음은 django의 contenttypes 앱에 migrations 폴더에 있는 마이그레이션 파일입니다.

위와 같이 앱에 모델이 있을 경우 makemigrations를 실행하면 앱에 있는 migrations 폴더에 마이그레이션 파일이 생성됩니다.

예를 들어, test라는 앱을 마이그레이션 한다면 test 앱에 있는 migrations 폴더에 0001_initial.py 파일이 생성됩니다.

python manage.py makemigrations test

test/ --> 앱 폴더
    migrations/ --> 마이그레이션 폴더 (앱 생성시 자동으로 생성됩니다.)
        __init__.py --> 초기화 파일 (파일에 내용은 없습니다. 앱 생성시 자동으로 생성됩니다.)
        0001_initial.py --> 처음 생성된 마이그레이션 파일

__init__.py 파일은 마이그레이션을 초기화하기 위해서 생성되는 파일입니다.

생선 된 마이그레이션 파일 명을 보면 앞에 0001_처럼 번호가 있는 것을 볼 수 있습니다.

이 번호는 makemigrations를 실행할 때 앱의 모델이 추가되거나 변경된 것이 있으면 자동으로 번호가 증가하여 마이그레이션 파일 명에 추가됩니다.

다음처럼, auth 앱은 처음 마이그레이션(0001_initial.py) 한 후 11번을 수정(0012_alter_user_first_name_max_length.py) 한 것을 알 수 있습니다.

이 번호는 또한 마이그레이션을 이전 상태로 변경하고 싶을 때 사용됩니다.

그럼 생성된 마이그레이션 파일을 통해 마이그레이션을 실행해 보겠습니다.

Migrate(마이그레이트)

마이그레이션을 실행해 주는 명령어인 migrate를 터미널(Terminal)에서 실행합니다.

python manage.py migrate {앱 이름} {마이그레이션 번호}

(앱 이름}은 마이그레이션을 할 앱의 이름입니다.

(앱 이름}이 있으면 해당 앱에서만 마이그레이션을 실행합니다.

(앱 이름}이 없으면 전체 앱을 대상으로 마이그레이션을 실행합니다.

(마이그레이션 번호}는 마이그레이션을 할 번호입니다.

(마이그레이션 번호}가 있으면 번호로 만들어진 마이그레이션 파일을 실행합니다. (Reversing Migrations - 이전 번호를 입력하면 이전 상태로 되돌아가게 됩니다.)

(마이그레이션 번호}가 없으면 전체 마이그레이션 파일을 실행합니다.

Reversing Migrations는 아래에서 설명드리겠습니다.

우리는 처음 실행하기 때문에 (앱 이름}과 (마이그레이션 번호}를 입력하지 않고 실행하겠습니다.

python manage.py migrate

실행 결과를 보면 장고 관리자의 앱(admin, auth, contenttypes, sessions)에 있는 마이그레이션 파일들이 실행된 것을 알 수 있습니다.

DBeaver로 db.sqlite3 파일을 오픈해 보면 장고 관리자 테이블들이 생성된 것을 확인할 수 있습니다.

Reversing Migrations(리버싱 마이그레이션, 마이그레이션을 이전 상태로 되돌리기)

다음처럼, test앱에서 3번의 마이그레이션을 실행했다고 가정하겠습니다.

test/
    migrations/
        __init__.py
        0001_initial.py
        0002_alter_user_name_max_length.py
        0003_alter_user_email_max_length.py

여기서 모델에 있는 메일의 길이가 수정할 필요가 없어졌다면 어떻게 해야 할까요?

모델에 있는 메일의 길이를 다시 이전 길이로 수정하고 다시 makemigrations를 실행하고 migrate를 실행합니다. (그럼 0004 마이그레이션 파일이 생성되고 실행됩니다.)

또는 이전 마이그레이션(0002)으로 되돌리고 0003 마이그레이션을 삭제합니다.

어떤 방식으로 해도 문제는 없습니다.

여기서는 이전 마이그레이션(0002)으로 되돌리고 0003 마이그레이션을 삭제해 보겠습니다.

마이그레이션을 0002번째로 되돌리기 위해서는 migrate를 실행할 때 test 앱과 0002 번호를 입력하면 됩니다.

python manage.py migrate test 0002

그럼 0002번째 마이그레이션으로 변경됩니다.

Operations to perform:
  Target specific migration: 0002_alter_user_name_max_length, from test
Running migrations:
  Rendering model states... DONE
  Unapplying test.0003_alter_user_email_max_length... OK

그러고 나서 0003_alter_user_email_max_length.py 파일을 삭제하면 됩니다.

마이그레이션 파일을 삭제할 때는 주의를 기울여야 합니다.

왜냐하면, 마이그레이션 파일은 이전 번호 마이그레이션에 의존하게 되어 있습니다.

그래서 중간에 있는 마이그레이션 파일은 임의로 삭제하면 안 됩니다.

다음처럼, auth 앱에 마지막 마이그레이션 파일을 보게 되면 dependencies에 "0011_update_proxy_permissions"과 의존하고 있는 것을 확인할 수 있습니다.

반드시 이전 번호로 Reversing Migrations 한 후에 마이그레이션 파일을 삭제하시길 바랍니다.

마이그레이션에 대한 더 자세한 내용 장고 문서 사이트를 참고하시기 바랍니다. (https://docs.djangoproject.com/en/5.1/topics/migrations/)

그럼 테스트로 auth 앱의 마이그레이션을 0011번으로 Reversing Migrations 한 후에 다시 0012번으로 마이그레이션 해보겠습니다.

python manage.py migrate auth 0011

python manage.py migrate auth 0012

파이썬 장고 설치 및 프로젝트 생성, 실행 - Installing Django, django-admin startproject, manage.py runserver

carrotweb — Sun, 20 Oct 2024 20:59:40 +0900

장고(Django)는 하이 레벨 파이썬 웹 프레임워크(high-level Python web framework)입니다.

웹 개발에 필요한 구성과 환경 설정들을 프레임워크가 처리해 주기 때문에 개발에 더 집중할 수 있습니다.

그리고 무료이며 오픈 소스입니다.

장고(Django)는 프런트엔드(사용자 대면)와 백엔드(데이터베이스 및 로직)를 모두 개발할 수 있는 풀 스택 프레임워크(Full Stack Framework)입니다.

Django에서 D가 묵음이기 때문에 "드장고"가 아닌 "장고"로 읽으시면 됩니다.

더 자세한 내용 장고 사이트를 참고하시기 바랍니다. (https://www.djangoproject.com)

장고 확인

현재 가상 환경에 장고가 설치되어 있는지 확인하기 위해서 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

python -m django --version

저는 가상 환경에 장고가 아직 설치되어 있지 않아서 "No module named django(장고라는 모듈이 없습니다.)"라고 나옵니다.

그럼 가상 환경에 장고를 설치해 보겠습니다.

장고 설치

장고를 설치하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

pip install django=={버전}

현재 작성 당시 버전은 5.1.2입니다.

pip install Django==5.1.2

버전을 입력하지 않으면 현재 최신 버전으로 설치됩니다.

pip install django

장고는 다음처럼 버전에 대한 지원 연도를 알려주고 있습니다.

그래서 특정 연도에 지원이 되지 않는 버전을 사용하고 있을 경우 장고 버전을 업그레이드해야 합니다.

지원이 되지 않는다고 해서 사용할 수 없는 것은 아닙니다. 다만, 보안 관련 이슈나 오류에 대해 더 이상 지원하지 않을 뿐입니다.

더 자세한 내용 장고 사이트를 참고하시기 바랍니다. (https://www.djangoproject.com/download/)

저는 최신 버전을 설치하기 위해 버전을 입력하지 않았습니다.

pip install django

장고를 설치한 후 다시 버전을 확인해 보면 5.1.2이 설치된 것을 알 수 있습니다.

그리고 가상 환경 폴더(myenv)의 Lib 폴더를 보면 장고(django)와 관련 모듈(asgiref, sqlparse, tzdata)들이 설치되어 있는 것을 확인할 수 있습니다.

그럼 장고를 기반으로 하는 프로젝트를 만들어 보겠습니다.

프로젝트 생성

프로젝트 관리 파일(manage.py)과 프로젝트 패키지 파일(settings.py, urls.py, asgi.py, wsgi.py)들을 생성하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

django-admin startproject {이름} {디렉토리}

django-admin은 장고를 관리하는 명령입니다.

django-admin <command> [options]

django-admin startproject 명령은 프로젝트가 구동될 수 있게 구조를 생성해 줍니다.

{이름}은 프로젝트 패키지 파일들이 들어갈 폴더 이름입니다.

{디렉토리}는 프로젝트를 생성할 디렉터리입니다. (현재 디렉토리에서 생성할 경우 "."를 입력하고 다른 디렉토리로 생성할 경우 디렉토리를 입력하면 됩니다.)

더 자세한 내용 장고 문서 사이트를 참고하시기 바랍니다. (https://docs.djangoproject.com/en/5.1/ref/django-admin/#startproject)

저는 현재 폴더에 프로젝트 구조를 생성할 것이 때문에 "."를 입력하였고 프로젝트 패키지 파일들이 들어갈 폴더 이름은 "config"으로 입력하였습니다.

django-admin startproject config .

EXPLORER를 보면 PROJECT1 폴더에 config 폴더(프로젝트 패키지 파일들이 있는 폴더)와 manage.py(프로젝트 관리 파일)가 생성된 것을 확인할 수 있습니다.

그럼 프로젝트를 실행해 보도록 하겠습니다.

프로젝트 실행(개발 웹 서버 실행)

1. 파이썬에서 제공하는 개발 웹 서버로 프로젝트를 실행하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

python manage.py runserver

개발 웹 서버는 로컬 컴퓨터에서 실행되기 때문에 도메인이 127.0.0.1로 실행되고 포트를 입력하지 않으면 자동으로 8000으로 설정되어 실행됩니다.

더 자세한 내용 장고 문서 사이트를 참고하시기 바랍니다. (https://docs.djangoproject.com/en/5.1/ref/django-admin/#runserver)

2. 웹 브라우저에서 "http://127.0.0.1:8000/"를 입력합니다.

장고 프로젝트에서 제공하는 기본 페이지가 실행되는 것을 확인할 수 있습니다.

윈도우 파이썬 가상 환경 생성 - Python venv - Creation of virtual environments

carrotweb — Sun, 6 Oct 2024 18:28:31 +0900

파이썬은 프로젝트 별로 파이썬 환경이 독립될 수 있도록 가상 환경(virtual environments)을 제공하고 있습니다.

가상 환경을 생성하면 프로젝트 별로 다른 라이브러리와 버전을 다르게 설치하고 관리할 수 있게 됩니다.

왜 가상 환경을 생성해야 할까요? 그냥 필요한 라이브러리를 설치하면 안 될까요?

여러 프로젝트들이 동일한 환경에서 개발되면 문제가 없겠지만 여러 프로젝트들이 다르게 사용하는 라이브러리가 있거나 다른 라이브러리 버전이 있을 경우에는 문제 됩니다. 그래서, 프로젝트 별로 가상 환경을 생성하고 가상 환경에 라이브러리를 설치하면 이런 문제점들을 해결할 수 있습니다.

더 자세한 내용은 파이썬 문서를 참고하시기 바랍니다. (https://docs.python.org/3/library/venv.html)

(python 사이트 상단에 있는 Docs 클릭 > Python 3.12.7 documentation에서 Library reference 클릭 > The Python Standard Library에서 Software Packaging and Distribution에 있는 venv — Creation of virtual environments 클릭)

가상 환경은 파이썬 3.3에 추가된 기능입니다. (파이썬 3.3.0은 2012년 9월 29일에 릴리즈 되었기 때문에 오래전에 설치하지 않았다면 사용하는 데는 문제가 없을 겁니다.)

설치된 파이썬의 버전을 확인하기 위해서는 콘솔에서 다음과 같이 명령어를 실행합니다.

python --version

저는 Python 3.12.4가 설치되어 있습니다. (파이썬 저장 위치 : C:\workspaces\Python\python312)

현재 PC에 설치된 파이썬 라이브러리를 확인하기 위해서는 콘솔에서 다음과 같이 명령어를 실행합니다.

pip list

저의 PC에는 다른 라이브러리가 설치되어 있지 않습니다. (pip 버전이 24.2로 업그레이드되었다고 알려주네요. 아래에 있는 명령어를 실행하여 업그레이드를 해야겠습니다.)

pip는 파이썬 패키지를 설치하고 관리해 주는 패키지 관리 시스템입니다. (https://pypi.org/project/pip/)

pip는 파이썬 설치 프로그램에서 선택하여 설치할 수 있습니다. (기본적으로 pip는 체크되어 있습니다.)

가상 환경은 콘솔에서 생성할 수 있습니다. 그러나 저는 새로운 프로젝트를 위해 폴더를 생성하고 프로젝트에서 사용할 가상 환경을 생성하도록 하겠습니다. 그리고 개발 IDE로 Visual Studio Code를 사용하겠습니다.

가상 환경 생성

1. 프로젝트 폴더를 생성합니다. (저는 C:\workspaces\projects\project1 폴더를 생성하였습니다.)

2. Visual Studio Code의 메뉴 File(파일) > Open Folder...(폴더 열기)를 클릭하여 "C:\workspaces\projects\project1" 폴더로 이동하고 "폴더 선택" 버튼을 누르면 폴더가 오픈됩니다.

보안을 위해 Trust(신뢰) 확인 창이 나타납니다. "Yes, I Trust the authors" 버튼을 누릅니다. 그리고 Welcome 창은 닫습니다.

python -m venv {가상 환경 이름 또는 경로를 포함한 가상 환경 이름}

저는 가상 환경 이름을 myenv(my environments)라고 하였습니다.

python -m venv myenv

가상 환경이 생성되면 project1 폴더에 myenv라는 폴더가 생성됩니다.

가상 환경 폴더 구조는 다음과 같습니다.

project1/
    myenv/ --> 가상 환경 풀더
        Lib --> 가상 환경에서 pip로 설치한 라이브러리들이 저장되는 폴더
        Scripts --> 가상 환경을 관리하는 스크립트가 있는 폴더

4. 생성된 가상 환경을 활성화하기 위해서는 myenv의 Scripts 폴더에 있는 activate를 Terminal(터미널)에서 실행해야 합니다.

cd myenv\Scripts                                                               
./activate

가상 환경이 활성화되면 가상 환경 이름인 (myenv)가 표시됩니다.

(myenv) PS C:\workspaces\projects\project1\myenv\Scripts>

이제 새로운 프로젝트를 위한 가상 환경이 생성되었습니다. (가상 환경이 활성화되어 있어야 pip로 설치한 라이브러리들이 가상 환경의 Lib 폴더에 저장이 됩니다.)

가상 환경의 파이썬의 버전을 확인해 보면 Python 3.12.4인 것을 알 수 있습니다.

그리고 설치된 파이썬 라이브러리를 확인하면 pip가 있는 것을 확인할 수 있습니다.

가상 환경을 비활성화하기 위해서는 myenv의 Scripts 폴더에 있는 deactivate를 Terminal(터미널)에서 실행해야 합니다.

deactivate

다른 버전의 파이썬으로 가상 환경 생성

저의 PC에는 다른 파이썬 버전인 3.11.1도 설치되어 있습니다. (파이썬 저장 위치 : C:\workspaces\Python\python311)

1. 프로젝트 폴더를 생성합니다. (저는 C:\workspaces\projects\project2 폴더를 생성하였습니다.)

2. Visual Studio Code의 메뉴 File(파일) > Open Folder...(폴더 열기)를 클릭하여 "C:\workspaces\projects\project2" 폴더를 오픈하였습니다.

3. Visual Studio Code의 메뉴 Terminal(터미널) > New Terminal(새 터미널)를 클릭하고 가상 환경을 생성하기 위해 Terminal(터미널)에서 다음과 같이 명령어를 실행합니다.

py -{파이썬 버전} -m venv myenv

여러 버전의 파이썬이 설치되어 있으면 python 명령어 대신 py 명령어를 사용하여 버전 별로 실행해야 합니다.

저는 3.11 버전으로 가상 환경을 생성하였습니다.

py -3.11 -m venv myenv

4. 생성된 가상 환경을 활성화하기 위해서는 myenv의 Scripts 폴더에 있는 activate를 Terminal(터미널)에서 실행했습니다. 그리고 가상 환경의 파이썬의 버전을 확인해 보았습니다.

가상 환경이 다른 파이썬 버전으로 생성된 것을 확인할 수 있습니다.

py 명령어 대신 다른 파이썬 버전이 설치되어 있는 경로를 이용해서 가상 환경을 생성할 수도 있습니다.

C:\workspaces\projects\project2> C:\workspaces\Python\python311\python.exe -m venv myenv

py 명령어

여러 버전의 파이썬이 설치되어 있을 경우 py 명령어를 사용하여 버전 별로 파이썬을 실행할 수 있습니다.

콘솔에서 다음과 같이 명령어를 실행합니다.

py -h

설치되어 있는 버전으로 파이썬을 실행하기 위해서는 launcher-args(Launcher arguments)에 실행할 버전을 입력하면 됩니다.

py [launcher-args]

설치되어 있는 파이썬 버전인 3.11.1과 3.12.4를 py 명령어를 이용하여 실행하고 3.X 버전 중 마지막 버전으로 실행되게 하였습니다.

py -3.11
py -3.12
py -3

three.js 3D 모델을 glTF 파일로 다운로드하기(.glb or .gltf)

carrotweb — Sun, 29 Oct 2023 19:44:33 +0900

이어서 추출된 glTF 정보를 .glb 파일(바이너리) 또는 .gltf 파일(JSON)로 다운로드하여 저장할 수 있게 헤보겠습니다.

glTF 정보를 스크립트에서 다운로드하기 위해서는 URL.createObjectURL() 메서드를 사용하면 됩니다.

URL.createObjectURL() 메서드에 대한 영문 설명은 다음과 같습니다.

The URL.createObjectURL() static method creates a string containing a URL representing the object given in the parameter.

번역해 보면 URL.createObjectURL() 정적 메서드는 파라미터로 전달받은 객체를 가리키는 URL이 포함된 문자열을 생성합니다.

URL.createObjectURL(object)

object: File, Blob, MediaSource 객체입니다.

즉, File 객체 또는 Blob 객체 또는 MediaSource 객체를 URL로 접근할 수 있게 아래와 같이 Blob URL를 생성하여 리턴하게 됩니다.

blob:http://localhost:5173/c95eb15c-3c2d-4ca1-b327-8e25a8bfe73e

그리고 URL.createObjectURL() 정적 메서드를 사용할 때마다 새로운 Blob URL를 생성되기 때문에 생성된 Blob URL은 URL.revokeObjectURL() 정적 메서드를 사용하여 해제해줘야 합니다.

그러나 생성된 Blob URL를 해제하지 않아도 웹 브라우저가 unload(다른 경로로 이동하거나 웹 브라우저가 종료될 때)가 되면 웹 브라우저가 자동으로 해제해 줍니다.

추가적으로 URL.createObjectURL()와 URL.revokeObjectURL() 정적 메서드로 blob URL를 생성하고 해제하는 방법은 W3C의 Creating and Revoking a blob URL를 참고하시기 바랍니다.

URL.createObjectURL() 정적 메서드로 Blob URL를 생성하기 위해서는 먼저 glTF 정보를 Blob 객체로 만들어야 합니다.

Blob(Binary Large Object, 비랍/블랍)은 대용량의 바이너리로 저장된 객체입니다.

new Blob(array, options)

array: ArrayBuffer[] 또는 TypedArray[] 또는 DataView[] 또는 USVString(UTF-8로 인코딩 된 string[]) 또는 다른 Blob 배열 객체이거나 객체 또는 여러 개의 타입이 혼합된 배열 객체입니다.
options: 데이터의 type과 endings을 설정하는 옵셥입니다.

options은 다음과 같이 설정할 수 있습니다.

type: 저장될 데이터의 MIME 타입입니다. 기본값 ""(빈 문자열)
endings(transparent, native): array 타입이 USVString(UTF-8로 인코딩 된 string[])일 때 개행 문자("\n")를 사용 중인 OS에 맞춰서 개행 문자를 변환할지(native) 아니면 변환하지 않을지(transparent) 선택합니다. 기본값 transparent

그럼 추출된 glTF 정보를 Blob(Binary Large Object, 비랍/블랍)으로 만들고 Blob URL를 생성하여 파일로 다운로드해 보겠습니다.

1. 추출된 glTF 정보를 파라미터로 받아 바이너리 형식과 JSON 형식의 Blob 객체를 만드는 함수를 만듭니다.

바이너리 형식으로 변환하기 위해서 options의 type를 "application/octet-stream"으로 설정합니다.

// 바이너리 형식으로 변환
function downloadBinary(buffer) {
    const blob = new Blob([buffer], {type: 'application/octet-stream'});
    console.log("Blob:", blob);
}

JSON 형식으로 변환하기 위해서 추출된 glTF 정보를 JSON 문자열로 변환하고 options의 type를 "application/json"으로 설정합니다.

// JSON 형식으로 변환
function downloadJSON(buffer) {
    const blob = new Blob([JSON.stringify(buffer)], {type: 'application/json'});
    console.log("Blob:", blob);
}

2. 기존 ExportglTF() 함수에 downloadBinary()와 downloadJSON()를 추가합니다. glTF 정보가 ArrayBuffer[]이면 downloadBinary() 함수를 호출하고 그렇지 않으면 downloadJSON() 함수를 호출하게 합니다.

function ExportglTF() {
    // GLTF익스포트 생성
    const exporter = new GLTFExporter();

    // GLTF익스포트 옵션 - 바이너리 형식으로 추출
    const options = {
        binary: false
    };

    exporter.parse(
        box2,
        function (gltf) {
            if (gltf instanceof ArrayBuffer) {
                console.log("export gltf:", gltf);
                downloadBinary(gltf);
            } else {
                console.log("export gltf:", gltf);
                downloadJSON(gltf);
            }
        },
        function (error) {
            console.error("exporter error:", error);
        },
        options
    );
}

Controls에서 "Export" 버튼을 클릭하면 콘솔에 Blob 객체 정보가 출력됩니다.

만약 glTF 익스포트 옵션의 binry가 flase이면 JSON 형식으로 다음과 같이 콘솔에 출력됩니다.

// GLTF익스포트 옵션 - JSON 형식으로 추출
const options = {
    binary: false
};

3. 파일로 다운로드하기 위해서 Blob 객체를 파라미터로 받는 다운로드 함수를 만듭니다.

다운로드 URL를 생성하기 위해서 URL.createObjectURL() 메서드를 사용합니다.

// 다운로드
function download(blob) {
    const blobURL = URL.createObjectURL(blob);
    console.log(blobURL);
}

기존 downloadBinary()와 downloadJSON()에 다운로드 함수를 추가합니다.

// 바이너리 형식으로 변환
function downloadBinary(buffer) {
    const blob = new Blob([buffer], {type: 'application/octet-stream'});
    console.log("Blob:", blob);
    download(blob);
}

// JSON 형식으로 변환
function downloadJSON(buffer) {
    const blob = new Blob([JSON.stringify(buffer)], {type: 'application/json'});
    console.log("Blob:", blob);
    download(blob);
}

Controls에서 "Export" 버튼을 클릭하면 콘솔에 Blob URL이 출력됩니다.

blob:http://localhost:5173/b8c1b2f5-f4ee-4a9d-b286-7aed8af4dd47

만약 glTF 익스포트 옵션의 binry가 flase이면 JSON 형식으로 다음과 같이 Blob URL이 콘솔에 출력됩니다.

// GLTF익스포트 옵션 - JSON 형식으로 추출
const options = {
    binary: false
};

blob:http://localhost:5173/b86e8950-8d45-4b8c-8822-16703dc678c2

4. 생성된 Blob URL로 다운로드하기 위해서 A 태그를 생성하고 href 속성 값으로 Blob URL를 설정합니다. 그리고 생성된 A 태그를 페이지에 추가하고 click() 메서드로 A 태그를 클릭하여 다운로드하게 합니다. 다운로드 후 생성된 Blob URL를 해제하고 페이지에 추가된 A 태그를 삭제합니다.

// 다운로드
function download(blob) {
    const blobURL = URL.createObjectURL(blob);
    console.log(blobURL);
    // 다운로드를 하기위해 Blob URL로 A 태그 생성
    const link = document.createElement('a');
    link.href = blobURL;
    // 다운로드 파일 명
    link.download = "test.glb";
    // A 태그 추가
    document.body.appendChild(link);
    // A 태그를 클릭하여 다운로드
    link.click();
    // 다운로드 후 Blob URL 해제
    URL.revokeObjectURL(blobURL);
    // A 태그 삭제
    document.body.removeChild(link);
}

Controls에서 "Export" 버튼을 클릭하면 콘솔에 glTF 파일이 다운로드됩니다.

그럼 glTF 익스포트 옵션과 다운로드되는 파일 명을 변경할 수 있게 처리해 보겠습니다.

5. Controls에서 glTF 익스포트 옵션을 변경하고 다운로드 파일명을 변경할 수 있게 객체(exporter1)에 추가합니다.

const exporter1 = {
    ExportglTFFileName : 'test.glb',
    ExportglTFFilebinary : true,
    ExportglTFFunction : ExportglTF
};

그리고 glTF 익스포트 옵션의 binary를 exporter1의 ExportglTFFilebinary로 설정합니다.

function ExportglTF() {
    // GLTF익스포트 생성
    const exporter = new GLTFExporter();

    // GLTF익스포트 옵션 - 바이너리/JSON 형식으로 추출
    const options = {
        binary: exporter1.ExportglTFFilebinary
    };

    exporter.parse(
        box2,
        function (gltf) {
            if (gltf instanceof ArrayBuffer) {
                console.log("export gltf:", gltf);
                downloadBinary(gltf);
            } else {
                console.log("export gltf:", gltf);
                downloadJSON(gltf);
            }
        },
        function (error) {
            console.error("exporter error:", error);
        },
        options
    );
}

그리고 다운로드 함수에서 다운로드 파일명을 exporter1의 ExportglTFFileName으로 설정합니다.

// 다운로드
function download(blob) {
    const blobURL = URL.createObjectURL(blob);
    console.log(blobURL);
    // 다운로드를 하기위해 Blob URL로 A 태그 생성
    const link = document.createElement('a');
    link.href = blobURL;
    // 다운로드 파일 명
    link.download = exporter1.ExportglTFFileName;
    // A 태그 추가
    document.body.appendChild(link);
    // A 태그를 클릭하여 다운로드
    link.click();
    // 다운로드 후 Blob URL 해제
    URL.revokeObjectURL(blobURL);
    // A 태그 삭제
    document.body.removeChild(link);
}

그리고 Controls에 추가합니다.

folder2.add(exporter1, 'ExportglTFFileName');
folder2.add(exporter1, 'ExportglTFFilebinary');
folder2.add(exporter1, 'ExportglTFFunction').name('Export');

그리고 Controls에 ExportglTFFileName과 ExportglTFFilebinary가 추가됩니다.

6. ExportglTFFilebinary가 체크되면 ExportglTFFileName의 확장자를 ".glb"로 변경시키고 ExportglTFFilebinary가 체크되지 않으면 ExportglTFFileName의 확장자를 ".gltf"로 변경되게 함수를 만듭니다.

// 파일 저장 형식에 따른 파일 확장자 변경
function updatesglTFFileName() {
    let fileName = exporter1.ExportglTFFileName;
    const pos = fileName.lastIndexOf('.');
    if (pos > 0) {
        if (exporter1.ExportglTFFilebinary) {
            exporter1.ExportglTFFileName = fileName.substring(0, pos) + ".glb";
        } else {
            exporter1.ExportglTFFileName = fileName.substring(0, pos) + ".gltf";
        }
    }
}

확장자를 변경하는 함수를 ExportglTFFilebinary에서 onChange()로 처리되게 추가하고 Controls에 있는 ExportglTFFileName이 변경된 확장로 변경되도록 listen() 함수를 추가합니다.

folder2.add(exporter1, 'ExportglTFFileName').listen();
folder2.add(exporter1, 'ExportglTFFilebinary').onChange(updatesglTFFileName);
folder2.add(exporter1, 'ExportglTFFunction').name('Export');

Controls에서 ExportglTFFilebinary를 선택할 때마다 ExportglTFFileName의 확장자가 변경되는 것을 확인할 수 있습니다.

그리고 Controls에서 "Export" 버튼을 클릭하면 변경된 확장자로 다운로드되는 것을 확인할 수 있습니다.

three.js 3D 모델 추출하기(glTF JSON or Binary) - GLTFExporter

carrotweb — Tue, 10 Oct 2023 00:10:02 +0900

이어서 우리가 만든 Object(객체, 3D 모델)을 glTF 포맷으로 추출해 보겠습니다.

1. import를 통해 GLTFExporter(GLTF익스포트) 모듈을 가져옵니다. GLTFExporter(GLTF익스포트)는 Scence(씬, 장면)이나 Scence(씬, 장면)에 있는 Object(객체)들을 glTF 포맷으로 추출합니다.

import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';

GLTFExporter(GLTF익스포트) 모듈의 실제 위치는 "\node_modules\three\examples\jsm\exporters\GLTFExporter.js" 입니다.

2. Scence(씬, 장면)이나 Scence(씬, 장면)에 있는 Object(객체)들을 glTF 포맷으로 추출하기 위한 함수를 만듭니다.

function ExportglTF() {
}

3. glTF 포맷으로 추출하기 위해 함수에 GLTFExporter(GLTF익스포트)를 생성합니다.

GLTFExporter()

파라미터는 없습니다.

GLTFExporter(GLTF익스포트)를 생성합니다.

function ExportglTF() {
    // GLTF익스포트 생성
    const exporter = new GLTFExporter();
}

Scence(씬, 장면)이나 Scence(씬, 장면)에 있는 Object(객체)들을 GLTFExporter(GLTF익스포트)의 parse(파서) 함수로 추출합니다.

.parse (input : Object3D, onCompleted : Function, onError : Function, options : Object)

input: 추출할 Scence(씬, 장면) 또는 Scence(씬, 장면)에 있는 Object(객체)입니다.
onCompleted: glTF 포맷으로 추출된 후 호출되는 함수입니다. (함수 파라미터로 glTF JSON 또는 바이너리(ArrayBuffer)를 넘겨줍니다.)
onError: glTF 생성 중에 오류가 발생하면 호출되는 함수입니다. (함수 파라미터로 에러 정보를 넘겨줍니다.)
options: 추출할 때 사용되는 옵션입니다.

input은 다음과 같이 설정할 수 있습니다.

Scence(씬, 장면)를 추출할 경우

// 하나의 Scence(씬, 장면)를 추출할 경우
exporter.parse(scene1, ...)
// 여러 개의 Scence(씬, 장면)를 추출할 경우 (배열로 추가)
exporter.parse([scene1, scene2], ...)

Scence(씬, 장면)에 있는 Object(객체)를 추출할 경우

// 하나의 객체(3D 모델)를 추출할 경우
exporter.parse(object1, ...)
// 여러 개의 객체(3D 모델)를 추출할 경우 (배열로 추가)
exporter.parse([object1, object2], ...)

Scence(씬, 장면)과 Object(객체)를 썩어서 추출할 경우

// 하나 또는 여러개의 Scence(씬, 장면)과 객체(3D 모델)를 썩어서 추출할 경우
exporter.parse([scene1, object1, object2, scene2], ...)

Object(객체)나 Scence(씬, 장면)과 객체를 썩어서 추출할 경우에는 새로운 Scence(씬, 장면)을 생성하여 glTF 포맷으로 추출됩니다.

options은 다음과 같이 설정할 수 있습니다.

trs: 추출되는 로드마다 Matrix 정보 대신 Position(위치), Rotation(회전), Scale(크기) 정보로 내보낼지 여부입니다. 기본값 false
onlyVisible: 보이는 Object(객체)만 추출할지 여부입니다. 기본값 true
binary: 바이너리(.glb) 형식으로 추출할지 여부입니다. 기본값 false
maxTextureSize: 텍스처(이미지)의 최대 크기(너비와 높이를 곱한 값)를 지정된 값으로 제한합니다. 기본값 Infinity(무한대)
animations: 추출할 애니메이션 목록입니다.
includeCustomExtensions: userData.gltfExtensions 속성으로 정의된 사용자 정보를 내보낼지 여부입니다. 기본값 false

우리는 Object(객체, 3D 모델)을 바이너리(.glb) 형식으로 추출하기 위해서 options에 binary를 true로 설정합니다.

function ExportglTF() {
    // GLTF익스포트 생성
    const exporter = new GLTFExporter();

    // GLTF익스포트 옵션 - 바이너리 형식으로 추출
    const options = {
        binary: true
    };
}

그리고 parse 함수로 주사위 객체를 glTF 포맷으로 추출하게 input에 box2를 설정하고 onCompleted에서는 생성된 glTF 포맷 정보를 콘솔 로그로 출력되게 함수를 설정하고 onError에서는 오류 정보가 콘솔 로그로 출력되게 합니다.

function ExportglTF() {
    // GLTF익스포트 생성
    const exporter = new GLTFExporter();

    // GLTF익스포트 옵션 - 바이너리 형식으로 추출
    const options = {
        binary: true
    };

    exporter.parse(
        box2,
        function (gltf) {
            if (gltf instanceof ArrayBuffer) {
                console.log("export gltf:", gltf);
            } else {
                console.log("export gltf:", gltf);
            }
        },
        function (error) {
            console.error("exporter error:", error);
        },
        options
    );
}

5. glTF 추출 함수를 호출하기 위해서 Controls에 별도의 Folder(폴더)를 추가합니다.

// 컨트롤러에 glTF 포맷으로 추출하기 위한 Folder(폴더) 추가
const folder2 = gui.addFolder('GLTFExporter');

Controls에서 버튼을 생성하기 위해서는 객체의 parameters(파라미터)를 값을 function으로 선언하면 됩니다.

const myObject = {
	myFunction: function() { ... }
};

우리는 위에서 만든 ExportglTF() 함수로 객체를 생성하고 Folder(폴더)에 추가합니다.

const exporter1 = {
    ExportglTFFunction : ExportglTF
};

folder2.add(exporter1, 'ExportglTFFunction').name('Export');

6. Controls에서 "Export" 버튼을 클릭하면 콘솔에 바이너리(ArrayBuffer)로 추출된 glTF 정보가 출력됩니다.

만약 JSON 형식으로 추출하고 싶다면 options에서 binary를 false로 설정하면 됩니다.

// GLTF익스포트 옵션 - JSON 형식으로 추출
const options = {
    binary: false
};

그리면 콘솔에 JSON 형식으로 추출된 glTF 정보가 출력됩니다.

이어서 추출된 glTF 정보를 .gltf 파일과 .glb 파일로 다운로드해 보겠습니다.

three.js 3D 모델 불러오기(glTF 파일 로드) - GLTFLoader

carrotweb — Sun, 10 Sep 2023 18:35:01 +0900

이번에는 외부에서 만들어진 3D 모델을 로드하여 Scence(씬, 장면)에 추가해 보도록 하겠습니다.

3D 모델들은 다양한 파일 포맷으로 저장됩니다. 대표적인 3D 파일 포맷으로 OBJ, FBX, glTF, USD가 있습니다.

다양한 파일 포맷 중에서 three.js에서는 glTF 파일 포맷을 사용하는 것을 추천하고 있습니다.

glTF(GL Transmission Format, GL 트랜스미션 포맷)는 응용프로그램에서 3D 장면과 3D 모델을 효율적으로 전송하고 로드시키는 방법에 대한 사양(규격, 명세)으로 로열티가 없는 오픈 소스 파일 포맷입니다.

glTF는 3D Assets(3D 에셋, 3D 자산(모델 정보, 텍스처, 바이너리 데이터))의 파일 크기를 최소화하였습니다. 그리고 3D Assets(3D 에셋)을 사용하기 위해 압축을 풀고 처리하는 런타임 프로세싱을 최소화하였습니다. (이것은 .glb 파일에 적용되는 내용입니다.)

glTF는 제작 작업 절차를 간소화하고 산업 전반에서 콘텐츠가 서로 호환되어 사용(상호운용)이 가능하게 3D 콘텐츠 도구 및 서비스를 위한 확장 가능한 공통 배포 포맷을 정의하였습니다.

자세한 설명은 glTF(https://github.com/KhronosGroup/glTF)를 참조하시기 바랍니다.

그럼 glTF는 어떤 구조로 되어 있을까요?

glTF 2.0 Specification(https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html)를 보면 다음과 같이 glTF의 Asset(에셋)에 대해 설명하고 있습니다.

glTF Asset(에셋, 자산)은 다음과 같이 표현됩니다.

Scence(씬, 장면)에 대한 전체 설명이 담긴 JSON 포맷 파일 (.gltf) : 노드 계층 구조, 머티리얼, 카메라 정보뿐만 아니라 메시, 애니메이션 그리고 기타 구성에 대한 설명자 정보도 포함됩니다.
지오메트리, 애니메이션 그리고 기타 버퍼 기반 데이터가 담긴 바이너리 파일 (.bin)
텍스처 이미지가 담긴 이미지 파일 (.jpg, .png, 등등)

즉, 아래 샘플(https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/BoomBox/glTF)처럼 glTF Asset(에셋, 자산)은 3개의 유형으로 JSON 포맷 파일 (.gltf), 데이터 파일 (.bin), 이미지 파일 (.jpg, .png, 등등)로 구성됩니다.

3D 모델에 대한 정보는 JSON 포맷으로 .gltf 파일로 저장되고 3D 모델의 지오메트리, 애니메이션, 스킨 정보들은 .bin 파일로 저장되고 3D 모델의 머티리얼에서 사용되는 이미지들은 각각의 이미지 파일(.jpg, .png, 등등)로 저장됩니다.

그리고 JSON 포맷 파일(.gltf)에는 데이터가 담긴 바이너리 파일 (.bin)과 이미지 파일 (.jpg, .png)들이 연결되어 있습니다.

또는 JSON 포맷 파일, 데이터 파일, 모든 이미지 파일들이 하나의 바이너리 파일 (.glb)로 결합되어 저장됩니다.

대부분 glTF는 .glb 파일로 저장되고 배포됩니다. 그 이유는 데이터 파일 (.bin)과 이미지 파일 (.jpg, .png, 등등)를 함께 배포하는 것보다 배포가 용이하기 때문입니다.

그럼 glTF 파일을 로드해 보겠습니다.

1. import를 통해 GLTFLoader(GLTF로더) 모듈을 가져옵니다. GLTFLoader(GLTF로더)는 glTF 파일을 로드합니다.

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

GLTFLoader(GLTF로더) 모듈의 실제 위치는 "\node_modules\three\examples\jsm\loaders\GLTFLoader.js" 입니다.

2. GLTF로더로 로드할 모델을 glTF-Sample-Models(https://github.com/KhronosGroup/glTF-Sample-Models/blob/master/2.0/BoomBox/glTF-Binary/BoomBox.glb)에서 다운로드합니다.

그리고 프로젝트에 resources \ textures 폴더 다운로드한 BoomBox 파일(BoomBox.glb)을 추가합니다.

VSCode에서는 glTF 파일을 볼 수 없습니다.

3. GLTFLoader(GLTF로더)를 생성합니다.

GLTFLoader(manager : LoadingManager)

manager(매니저) : GLTF로더가 사용할 LoadingManager(로딩 매니저)입니다. 기본값 THREE.DefaultLoadingManager

기본 로딩 매니저로 GLTFLoader(GLTF로더)를 생성합니다.

// GLTF로더 생성
const loader = new GLTFLoader();

4. resources \ textures 폴더에 있는 BoomBox 파일(BoomBox.glb)을 GLTFLoader(GLTF로더)로 로드합니다.

.load (url : String, onLoad : Function, onProgress : Function, onError : Function)

url: .glb 파일 또는 .gltf 파일의 웹 주소입니다.
onLoad: 로딩이 성공적으로 완료된 후 호출되는 함수입니다. (함수 파라메타로 glTF JSON를 넘겨줍니다.)
onProgress: 로딩이 진행되는 동안 호출될 함수입니다. (함수 파라메타로 로드 정보를 넘겨줍니다. - 옵션)
onError: 로딩 중 오류가 발생하면 호출되는 함수입니다. ( 함수 파라메타로 에러 정보를 넘겨줍니다. - 옵션)

onLoad 함수에서는 콘솔 로그로 로드한 glTF의 JSON 정보를 출력하고 onProgress 함수에서는 콘솔 로그로 로딩 프로세스를 출력하고 onError 함수에서는 콘솔 로그로 오류 정보를 출력하게 합니다.

// glTF 파일 로드
loader.load('resources/textures/BoomBox.glb', 
    function (gltf) {
        console.log(gltf);
    },
    function (xhr) {
        console.log((xhr.loaded / xhr.total * 100) + '% loaded');
	}, 
    function (error) {
        console.error(error);
    })
;

그러면 콘솔 로그에 로딩 프로세스가 출력되고 glTF의 JSON 정보가 출력됩니다.

5. Scence(씬, 장면)에 로드한 모델을 추가하기 위해 onLoad 함수에 glt의 scene를 추가하고 로드한 모델을 보기 위해 Camera(카메라)의 Focus Point(포커스 포인트, 초점)과 Position(포지션, 위치)를 변경합니다.

// glTF 파일 로드
loader.load('resources/textures/BoomBox.glb', 
    function (gltf) {
        console.log(gltf);
        scene.add(gltf.scene);
        // 육면체 옆으로 위치 변경
        gltf.scene.position.set(-2, 0, 0);
        // 카메라 초점 변경
        controls.target.copy(gltf.scene.position);
        // 카메라 위치 변경
        camera.position.set(-2, 1, 2);
    },
    function (xhr) {
        console.log((xhr.loaded / xhr.total * 100) + '% loaded');
	}, 
    function (error) {
        console.error(error);
    })
;

그런데 로드된 모델이 점으로 보입니다. 그 이유는 로드되는 모델마다 크기가 일정하지 않기 때문입니다. 어떤 모델은 크기가 크고 어떤 모델은 크기가 작습니다.

그럼 로드된 모델의 크기가 어떻게 되는지 확인해 보겠습니다.

onLoad 함수에서 로드된 모델의 객체를 가져옵니다. 그리고 객체의 크기를 가져와서 콘솔 로그로 출력합니다.

// 로드된 모델의 크기 확인
var gltfObject = new THREE.Box3().setFromObject(gltf.scene);
var gltfObjectSize = gltfObject.getSize(new THREE.Vector3());
console.log(gltfObjectSize);

콘솔 로그에 보면 크기가 매우 작은 것을 확인할 수 있습니다.

{
    "x": 0.019842308,
    "y": 0.01954326,
    "z": 0.0201524906
}

모델의 크기를 키우기 위해 전체 Scale(스케일)의 크기를 변경합니다. 크기를 100배 정도 크게 하겠습니다.

// glTF 파일 로드
loader.load('resources/textures/BoomBox.glb', 
    function (gltf) {
        console.log(gltf);

        // 로드된 모델의 크기 확인
        var gltfObject = new THREE.Box3().setFromObject(gltf.scene);
        var gltfObjectSize = gltfObject.getSize(new THREE.Vector3());
        console.log(gltfObjectSize);

        // 모델의 스케일 변경
        gltf.scene.scale.x = 100;
        gltf.scene.scale.y = 100;
        gltf.scene.scale.z = 100;

        scene.add(gltf.scene);
        // 육면체 옆으로 위치 변경
        gltf.scene.position.set(-2, 0, 0);
        // 카메라 초점 변경
        controls.target.copy(gltf.scene.position);
        // 카메라 위치 변경
        camera.position.set(-2, 1, 2);
    },
    function (xhr) {
        console.log((xhr.loaded / xhr.total * 100) + '% loaded');
	}, 
    function (error) {
        console.error(error);
    })
;

모델의 Scale(스케일)을 크게 하니 적당한 크기로 보입니다.

three.js GUI Controls - lil-gui, addFolder, geometry.dispose

carrotweb — Sun, 27 Aug 2023 20:40:13 +0900

이전에 만든 Controls에 아래의 three.js 사이트의 doc 처럼 SphereGeometry(스피어 지오메트리, 구 기하 도형)에 대한 속성들을 추가해 보겠습니다. (https://threejs.org/docs/index.html#api/en/geometries/SphereGeometry)

우선 Camera(카메라)의 위치(position)를 구 객체(sphere1) 앞으로 이동시키겠습니다.

현재 OrbitControls(오빗 컨트롤, 궤도 컨트롤)를 사용하고 있습니다. 그래서 항상 Camera(카메라)의 Focus Point(포커스 포인트, 초점)가 {x: 0, y: 0, z: 0} 입니다.

console.log(controls.target);
--> Vector3 {x: 0, y: 0, z: 0}

(OrbitControls(오빗 컨트롤, 궤도 컨트롤)를 사용하면 Camera(카메라)의 lookAt 함수를 사용해도 적용되지 않습니다.)

우선 Camera(카메라)의 Focus Point(포커스 포인트, 초점)을 구 객체(sphere1)의 위치로 조정하겠습니다.

console.log(sphere1.position);
--> Vector3 {x: 2, y: 1, z: -2}

OrbitControls(오빗 컨트롤, 궤도 컨트롤)의 target에 구 객체(sphere1)의 위치 값을 복사하거나 Vector3(백터)로 위치 값을 생성하여 설정합니다.

// 카메라 초점 변경
controls.target.copy(sphere1.position);

또는

// 카메라 초점 변경
controls.target = new THREE.Vector3(2, 1, -2);

그러면 Camera(카메라)의 Focus Point(포커스 포인트, 초점)가 구 객체(sphere1)의 위치로 변경됩니다.

만약, OrbitControls(오빗 컨트롤, 궤도 컨트롤)의 target에 구 객체(sphere1)의 위치 값을 바로 사용하면 OrbitControls(오빗 컨트롤, 궤도 컨트롤)에서 오른쪽 마우스로 Camera(카메라)의 위치를 변경하면 구 객체(sphere1)가 항상 중앙에 위치하게 되어 라인 세그먼트즈 객체와 분리되는 문제가 발생합니다.

controls.target = sphere1.position;

화면에 구 객체(sphere1)가 크게 보이도록 Camera(카메라)의 위치(position)를 조정합니다.

// 카메라 위치 변경
camera.position.set(2, 2.5, -1);

구 객체(sphere1)와 라인 세그먼트즈 객체(sphere1WireframeLine)는 구 그룹(sphere1Group)으로 구성되어 있습니다.

구 그룹(sphere1Group)의 첫 번째 자식은 구 객체(sphere1)이고 두 번째 자식은 와이어프레임을 선으로 그린 세그먼트즈 객체(sphere1WireframeLine)입니다.

console.log(sphere1Group.children);

라인 세그먼트즈 객체(sphere1WireframeLine)는 와이어프레임 지오메트리(sphere1WireframeGeometry)를 parameters(파라미터)로 전달받아 선으로 그립니다. 그리고 와이어프레임 지오메트리(sphere1WireframeGeometry)는 parameters(파라미터)로 구 지오메트리(sphere1Geometry)를 전달받아 와이어프레임을 생성합니다.

위에서 말한 것처럼 parameters(파라미터) 값으로 전달받기 때문에 값을 변경하여도 생성된 객체는 변경되지 않습니다.

console.log(sphere1Group.children[1].geometry.parameters.geometry.parameters.heightSegments);
--> 32

sphere1Group.children[1].geometry.parameters.geometry.parameters.heightSegments = 4;

console.log(sphere1Group.children[1].geometry.parameters.geometry.parameters.heightSegments);
--> 4

즉, 객체를 생성할 때 사용된 정보들은 객체 생성 후 변경되어도 다시 Rendering(렌더링)되지 않습니다.

그래서 Scence(씬, 장면)에 객체를 제거하고 객체를 폐기(Dispose)하고 다시 생성해서 Scence(씬, 장면)에 객체를 추가하면 됩니다. 그러나 너무 번거롭습니다.

그래서 쉽게 처리하는 방법으로 객체의 Geometry(지오메트리, 기하 도형)만 폐기(Dispose)하고 변경되는 정보로 생성하여 객체의 Geometry(지오메트리, 기하 도형)에 적용하는 겁니다.

그럼 테스트를 통해 확인해 보겠습니다.

1. 구 그룹(sphere1Group)에 있는 구 객체(sphere1)와 라인 세그먼트즈 객체(sphere1WireframeLine)의 Geometry(지오메트리, 기하 도형)를 폐기(Dispose)합니다.

// 적용된 지오메트리 폐기
sphere1Group.children[0].geometry.dispose();
sphere1Group.children[1].geometry.dispose();

2. 새로운 SphereGeometry(스피어 지오메트리, 구 기하 도형)의 radius(반지름, 반경)는 기존과 동일하게 1로 하고 widthSegments(수평 세그먼트, 가로 분절 수)와 heightSegments(수직 세그먼트, 세로 분절 수)는 10으로 설정하여 생성합니다.

// 새로운 지오메트리 생성
const sphere2Geometry = new THREE.SphereGeometry(1, 10, 10);

3. 새롭게 생성된 구 지오메트리(sphere2Geometry)를 구 객체(sphere1)의 Geometry(지오메트리, 기하 도형)에 적용시키고 라인 세그먼트즈 객체(sphere1WireframeLine)의 Geometry(지오메트리, 기하 도형)에는 구 지오메트리(sphere2Geometry)로 새로운 WireframeGeometry(와이어프레임 지오메트리)를 생성하여 적용시킵니다.

// 새로운 지오메트리 적용
sphere1Group.children[0].geometry = sphere2Geometry;
sphere1Group.children[1].geometry = new THREE.WireframeGeometry(sphere2Geometry);

그러면 변경된 정보로 변경되는 것을 확인할 수 있습니다.

만약, 구 그룹(sphere1Group)에 있는 구 객체(sphere1)의 Geometry(지오메트리, 기하 도형)는 변경하지 않고 라인 세그먼트즈 객체(sphere1WireframeLine)의 Geometry(지오메트리, 기하 도형)만 변경한다면 구의 객체의 모양과 와이어프레임 모양이 다르기 때문에 와이어프레임 선들이 구의 객체 안으로 들어가게 됩니다.

// 적용된 지오메트리 폐기
//sphere1Group.children[0].geometry.dispose();
sphere1Group.children[1].geometry.dispose();

// 새로운 지오메트리 생성
const sphere2Geometry = new THREE.SphereGeometry(1, 10, 10);

// 새로운 지오메트리 적용
//sphere1Group.children[0].geometry = sphere2Geometry;
sphere1Group.children[1].geometry = new THREE.WireframeGeometry(sphere2Geometry);

그럼 Controls에 SphereGeometry(스피어 지오메트리, 구 기하 도형)의 속성들을 컨트롤러로 추가해 보겠습니다.

위에서 테스트한 것처럼 매번 새로운 SphereGeometry(스피어 지오메트리, 구 기하 도형)를 생성해야 하기 때문에 parameters(파라미터)들을 별도의 객체로 관리해야 합니다.

1. SphereGeometry(스피어 지오메트리, 구 기하 도형)를 생성할 때 사용되는 parameters(파라미터)들로 객체(dataSphere1)를 만듭니다. (기본값으로 설정했습니다.)

const dataSphere1 = {
    radius: 1,
    widthSegments: 32,
    heightSegments: 16,
    phiStart: 0,
    phiLength: Math.PI * 2,
    thetaStart: 0,
    thetaLength: Math.PI
};

2. SphereGeometry(스피어 지오메트리, 구 기하 도형)의 parameters(파라미터)를 객체(dataSphere1)로 변경합니다.

const sphere1Geometry = new THREE.SphereGeometry(dataSphere1.radius, dataSphere1.widthSegments, dataSphere1.heightSegments, dataSphere1.phiStart, dataSphere1.phiLength, dataSphere1.thetaStart, dataSphere1.thetaLength);

3. Material(머티리얼)에서 구 객체의 안쪽에도 렌더링 되도록 side 속성을 THREE.DoubleSide로 추가합니다.

const sphere1Material = new THREE.MeshStandardMaterial({color: 0x0000ff, side: THREE.DoubleSide});

4. 구 그룹(sphere1Group)에 있는 구 객체(sphere1)와 라인 세그먼트즈 객체(sphere1WireframeLine)의 Geometry(지오메트리, 기하 도형)를 폐기(Dispose)하고 새로운 SphereGeometry(스피어 지오메트리, 구 기하 도형)를 생성하여 적용시키는 함수를 만듭니다.

// 구 그룹 지오메트리 변경 함수
function updatesShereGroupGeometry() {

    sphere1Group.children[0].geometry.dispose();
    sphere1Group.children[1].geometry.dispose();

    const newSphereGeometry = new THREE.SphereGeometry(dataSphere1.radius, dataSphere1.widthSegments, dataSphere1.heightSegments, dataSphere1.phiStart, dataSphere1.phiLength, dataSphere1.thetaStart, dataSphere1.thetaLength);

    sphere1Group.children[0].geometry = newSphereGeometry;
    sphere1Group.children[1].geometry = new THREE.WireframeGeometry(newSphereGeometry);
}

위의 예제처럼 구 객체에 있는 속성들 컨트롤러로 추가해 보겠습니다.

5. 구 객체에 있는 속성들을 별도의 그룹으로 분리하기 위해서 Controls에 Folder(폴더)를 추가합니다.

gui.addFolder(title)

title(타이틀) : 폴더의 제목 표시줄에 표시할 이름입니다.

예제처럼 동일하게 폴더에 표시할 이름을 "THREE.SphereGeometry"으로 설정합니다.

// 컨트롤러에 구 그룹 객체를 위한 Folder(폴더) 추가
const folder1 = gui.addFolder('THREE.SphereGeometry');

6. 객체(dataSphere1)로 컨트롤러에 추가합니다.

각각의 컨트롤러에 $1(최소 값, 선택 값), max(최대 값)은 SphereGeometry(스피어 지오메트리, 구 기하 도형)의 기본값으로 설정합니다.
컨트롤러가 변경될 때마다 구 그룹 지오메트리 변경 함수(updatesShereGroupGeometry)가 호출되도록 설정합니다.

// 컨트롤러 추가
// 구 지오메트리의 파라미터들로 추가
folder1.add(dataSphere1, 'radius', 1, 30).onChange(updatesShereGroupGeometry);
folder1.add(dataSphere1, 'widthSegments', 3, 64).step(1).onChange(updatesShereGroupGeometry);
folder1.add(dataSphere1, 'heightSegments', 2, 32).step(1).onChange(updatesShereGroupGeometry);
folder1.add(dataSphere1, 'phiStart', 0, Math.PI * 2).onChange(updatesShereGroupGeometry);
folder1.add(dataSphere1, 'phiLength', 0, Math.PI * 2).onChange(updatesShereGroupGeometry);
folder1.add(dataSphere1, 'thetaStart', 0, Math.PI * 2).onChange(updatesShereGroupGeometry);
folder1.add(dataSphere1, 'thetaLength', 0, Math.PI * 2).onChange(updatesShereGroupGeometry);

다양하게 컨트롤러의 값들을 변경시켜서 구 객체가 변경되는 것을 확인해 보시기 바랍니다.

three.js GUI Controls - lil-gui, gui.add

carrotweb — Sun, 20 Aug 2023 19:10:37 +0900

three.js 사이트의 doc에서 Geometry(지오메트리, 기하 도형)들의 설명을 보면 오른쪽 상단에 Controls가 있습니다. (https://threejs.org/docs/index.html#api/en/geometries/SphereGeometry)

Controls에는 객체의 속성 값들이 표시되고 속성 값을 변경하면 객체가 변경됩니다.

이번에 위의 예제 화면처럼 Controls를 만들어 주사위 객체의 Material(머티리얼)에 있는 alphaTest(알파 테스트) 속성을 변경해 보도록 하겠습니다.

이전에는 Controls를 만들기 위해 dat.GUI를 사용하였으나 최근에는 lil-gui를 대체하여 사용하고 있습니다. three.js에서도 lil-gui를 모듈에 포함하여 배포하고 있습니다.

Controls를 만들기 위해서는 lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스) 모듈을 가져와야 합니다.

lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스)는 사용자가 웹 페이지에서 객체의 속성 값들을 변경할 수 있게 플로팅 패널(Floating Panel, 떠 있는 패널)로 컨트롤러(Controller) UI를 만들어 줍니다.

자세한 설명은 lil-gui 사이트(https://lil-gui.georgealways.com/)를 참고하시기 바랍니다.

1. import를 통해 lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스) 모듈을 가져옵니다.

import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

lil-gui 모듈의 실제 위치는 "\node_modules\three\examples\jsm\libs\lil-gui.module.min.js" 입니다.

2. lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스)를 생성합니다.

// GUI 생성
const gui = new GUI();

그러면 오른쪽 상단에 Controls가 생성되어 나타납니다.

3. Controls에 컨트롤러를 추가합니다.

gui.add(object, property, [$1], [max], [step])

object(객체) : 컨트롤러가 제어할 객체입니다.
property(프로퍼티, 속성) : 객체에서 제어할 속성 이름입니다.
$1(최소 값, 선택 값) : 숫자 컨트롤러의 최소 값이거나 드롭다운에서 선택 가능한 값입니다.
max(최대 값) : 숫자 컨트롤러의 최대 값입니다.
step(스탭, 간격) : 숫자 컨트롤러의 간격 값입니다.

object(객체)는 주사위 육면체 객체에 적용되어 있는 Material(머티리얼) 배열에서 첫 번째 배열을 설정하고 property(프로퍼티, 속성)는 alphaTest(알파 테스트)로 설정합니다.

// 컨트롤러 추가
// 주사위 육면체 객체에 적용되어 있는 머티리얼 객체, 프로퍼티는 alphaTest로 설정
gui.add(box2Materials[0], 'alphaTest');

그러면 오른쪽 상단에 있는 Controls에 alphaTest라는 이름(속성 이름)으로 숫자 컨트롤러가 추가됩니다.

alphaTest 숫자 컨트롤러에는 현재 alphaTest 속성 값이 나타납니다. (현재 속성 값은 0.1입니다.)

속성 값을 입력하거나 상/하 화살표 키보드를 눌러 값을 변경할 수 있습니다. (상/하 화살표 키보드를 누르면 1 간격으로 변경됩니다.)

맨 위의 예제 화면처럼 숫자 컨트롤러에 슬라이더(Sliders)를 추가하기 위해서는 $1(최소 값)과 max(최대 값)를 추가하면 됩니다.

alphaTest(알파 테스트) 속성 값인 알파 값(0 ~ 1)으로 $1(최소 값)과 max(최대 값)를 설정하고 step(스탭, 간격)으로 0.01로 설정합니다.

// 컨트롤러 추가
// 주사위 육면체 객체에 적용되어 있는 머티리얼 객체, 프로퍼티는 alphaTest로 설정
// 최소 값은 0, 최대 값은 1, 간격은 0.01로 설정
gui.add(box2Materials[0], 'alphaTest', 0, 1, 0.01);

또는 min(), max(), step() 메서드를 사용하여 설정할 수 있습니다.

gui.add(box2Materials[0], 'alphaTest').min(0).max(1).step(0.01);

그러면 alphaTest 숫자 컨트롤러에 슬라이더(Sliders)가 추가됩니다. 그리고 슬라이더(Sliders)를 마우스로 이동시키면 step(스탭, 간격) 값만큼 변경됩니다. (상/하 화살표 키보드를 눌러도 step 값만큼 변경됩니다.)

alphaTest 숫자 컨트롤러의 이름은 name() 메서드로 변경할 수 있습니다. alphaTest 숫자 컨트롤러의 이름을 "알파 테스트"로 변경하겠습니다.

// 컨트롤러 추가
// 주사위 육면체 객체에 적용되어 있는 머티리얼 객체, 프로퍼티는 alphaTest로 설정
// 최소 값은 0, 최대 값은 1, 간격은 0.01로 설정
// 칸트롤러의 이름을 '알파 테스트'로 변경
gui.add(box2Materials[0], 'alphaTest', 0, 1, 0.01).name('알파 테스트');

그러면 alphaTest 숫자 컨트롤러의 이름이 "알파 테스트"로 변경됩니다.

alphaTest 숫자 컨트롤러의 슬라이더(Sliders)를 마우스로 이동시켜 alphaTest 속성 값을 0으로 변경시키면 5번 주사위 이미지가 투명하지 않게 되고 그림자도 투명하지 않게 됩니다.

그리고 alphaTest 속성 값을 1로 변경시키면 5번 주사위 이미지가 투명해지지만 Aliasing(앨리어싱)이 발생되어 5번 주사위 이미지가 각지게 되고 그림자는 없어지게 됩니다. (alphaTest 속성이 1이 되면 흰색까지 투과되지 않습니다.)

alphaTest 속성 값의 변화에 따라 주사위 이미지와 그림자가 변화되는 것을 좀 더 명확하게 확인하기 위해서 주사위 육면체 객체에 적용되어 있는 Material(머티리얼) 배열에서 첫 번째 배열에 있는 alphaMap(알파 맵)을 이전에 추가한 그라데이션된 이미지 파일(dicemap.png)로 변경하여 테스트 헤보겠습니다.

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5.png"), alphaMap: box2TextureLoader.load("resources/textures/dicemap.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true})
];

[alphaTest 속성 값을 0.1로 변경할 경우]

[alphaTest 속성 값을 0.54로 변경할 경우]

[alphaTest 속성 값을 0.9로 변경할 경우]

three.js 텍스처 매핑, 알파 맵과 알파 테스트로 이미지 자르기와 그림자 처리 - alphaMap, alphaTest

carrotweb — Mon, 14 Aug 2023 00:55:48 +0900

이번에는 배경이 투명하지 않는 주사위 이미지를 Material(머티리얼)의 alphaMap(알파 맵) 속성을 사용하여 이미지를 자르고 반투명하게 처리해 보겠습니다. 그리고 alphaTest(알파 테스트) 속성을 사용하여 처리되는 범위를 조정해 보겠습니다. (그림자는 자동으로 이미지에 맞게 처리됩니다.)

그럼 alphaMap(알파 맵) 속성에 대해 간단하게 알아보고 진행하겠습니다.

alphaMap(알파 맵)은 흰색과 검은색 그리고 흰색과 검은색 사이의 회색(밝은 회색부터 어두운 회색까지)으로 구성된 이미지입니다.

alphaMap(알파 맵)에 있는 흰색은 이미지 처리 시 원본 이미지가 그대로 투과됩니다.

alphaMap(알파 맵)에 있는 검은색은 이미지 처리 시 원본 이미지가 투과되지 않습니다. (검은색과 같은 위치에 있는 이미지는 삭제 처리됩니다.)

alphaMap(알파 맵)에 있는 흰색과 검은색 사이의 회색(밝은 회색부터 어두운 회색까지)은 이미지 처리 시 반투명하게 투과됩니다. (회색이 어두울 수 록 투명해집니다.)

즉, alphaMap(알파 맵)은 검은색의 농도에 따라 이미지 처리 시 삭제(검은색)하거나 반투명(밝은 회색부터 어두운 회색까지 농도에 따라 투명도가 달라짐)으로 처리됩니다.

그리고 alphaTest(알파 테스트) 속성 값인 알파 값(0.1 ~ 0.9)에 따라 회색(밝은 회색부터 어두운 회색까지)의 처리되는 범위가 넓어집니다. (기본적으로 alphaTest 속성은 0입니다. 그리고 alphaTest 속성이 1이 되면 흰색까지 투과되지 않습니다.)

즉, 알파 값이 작을수록 alphaMap(알파 맵)에서 어두운 회색들은 투과되지 않습니다. 반대로 알파 값이 클수록 밝은 회색까지도 투과되지 않습니다.

그럼 테스트를 통해 확인해 보겠습니다.

PPT로 alphaMap(알파 맵)으로 사용할 이미지를 간단하게 만들어 보겠습니다.

주사위 이미지와 같은 크기(가로/세로는 3cm)의 도형(직사각형)을 생성합니다.
도형 윤곽선은 "윤곽선 없음"으로 설정합니다.
도형을 선택하고 콘텍스트 메뉴에서 "도형 서식"을 클릭합니다.
도형 서식에서 "그라데이션 채우기"를 선택하고 그라데이션 중지점에서 첫 번째 중지점을 선택하고 색은 검은색으로 선택합니다. 그리고 그라데이션 중지점에서 세 번째 중지점을 선택하고 색은 흰색으로 선택합니다.
도형을 PNG 파일로 저장합니다. (저는 dicemap.png으로 저장하였습니다.)

프로젝트의 resources \ textures 폴더에 alphaMap(알파 맵)으로 사용할 이미지(dicemap.png) 파일을 추가합니다.

테스트를 위해 Material(머티리얼) 배열에서 5번 주사위 이미지를 배경이 투명하지 않는 주사위 이미지(dice5.png)로 변경하고 추가된 이미지 파일(dicemap.png)을 TextureLoader(텍스처로더)로 로드하여 alphaMap 속성 값으로 설정합니다. 그리고 alphaTest 속성 값을 0으로 설정합니다.

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5.png"), alphaMap: box2TextureLoader.load("resources/textures/dicemap.png"), side: THREE.DoubleSide, alphaTest: 0, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true})
];

마우스로 이동해서 보시면 5번 주사위 이미지가 alphaMap(알파 맵)으로 이미지 처리가 되어서 alphaMap(알파 맵)에서 검은색 영역은 삭제처리되고 회색(밝은 회색부터 어두운 회색까지) 영역은 반투명하게 처리되어 나오는 것을 확인할 수 있습니다.

alphaTest(알파 테스트) 속성 값인 알파 값(0.1 ~ 0.9)에 따라 다음처럼 처리됩니다.

그림자도 처리된 이미지에 맞게 나타납니다. (alphaMap(알파 맵) 이미지가 그라데이션으로 되어있어 처리된 이미지 크기만큼 그림자가 나오게 됩니다.)

그럼 5번 주사위 이미지(dice5.png)에 맞게 alphaMap(알파 맵) 이미지를 만들어 처리해 보겠습니다.

5번 주사위 이미지를 만든 PPT에서 도형의 윤곽선 색을 흰색으로 변경합니다. (윤관선 색이 검은색이면 원본 이미지에 있는 윤관선이 투과되지 않기 때문입니다.)
검은색 점 도형은 흰색으로 흰색 배경은 검은색으로 변경합니다. (흰색만 투과되기 때문입니다.)
도형을 PNG 파일로 저장합니다. (기존 파일명에 'm'를 추가하여 dice5m.png으로 저장하였습니다.)

프로젝트의 resources \ textures 폴더에 alphaMap(알파 맵)으로 사용할 5번 주사위 이미지(dice5m.png) 파일을 추가합니다.

Material(머티리얼) 배열에서 추가된 이미지 파일(dice5m.png)로 alphaMap 속성의 값을 변경합니다. 그리고 alphaTest 속성 값을 0.1로 설정합니다. (alphaTest 속성 값을 0으로 설정하면 투명처리가 되지 않습니다.)

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5.png"), alphaMap: box2TextureLoader.load("resources/textures/dice5m.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true})
];

그러면 5번 주사위 이미지가 투명하게 처리되어 보이게 됩니다.

참고로, 어도비 포토샵(Photoshop)에서도 alphaMap(알파 맵)과 같은 방식으로 이미지의 배경을 투명하게 하거나 반투명하게 처리하여 여러 이미지들을 겹칠 때 사용합니다. 이런 방식을 alpha channel(알파 채널)이라고 합니다.

three.js 텍스처 매핑, 이미지 투명처리, 투명한 그림자 처리 - transparent, alphaTest, THREE.DoubleSide

carrotweb — Sat, 5 Aug 2023 23:49:41 +0900

이번에는 주사위의 흰색 배경을 없애고 투명하게 처리해 보겠습니다.

주사위 이미지를 만든 PPT에서 주사위 틀의 도형 채우기를 "채우기 없음"으로 변경합니다.

그리고 각각을 PNG 파일로 저장합니다. (기존 파일명에 't'를 추가했습니다.)

프로젝트의 resources \ textures 폴더에 주사위 이미지 파일을 추가합니다.

추가된 주사위 이미지에 배경이 없는 것을 확인할 수 있습니다. (체크무늬가 투명처리되는 부분입니다.)

Material(머티리얼) 배열에서 기존 이미지를 추가된 주사위 이미지로 변경하고 주사위 이미지의 체크무늬 부분이 투명하게 처리되도록 transparent 속성을 true로 추가합니다. (기본적으로 transparent 속성은 false입니다.)

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5t.png"), transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2t.png"), transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1t.png"), transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6t.png"), transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3t.png"), transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4t.png"), transparent: true})
];

그러면 주사위가 투명하게 처리되어 바닥과 그림자가 보이게 됩니다.

마우스로 이동해서 보면 주사위 뒤에 있는 객체가 보이는 것을 확인할 수 있습니다.

그렇지만, 2가지가 투명하게 처리되지 않았습니다.

첫 번째, 주사위의 그림자가 투명하지 않게 나옵니다.

두 번째, 주사위안이 투명하지 않게 나옵니다. (위를 보면 3번 주사위 왼쪽에 있는 2번, 바닥에 있는 6번, 뒤에 있는 4번 이미지가 보이지 않습니다.)

그럼, 첫 번째 문제인 그림자가 투명한 주사위 이미지에 맞게 투과되어 나오게 하려면 어떻게 해야 할까요?

그림자를 처리하는 방법이 여러 가지 있지만 여기서는 텍스처를 사용하는 Material(머티리얼)에서 처리할 수 있는 방법에 대해 알아보겠습니다.

1. 투명하지 않는 텍스처와 alphaMap(알파 맵), alphaTest(알파 테스트)를 사용하는 방법

2. 투명한 텍스처와 alphaTest(알파 테스트)를 사용하는 방법

주사위 이미지가 투명하기 때문에 우리는 2번째 방법으로 alphaTest(알파 테스트) 속성을 추가하면 간단하게 처리할 수 있습니다.

간단하게 alphaTest(알파 테스트) 속성에 대해 알아보고 진행하겠습니다.

Material(머티리얼)의 alphaTest 속성은 알파 테스트를 실행할 때 사용할 알파 값으로 0.0부터 1.0까지 값을 가질 수 있습니다. (주의할 점은 Material(머티리얼)의 opacity 속성을 사용하고 있다면 opacity 값이 alphaTest 값 보다 작으면 렌더링이 되지 않습니다.)

alphaTest(알파 테스트)는 이미지 조각(픽셀)의 알파 값을 비교하여 조각(픽셀)을 삭제처리 합니다.

alphaTest(알파 테스트)를 위해 주사위 이미지 보다 복잡한 나무 이미지를 사용하여 alphaTest 값에 따라 어떻게 이미지가 삭제 처리되는지 확인해 보겠습니다.

alphaTest(알파 테스트)할 나무 이미지(배경이 투명)입니다.

Material(머티리얼)의 alphaTest 값을 각각 0.1, 0.5, 0.9로 설정하였습니다.

new THREE.MeshStandardMaterial({map: textureLoader.load("resources/textures/tree1.png"), alphaTest: 0.1, transparent: true});

new THREE.MeshStandardMaterial({map: textureLoader.load("resources/textures/tree1.png"), alphaTest: 0.5, transparent: true});

new THREE.MeshStandardMaterial({map: textureLoader.load("resources/textures/tree1.png"), alphaTest: 0.9, transparent: true});

위의 결과처럼 alphaTest 값이 높을수록 더 많은 부분이 삭제가 되는 것을 확인할 수 있습니다.

그리고 계단 현상인 Aliasing(앨리어싱)이 발생되어 이미지가 각지게 됩니다.

그래서 이미지에 맞게 alphaTest 값을 설정해야 합니다. 일반적으로 0.1에서 0.5 이하로 설정합니다.

각각의 Material(머티리얼)에 alphaTest 속성을 0.1로 추가합니다.

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5t.png"), alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2t.png"), alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1t.png"), alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6t.png"), alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3t.png"), alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4t.png"), alphaTest: 0.1, transparent: true})
];

그럼 주사위 이미지가 투과되어 보이게 됩니다.

그러나 자세히 보면 투과된 그림자의 주사위 이미지는 오른쪽에 있는 5번, 바닥에 있는 6번, 뒤에 있는 4번 이미지입니다.

주사위의 1번, 2번, 3번은 왜 투과되어 나오지 않는 걸까요?

이 문제는 위의 두 번째 문제인 주사위안이 투명하지 않게 나오는 현상과 같은 문제입니다.

이유는 렌더링 되는 면에 영향을 받기 때문입니다.

기본적으로 Material(머티리얼)에서는 텍스처를 렌더링 할 때 앞면(THREE.FrontSide)만 처리합니다.

그래서 우리가 사용한 육면체는 전부 앞면만 렌더링 된 겁니다.

그렇기 때문에 뒷면(THREE.BackSide)이 없는 주사위의 1번(위), 2번(왼쪽), 3번(앞쪽)은 그림자로 투과되지 않았습니다. 그리고 주사위의 4번(뒤), 5번(오른쪽), 6번(바닥)도 뒷면(THREE.BackSide)이 없어 주사위안에서 보이지 않았던 겁니다.

그래서 Material(머티리얼)에서 렌더링 할 면을 앞면과 뒷면 둘 다 되게 처리하면 됩니다.

각각의 Material(머티리얼)에서 주사위 이미지가 앞면과 뒷면에서 렌더링 되도록 side 속성을 THREE.DoubleSide로 추가합니다. (기본적으로 side 속성은 THREE.FrontSide입니다.)

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true})
];

그럼 주사위 안도 그림자도 모두 이미지가 투과되어 보이게 됩니다.

three.js 텍스처 매핑, 이미지 입히기 - TextureLoader

carrotweb — Sun, 16 Jul 2023 21:48:42 +0900

Texture(텍스처)란 객체의 색상과 질감을 표현하는 Material(머티리얼)에서 사용되는 이미지나 비디오를 말합니다.

Texture Mapping(텍스처 매핑)이란 객체의 표면에 색을 칠하거나 이미지를 입히는 것입니다.

객체에 Texture Mapping(텍스처 매핑)하기 위해서는 Texture(텍스처)를 로드해야 합니다.

three.js에서는 TextureLoader(텍스처로더)로 Texture(텍스처)를 로드합니다.

TextureLoader(텍스처로더)는 이미지 (PNG, JPG, GIF, DDS) 또는 비디오 (MP4, OGG/OGV)를 로드합니다.

TextureLoader(manager : LoadingManager)

manager(매니저) : 로딩매니저입니다. 기본값 THREE.DefaultLoadingManage

그럼 두 번째 육면체 객체에 Texture Mapping(텍스처 매핑)을 해보겠습니다.

육면체 객체에 Texture(텍스처 매핑)할 나무 바닥 이미지를 다운로드합니다.

저는 나무 바닥 이미지를 Freepik 사이트에서 무료로 다운로드하였습니다.

다운로드한 나무 바닥 이미지의 크기가 크기 때문에 이미지 크기를 넓이 150px, 높이 100px으로 조정하였습니다.

1. 프로젝트에 resources \ textures 폴더를 생성하고 다운로드한 나무 바닥 이미지 파일(wood1.jpg)을 추가합니다.

2. resources \ textures 폴더에 있는 나무 바닥 이미지 파일(wood1.jpg)을 TextureLoader(텍스처로더)로 로드합니다.

// 텍스처 매핑할 텍스처를 로드
const box2Texture = new THREE.TextureLoader().load('resources/textures/wood1.jpg');

3. 로드한 Texture(텍스처)를 Material(머티리얼)의 map 속성에 설정합니다.

// 육면체에 사용할 색상과 질감의 데이터를 생성
const box2Material = new THREE.MeshStandardMaterial({map:box2Texture});

기존에 있는 color 속성은 삭제합니다. 그 이유는 Texture(텍스처)의 map color가 color 속성 값과 결합되어 변경되기 때문입니다. 글 끝부분에서 테스트로 color 속성과 같이 사용해 보도록 하겠습니다.

4. 두 번째 육면체 객체가 보이도록 Camera(카메라)의 위치를 변경합니다.

// 카메라 위치 변경
camera.position.set(0, 2, 8);

그러면 두 번째 육면체 객체의 모든 면이 나무 바닥 이미지로 변경됩니다.

마우스로 이동해서 보시면 입체적으로 확인할 수 있습니다. 나무 바닥 이미지가 육면체 객체에 잘 어울립니다.

이번에는 주사위 이미지를 만들어서 두 번째 육면체 객체에 Texture Mapping(텍스처 매핑)을 해보겠습니다.

주사위 이미지를 간단하게 PPT로 만들었습니다.

틀은 직사각형으로 가로/세로는 3cm, 도형 채우기는 흰색, 도형 윤곽선은 검은색입니다.

점은 원형으로 가로/가로는 0.6cm, 도형 채우기와 도형 윤곽선은 검은색입니다.

직사각형안의 점선은 중앙을 맞추기 위해서 사용했습니다. 저장하기 전에 점선은 삭제합니다.

각각을 PNG 파일로 저장합니다.

그리고 프로젝트에 resources \ textures 폴더에 주사위 이미지 파일을 추가합니다.

여러 Texture(텍스처)들을 여러 번 로드하기 위해서 TextureLoader(텍스처로더)를 분리하여 생성합니다.

// 텍스처 로드 생성
const box2TextureLoader = new THREE.TextureLoader();

육면체 면마다 텍스처가 다른 Material(머티리얼)을 설정해줘야 합니다.

그래서 6개의 Material(머티리얼)을 생성해서 배열로 전달해야 합니다.

6개의 Material(머티리얼)이 육면체에 매핑되는 순서는 오른쪽(1), 왼쪽(2), 위(3), 아래(4), 앞(5), 뒤(6)입니다. (전개도 모양은 다를 수 있습니다.)

그러나 대부분의 주사위는 1을 기준(1이 위에 있을 경우)으로 다음과 같이 되어 있습니다.

그래서 6개의 Material(머티리얼)로 배열을 만들 때 주사위 위치에 맞게 텍스처(주사위 이미지)를 로드해야 합니다.

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5.png")}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2.png")}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1.png")}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6.png")}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3.png")}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4.png")})
];

6개의 면이 다른 텍스처(주사위 이미지)가 되기 위해서 Material(머티리얼) 배열로 변경합니다.

// 육면체와 색상과 질감의 데이터 배열을 결합하여 육면체 객체 생성
const box2 = new THREE.Mesh(box2Geometry, box2Materials);

그러면 두 번째 육면체 객체의 모든 면이 주사위 이미지로 변경됩니다.

마우스로 이동해서 보시면 입체적으로 확인할 수 있습니다.

위에서 말한 것처럼 Material(머티리얼)의 map 속성과 color 속성이 같이 사용하게 되면 Texture(텍스처)의 map color가 color 속성 값과 결합되어 색이 변경됩니다. map color가 흰색인 경우 color 속성 값이 됩니다.

Material(머티리얼)에 기존 color 속성을 추가합니다.

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5.png"), color:box2Color}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2.png"), color:box2Color}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1.png"), color:box2Color}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6.png"), color:box2Color}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3.png"), color:box2Color}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4.png"), color:box2Color})
];

그러면 새로고침 할 때마다 주사위의 색상이 변경되는 것을 확인할 수 있습니다.

그 이유는 주사위 이미지가 흰색이기 때문에 변경되는 색상으로 변경됩니다.

흰색이 아닌 다른 색상일 경우 색이 변경되어 보일 겁니다.

three.js 객체 결합 - Group

carrotweb — Sun, 9 Jul 2023 22:58:12 +0900

이전에 만든 육면체 객체의 와이어프레임을 선으로 그린 라인 세그먼트즈 객체를 육면체 객체와 결합해 보겠습니다.

객체들을 결합하기 위해서 Group(그룹)을 사용하면 됩니다.

Group(그룹)은 객체들을 결합시켜 하나의 객체(Object3D)를 생성합니다.

1. 객체를 합치기 전에 육면체 객체(box1)와 라인 세그먼트즈 객체(box1WireframeLine)를 Scence(씬, 장면)에 추가되지 않게 주석처리합니다.

// 장면에 육면체 객체 추가
//scene.add(box1);

// 장면에 라인 세그먼트즈 객체 추가
//scene.add(box1WireframeLine);

2. 라인 세그먼트즈 객체(box1WireframeLine)의 라인 색상을 붉은색에서 짙은 녹색으로 변경하고 위치(position)를 육면체 객체와 동일하게 합니다.

// 선 색상을 짙은 녹색으로 변경
box1WireframeLine.material.color = new THREE.Color(0x006400);
// 육면체 객체와 결합하기 위해 육면체 객체의 위치를 복사하여 라인 세그먼트즈 객체의 위치 설정
box1WireframeLine.position.copy(box1.position);

3. 객체들을 결합하기 위해 Group(그룹)을 생성하고 Group(그룹)에 육면체 객체(box1)와 라인 세그먼트즈 객체(box1WireframeLine)를 추가합니다. 그리고 생성된 Group(그룹)를 Scence(씬, 장면)에 추가합니다.

// 육면체 객체와 라인 세그먼트즈 객체를 결합하기 위한 육면체 그룹 생성
const box1Group = new THREE.Group();
// 그룹에 육면체 객체 추가
box1Group.add(box1);
// 그룹에 라인 세그먼트즈 객체 추가
box1Group.add(box1WireframeLine);
// 장면에 육면체 그룹 추가
scene.add(box1Group);

육면체 객체에 와이어프레임이 결합되어 보입니다.

4. 라인 세그먼트즈 객체(box1WireframeLine)가 육면체 객체와 결합될 때 투명하게 결합되게 설정을 추가합니다.

Material(머티리얼)의 opacity은 0.0에서 부터 1.0까지 값을 가질 수 있습니다. opacity 값이 낮을수록 더 투명해집니다.

// 선이 투명해지게 설정
box1WireframeLine.material.transparent = true;
// 선의 불투명도를 낮게 설정
box1WireframeLine.material.opacity = 0.3;

5. 육면체 그룹 객체가 회전되게 주석처리된 육면체 객체를 육면체 그룹 객체로 변경하고 주석을 해제시킵니다.

// 애니메이팅
function animate() {
    box1Group.rotation.x += 0.01;
    box1Group.rotation.y += 0.01;
    box1Group.rotation.z += 0.01;
    controls.update();
    renderer.render(scene, camera);
    requestAnimationFrame(animate);
};

구 객체(sphere1)도 라인 세그먼트즈 객체(sphere1WireframeLine)와 결합되도록 처리합니다.

1. 구 객체(sphere1)를 Scence(씬, 장면)에 추가되지 않게 주석처리합니다.

// 장면에 구 객체 추가
//scene.add(sphere1);

2. 라인 세그먼트즈 객체(sphere1WireframeLine)의 라인 색상을 붉은색에서 흰색으로 변경하고 위치(position)를 구 객체와 동일하게 하고 투명하게 결합되게 설정을 추가합니다. 그리고 라인 세그먼트즈 객체(sphere1WireframeLine)를 Scence(씬, 장면)에 추가되지 않게 주석처리합니다.

// 선 색상을 짙은 흰색으로 변경
sphere1WireframeLine.material.color = new THREE.Color(0xffffff);
// 선이 투명해지게 설정
sphere1WireframeLine.material.transparent = true;
// 선의 불투명도를 낮게 설정
sphere1WireframeLine.material.opacity = 0.3;
// 구 객체와 결합하기 위해 구 객체의 위치를 복사하여 라인 세그먼트즈 객체의 위치 설정
sphere1WireframeLine.position.copy(sphere1.position);
// 장면에 라인 세그먼트즈 객체 추가
//scene.add(sphere1WireframeLine);

3. 객체들을 결합하기 위해 Group(그룹)을 생성하고 Group(그룹)에 구 객체(sphere1)와 라인 세그먼트즈 객체(sphere1WireframeLine)를 추가합니다. 그리고 생성된 Group(그룹)를 Scence(씬, 장면)에 추가합니다.

// 구 객체와 라인 세그먼트즈 객체를 결합하기 위한 구 그룹 생성
const sphere1Group = new THREE.Group();
// 그룹에 구 객체 추가
sphere1Group.add(sphere1);
// 그룹에 라인 세그먼트즈 객체 추가
sphere1Group.add(sphere1WireframeLine);
// 장면에 구 그룹 추가
scene.add(sphere1Group);

이제 three.js 사이트의 doc에 있는 예제처럼 보입니다.

각 객체의 Segments(세그먼트, 분절 수)를 변경시켜 변화되는 모습을 보시기 바랍니다.