AI 기반 시각화 전문지식 서비스

프로그램개발 · 분야 선택22개 분야

Ver3.0 전체 열람

Ver3.0 🚀 Node.js와 TypeScript로 만드는 Express 백엔드 API 개발 완벽 가이드

2025.10.16

재능넷

댓글 0 전체 35 페이지

🚀 Node.js와 TypeScript로 만드는 Express 백엔드 API 개발 완벽 가이드

타입 안정성을 갖춘 프로페셔널한 백엔드 서버 구축하기

🎯 왜 TypeScript로 백엔드를 개발해야 할까?

야, 솔직히 말해서 JavaScript로도 백엔드 개발 충분히 할 수 있잖아? 근데 프로젝트가 커지면서 느끼는 거 있지 않아? 😅 "이 함수가 뭘 리턴하더라?", "이 파라미터 타입이 뭐였지?", "런타임에서 왜 갑자기 에러가...?" 이런 경험들 말이야.

바로 이런 문제들 때문에 요즘 백엔드 개발자들이 TypeScript로 넘어오고 있어. 특히 Node.js와 Express 조합에 TypeScript를 더하면, 정말 강력한 시너지가 나거든. 🚀

💡 TypeScript 백엔드의 핵심 장점 타입 안정성: 컴파일 타임에 에러를 잡아내서 런타임 버그를 대폭 줄여줘
자동완성: IDE가 똑똑해져서 개발 속도가 2배는 빨라져
리팩토링: 코드 구조 변경할 때 어디서 문제 생길지 바로 알 수 있어
협업: 타입 정의가 곧 문서화야. 팀원들이 코드 이해하기 훨씬 쉬워져
유지보수: 6개월 후에 내가 짠 코드 봐도 무슨 의미인지 바로 파악 가능

실제로 재능넷 같은 플랫폼에서도 TypeScript 백엔드 개발 재능을 찾는 수요가 엄청 늘어나고 있어. 왜냐면 기업들이 이제 타입 안정성의 중요성을 깨달았거든. 💼

🛠️ 개발 환경 세팅부터 시작해보자

자, 이제 본격적으로 시작해볼까? 먼저 개발 환경부터 제대로 갖춰야 해. 이 부분이 튼튼해야 나중에 삽질 안 하거든! 😎

📦 필수 패키지 설치하기

Node.js는 이미 설치되어 있다고 가정할게. 없으면 nodejs.org에서 LTS 버전 받아서 설치하면 돼. 그럼 이제 프로젝트 폴더 만들고 시작해보자!

# 프로젝트 폴더 생성 및 이동
mkdir my-typescript-api
cd my-typescript-api

# package.json 초기화
npm init -y

# TypeScript 및 필수 패키지 설치
npm install express
npm install -D typescript @types/node @types/express

# TypeScript 설정 파일 생성
npx tsc --init

여기서 -D 플래그는 개발 의존성(devDependencies)으로 설치한다는 뜻이야. TypeScript는 개발할 때만 필요하고, 실제 프로덕션에서는 컴파일된 JavaScript가 실행되니까 말이지. 🎯

🔥 Pro Tip: @types/로 시작하는 패키지들은 TypeScript 타입 정의 파일이야. JavaScript로 작성된 라이브러리들에 타입 정보를 추가해주는 역할을 해. Express도 원래는 JavaScript 라이브러리지만, @types/express를 설치하면 TypeScript에서 타입 체크가 가능해져!

⚙️ tsconfig.json 설정하기

npx tsc --init 명령어를 실행하면 tsconfig.json 파일이 생성돼. 이 파일은 TypeScript 컴파일러 설정을 담고 있어. 기본 설정도 괜찮지만, 백엔드 개발에 최적화된 설정으로 바꿔보자! 💪

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "sourceMap": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

🎓 주요 설정 항목 설명

target: 컴파일될 JavaScript 버전. ES2020이면 최신 Node.js에서 잘 돌아가
module: Node.js는 CommonJS 모듈 시스템을 사용해
outDir: 컴파일된 파일이 저장될 폴더
rootDir: 소스 코드가 있는 폴더
strict: 엄격한 타입 체크 활성화. 이게 TypeScript의 진짜 파워야! 💪
esModuleInterop: CommonJS와 ES Module 간 호환성 개선
sourceMap: 디버깅할 때 원본 TypeScript 코드 위치를 알려줘

📁 프로젝트 구조 잡기

프로젝트 구조를 처음부터 잘 잡아놓으면 나중에 정말 편해. 내가 추천하는 구조는 이거야:

my-typescript-api/
├── src/
│   ├── controllers/     # 비즈니스 로직 처리
│   ├── routes/          # API 라우트 정의
│   ├── models/          # 데이터 모델 및 타입
│   ├── middlewares/     # 미들웨어 함수들
│   ├── services/        # 외부 서비스 연동
│   ├── utils/           # 유틸리티 함수
│   ├── types/           # 공통 타입 정의
│   └── app.ts           # Express 앱 설정
│   └── server.ts        # 서버 시작점
├── dist/                # 컴파일된 파일
├── node_modules/
├── package.json
└── tsconfig.json

이렇게 폴더별로 역할을 명확히 나누면 코드 찾기도 쉽고, 나중에 팀원이 합류해도 구조 파악이 빨라져. 🎯

🚀 첫 번째 TypeScript Express 서버 만들기

자, 이제 진짜 코딩 시작이야! 먼저 간단한 서버부터 만들어보자. src/app.ts 파일을 만들어줘.

📝 app.ts - Express 앱 설정

import express, { Application, Request, Response, NextFunction } from 'express';

// Express 앱 생성
const app: Application = express();

// JSON 파싱 미들웨어
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// 기본 라우트
app.get('/', (req: Request, res: Response) => {
  res.json({
    message: '🎉 TypeScript Express API 서버가 정상 작동 중입니다!',
    timestamp: new Date().toISOString()
  });
});

// 404 에러 핸들링
app.use((req: Request, res: Response) => {
  res.status(404).json({
    error: 'Not Found',
    message: '요청하신 리소스를 찾을 수 없습니다.'
  });
});

// 에러 핸들링 미들웨어
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error(err.stack);
  res.status(500).json({
    error: 'Internal Server Error',
    message: err.message
  });
});

export default app;

여기서 주목할 점은 타입 어노테이션이야. Application, Request, Response 같은 타입들을 명시해줌으로써, IDE가 자동완성을 제공하고 타입 에러를 미리 잡아낼 수 있어. 😊

🎬 server.ts - 서버 시작점

import app from './app';

const PORT: number = parseInt(process.env.PORT || '3000', 10);

app.listen(PORT, () => {
  console.log(`🚀 서버가 포트 ${PORT}에서 실행 중입니다.`);
  console.log(`📍 http://localhost:${PORT}`);
});

app.ts와 server.ts를 분리하는 이유는 테스트 때문이야. 나중에 유닛 테스트 작성할 때 서버를 실제로 시작하지 않고도 앱 로직을 테스트할 수 있거든! 🧪

🏃 실행 스크립트 설정

package.json에 실행 스크립트를 추가해주자. 개발할 때는 코드 변경 시 자동으로 재시작되면 편하니까 nodemon과 ts-node를 사용할 거야.

# 개발 도구 설치
npm install -D ts-node nodemon @types/nodemon

그리고 package.json의 scripts 섹션을 이렇게 수정해:

{
  "scripts": {
    "dev": "nodemon --exec ts-node src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js",
    "watch": "tsc --watch"
  }
}

이제 npm run dev 명령어로 개발 서버를 실행할 수 있어. 코드를 수정하면 자동으로 재시작되니까 엄청 편해! 🎉

# 개발 서버 실행
npm run dev

# 브라우저나 curl로 테스트
curl http://localhost:3000

🎨 타입 정의로 API 구조 설계하기

TypeScript의 진짜 힘은 타입 정의에서 나와. API를 만들기 전에 먼저 데이터 구조를 타입으로 정의해두면, 개발하면서 실수할 일이 확 줄어들어. 🛡️

📋 인터페이스와 타입 정의

src/types/user.types.ts 파일을 만들어서 사용자 관련 타입을 정의해보자:

// 기본 사용자 인터페이스
export interface User {
  id: string;
  email: string;
  username: string;
  createdAt: Date;
  updatedAt: Date;
}

// 사용자 생성 요청 DTO
export interface CreateUserDto {
  email: string;
  username: string;
  password: string;
}

// 사용자 업데이트 요청 DTO
export interface UpdateUserDto {
  email?: string;
  username?: string;
}

// 사용자 응답 DTO (비밀번호 제외)
export interface UserResponseDto {
  id: string;
  email: string;
  username: string;
  createdAt: string;
}

// API 응답 래퍼
export interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

💡 DTO가 뭐야? DTO(Data Transfer Object)는 데이터 전송 객체라는 뜻이야. 클라이언트와 서버 간에 주고받는 데이터의 형태를 정의하는 거지. 예를 들어 CreateUserDto는 사용자 생성할 때 필요한 데이터만 담고 있어. 이렇게 하면 불필요한 데이터가 전송되는 걸 막을 수 있어! 🎯

🔧 제네릭 타입 활용하기

위에서 ApiResponse<T>를 봤지? 이게 바로 제네릭이야. 어떤 타입의 데이터든 담을 수 있는 유연한 응답 구조를 만들 수 있어.

// 사용 예시
const userResponse: ApiResponse<UserResponseDto> = {
  success: true,
  data: {
    id: '123',
    email: 'user@example.com',
    username: 'cooluser',
    createdAt: new Date().toISOString()
  }
};

const usersListResponse: ApiResponse<UserResponseDto[]> = {
  success: true,
  data: [
    // 여러 사용자 데이터...
  ]
};

제네릭을 쓰면 코드 재사용성이 엄청 높아져. 같은 응답 구조를 다양한 데이터 타입에 적용할 수 있거든! 🚀

🛣️ 라우터와 컨트롤러 구조화하기

이제 실제 API 엔드포인트를 만들어볼 차례야. Express에서는 라우터를 사용해서 엔드포인트를 깔끔하게 정리할 수 있어.

🎮 컨트롤러 작성하기

먼저 src/controllers/user.controller.ts를 만들어보자:

import { Request, Response, NextFunction } from 'express';
import { 
  User, 
  CreateUserDto, 
  UpdateUserDto, 
  UserResponseDto, 
  ApiResponse 
} from '../types/user.types';

// 임시 데이터 저장소 (실제로는 DB 사용)
let users: User[] = [];

export class UserController {
  // 모든 사용자 조회
  static async getAllUsers(
    req: Request, 
    res: Response, 
    next: NextFunction
  ): Promise<void> {
    try {
      const response: ApiResponse<UserResponseDto[]> = {
        success: true,
        data: users.map(user => ({
          id: user.id,
          email: user.email,
          username: user.username,
          createdAt: user.createdAt.toISOString()
        }))
      };
      
      res.json(response);
    } catch (error) {
      next(error);
    }
  }

  // 특정 사용자 조회
  static async getUserById(
    req: Request<{ id: string }>, 
    res: Response, 
    next: NextFunction
  ): Promise<void> {
    try {
      const { id } = req.params;
      const user = users.find(u => u.id === id);

      if (!user) {
        res.status(404).json({
          success: false,
          error: 'User not found'
        });
        return;
      }

      const response: ApiResponse<UserResponseDto> = {
        success: true,
        data: {
          id: user.id,
          email: user.email,
          username: user.username,
          createdAt: user.createdAt.toISOString()
        }
      };

      res.json(response);
    } catch (error) {
      next(error);
    }
  }

  // 사용자 생성
  static async createUser(
    req: Request<{}, {}, CreateUserDto>, 
    res: Response, 
    next: NextFunction
  ): Promise<void> {
    try {
      const { email, username, password } = req.body;

      // 이메일 중복 체크
      const existingUser = users.find(u => u.email === email);
      if (existingUser) {
        res.status(400).json({
          success: false,
          error: 'Email already exists'
        });
        return;
      }

      const newUser: User = {
        id: Date.now().toString(),
        email,
        username,
        createdAt: new Date(),
        updatedAt: new Date()
      };

      users.push(newUser);

      const response: ApiResponse<UserResponseDto> = {
        success: true,
        message: 'User created successfully',
        data: {
          id: newUser.id,
          email: newUser.email,
          username: newUser.username,
          createdAt: newUser.createdAt.toISOString()
        }
      };

      res.status(201).json(response);
    } catch (error) {
      next(error);
    }
  }

  // 사용자 업데이트
  static async updateUser(
    req: Request<{ id: string }, {}, UpdateUserDto>, 
    res: Response, 
    next: NextFunction
  ): Promise<void> {
    try {
      const { id } = req.params;
      const updates = req.body;

      const userIndex = users.findIndex(u => u.id === id);
      if (userIndex === -1) {
        res.status(404).json({
          success: false,
          error: 'User not found'
        });
        return;
      }

      users[userIndex] = {
        ...users[userIndex],
        ...updates,
        updatedAt: new Date()
      };

      const response: ApiResponse<UserResponseDto> = {
        success: true,
        message: 'User updated successfully',
        data: {
          id: users[userIndex].id,
          email: users[userIndex].email,
          username: users[userIndex].username,
          createdAt: users[userIndex].createdAt.toISOString()
        }
      };

      res.json(response);
    } catch (error) {
      next(error);
    }
  }

  // 사용자 삭제
  static async deleteUser(
    req: Request<{ id: string }>, 
    res: Response, 
    next: NextFunction
  ): Promise<void> {
    try {
      const { id } = req.params;
      const userIndex = users.findIndex(u => u.id === id);

      if (userIndex === -1) {
        res.status(404).json({
          success: false,
          error: 'User not found'
        });
        return;
      }

      users.splice(userIndex, 1);

      res.json({
        success: true,
        message: 'User deleted successfully'
      });
    } catch (error) {
      next(error);
    }
  }
}

여기서 주목할 점이 몇 가지 있어! 😊

🎯 Request 타입 제네릭 Request<{ id: string }, {}, CreateUserDto> 이런 식으로 Request 타입에 제네릭을 사용했어. 순서대로:
1️⃣ URL 파라미터 타입 (req.params)
2️⃣ 응답 바디 타입 (보통 사용 안 함)
3️⃣ 요청 바디 타입 (req.body)
4️⃣ 쿼리 파라미터 타입 (req.query)

이렇게 하면 req.params.id나 req.body.email 같은 걸 쓸 때 자동완성이 되고, 타입 체크도 돼!

🛤️ 라우터 설정하기

이제 src/routes/user.routes.ts를 만들어서 라우트를 정의해보자:

import { Router } from 'express';
import { UserController } from '../controllers/user.controller';

const router: Router = Router();

// GET /api/users - 모든 사용자 조회
router.get('/', UserController.getAllUsers);

// GET /api/users/:id - 특정 사용자 조회
router.get('/:id', UserController.getUserById);

// POST /api/users - 사용자 생성
router.post('/', UserController.createUser);

// PUT /api/users/:id - 사용자 업데이트
router.put('/:id', UserController.updateUser);

// DELETE /api/users/:id - 사용자 삭제
router.delete('/:id', UserController.deleteUser);

export default router;

그리고 src/app.ts에 이 라우터를 등록해줘야 해:

import express, { Application } from 'express';
import userRoutes from './routes/user.routes';

const app: Application = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// 라우터 등록
app.use('/api/users', userRoutes);

// ... 나머지 코드

export default app;

이제 API가 완성됐어! 테스트해보자. 🎉

# 사용자 생성
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","username":"testuser","password":"secret123"}'

# 모든 사용자 조회
curl http://localhost:3000/api/users

# 특정 사용자 조회
curl http://localhost:3000/api/users/1234567890

🛡️ 미들웨어로 검증 로직 추가하기

API에 데이터가 들어올 때 검증하는 건 정말 중요해. 잘못된 데이터가 들어오면 서버가 터질 수도 있거든! 😱 TypeScript와 함께 검증 라이브러리를 사용하면 더 안전해져.

✅ 입력 검증 미들웨어

src/middlewares/validation.middleware.ts를 만들어보자:

import { Request, Response, NextFunction } from 'express';
import { CreateUserDto, UpdateUserDto } from '../types/user.types';

// 이메일 형식 검증
const isValidEmail = (email: string): boolean => {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
};

// 사용자 생성 검증
export const validateCreateUser = (
  req: Request<{}, {}, CreateUserDto>,
  res: Response,
  next: NextFunction
): void => {
  const { email, username, password } = req.body;

  // 필수 필드 체크
  if (!email || !username || !password) {
    res.status(400).json({
      success: false,
      error: 'Missing required fields',
      message: 'email, username, password are required'
    });
    return;
  }

  // 이메일 형식 검증
  if (!isValidEmail(email)) {
    res.status(400).json({
      success: false,
      error: 'Invalid email format'
    });
    return;
  }

  // 사용자명 길이 검증
  if (username.length < 3 || username.length > 20) {
    res.status(400).json({
      success: false,
      error: 'Username must be between 3 and 20 characters'
    });
    return;
  }

  // 비밀번호 길이 검증
  if (password.length < 6) {
    res.status(400).json({
      success: false,
      error: 'Password must be at least 6 characters'
    });
    return;
  }

  next();
};

// 사용자 업데이트 검증
export const validateUpdateUser = (
  req: Request<{ id: string }, {}, UpdateUserDto>,
  res: Response,
  next: NextFunction
): void => {
  const { email, username } = req.body;

  // 최소 하나의 필드는 있어야 함
  if (!email && !username) {
    res.status(400).json({
      success: false,
      error: 'At least one field must be provided'
    });
    return;
  }

  // 이메일이 있으면 형식 검증
  if (email && !isValidEmail(email)) {
    res.status(400).json({
      success: false,
      error: 'Invalid email format'
    });
    return;
  }

  // 사용자명이 있으면 길이 검증
  if (username && (username.length < 3 || username.length > 20)) {
    res.status(400).json({
      success: false,
      error: 'Username must be between 3 and 20 characters'
    });
    return;
  }

  next();
};

이제 라우터에 이 미들웨어를 적용해보자:

import { Router } from 'express';
import { UserController } from '../controllers/user.controller';
import { validateCreateUser, validateUpdateUser } from '../middlewares/validation.middleware';

const router: Router = Router();

router.get('/', UserController.getAllUsers);
router.get('/:id', UserController.getUserById);

// 검증 미들웨어 추가
router.post('/', validateCreateUser, UserController.createUser);
router.put('/:id', validateUpdateUser, UserController.updateUser);

router.delete('/:id', UserController.deleteUser);

export default router;

🔥 더 강력한 검증이 필요하다면? 실무에서는 joi, yup, class-validator 같은 검증 라이브러리를 많이 써. 특히 class-validator는 TypeScript 데코레이터를 활용해서 정말 깔끔하게 검증 로직을 작성할 수 있어! 나중에 프로젝트가 커지면 이런 라이브러리 도입을 고려해봐. 😊

🎭 에러 핸들링 제대로 하기

에러 처리는 백엔드 개발에서 정말 중요한 부분이야. 에러가 발생했을 때 적절하게 처리하지 않으면 서버가 죽거나, 사용자에게 이상한 메시지가 가거나, 보안 정보가 노출될 수도 있거든! 😰

🚨 커스텀 에러 클래스 만들기

src/utils/errors.ts를 만들어서 커스텀 에러 클래스를 정의해보자:

// 기본 API 에러 클래스
export class ApiError extends Error {
  statusCode: number;
  isOperational: boolean;

  constructor(statusCode: number, message: string, isOperational = true) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = isOperational;

    // 스택 트레이스 유지
    Error.captureStackTrace(this, this.constructor);
  }
}

// 404 Not Found 에러
export class NotFoundError extends ApiError {
  constructor(message = 'Resource not found') {
    super(404, message);
  }
}

// 400 Bad Request 에러
export class BadRequestError extends ApiError {
  constructor(message = 'Bad request') {
    super(400, message);
  }
}

// 401 Unauthorized 에러
export class UnauthorizedError extends ApiError {
  constructor(message = 'Unauthorized') {
    super(401, message);
  }
}

// 403 Forbidden 에러
export class ForbiddenError extends ApiError {
  constructor(message = 'Forbidden') {
    super(403, message);
  }
}

// 409 Conflict 에러
export class ConflictError extends ApiError {
  constructor(message = 'Conflict') {
    super(409, message);
  }
}

// 500 Internal Server Error
export class InternalServerError extends ApiError {
  constructor(message = 'Internal server error') {
    super(500, message, false);
  }
}

🛠️ 에러 핸들링 미들웨어

src/middlewares/error.middleware.ts를 만들어서 에러를 처리하는 미들웨어를 작성해보자:

import { Request, Response, NextFunction } from 'express';
import { ApiError } from '../utils/errors';

export const errorHandler = (
  err: Error | ApiError,
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  // ApiError인 경우
  if (err instanceof ApiError) {
    res.status(err.statusCode).json({
      success: false,
      error: err.message,
      ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
    });
    return;
  }

  // 일반 에러인 경우
  console.error('Unexpected error:', err);
  res.status(500).json({
    success: false,
    error: 'Internal server error',
    ...(process.env.NODE_ENV === 'development' && { 
      message: err.message,
      stack: err.stack 
    })
  });
};

// 404 핸들러
export const notFoundHandler = (
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  res.status(404).json({
    success: false,
    error: 'Not Found',
    message: `Cannot ${req.method} ${req.path}`
  });
};

이제 컨트롤러에서 이 에러 클래스들을 사용할 수 있어:

import { NotFoundError, ConflictError } from '../utils/errors';

// 컨트롤러 내부에서
static async getUserById(
  req: Request<{ id: string }>, 
  res: Response, 
  next: NextFunction
): Promise<void> {
  try {
    const { id } = req.params;
    const user = users.find(u => u.id === id);

    if (!user) {
      throw new NotFoundError('User not found');
    }

    // ... 응답 처리
  } catch (error) {
    next(error);
  }
}

static async createUser(
  req: Request<{}, {}, CreateUserDto>, 
  res: Response, 
  next: NextFunction
): Promise<void> {
  try {
    const { email } = req.body;
    
    const existingUser = users.find(u => u.email === email);
    if (existingUser) {
      throw new ConflictError('Email already exists');
    }

    // ... 사용자 생성 로직
  } catch (error) {
    next(error);
  }
}

그리고 app.ts에 에러 핸들러를 등록해줘:

import { errorHandler, notFoundHandler } from './middlewares/error.middleware';

// ... 라우터 등록 후

// 404 핸들러 (모든 라우트 뒤에 위치)
app.use(notFoundHandler);

// 에러 핸들러 (가장 마지막에 위치)
app.use(errorHandler);

export default app;

🔐 환경 변수와 설정 관리

실제 프로젝트에서는 포트 번호, 데이터베이스 연결 정보, API 키 같은 설정값들을 코드에 직접 넣으면 안 돼. 환경 변수로 관리해야 해! 🔒

📦 dotenv 설정하기

# dotenv 설치
npm install dotenv
npm install -D @types/dotenv

프로젝트 루트에 .env 파일을 만들어:

# 서버 설정
NODE_ENV=development
PORT=3000

# 데이터베이스 (나중에 사용)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=postgres
DB_PASSWORD=secret

# JWT 시크릿 (나중에 사용)
JWT_SECRET=your-super-secret-key-change-this

# API 키 등
API_KEY=your-api-key

⚠️ 중요! .env 파일은 절대로 Git에 커밋하면 안 돼! .gitignore에 추가해줘:

node_modules/
dist/
.env
.env.local

⚙️ 설정 파일 만들기

src/config/index.ts를 만들어서 환경 변수를 타입 안전하게 관리하자:

import dotenv from 'dotenv';

// .env 파일 로드
dotenv.config();

interface Config {
  env: string;
  port: number;
  db: {
    host: string;
    port: number;
    name: string;
    user: string;
    password: string;
  };
  jwt: {
    secret: string;
    expiresIn: string;
  };
}

const config: Config = {
  env: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT || '3000', 10),
  db: {
    host: process.env.DB_HOST || 'localhost',
    port: parseInt(process.env.DB_PORT || '5432', 10),
    name: process.env.DB_NAME || 'myapp',
    user: process.env.DB_USER || 'postgres',
    password: process.env.DB_PASSWORD || ''
  },
  jwt: {
    secret: process.env.JWT_SECRET || 'default-secret-change-this',
    expiresIn: '7d'
  }
};

// 필수 환경 변수 체크
const requiredEnvVars = ['JWT_SECRET'];
const missingEnvVars = requiredEnvVars.filter(
  envVar => !process.env[envVar]
);

if (missingEnvVars.length > 0 && config.env === 'production') {
  throw new Error(
    `Missing required environment variables: ${missingEnvVars.join(', ')}`
  );
}

export default config;

이제 server.ts에서 이렇게 사용할 수 있어:

import app from './app';
import config from './config';

app.listen(config.port, () => {
  console.log(`🚀 서버가 ${config.env} 모드로 포트 ${config.port}에서 실행 중입니다.`);
  console.log(`📍 http://localhost:${config.port}`);
});

📊 로깅 시스템 구축하기

프로덕션 환경에서는 console.log만으로는 부족해. 제대로 된 로깅 시스템이 필요하거든! 😊

📝 Winston 로거 설정

# Winston 설치
npm install winston
npm install -D @types/winston

src/utils/logger.ts를 만들어보자:

import winston from 'winston';
import config from '../config';

const levels = {
  error: 0,
  warn: 1,
  info: 2,
  http: 3,
  debug: 4,
};

const level = () => {
  const env = config.env;
  const isDevelopment = env === 'development';
  return isDevelopment ? 'debug' : 'warn';
};

const colors = {
  error: 'red',
  warn: 'yellow',
  info: 'green',
  http: 'magenta',
  debug: 'white',
};

winston.addColors(colors);

const format = winston.format.combine(
  winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss:ms' }),
  winston.format.colorize({ all: true }),
  winston.format.printf(
    (info) => `${info.timestamp} ${info.level}: ${info.message}`,
  ),
);

const transports = [
  new winston.transports.Console(),
  new winston.transports.File({
    filename: 'logs/error.log',
    level: 'error',
  }),
  new winston.transports.File({ filename: 'logs/all.log' }),
];

const logger = winston.createLogger({
  level: level(),
  levels,
  format,
  transports,
});

export default logger;

이제 코드 전체에서 console.log 대신 logger를 사용할 수 있어:

import logger from './utils/logger';

// 다양한 레벨의 로그
logger.info('서버가 시작되었습니다');
logger.debug('디버그 정보');
logger.warn('경고 메시지');
logger.error('에러 발생!', { error: err });

// 컨트롤러에서
static async createUser(req: Request, res: Response, next: NextFunction) {
  try {
    logger.info(`새 사용자 생성 요청: ${req.body.email}`);
    // ... 로직
    logger.info(`사용자 생성 완료: ${newUser.id}`);
  } catch (error) {
    logger.error('사용자 생성 실패', { error });
    next(error);
  }
}

🧪 테스트 작성하기

테스트는 선택이 아니라 필수야! 특히 TypeScript를 쓰면 타입 체크로 많은 버그를 잡을 수 있지만, 비즈니스 로직은 테스트로 검증해야 해. 🎯

🔧 Jest 설정하기

# Jest 및 관련 패키지 설치
npm install -D jest ts-jest @types/jest supertest @types/supertest

jest.config.js 파일을 만들어:

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
  moduleFileExtensions: ['ts', 'js', 'json'],
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
    '!src/**/*.test.ts',
    '!src/**/*.spec.ts',
  ],
};

✅ API 테스트 작성

src/__tests__/user.test.ts를 만들어보자:

import request from 'supertest';
import app from '../app';

describe('User API', () => {
  describe('POST /api/users', () => {
    it('should create a new user', async () => {
      const userData = {
        email: 'test@example.com',
        username: 'testuser',
        password: 'password123'
      };

      const response = await request(app)
        .post('/api/users')
        .send(userData)
        .expect(201);

      expect(response.body.success).toBe(true);
      expect(response.body.data).toHaveProperty('id');
      expect(response.body.data.email).toBe(userData.email);
      expect(response.body.data.username).toBe(userData.username);
    });

    it('should return 400 for invalid email', async () => {
      const userData = {
        email: 'invalid-email',
        username: 'testuser',
        password: 'password123'
      };

      const response = await request(app)
        .post('/api/users')
        .send(userData)
        .expect(400);

      expect(response.body.success).toBe(false);
      expect(response.body.error).toContain('email');
    });

    it('should return 400 for missing fields', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({ email: 'test@example.com' })
        .expect(400);

      expect(response.body.success).toBe(false);
    });
  });

  describe('GET /api/users', () => {
    it('should return all users', async () => {
      const response = await request(app)
        .get('/api/users')
        .expect(200);

      expect(response.body.success).toBe(true);
      expect(Array.isArray(response.body.data)).toBe(true);
    });
  });

  describe('GET /api/users/:id', () => {
    it('should return 404 for non-existent user', async () => {
      const response = await request(app)
        .get('/api/users/999999')
        .expect(404);

      expect(response.body.success).toBe(false);
    });
  });
});

package.json에 테스트 스크립트를 추가해:

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage"
  }
}

이제 npm test로 테스트를 실행할 수 있어! 🎉

🚀 프로덕션 배포 준비하기

개발은 끝났어. 이제 실제 서버에 배포할 준비를 해보자! 💪

📦 빌드 최적화

package.json에 빌드 관련 스크립트를 추가해:

{
  "scripts": {
    "dev": "nodemon --exec ts-node src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js",
    "clean": "rm -rf dist",
    "prebuild": "npm run clean",
    "postbuild": "echo 'Build completed successfully!'",
    "prod": "npm run build && npm start"
  }
}

🐳 Docker 설정 (선택사항)

Docker를 사용하면 어디서든 동일한 환경에서 실행할 수 있어. Dockerfile을 만들어보자:

# Node.js 이미지 사용
FROM node:18-alpine

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

# package.json과 package-lock.json 복사
COPY package*.json ./

# 의존성 설치
RUN npm ci --only=production

# 소스 코드 복사
COPY . .

# TypeScript 빌드
RUN npm run build

# 포트 노출
EXPOSE 3000

# 환경 변수 설정
ENV NODE_ENV=production

# 앱 실행
CMD ["node", "dist/server.js"]

.dockerignore 파일도 만들어줘:

node_modules
dist
.env
.git
.gitignore
README.md
npm-debug.log

🔒 보안 강화

프로덕션 환경에서는 보안이 정말 중요해. 몇 가지 필수 보안 패키지를 설치하자:

# 보안 관련 패키지 설치
npm install helmet cors express-rate-limit

app.ts에 보안 미들웨어를 추가해:

import express, { Application } from 'express';
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';

const app: Application = express();

// 보안 헤더 설정
app.use(helmet());

// CORS 설정
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  credentials: true
}));

// Rate limiting
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15분
  max: 100, // 최대 100개 요청
  message: 'Too many requests from this IP, please try again later.'
});

app.use('/api/', limiter);

// JSON 파싱 (크기 제한)
app.use(express.json({ limit: '10mb' }));
app.use(express.urlencoded({ extended: true, limit: '10mb' }));

// ... 나머지 코드

export default app;

📈 성능 모니터링과 최적화

서버가 잘 돌아가는지 모니터링하는 것도 중요해. 실시간으로 성능을 체크하고 문제를 빨리 발견할 수 있거든! 📊

⏱️ 요청 시간 로깅

src/middlewares/logger.middleware.ts를 만들어보자:

import { Request, Response, NextFunction } from 'express';
import logger from '../utils/logger';

export const requestLogger = (
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  const start = Date.now();

  // 응답이 완료되면 로그 출력
  res.on('finish', () => {
    const duration = Date.now() - start;
    const message = `${req.method} ${req.path} ${res.statusCode} - ${duration}ms`;

    if (res.statusCode >= 500) {
      logger.error(message);
    } else if (res.statusCode >= 400) {
      logger.warn(message);
    } else {
      logger.http(message);
    }
  });

  next();
};

app.ts에 추가해:

import { requestLogger } from './middlewares/logger.middleware';

app.use(requestLogger);

🎓 실전 팁과 베스트 프랙티스

자, 여기까지 왔으면 기본은 다 배운 거야! 이제 실전에서 유용한 팁들을 알려줄게. 😊

💡 TypeScript 백엔드 개발 베스트 프랙티스

1. 타입을 최대한 구체적으로 정의하기

any 타입은 최대한 피해. TypeScript를 쓰는 이유가 없어지거든! 대신 unknown을 쓰거나 제네릭을 활용해봐.

2. 인터페이스 vs 타입 별칭

객체 구조를 정의할 때는 interface를, 유니온이나 튜플 같은 복잡한 타입은 type을 사용하는 게 일반적이야.

3. 비동기 처리는 async/await 사용

Promise 체이닝보다 async/await가 가독성이 훨씬 좋아. 에러 처리도 try-catch로 깔끔하게 할 수 있고!

4. 환경별 설정 분리

개발, 스테이징, 프로덕션 환경별로 설정을 분리해서 관리해. .env.development, .env.production 이런 식으로!

5. 의존성 주입 패턴 활용

컨트롤러, 서비스, 리포지토리 계층을 분리하고 의존성 주입을 사용하면 테스트하기 훨씬 쉬워져.

🚀 성능 최적화 팁 데이터베이스 쿼리 최적화: N+1 문제를 조심하고, 인덱스를 적절히 활용해
캐싱 활용: Redis 같은 인메모리 캐시를 사용하면 응답 속도가 엄청 빨라져
압축 사용: compression 미들웨어로 응답 데이터를 압축해
비동기 처리: 무거운 작업은 큐(Bull, BullMQ)를 사용해서 백그라운드에서 처리해
클러스터링: PM2로 멀티 프로세스를 활용하면 CPU를 효율적으로 사용할 수 있어

🔮 다음 단계로 나아가기

기본적인 TypeScript Express API 서버를 만들 수 있게 됐어! 🎉 하지만 여기서 끝이 아니야. 더 발전하고 싶다면 이런 것들을 공부해봐:

📚 추가로 공부하면 좋은 것들

🗄️ 데이터베이스 연동

PostgreSQL, MongoDB 같은 데이터베이스와 연동하고, TypeORM, Prisma, Mongoose 같은 ORM을 사용해봐. 타입 안정성을 유지하면서 데이터베이스를 다룰 수 있어!

🔐 인증/인가 시스템

JWT, OAuth2.0, Passport.js를 활용한 인증 시스템을 구축해봐. 보안은 정말 중요하거든!

📡 WebSocket 실시간 통신

Socket.io를 사용해서 실시간 채팅이나 알림 기능을 만들어봐. TypeScript와 함께 쓰면 이벤트 타입도 정의할 수 있어!

🧪 고급 테스팅

통합 테스트, E2E 테스트, 테스트 커버리지 향상 등 더 깊이 있는 테스팅 전략을 공부해봐.

🐳 컨테이너화와 CI/CD

Docker, Kubernetes, GitHub Actions, Jenkins 같은 도구들로 자동화된 배포 파이프라인을 구축해봐.

📊 마이크로서비스 아키텍처

서비스를 작은 단위로 나누고, gRPC나 메시지 큐로 통신하는 마이크로서비스 패턴을 공부해봐.

🎯 마무리하며

와, 여기까지 정말 긴 여정이었어! 😅 Node.js와 TypeScript로 Express 백엔드 API를 개발하는 방법을 처음부터 끝까지 다뤄봤어. 타입 정의부터 시작해서 라우팅, 미들웨어, 에러 핸들링, 테스팅, 배포까지 정말 많은 내용을 배웠지?

TypeScript를 사용하면 처음에는 타입 정의하느라 시간이 좀 걸릴 수 있어. 하지만 프로젝트가 커질수록 그 진가를 발휘해. 버그가 줄어들고, 리팩토링이 쉬워지고, 협업이 편해지거든! 💪

재능넷 같은 플랫폼에서도 TypeScript 백엔드 개발자에 대한 수요가 계속 늘어나고 있어. 이 기술을 잘 익혀두면 정말 많은 기회가 있을 거야! 🚀

🌟 실전 프로젝트 아이디어 배운 내용을 바탕으로 실제 프로젝트를 만들어봐:
• 블로그 API 서버
• 할 일 관리 앱 백엔드
• 간단한 전자상거래 API
• 소셜 미디어 백엔드
• 파일 업로드 서비스

직접 만들어보면서 부딪히는 문제들을 해결하다 보면 실력이 쑥쑥 늘어날 거야! 💯

기억해, 완벽한 코드는 없어. 처음부터 모든 걸 완벽하게 하려고 하지 말고, 일단 만들어보고 점진적으로 개선해나가는 게 중요해. 에러가 나면? 그게 바로 배우는 기회야! 😊

TypeScript와 Express로 멋진 백엔드 API를 만들어봐. 너의 아이디어를 현실로 만들 수 있는 강력한 도구를 손에 넣은 거야. 화이팅! 🎉

지식인의 숲 - 지적 재산권 보호 고지

지적 재산권 보호 고지

사용 제한: 재능넷의 명시적 서면 동의 없이 본 컨텐츠를 복제, 수정, 배포, 또는 상업적으로 활용하는 행위는 엄격히 금지됩니다.
데이터 수집 금지: 본 컨텐츠에 대한 무단 스크래핑, 크롤링, 및 자동화된 데이터 수집은 법적 제재의 대상이 됩니다.
AI 학습 제한: 재능넷의 AI 생성 컨텐츠를 타 AI 모델 학습에 무단 사용하는 행위는 금지되며, 이는 지적 재산권 침해로 간주됩니다.

9.7K

사이트를 모바일앱으로 제작해 드립니다. 안드로이드 아이폰 앱제작 어플제작 전문

운영하는 사이트 주소가 있다면 사이트를 안드로이드 앱으로 만들어 드립니다. 기본 5000원은 아무런 기능이 없고 단순히 html 페이지를 로딩하는 앱을 제작하는 경우입니다. 구매할때 쇼핑몰 및 커뮤니티 사이트 등 일반사이트들은 구매옵션의 자바스크립트 지원을 필수 선택해야 제작해드립니다. 아이폰 ios 용 앱제작 의뢰의 경우 협의 가격으로 진행됩니다.먼저 문

5,000원~

4.3K

홈페이지 연동 모바일 앱, 유튜브 연동 앱, 퀴즈 앱 등 앱개발을 도와 드려요.

안녕하세요. 안드로이드 기반 개인 앱, 프로젝트용 앱부터 그 이상 기능이 추가된 앱까지 제작해 드립니다. - 앱 개발 툴: 안드로이드 스튜디오 - 안드로이드 언어: JAVA, XML - 데이터베이스 언어: 로컬DB-SQLite, 웹DB-MYSQL - 안드로이드 와 서버 통신 언어 - PHP 기능 추가 시 구현정도에 따라 협의가 필요하며 밑에 사항과 같이 연

30,000원~

8.3K

신뢰있는 앱 개발, 아무에게나 맡기지 마세요!

본 페이지는 실제 서비스와 시스템을 개발·운영하며 축적한 개발 경험과 프로젝트 사례를 소개합니다.사용자 화면, 관리 기능, 내부 처리 구조 등 서비스 전반을 고려한 개발 경험을 바탕으로 구성되어 있습니다. 150만명 회원 규모의 서비스를 직접 개발·운영해 온 경험을 바탕으로, 현실적인 운영 환경에 적합한 실효성 있는 솔루션을 제안합니다. 각 프로젝트는 단순

10,000원~

1.5K

[Android / JAVA/ C] 신호처리 알고리즘/ 안드로이드 앱 개발

안녕하세요. 신호처리를 전공한 개발자 입니다. 1. 영상신호처리, 생체신호처리 알고리즘 개발 2. 안드로이드 앱 개발 3. 윈도우 프로그램 개발 위와 같은 개발에 도움을 드릴 수 있습니다.

1,000,000원~

1.8K

안드로이드, 메트렙, 자료구조, 신호처리, 통신이론 요청 받습니다.

------------------------------------ 만들고 싶어하는 앱을 제작해드립니다. ------------------------------------ 1. 안드로이드 ( 자바 ) * 블루투스, 카메라, 미디어 플레이어, 음성인식, 가계부, 소개팅 앱, 알람 앱, 사진 앱 등등 원하시는 어플리케이션을 만들어 드립니다. 2. 자료구조 ( C