명왕성의 공전기록

모두가 자신의 무가치함과 싸우고 있다 2화 감상

자전하는명왕성 — Mon, 18 May 2026 21:21:30 +0900

2화에서는 동만과 은하에 대한 연결을 다룬다.

먼저, 은하라는 인물에 대해 얘기해본다.
이전 1화에서, 동만이라는 인물에 대해 ‘명왕성’과 닮았다고 얘기한 적 있다.
태양계에 잠시 속했다가 퇴출당한 명왕성.
은하라는 인물은 행성으로 비유하자면, 어느 이름 없는 행성과 같다.
어느곳에도 속하지 못하고 그저 자신만의 박자로 공전이 아닌 자전만 하고 있는 행성.

스크린에서 보여지는 은하의 표정은 대체로 무표정에 가깝다.
무슨 생각을 하는지도 알 수 없고,
이따금 감정을 느낄 수 있는 장면은 그녀가 스트레스를 받을 때 코피를 흘리는 것 정도.
여기서의 코피는 마치 소리 없는 아우성에 가까워, 동만의 직접적인 발화를 통한 감정 표출과 대비된다.
다만, 작품에서 보여진 감정 워치라는 소품에서 ‘알 수 없음’이라고 뜨는 것으로 봐서는
그 감정이 단순 부정적인 감정일 뿐 어떤 감정인지 특정할 수는 없다는 건
은하의 정체성 자체를 대변하는 것으로 보여 보는 입장에서 꽤 재밌다.

그녀의 외모는 차분하다.
눈에 튀지 않는 옷과 헤어스타일, 그리고 화장.
내가 생각하는 ‘외모는 무의식에서 행하는 자신의 감정 표현의 한 가지 방식이기 때문에,
아마 그녀는 무의식에서 조차 자신의 감정을 드러내지 않으려고 하는 것처럼 보인다.

때문에 그녀가 하는 말은 힘이 있으면서도 냉소적이다.
드러내는 감정이 없음에도 말로써 타인에게 흥분을 일으키거나 공격성을 보이게 한다.
은하는 동만과 달리 능력을 가지고 있지만,
그 능력 때문에 집단의 울타리 안에 속할 수 없는 인물이다.

-

2화까지의 동만과 은하의 만남은 기차가 없는 기찻길에서 이루어진다.
기찻길은 그 말마따나 ‘길’이라는 측면에서, 이 둘이 함께 길을 걸을 것이라는 것을 암시한다.
어쩌면 명왕성과 이름 없는 행성의 공전 궤도가 맞닿아 있다고도 말할 수 있다.

다음화는 동만과 은하가 규합하여 어떤 일들을 시작하는 장면을 보여줄 듯하다.

모두가 자신의 무가치함과 싸우고 있다 1화 감상

자전하는명왕성 — Thu, 7 May 2026 04:13:17 +0900

해당 드라마는 20년째 시나리오를 쓰고 있음에도

영화감독으로 데뷔조차 하지 못한 인물을 주인공으로 다룬다.

주인공은 황동만(구교환)이다.

아무래도 1화는 주인공이 어떤 인물인지에 집중하고 있기 때문에,

이번 감상에서도 나름의 인물 분석을 중심으로 이야기해보고자 한다.

먼저, 이 인물을 한마디로 표현하자면 ‘명왕성’ 같다고 말하고 싶다.

황동만을 보며 몇 년 전의 내 모습이 떠올랐다. 일 년 만에 시인으로 등단했음에도,

어린 나이 때문이었는지, 혹은 내지 못했던 30만 원의 회비 때문이었는지

시인협회라는 소속에 끝내 녹아들지 못했던 나.

나는 당시의 나를 ‘명왕성’이라 비유하곤 했다.

명왕성은 한때 태양계의 행성으로 인정받았지만, 얼마 지나지 않아 그 지위를 잃어버린 존재이기 때문이다.

황동만 역시 나와는 다른 우주에 놓인 또 하나의 명왕성처럼 보였다.

모두가 비슷한 행성처럼 보이는데, 왜 나만 이곳에 속하지 못하는지에 대해 홀로 지독한 외로움을 견디는 인물이다.

그는 곰팡이로 얼룩진 듯 누리끼리한 원룸에서 살며, 관리비조차 제대로 내지 못하는 삶을 이어간다.

그는 가난한 사람일수록 더 좋은 글을 쓸 수 있다고 말하지만,

스스로를 ‘퍼펙트하게 가난하다’고 표현하는 그는 아무것도 증명하지 못한 채 억울함만을 느낀다.

밖을 나설 때면 마치 독일군이 입었을 법한 총알 구멍 난 코트를 걸치고, 검은 가방 위에 헤드셋을 묶어 다닌다.

그 헤드셋은 외로운 술자리 이후의 귀갓길, 그리고 혼자 영화를 볼 때 착용되는데,

이때의 헤드셋은 외부로부터 자신을 보호하는 방패에 가깝다.

결국 그는 전투복과 방패로 스스로를 무장한 채 세상 밖으로 나서는 셈이다.

그는 말로 주변 사람들을 찌르는 인물이다.

‘나는 안 되었는데 왜 너는 되느냐’라는 마음으로, 때로는 눈치 없이 타인을 향해 모진 말을 내뱉는다.

하지만 그 역시 그것이 옳은 방식이 아니라는 것을 알고 있는 듯하다.

자아실현의 결핍을 느낄 때마다 말을 삼키는 대신 음식을 입에 넣거나,

그것마저 어려울 때는 늘 해오던 것처럼 남들에게 혓바늘을 세우기 때문이다.

또한 그가 쓰는 작품은 ‘날씨가 없는 세상에서 날씨를 만들어내는 주인공의 이야기’라고 한다.

여기서 날씨는 감정과 맞닿아 있다.

그는 ‘감정 워치’라는 장치를 착용하고 다니는데, 이는 자신의 감정을 시각적으로 드러내는 물건이다.

그리고 이 물건은 오히려 황동만을 지배한다.

결국 그가 쓰는 이야기는, 감정조차 스스로 통제하지 못하는 현재의 자신을 벗어나고자 하는 자아실현의 또 다른 표현일지도 모른다.

1화의 감상을 마쳤다.

앞으로 황동만의 날씨는 어떨지, 그는 작품 제목처럼 어떻게 자신의 무가치함과 싸울지 궁금하다.

아마 2화의 이야기는 여주인공처럼 비중있게 다루는 고윤정에 대한 인물 분석을 하게되지 않을까 싶다.

Next.js - zustand 를 사용한 상태 관리

자전하는명왕성 — Wed, 28 May 2025 20:02:50 +0900

오늘은 next.js로 프론트엔드 개발하던 중 사용한 zustand 라이브러리에 대해 포스팅한다.

원래는 zustand를 쓸 생각이 없었다.

다만 recoil을 쓰다보니 아래와 같은 에러가 발생했다.

이유를 찾아보니, react 15버전 이상에서는 recoil이 호환성 에러가 발생한다는 거.

사실 이 원인을 모른 채 gpt를 붙잡고 한 시간 가까이 씨름하다 구글링으로 알게 되었다. 하참.

그리고, 나는 라이브러리 하나 때문에

전체 프로젝트의 버전을 기존 19버전에서 14버전까지 내릴 생각이 없었기 때문에 zustand를 사용하기로 했다.

zustand 를 쓰는 방법은 단순하다.

1. 먼저 해당 라이브러리를 설치한다.

yarn add zustand

2. 이후, 상태 관리 스토어를 설정한다.

내 경우, 유저 정보를 설정했다.

// app/common/store/user.ts
import { create } from "zustand";

// 사용자 정보 인터페이스 정의
interface User {
  id: string;
  email: string;
  nickname: string;
  role?: string;
 // 중략
}

// Zustand 스토어 인터페이스 정의
interface UserState {
  user: User | null;
  setUser: (user: User | null) => void;
}

// Zustand 스토어 생성
export const useUserStore = create<UserState>((set) => ({
  user: null,
  setUser: (user) => set({ user }),
}));

3. 컴포넌트에서 사용한다.

export const useLogin = (
  onSuccess: () => void,
  onFail?: (errorMessage: string) => void
) => {
  const setUser = useUserStore((state) => state.setUser);
  const router = useRouter();

zustand의 장점

- 설정 방법이 매우 단순하다. (Recoil과 달리, 별도의 provider 설정이 필요 없다.)

- typescript와 완벽히 통합된다.

Spring boot - GraphQL 적용하기

자전하는명왕성 — Fri, 16 May 2025 20:26:19 +0900

오늘 포스팅에서는 graphQL을 스프링 부트에 적용하는 방법에 대해 다룬다.

먼저 아래를 참고하여 의존성을 추가한다.

// build.gradle

// graphql 스타터 라이브러리
implementation 'org.springframework.boot:spring-boot-starter-graphql' 
// GraphQL Java에서 제공하지 않는 추가 스칼라 타입들을 사용할 수 있도록 해주는 라이브러리
implementation 'com.graphql-java:graphql-java-extended-scalars:21.0'

// application.yml

	graphql:
        schema:
            printer: // 서버 구동 시 실제 graphQL 스키마 파일 출력
                enabled: true
                location: classpath:graphql/schema.graphqls
        graphiql: // 웹 UI
            enabled: true
            path: /graphiql
        schema-location-pattern: "**/*.graphqls"
        tools: // 스키마 정보조회 허용
            introspection:
                enabled: true
            schema-location-pattern: "**/*.graphqls"

여기까지 마치면 초기 설정은 끝났다.

이제, 실제 사용하기 위한 스키마와 DTO를 정의한다.

// schema.graphqls
type Query {
    fetchUser(userId: ID): User
    fetchUsers: [User]
}

type Mutation {
    createUser(createUserDTO: CreateUserDTO!): User
}

input CreateUserDTO {
    nickName: String!
    password: String!
}

// CreateUserDTO.java

@Data
public class CreateUserDTO {
    private String nickName;
    private String password;
}

nest.js와 굉장히 흡사하다.

// UserResolver

package com.chessy.resolver;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

import com.chessy.domain.Users;
import com.chessy.dto.userDTO.UserDTO;
import com.chessy.dto.userDTO.CreateUserDTO;
import com.chessy.service.UserService;

@Controller
public class UserResolver {

  @Autowired
  private UserService userService;

  @MutationMapping
  public UserDTO createUser(
      @Argument("createUserDTO") CreateUserDTO createUserDTO) {
    Users user = userService.createUser(createUserDTO);
    return convertToDTO(user);
  }
 
// 중략 
}

// UserService

  public Users createUser(CreateUserDTO createUserDTO) {
    if (createUserDTO == null) {
      throw new CustomException(ErrorCode.INVALID_INPUT_VALUE, "사용자 정보는 필수입니다.");
    }

    Users user = new Users();
    user.setNickName(createUserDTO.getNickName());
    user.setPassword(passwordEncoder.encode(createUserDTO.getPassword()));
    user.setRole(Role.USER);
    return userRepository.save(user);
  }

이러면 graphQL 사용을 테스트 해볼 수 있다.

localhost:8080/graphiql 로 접속하면, 아래와 같은 화면이 뜨는데, 내게는 익숙치 않은 편.

그래서, 익숙한 Sandbox의 플레이그라운드를 사용해주기로 했다.

이와 같은 페이지를 만들어서 접속할 수 있다.

// resources/static/sandbox.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>GraphQL Sandbox</title>
        <style>
            html,
            body {
                margin: 0;
                padding: 0;
                width: 100vw;
                height: 100vh;
                overflow: hidden;
            }
            #sandbox {
                width: 100vw;
                height: 100vh;
            }
        </style>
    </head>
    <body>
        <script src="https://embeddable-sandbox.cdn.apollographql.com/_latest/embeddable-sandbox.umd.production.min.js"></script>
        <div id="sandbox"></div>
        <script>
            new window.EmbeddedSandbox({
                target: "#sandbox",
                initialEndpoint: window.location.origin + "/graphql",
                includeCookies: true,
                initialState: {
                    document: `query {
                        fetchUser(id: 1) {
                            id
                            role
                            nickName
                            createdAt
                            updatedAt
                        }
                    }`,
                },
            });
        </script>
    </body>
</html>

다만, 매번 sandbox.html 을 입력하는 건 번거로우니까,

지난번 swagger 를 사용했던 방식을 응용하여 아래와 같은 방식을 채택했다.

이제 localhost:8080/sandbox로 플레이그라운드에 접근이 가능해졌다.

package com.chessy.controller;

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

@Controller
public class DocsController {

  @GetMapping("/api")
  public String redirectSwagger() {
    return "redirect:/swagger-ui/index.html";
  }

  @GetMapping("/sandbox")
  public String redirectSandbox() {
    return "forward:/sandbox.html";
  }
}

테스트까지 하면 끝!

node.js - npm 라이브러리 배포하기

자전하는명왕성 — Mon, 12 May 2025 10:09:06 +0900

오늘은 npm에 라이브러리를 배포해보았다.

nest.js를 쓰면서 class-validator의 한계로 인해 매번 커스텀을 해야한다는 게 불편하기도 했고,

개발자로서 나름의 발자취를 남기고 싶은 마음도 있었다.

때문에, class-validator를 계승하는 방식으로,

커스텀 데코레이터를 제작하기로 했다.

이왕 만드는 김에, 타입스크립를 사용하고,

cjs(CommonJS)와 ESM(ES Module) 환경에서 모두 사용할 수 있도록 설계하기로 했다.

* CJS와 ESM을 모두 지원하는 이유

- Node.js나 Nest.js는 여전히(CommonJS) 형식을 주로 사용

- Next.js 등은 ESM을 기본으로 사용하기 때문에,

패키지를 다양한 프로젝트에서 사용할 수 있도록 하기 위해

두 형식을 모두 배포하는 게 중요하다고 생각했다.

- 폴더 구조 예시

zyno-validator/
├── src/
│   └── validators/
│       └── is-english.validator.ts
│   └── index.ts
├── dist/
│   ├── cjs/   ← CommonJS 빌드 결과
│   └── esm/   ← ESM 빌드 결과
├── tsconfig.cjs.json
├── tsconfig.esm.json
└── package.json

- 초기 설정

먼저, 작업할 프로젝트의 폴더를 만들었다.

mkdir zyno-validator && cd zyno-validator
yarn init

- 패키지 개발에 필요한 의존성 설치

yarn add class-validator class-transformer reflect-metadata
yarn add -D typescript ts-node jest ts-jest @types/jest

- tsconfig.json 설정

이후, src/index.ts 에 다음과 같은 설정을 해줘야 정상 작동한다.

각 tsconfig의 설정은 다음과 같다.

// tsconfig.cjs.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "dist/cjs",
    "module": "CommonJS"
  }
}


// tsconfig.esm.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "dist/esm",
    "module": "ES2020"
  }
}

// tsconfig.json
{
  "name": "@zynoobb/validator",
  "version": "1.0.0",
  "type": "module", // ESM을 기본으로 지정
  "main": "./dist/cjs/index.js",      // CommonJS 진입점
  "module": "./dist/esm/index.js",    // ESM 진입점
  "types": "./dist/esm/index.d.ts",
  "exports": {
    "import": "./dist/esm/index.js",  // ESM
    "require": "./dist/cjs/index.js"  // CJS
  },
  "scripts": {
    "build:cjs": "tsc -p tsconfig.cjs.json",
    "build:esm": "tsc -p tsconfig.esm.json",
    "build": "npm run build:cjs && npm run build:esm",
    "prepare": "npm run build"
  }
}

// src.index.ts
import "reflect-metadata"; // 해당 라이브러리를 임포트해야 데코레이터 정상 작동한다

- 기능 작성

// src/decorator/is-english.validator.ts

import {
  registerDecorator,
  ValidationOptions,
  ValidationArguments,
  ValidatorConstraint,
  ValidatorConstraintInterface,
} from "class-validator";
import { Transform } from "class-transformer";

/**
 * 실제로 영어 검사 로직을 수행하는 Constraint 클래스
 */
@ValidatorConstraint({ name: "isEnglish", async: false })
export class IsEnglishConstraint implements ValidatorConstraintInterface {
  validate(value: any, args: ValidationArguments): boolean {
    if (value === null || value === undefined || value === "") return true; // 빈 값은 스킵
    return /^[a-zA-Z\s-]+$/.test(value.trim());
  }

  defaultMessage(args: ValidationArguments): string {
    // custom message 가 들어오면 validationOptions.message 를 우선, 아니면 기본 메시지
    return `${args.property} must contain only English letters`;
  }
}

/**
 * 영어로만 구성된 값인지 검증하는 데코레이터
 */
export function IsEnglish(
  validationOptions?: ValidationOptions
): PropertyDecorator {
  return (object: Object, propertyName: string | symbol) => {
    // 1) 먼저 Transform 으로 트리밍
    Transform(({ value }) =>
      typeof value === "string" ? value.trim() : value
    )(object, propertyName);
    // 2) registerDecorator 로 class-validator 에 등록
    registerDecorator({
      name: "isEnglish",
      target: object.constructor,
      propertyName: propertyName as string,
      options: validationOptions,
      validator: IsEnglishConstraint,
    });
  };
}

위처럼, 앞서 받아놓은 class-transformer, class-validator 라이브러리를 활용하여 검증 로직을 만들었다.

이후 index.ts 에 해당 기능을 임포트하고 내보내면 된다.

// index.ts

import "reflect-metadata";
import { IsKorean, IsKoreanConstraint } from "./validators/is-korean.validator";
import {
  IsEnglish,
  IsEnglishConstraint,
} from "./validators/is-english.validator";

export { IsKorean, IsEnglish, IsKoreanConstraint, IsEnglishConstraint };

- 배포 전 단계

배포하기 전, package.json을 자신의 취향대로 수정한다.

{
  "name": "@zynoobb/validator", // 패키지 이름
  "version": "1.0.0", // 버전
  "description": "한글과 영어 입력을 위한 검증 라이브러리",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "require": "./dist/index.js",
      "import": "./dist/index.mjs",
      "types": "./dist/index.d.ts"
    },
    "./validators": {
      "require": "./dist/validators/index.js",
      "import": "./dist/validators/index.mjs",
      "types": "./dist/validators/index.d.ts"
    }
  },
  "files": [
    "dist", // 빌드된 내용
    "README.md", // 라이브러리 설명
    "LICENSE" // 라이센스에 대한 내용을 적어주면 좋다
  ],
  
  ... 중략

- 배포 단계

먼저 npm 계정이 필요하다. 아래 명령어를 입력하여,

npm 계정을 생성하는 페이지로 이동하거나, 로그인 할 수 있다.

npm login

이후 아래와 같은 명령어를 입력한다.

npm run build // 라이브러리 빌드
npm pack // 라이브러리 압축

이떄 npm pack 명령어를 실행하면, .tgz 압축 파일이 생성되는데,

그 안에 dist, readme.md 파일이 있는지 확인하면 좋다.

npm publish --access public // 공개 배포

여기까지 마치면, npm.js에 자신이 만든 라이브러리가 배포된다.

이때 라이브러리는 배포된 순간 삭제할 수 없다.

https://www.npmjs.com/package/@zynoobb/validator

이제 실제 다운 받아서 테스트 해보도록 한다.

테스트하기 위한 코드는 아래와 같이 작성했다.

import { IsEnglish } from '@zynoobb/validator';
import { validate } from 'class-validator';
import express, { Request, Response } from 'express';

class TestDTO {
  @IsEnglish()
  name!: string;
}

const app = express();

app.use(express.json());

app.post('/', async (req: Request, res: Response) => {
  const testDTO = new TestDTO();
  testDTO.name = (req.body as { name: string }).name;

  const errors = await validate(testDTO);
  if (errors.length > 0) {
    return res.status(400).json({ errors });
  }

  return res.status(200).json({ message: 'successful' });
});

app.listen(3000, () => {
  console.log('Server running');
});

포스트맨으로 실행한 결과, 내 예상대로 에러가 나타남을 확인할 수 있었다.

Docker-compose - .sh 파일과 DB 백업

자전하는명왕성 — Fri, 9 May 2025 23:14:19 +0900

이번 포스팅은 Docker-compose 를 사용하며, 데이터베이스를 백업하는 방식에 대해 다룬다.

먼저, 해당 포스팅을 작성하기 전, 나는 다음과 같은 문제를 겪었다.

- Nest.js 를 Docker-compose 를 활용해 개발 중이었다.

- 그리고, Docker 컨테이너 안에서는 docker exec 명령어 자체가 불가능한 상황이었으며

- 따라서 DB 백업 명령어를 서버 안에서 직접 실행할 수 없는 문제가 발생했다.

즉, Docker 컨테이너 내부가 아닌 외부에서 백업 명령어를 수행시키면 될 일이다.

해결 방식은 다음과 같다.

- Nest.js는 백업 요청(.todo 파일)만 생성한다.

- 호스트(내 맥북)에서 .sh 파일(backup-watch.sh)이 백그라운드로 실행되게 하고

- .todo 파일이 생겼는지 감지하며

- 해당 파일이 감지된 경우, 진짜 docker exec 명령어로 백업을 수행한다.

정리하자면, 서버 컨테이너가 직접 docker 명령어를 사용하지 못하니,

내 맥북에서 감시하고 명령을 실행할 수 있도록 자동화된 Shell script(.sh)파일을 작성했다고 보면 좋다.

.sh 파일이란, shell script 파일로, 여러 터미널 명령어를 모아놓고, 한번에 실행할 수 있게 만든 스크립트.

폴더 구조는 다음과 같다

// 폴더 구조
root/
├── backup/
│   ├── db/                   # 실제 백업된 .sql.gz 파일 저장 폴더
│   └── tasks/                 # .todo 파일 저장 폴더 (백업 요청용)
│
├── backup-watcher.sh          # 호스트에서 돌아가는 감시 스크립트
│
└── src/
    └── data-backup/
        ├── data-backup.service.ts    # 백업 요청(create-backup.todo 파일 생성)
        └── data-backup.resolver.ts   # graphQL API (백업 요청, 삭제 등)

.sh 작성 요령에 대해서는 다음과 같다.

# backup-watcher.sh  

#!/bin/bash # 선언 명시

echo "[Watcher] 백업 감시" # echo 문자열 터미널에 출력

while true; do # 무한 루프 시작
  if [ -f backup/tasks/create-backup.todo ]; then # -f 파일 경로에 파일 존재 확인
    echo "[Watcher] 백업 요청 감지" # 존재한다면 문자열 출력 

    timestamp=$(date +"%Y-%m-%dT%H-%M-%S") # 파일 이름으로 쓸 시간 변수 저장
    backup_dir="backup/db" # 저장 위치
    backup_file="$backup_dir/neodb_${timestamp}.sql.gz" # 파일 이름

    mkdir -p $backup_dir # 해당 디렉토리가 있으면 새로 만들고 있으면 무시
    # 즉, backup/db 폴더가 없으면 새로 만듬

    echo "[Watcher] 백업 파일 생성 중: $backup_file" 

    docker exec {db_container_name} sh -c 'mysqldump -u {user_id} -p"{user_password}" {db_name}' | gzip > $backup_file
    # {} 안에는 해당되는 내용의 이름을 넣어주면 된다
    # docker exec docker 컨테이너 안에서 명령어 실행
    # mysqldump mysql db 백업 명령어
    # gzip 결과를 바로 압축
    # 해당 결과를 back_file 이름으로 저장

    if [ -s "$backup_file" ]; then # 파일 존재하고, 크기가 0보다 크면 true
      echo "[Watcher] 백업 성공: $backup_file"
    else
      echo "[Watcher] 백업 실패: 파일이 비어있음"
      rm -f "$backup_file" # 백업 파일 강제 삭제
    fi

    # todo 파일 삭제
    rm -f backup/tasks/create-backup.todo # 트리거로써 역할 완수했으니 todo파일 삭제
    echo "[Watcher] 백업 요청 완료 및 .todo 파일 삭제"

  fi
  sleep 3  # 3초마다 체크
done

서비스 로직은 위에서 언급한 것과 같이,

백업 파일 생성 기능이 실행되면 .todo 파일을 생성하기만 하면 된다.

// data-backup.service.ts

taskDir = path.resolve('backup/tasks'); // .todo 파일 위치

async createBackup(): Promise<boolean> {
  try {
    // tasks 폴더가 없으면 생성
    if (!fs.existsSync(this.taskDir)) {
      fs.mkdirSync(this.taskDir, { recursive: true });
    }

    // create-backup.todo 파일 경로 지정
    const todoPath = path.join(this.taskDir, 'create-backup.todo');

    // .todo 파일 생성 (백업 요청)
    fs.writeFileSync(todoPath, 'CREATE_BACKUP');

    return true;
  } catch (error) {
    throw new CusException();
  }
}

라즈베리파이 - OS 설치 방법과 원격 접속 방법(VNC)

자전하는명왕성 — Tue, 6 May 2025 20:10:45 +0900

홈서버를 구축해보고자, '일단' 라즈베리파이5를 구매했다.

먼저, 해당 설치 방식은 SD카드가 필요하니 참고할 것.

아래 해당 홈페이지에서 OS를 설치할 수 있다.

https://www.raspberrypi.com/software/

현재 자신의 PC에 맞는 운영체제를 선택 후, Raspberry Pi imager를 설치해준다.

설치가 완료되면, 아래와 같은 화면이 뜨는데

자신의 라즈베리파이 디바이스 모델, 원하는 OS(추천하길래 64Bit OS로 설치)

그리고 설치를 원하는 SD 카드를 선택한다.

이후 설치된 파일을 라즈베리파이에 옮겨, 와이파이 및 추가적인 설정을 완료한다.

(내 경우, 라즈베리파이와의 인풋 연결을 위해, 방에 있는 마우스와 키보드를 모두 꺼내야 했음 ㅡ.ㅡ)

여자저차 세팅을 완료했는데, 키보드며 마우스, hdmi 선까지 온통 테이블 위에 올라가 있으니, 불편하다 느껴졌고,

이를 타파하고자 원격으로 접속할 수 있는 방법을 찾았다.

그리고 이에 대해 설명한다.

1. VNC

먼저, VNC란, 원격 컴퓨터의 데스크탑 화면을 캡쳐하여 네트워크로 전송 & 입력(키보드, 마우스) 원격 컴퓨터로 전달하는 프로토콜을 말한다.

이때, VNC 서버는 화면을 캡처하고 입력 이벤트를 수신하는 쪽으로 여기서는 라즈베리 파이.

반대로 VNC 뷰어는 화면을 렌더링하고 키보드, 마우스 입력을 전송하는 쪽으로 여기서는 내 PC를 의미한다.

2. 작동 원리

작동원리는 간략히 말하면 다음과 같은데,

화면의 경우 서버는 화면 출력을 일정 주기로 캡처하고, 이를 이미지로 압축한다.

그리고 압축된 화면 데이터를 프레임 단위로 뷰어에게 전송하고, 뷰어는 이를 받아 디코딩해 화면으로 출력하는 순이다.

입출력도 비슷한데, 키보드 마우스 이벤트를 패킹해 서버로 전송하고, 서버는 이를 ㅂ다아 로컬 입력으로 주입한다.(가상 입력장치 사용)

3. 필요 조건

서버와 뷰어가 같은 네트워크에 존재해야 하며,

VNC포트가 열려있고, 방화벽에서 허용된 상태여야 한다.

4. 적용 방법

먼저 라즈베리파이에서 터미널을 열고 아래와 같은 명령어를 입력한다.

sudo apt update
sudo apt install realvnc-vnc-server // vnc-server 다운
sudo raspi-config // 라즈베리파이 설정 창 열기

터미널은 좌측 상단에 있다.

config 관련 명령어까지 입력했으면 위와 같은 창이 뜨는데, 여기서 Interface Option 탭으로 들어가,

VNC설정을 Enable로 바꾼다.

이후 터미널에서 아래의 명령어를 입력하면 라즈베리파이의 IP가 나타나는데 이를 기록해두자.

hostname -I

다음 원격을 하기 위한 PC에서는

https://www.realvnc.com/en/connect/download/viewer/

위 홈페이지에서 자신의 OS에 맞는 VNC뷰어를 설치하고 실행한다.

그리고, 위에 언급한 라즈베리파이의 IP를 VNC뷰어에 입력해주면 된다.

그러면 이와 같이 연결된 화면을 띄울 수가 있다.

Spring boot - Custom Global exception Handler 적용

자전하는명왕성 — Sun, 4 May 2025 11:05:35 +0900

Spring boot를 사용 중에 있어, 내 서버의 에러가 곧이 곧대로 반환되는 게 마음에 들지 않았다.

따라서, 클라이언트에 보여지는 건, 프론트엔드 개발자와 약속한 코드가 보여지고

직접적인 에러는 서버 콘솔에서 로그로 남게끔 설정하는 과정을 다룬 포스팅을 남긴다.

먼저, global exception handler를 적용하는 이유는 다음과 같다.

서버를 만들다보면 어떤 이유에서든 예상하지 못한 예외가 발생할 수 있는데,

이에 대해 매번 try-catch 로 직접 처리하는 것은 비효율적이고 지저분하며, 잊어버릴 수도 있다.

따라서, 서버 전역에서 예외를 통합 관리하는 구조가 필요한데,

해당 기능을 해주는 것이 해당 핸들러다.

// CustomException.java
package com.chessy.exception;

public class CustomException extends RuntimeException {
  private final ErrorCode errorCode;

  public CustomException(ErrorCode errorCode) {
    super(errorCode.getMessage());
    this.errorCode = errorCode;
  }

  public CustomException(ErrorCode errorCode, String message) {
    super(message);
    this.errorCode = errorCode;
  }

  public ErrorCode getErrorCode() {
    return errorCode;
  }
}

해당 에러를 어떻게 다룰 것인지에 대한 핸들러다.

만약

에러 코드 이름=NOT_FOUND_USER

에러 코드 넘버=200 이라고 한다면,

나는 서비스 로직에서 에러 코드 이름을 CustomException에 전달하고,

해당 클래스에서 에러 코드 이름에 대응하는 에러 코드 넘버를 가져와 반환토록 한다.

에러 코드를 매핑한 코드는 다음과 같다.

package com.chessy.exception;

import lombok.Getter;

@Getter
public enum ErrorCode {
  USER_NOT_FOUND(200, "사용자를 찾을 수 없습니다."),

  private final int code;
  private final String message;

  ErrorCode(int code, String message) {
    this.code = code;
    this.message = message;
  }
}

마지막 GlobalExceptionHandler를 작성한다.

package com.chessy.exception;

import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@Slf4j
@ControllerAdvice
public class GlobalExceptionHandler {
  // 의도된 에러
  @ExceptionHandler(CustomException.class)
  public ResponseEntity<ErrorResponse> handleCustomException(CustomException ex) {
    log.error("[CustomException] {} - cause: {}", ex.getMessage(), ex.getCause() != null ? ex.getCause() : "-");

    return ResponseEntity
        .status(HttpStatus.INTERNAL_SERVER_ERROR) // HTTP Status는 500 고정
        .body(ErrorResponse.of(ex.getErrorCode().getCode()));
  }

  // 의도되지 않은 에러
  @ExceptionHandler(Exception.class)
  public ResponseEntity<ErrorResponse> handleAllExceptions(Exception ex) {
    log.error("[UnknownException] {} - cause: {}", ex.getMessage(), ex.getCause() != null ? ex.getCause() : "-");

    return ResponseEntity
        .status(HttpStatus.INTERNAL_SERVER_ERROR)
        .body(ErrorResponse.of(ErrorCode.INTERNAL_SERVER_ERROR.getCode()));
  }
}

소스 코드는 다음과 같다.

- 추가설명

@ControllerAdvice => 모든 @Controller, @RestController 에 적용되는 전용 어노테이션
	내부적으로 @Component가 포함되어 있어, 별도 bean 등록 없이 사용이 가능하다.

@ExceptionHandler => 특정 예외를 캐치해서 처리할 수 있도록 도와주는 어노테이션
	어떤 타입의 예외를 잡을지 명시할 수 있다.
    
해당 코드의 경우, http 상태 코드는 에러 시 무조건 internal_server 에러로 반환토록 하고,
	내가 의도한 에러와 의도되지 않은 에러를 같은 방식으로 반환할 수 있게 작성했다.

Spring boot - Api docs 설정 (Swagger + OpenAPI)

자전하는명왕성 — Thu, 1 May 2025 22:13:02 +0900

이번 포스팅은 스프링부트에서 Api docs를 설정하는 방식에 대해 다룬다.

(아마 다음 포스팅은 GraphQL 설정 방식에 대해 다룰 듯 싶다.)

Api docs를 사용하기 있어, 먼저 해당 기능 사용을 돕는 라이브러리를 추가한다.

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    
    // Swagger 
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
    implementation 'org.springdoc:springdoc-openapi-starter-common:2.5.0'
    implementation 'io.swagger.core.v3:swagger-annotations:2.2.20'
    
    // 중략
}

여기서, org.springdoc의 버전은 1.8.0 | 2.3.0 | 2.5.0 이 존재하니 자신이 원하는 버전으로 설치하면 될 것 같다.

이후 Swagger UI 기본 경로 및 문서 경로를 설정한다.

// application.yml
springdoc:
    swagger-ui:
        enabled: true
        path: /swagger-ui.html // Swagger ui 접근 경로
        operationsSorter: method // 메소드 정렬
        tagsSorter: alpha // 태그 알파벳순 정렬
        tryItOutEnabled: true
        filter: true // 필터
        urls:
            - url: /v3/api-docs 
              name: Chessy API
    api-docs:
        enabled: true
        path: /v3/api-docs // open api 스펙 json 경로
    default-produces-media-type: application/json
    default-consumes-media-type: application/json

이후 각 컨트롤러에

@Tag, @Operation 어노테이션으로 Swagger가 적용됨을 명시하며, 설명을 덧붙일 수 있다.

// AppController.java

package com.chessy.controller;

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

import com.chessy.exception.CustomException;
import com.chessy.exception.ErrorCode;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "AppController", description = "기본 API")
@RestController
@RequestMapping("/api/")
public class AppController {
  @Operation(summary = "헬스 체커", description = "애플리케이션 상태 확인 API")
  @GetMapping("/")

  public String healthCheck() {
    return "ok";
  }

  @Operation(summary = "테스트 API", description = "예외 처리 테스트용 API")
  @GetMapping("/test")
  public String test() {
    throw new CustomException(ErrorCode.USER_NOT_FOUND);
  }

}

보통은 여기까지하면 아래 주소로 접속이 가능하다.

/swagger-ui.html

하지만, 언제든 api 버전 관리는 필요하기 때문에 커스텀 하는 방법도 소개한다.

// Spring.Config.java

@Configuration
public class SpringConfig implements WebMvcConfigurer {

  // 중략

  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("Test API") // 제목
            .version("1.0.0") // 버전
            .description("API 문서") // 설명
            .contact(new Contact()
                .name("zynoobb") // 작성자
                .email("jw9491@gmail.com")) // 연락처
            .license(new License()
                .name("Apache 2.0")
                .url("http://springdoc.org")));
  }
}

이와 같은 방식으로 해당 내용을 추가해줄 수 있다.

추가로, 위 html 주소를 일일히 외워쓰기 번거롭다면 아래와 같은 방법을 사용할 수 있다.

// SwaggerController.java

package com.**.controller;

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

@Controller
public class SwaggerController {

  @GetMapping("/api")
  public String redirectSwagger() {
    return "redirect:/swagger-ui/index.html";
  }
}

/api 로 접속 시, 내 swagger 주소로 리디렉션하는 방식으로

URI 뒤에 api 로 접속하면 스웨거로 빠르게 접속할 수 있다.

ps. 자바스크립트 기반 프레임워크 같은 경우는,

swagger를 작성함에 있어 api에서 사용하는 인풋값의 타입을 직접 지정해주어야 하는 불편함이 있었는데,

스프링부트의 경우 아직까지는 그럴 필요가 없어서 꽤 만족스럽다.

Spring boot - Docker-compose hot loading 환경 설정(with, vscode)

자전하는명왕성 — Fri, 25 Apr 2025 23:03:00 +0900

오늘은 몇날 며칠 숙고했던 Spring boot 에서의 Docker 환경 설정에 대해 다룬다.

포스팅에 앞서, 겪고 있던 문제에 대해 설명하면, 소스 코드 변경 시 해당 변경 사항이 적용되지 않은 채 docker가 재로딩되는 문제였다.

재로딩 자체는 의도했던 것이었지만, 변경된 소스 코드가 적용되지 않은 채 변경되었다는 게 문제.

따라서, 마침내 승리한 기록을 남기고자, 미래에 나에게 전하고자 중점 소스 코드 위주로 해당 포스팅을 남긴다.

1. build.gradle 설정을 아래와 같이 추가한다.

// Spring Boot DevTools 의존성 추가
implementation 'org.springframework.boot:spring-boot-devtools'

// bootRun 태스크 설정
bootRun {
    dependsOn 'classes'
    sourceResources sourceSets.main
}

// 소스 코드 변경 감지 태스크
tasks.register('watch') {
    doLast {
        println '소스코드 변경 감지 중'
        exec {
            executable = 'gradle'
            args = ['build', '--continuous']
        }
    }
}

2. Dockerfile 을 아래와 같이 수정한다.

# 베이스 이미지 (Gradle + JDK 17 포함)
FROM gradle:8.6-jdk17 as builder 

# 작업 디렉토리 설정
WORKDIR /app

# 의존성 설치를 위해 gradle 관련 파일만 먼저 복사
COPY build.gradle settings.gradle gradlew gradlew.bat ./
COPY gradle ./gradle

# 의존성만 미리 다운 (캐시 최적화)
RUN ./gradlew dependencies --no-daemon || return 0

# 소스 복사
COPY src ./src

# 실행 포트 오픈
EXPOSE 8080

# gradlew 실행권한 부여
RUN chmod +x ./gradlew

# 환경변수 설정 (optional, devtools)
ENV SPRING_DEVTOOLS_RESTART_ENABLED=true
ENV SPRING_DEVTOOLS_LIVERELOAD_ENABLED=true

# 어플리케이션 실행
CMD ["./gradlew", "bootRun", "--continuous", "--no-daemon"]

# --continuous => 소스 코드를 지속적으로 감지
# --no-daemon => grdale 데몬을 사용하지 않고 직접 실행
# (빌드 속도는 빠르나, Docker 컨테이너 자체가 일회성이 잦기에 데몬 유지가 의미 없을 뿐더러 메모리 누수 방지)

3. docker-compose.yaml 파일 설정

version: '3.8'

services:
  app:
    container_name: ${container_name}
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "8080:8080"
    environment:
      SPRING_PROFILES_ACTIVE: dev
      SPRING_DATASOURCE_URL: jdbc:mysql://db:3306/${DB_NAME}
      SPRING_DATASOURCE_USERNAME: ${DB_USERNAME}
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
    volumes:
      - ./src:/app/src
      - ./gradle:/app/gradle
      - ./build.gradle:/app/build.gradle
      - ./settings.gradle:/app/settings.gradle
      - ./gradlew:/app/gradlew
      - ./gradlew.bat:/app/gradlew.bat
      - ./build:/app/build
      - ~/.gradle:/root/.gradle
    env_file:
      - .env
    depends_on:
      - db
    command: sh -c "./gradlew classes --continuous --no-daemon & ./gradlew bootRun --no-daemon"

// 이하 중략

해당 파일에 대해 설명을 하자면,

# 볼륨
./src:/app/src => 소스 코드 변경을 실시간으로 반영토록 하는 볼륨
~/.gradle:/root/.gradle => gradle 캐시 공유
기타 => gradle 관련 파일 & 설정 유지

# 명령어
./gradlew classes --continuous --no-daemon: 소스 코드 변경 감지
./gradlew bootRun --no-daemon: 애플리케이션 실행

주의 사항

- 소스 코드 변경 시 자동으로 재빌드 되지만, 일부 변경 사항의 경우 서버 재시작이 필요할 수 있음.

추신

- nest.js할 때가 좋았다.