Wallet Gateway API

NestJS + TypeScript 기반의 Wallet Gateway API 서버입니다.

설치

pnpm install

실행

# 개발 모드
pnpm run start:dev

# 프로덕션 빌드
pnpm run build
pnpm run start:prod

환경 설정

데이터베이스

PostgreSQL 데이터베이스가 필요합니다. 설정은 application.yaml 파일에서 관리됩니다:

database:
  host: localhost
  port: 5432
  username: postgres
  password: 'postgres'
  database: wallet
  synchronize: false
  logging: false

환경 변수로도 설정할 수 있습니다:

• DB_HOST
• DB_PORT
• DB_USERNAME
• DB_PASSWORD
• DB_DATABASE
• DB_LOGGING

API 스펙

API 스펙은 다음을 참조하세요:

• Notion 문서: Server API Spec
• Swagger UI: 서버 실행 후 http://localhost:8080/api에서 확인 가능 (기본 포트: 8080)

주요 엔드포인트

• POST /v1/wallet - 주소 생성 요청 (tokenId 사용)
• POST /v1/withdrawal - 출금 요청 (tokenId 사용)

모든 API는 x-request-id 헤더가 필수이며, 통일된 응답 형식을 사용합니다.

API 요청 예시

주소 생성 요청:

{
  "organizationId": "KqQjPXZna31P4mhQ",
  "tokenId": 1,
  "accountId": 0,
  "change": 0
}

출금 요청:

{
  "organizationId": "KqQjPXZna31P4mhQ",
  "tokenId": 1,
  "from": "0x1111111111111111111111111111111111111111",
  "to": "0x2222222222222222222222222222222222222222",
  "amount": "0.125"
}

더 많은 예시는 api.http 파일을 참조하세요.

HTTP 요청 테스트

프로젝트에 포함된 api.http 파일을 사용하여 API를 테스트할 수 있습니다.

VS Code 사용 시:

1. REST Client 확장 설치
2. api.http 파일 열기
3. 각 요청 위에 표시되는 "Send Request" 버튼 클릭

IntelliJ IDEA / WebStorm 사용 시:

• 내장 HTTP Client 기능 사용 (별도 설치 불필요)
• api.http 파일에서 요청 실행

프로젝트 구조

src/
├── common/
│   ├── decorators/      # 커스텀 데코레이터
│   ├── filters/         # 예외 필터
│   ├── guards/          # 가드
│   ├── interceptors/    # 인터셉터
│   └── dto/             # 공통 DTO
├── entities/            # TypeORM 엔티티
│   ├── chain.entity.ts
│   ├── token.entity.ts
│   ├── wallet-request.entity.ts
│   ├── wallet.entity.ts
│   ├── withdrawal-request.entity.ts
│   └── withdrawal-receipt.entity.ts
├── wallet/              # 주소 생성 요청 모듈
│   ├── dto/
│   ├── wallet.controller.ts
│   ├── wallet.service.ts
│   └── wallet.module.ts
├── withdrawal/          # 출금 요청 모듈
│   ├── dto/
│   ├── withdrawal.controller.ts
│   ├── withdrawal.service.ts
│   └── withdrawal.module.ts
├── config/              # 설정 파일
│   └── database.config.ts
├── app.module.ts
└── main.ts

주요 기능

• ✅ 글로벌 Validation Pipe (class-validator, class-transformer)
• ✅ 글로벌 Exception Filter 및 통일된 에러 응답 포맷
• ✅ Winston 기반 로깅 (nest-logger)
  • HTTP 요청/응답 로깅 (HttpLoggerMiddleware)
  • 요청/응답 시간 측정
  • 서비스 레벨 로깅 (LoggerService)
• ✅ x-request-id 헤더 필수 검증 (UUID 형식)
• ✅ Idempotency 지원 (동일한 request-id로 중복 요청 방지)
• ✅ TypeORM을 사용한 DB 저장 로직
• ✅ Swagger API 문서화
• ✅ 통일된 API 응답 형식
  • 성공: { "success": true, "data": {...}, "error": null }
  • 실패: { "success": false, "data": null, "error": { "code": 400, "message": "..." } }

로깅

이 프로젝트는 nest-logger를 사용합니다.

HTTP 로깅

HttpLoggerMiddleware가 모든 HTTP 요청/응답을 자동으로 로깅합니다:

• 요청: method, url, body, query, params, x-request-id
• 응답: method, url, statusCode, responseTime, body
• 에러: 에러 정보 및 스택 트레이스

서비스 로깅

서비스에서 LoggerService를 주입받아 사용할 수 있습니다:

import { LoggerService } from 'nest-logger';

constructor(private readonly logger: LoggerService) {}

this.logger.log('Message', 'Context');
this.logger.warn('Warning', 'Context');
this.logger.error('Error', 'Stack', 'Context');