웹 서비스 개발을 위한 프로젝트 초기 세팅 가이드

안녕하세요! 오늘은 어떤 언어를 사용하든 웹 서비스 개발을 시작할 때 필요한 기본적인 세팅과 준비사항에 대해 정리해보려고 합니다. 프로젝트를 시작할 때마다 같은 과정을 반복하기보다는, 체크리스트처럼 활용할 수 있는 가이드를 만들어 봤습니다. 이 글을 따라가다 보면 프로젝트 초기 세팅을 뚝딱 마칠 수 있을 거예요!

시스템 구상도 작성

1. 시스템 아키텍처 설계

프로젝트의 기술적 구조를 시각화하는 것부터 시작하세요.

꿀팁:

• Draw.io, Lucidchart, Miro 등의 도구 활용
• 아키텍처는 너무 복잡하지 않게, 팀원 모두가 이해할 수 있는 수준으로 작성
• 백엔드, 프론트엔드, 데이터베이스, 외부 API 연동 등을 명확히 구분

2. 데이터 모델링

서비스에 필요한 데이터 구조를 설계합니다.

꿀팁:

• ERD(Entity-Relationship Diagram)를 작성하여 데이터 간의 관계를 시각화
• 확장성을 고려한 설계 할 것

3. API 설계

백엔드와 프론트엔드 간의, 또는 외부 서비스와의 통신 방식을 정의합니다.

꿀팁:

• RESTful API 설계 원칙을 따르고, Swagger 같은 도구로 문서화
• 테스트 코드 작성은 첫삽부터!

개발 환경 구축

1. 코드 에디터/IDE 세팅

• VS Code, IntelliJ, WebStorm 등 선호하는 에디터 설치
• 필수 확장 프로그램/플러그인:
  • 코드 포맷터 (Prettier, ESLint 등)
  • 테마 및 아이콘
  • 언어별 확장 프로그램
  • Git 관련 확장 프로그램

2. 버전 관리 시스템 세팅

• Git 설치 및 설정
• GitHub/GitLab/Bitbucket 계정 연결
• .gitignore 파일 설정 (node_modules, build 폴더, 환경변수 파일 등)
• 커밋 메시지 컨벤션 설정 (예: Conventional Commits)

3. 패키지 매니저

• npm/yarn/pnpm 설치 (Node.js 기반)
• pip (Python 기반)
• Composer (PHP 기반)
• 등등 필요한 패키지 매니저 설치

GitHub 세팅 가이드

1. 저장소(Repository) 구조 설정

꿀팁:

• 모노레포(Monorepo) vs 멀티레포(Multi-repo) 고민
• README.md 이쁘게 꾸미기
• .gitignore 세팅 (인텔리제이와 이클립스의 혼용하고 있는지?)

2. 브랜치 전략 수립

꿀팁:

• Git-flow(master, develop, feature, release, hotfix) or GitHub-flow(main, feature)
• 브랜치 네이밍 컨벤션 (예: feature/login, bugfix/user-profile)
• 브랜치 보호 규칙을 설정하여 실수로 인한 코드 손상 방지
• master 권한은 한명에게!

3. PR(Pull Request) 및 코드 리뷰 프로세스 설정

꿀팁:

• PR 템플릿을 만들어 변경 내용, 관련 이슈, 테스트 방법 등을 명시
• GitHub Actions → PR→ 린트 검사 도입

4. 이슈(Issue) 및 프로젝트 관리

꿀팁:

• 이슈 템플릿을 만들어 버그 리포트, 기능 요청 등의 형식을 표준화
• GitHub Projects 칸반 보드를 구성
• 이슈에는 항상 담당자(Assignee), 라벨(Label), 마일스톤(Milestone)을 지정
• 짧은 목표는 마일스톤, 긴 목표는 프로젝트단위
• 버그 리포트에 적절한 라벨 추가

5. GitHub Actions 활용

꿀팁:

• CI/CD 파이프라인을 구축하여 빌드, 테스트, 배포 자동화
• 오버스펙을 항상 경계
• SonarQube 활용
• Dependabot 활용

프로젝트 구조 설계

1. 폴더 구조 설계

project/
├── src/              # 소스 코드
├── public/           # 정적 파일
├── tests/            # 테스트 코드
├── docs/             # 문서
├── config/           # 설정 파일
└── scripts/          # 유틸리티 스크립트

2. 명명 규칙 정하기

• 파일명: camelCase vs kebab-case vs snake_case
• 컴포넌트/클래스: PascalCase
• 함수/변수: camelCase
• 상수: UPPER_SNAKE_CASE

개발 환경 설정 파일

1. 환경 변수 설정

• .env, .env.development, .env.production 파일 설정
• 환경별 변수 관리 방법 결정
• 민감 정보 관리 방법 결정 (API 키, 비밀번호 등)

2. 코드 품질 관리 도구

• ESLint 설정 (JavaScript/TypeScript)
• Prettier 설정
• StyleLint (CSS)
• 해당 언어에 맞는 정적 분석 도구

예시 .eslintrc.json 파일:

{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaFeatures": {
      "jsx": true
    },
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "plugins": [
    "react",
    "@typescript-eslint",
    "prettier"
  ],
  "rules": {
    "prettier/prettier": "error",
    "react/react-in-jsx-scope": "off",
    "no-console": "warn",
    "no-unused-vars": "warn"
  }
}

백엔드 기본 세팅

1. 서버 환경 구성

• 웹 서버 선택 (Nginx, Apache 등)
• 애플리케이션 서버 선택 (Express, Django, Spring Boot, Laravel 등)
• 데이터베이스 선택 (MySQL, PostgreSQL, MongoDB 등)
• 캐싱 시스템 선택 (Redis, Memcached 등)

주요 기술 선택 예시와 근거:

Spring Boot, Spring Data JPA

• 스프링 부트는 많은 설정을 기본적으로 갖추고 있고 Apache Tomcat이 내장되어 있습니다.
• 스프링 Data JPA는 JPA를 더 쉽고 편하게 사용할 수 있게 해줍니다.

Spring Security + JWT

• 스프링 시큐리티는 보안과 관련된 많은 옵션을 제공하므로 일일이 보안 관련 로직을 작성하지 않아도 됩니다.
• JWT는 서버가 토큰을 발급하고 보내주면, 토큰이 클라이언트에 저장되기 때문에, 확장성이 좋습니다. 또한, 토큰 기반 인증 방식은 다양한 도메인에 관리하기가 쉽습니다.

MySQL

• 오픈 소스 라이센스를 따르기 때문에 무료로 사용할 수 있어서 사용했습니다.
• 정형화된 데이터 구조를 사용하기 위해 선택했습니다.

Docker

• 빠르고 가볍게 동일한 개발환경을 구축하기 위해 사용했습니다.

2. API 설계

• REST API vs GraphQL 선택
• API 엔드포인트 명명 규칙 정하기
• API 문서화 도구 선택 (Swagger, Postman 등)
• 에러 핸들링 전략 결정

3. 인증/인가 시스템

• 인증 방식 선택 (JWT, OAuth, Session 등)
• 사용자 역할 및 권한 설계
• 보안 설정 (CORS, XSS 방지, CSRF 방지 등)

프론트엔드 기본 세팅

1. UI 프레임워크/라이브러리 선택

• React, Vue, Angular, Svelte 등
• CSS 프레임워크 (Tailwind CSS, Bootstrap, MUI 등)
• 상태 관리 라이브러리 (Redux, MobX, Zustand, Recoil 등)

2. 라우팅 설정

• 클라이언트 라우팅 설계
• 페이지 구조 설계
• 레이아웃 컴포넌트 설계

3. 에셋 관리

• 이미지, 폰트, 아이콘 등 에셋 관리 방법
• CDN 활용 방안

프론트엔드 서버 인프라 예시:

• S3와 CloudFront로 구성
  • S3의 정적인 웹호스팅 기능을 사용하여, 정적인 컨텐츠에 간단하고 유연하게 접근
  • Cloud Front를 통해, 웹 컨텐츠를 사용자와 가까운 곳에 전송함으로써 전송속도를 높임

테스트 환경 구성

1. 테스트 도구 선택

• 단위 테스트 (Jest, Mocha, Pytest 등)
• 통합 테스트 (Supertest, pytest-django 등)
• E2E 테스트 (Cypress, Playwright, Selenium 등)

2. 테스트 전략 수립

• TDD vs BDD
• 테스트 커버리지 목표 설정
• 모킹 전략 결정

CI/CD 파이프라인 구성

1. CI 도구 선택

• GitHub Actions, GitLab CI, Jenkins, CircleCI 등

2. 배포 전략 수립

• 배포 환경 구성 (개발, 스테이징, 프로덕션)
• 배포 자동화 스크립트 작성
• 블루/그린 배포, 카나리 배포 등 전략 결정

예시 GitHub Actions 워크플로우:

name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Lint
      run: npm run lint
    
    - name: Run tests
      run: npm test
    
    - name: Build
      run: npm run build
    
    - name: Deploy to staging
      if: github.ref == 'refs/heads/develop'
      run: |
        echo "Deploying to staging..."
        # 스테이징 배포 스크립트
    
    - name: Deploy to production
      if: github.ref == 'refs/heads/main'
      run: |
        echo "Deploying to production..."
        # 프로덕션 배포 스크립트

모니터링 및 로깅 시스템 구성

1. 로깅 시스템

• 로깅 라이브러리 선택 (Winston, Logback 등)
• 로그 수집 도구 선택 (ELK Stack, Papertrail 등)
• 로그 레벨 및 포맷 결정

2. 모니터링 도구

• 성능 모니터링 (New Relic, Datadog 등)
• 에러 트래킹 (Sentry, Rollbar 등)
• 서버 모니터링 (Prometheus, Grafana 등)

문서화

1. 코드 문서화

• JSDoc, PyDoc 등 코드 주석 규칙
• README.md 파일 작성
• API 문서 자동화

2. 프로젝트 관리 문서

• 기능 명세서
• 아키텍처 다이어그램
• 컴포넌트 구조도

협업 도구 설정

1. Notion 워크스페이스 구조 설계

꿀팁:

• 최상위 페이지는 ‘프로젝트 개요’, ‘개발 문서’, ‘디자인’, ‘회의록’, ‘리소스’ 등으로 카테고리화
• 템플릿을 활용하여 일관된 문서 형식을 유지
• API 문서, 기술 스택, 트러블슈팅 가이드 등 개발 관련 정보를 체계적으로 정리

2. Slack 채널 구조 설정

꿀팁:

• 채널은 목적을 알 수 있도록!(예: #general, #dev, #design, #marketing)
• 프로젝트 단위 또는 기능 단위로 채널을 생성 (예: #project-login, #feature-payment)
• @channel, @here의 사용 기준을 명확히 하여 불필요한 알림 방지

3. 이슈 트래킹

• GitHub Issues, Jira, Trello 등 설정
• 이슈 템플릿 작성

4. 코드 리뷰 프로세스

• PR 템플릿 작성
• 코드 리뷰 규칙 정하기
• 병합 전략 결정 (Squash, Rebase, Merge 등)

5. 커뮤니케이션 채널

• Slack, Discord, Microsoft Teams 등 설정
• 알림 설정 (CI/CD, 배포, 이슈 등)

협업 규칙 및 컨벤션 설정

1. 코드 컨벤션

꿀팁:

• 언어/프레임워크별 코딩 스타일 가이드를 문서화
• ESLint, Prettier 등의 도구를 활용하여 코드 스타일을 자동으로 통일
• 변수명, 함수명, 클래스명 등의 네이밍 컨벤션을 명확히 정의

참고: 네이버 핵데이 Java 코딩 컨벤션 https://naver.github.io/hackday-conventions-java/

2. 커밋 메시지 컨벤션

꿀팁:

• 일관된 커밋 메시지 형식을 사용 (예: “[feat] 로그인 기능 구현”)
• 히스토리 관리가 편함
• Conventional Commits(feat, fix, docs, style, refactor, test, chore 등)을 활용
• 커밋 메시지에 관련 이슈 번호 포함

3. 문서화 컨벤션

꿀팁:

• 버전 관리 규칙(Semantic Versioning)을 정하고 CHANGELOG.md를 업데이트

프로젝트 킥오프 체크리스트

마지막으로, 프로젝트를 공식적으로 시작하기 전에 확인해야 할 체크리스트입니다:

• 시스템 아키텍처 다이어그램 작성
• 데이터 모델 설계 완료
• GitHub 저장소 생성 및 기본 설정 완료
• 브랜치 전략 및 PR 프로세스 문서화
• Notion 워크스페이스 구조 설정
• 프로젝트 로드맵 및 마일스톤 설정
• Slack 채널 구조 및 통합 설정
• 코드 컨벤션 및 협업 규칙 문서화
• 팀 멤버 권한 및 역할 정의
• 개발 환경 설정 가이드 작성
• 첫 스프린트 계획 수립

마치며

이렇게 웹 서비스 개발을 위한 기본적인 세팅 사항들을 정리해봤습니다. 물론 모든 프로젝트에 이 모든 것을 적용할 필요는 없어요. 프로젝트의 규모나 성격에 맞게 필요한 부분만 골라서 적용하면 됩니다.

프로젝트 초기에 이런 기본 세팅을 제대로 해두면 나중에 많은 시간과 노력을 절약할 수 있어요. 특히 팀 프로젝트라면 모두가 같은 규칙과 환경에서 개발할 수 있게 도와주죠.

다음 프로젝트를 시작할 때 이 글을 참고해서 체크리스트처럼 활용해보세요. 뚝딱 세팅 완료하고 본격적인 개발에 집중할 수 있을 거예요! 😊

혹시 특정 부분에 대해 더 자세한 설명이 필요하거나, 특정 언어나 프레임워크에 맞는 세팅 방법을 알고 싶으시다면 언제든 메일일로 알려주세요!