시흥 커뮤니케이션 플랫폼의 백엔드 REST API 서버입니다. Spring Boot 기반으로 구축되었으며, 인증, 커뮤니티, 실시간 채팅, 분실물 관리 등 다양한 기능을 제공합니다.
- Java 17 - 프로그래밍 언어
- Spring Boot 3.3.0 - 애플리케이션 프레임워크
- Spring Security - 보안 및 인증
- Spring Data JPA - 데이터베이스 접근
- Spring WebSocket - 실시간 통신
- MySQL - 관계형 데이터베이스
- Hibernate - ORM 프레임워크
- JWT (JSON Web Token) - 토큰 기반 인증
- Spring Security - 보안 프레임워크
- Gradle - 빌드 및 의존성 관리
- Lombok - 보일러플레이트 코드 감소
- Jackson - JSON 직렬화/역직렬화
- Validation - 입력 데이터 검증
- 회원가입 / 로그인
- JWT 토큰 기반 인증
- 프로필 관리 (이미지 업로드 포함)
- 아이디/비밀번호 찾기
- 사용자 통계 조회
- 게시글 CRUD 작업
- 카테고리별 게시글 분류
- 검색 기능
- 좋아요 기능
- 이미지 업로드 지원
- 인기 게시글 조회
- 댓글 작성/삭제
- 게시글별 댓글 조회
- 1:1 개인 채팅
- 그룹 채팅
- WebSocket 기반 실시간 메시징
- 이미지 전송 지원
- 읽음 확인 기능
- 채팅방 관리
- 경기도 문화행사 API 연동
- 행사 목록 조회 (페이지네이션)
- 행사 상세 정보
- 외부 API 동기화 (관리자)
- 분실물/습득물 등록
- 카테고리별 분류
- 상태 관리 (검색중/발견됨/반환됨)
- 이미지 업로드
- 분실물 수정/삭제
- 이미지 업로드
- 파일 다운로드
- 파일 삭제
- 총 게시글 수
- 진행중인 축제 수
backend/
├── src/
│ ├── main/
│ │ ├── java/com/example/shiheunglink/
│ │ │ ├── config/ # 설정 클래스
│ │ │ │ ├── security/ # Security 설정
│ │ │ │ ├── JpaAuditingConfig.java
│ │ │ │ ├── RestTemplateConfig.java
│ │ │ │ └── WebSocketConfig.java
│ │ │ ├── controller/ # REST API 컨트롤러
│ │ │ │ ├── AdminController.java
│ │ │ │ ├── AuthController.java
│ │ │ │ ├── ChatController.java
│ │ │ │ ├── ChatWebSocketController.java
│ │ │ │ ├── CommentController.java
│ │ │ │ ├── EventController.java
│ │ │ │ ├── FileController.java
│ │ │ │ ├── GlobalExceptionHandler.java
│ │ │ │ ├── LostAndFoundController.java
│ │ │ │ ├── PostController.java
│ │ │ │ └── PublicController.java
│ │ │ ├── domain/ # Entity 클래스
│ │ │ │ ├── User.java
│ │ │ │ ├── Post.java
│ │ │ │ ├── Comment.java
│ │ │ │ ├── ChatRoom.java
│ │ │ │ ├── Message.java
│ │ │ │ ├── LostAndFound.java
│ │ │ │ ├── Event.java
│ │ │ │ └── ...
│ │ │ ├── dto/ # DTO 클래스
│ │ │ │ ├── request/ # 요청 DTO
│ │ │ │ └── response/ # 응답 DTO
│ │ │ ├── repository/ # JPA Repository
│ │ │ ├── service/ # 비즈니스 로직
│ │ │ ├── util/ # 유틸리티 클래스
│ │ │ │ ├── FileUtil.java
│ │ │ │ └── JwtUtil.java
│ │ │ └── ShiheunglinkApplication.java
│ │ └── resources/
│ │ ├── application.yml # 설정 파일
│ │ └── data.sql # 초기 데이터
│ └── test/ # 테스트 코드
├── build.gradle # Gradle 빌드 설정
├── settings.gradle # Gradle 프로젝트 설정
├── gradlew # Gradle Wrapper (Unix)
├── gradlew.bat # Gradle Wrapper (Windows)
├── create_database.sql # 데이터베이스 생성 스크립트
├── README.md # 프로젝트 문서
├── API_SPECIFICATION.md # API 명세서
├── QUICK_START.md # 빠른 시작 가이드
└── uploads/ # 업로드된 파일 저장 디렉토리
- Java 17 이상
- MySQL 8.0 이상
- Gradle (또는 Gradle Wrapper 사용)
CREATE DATABASE shiheunglink CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;src/main/resources/application.yml 파일을 열어서 데이터베이스 연결 정보를 수정하세요:
spring:
datasource:
url: jdbc:mysql://localhost:3306/shiheunglink?useSSL=false&serverTimezone=Asia/Seoul&characterEncoding=UTF-8&allowPublicKeyRetrieval=true&useUnicode=true
username: root # 본인의 MySQL 사용자명으로 변경
password: root # 본인의 MySQL 비밀번호로 변경Windows:
cd backend
.\gradlew.bat bootRunLinux/Mac:
cd backend
./gradlew bootRun- IntelliJ IDEA나 Eclipse에서 프로젝트 열기
src/main/java/com/example/shiheunglink/ShiheunglinkApplication.java파일 열기main메서드에서 우클릭 → "Run 'ShiheunglinkApplication'"
# 빌드
.\gradlew.bat build
# 실행
java -jar build/libs/shiheunglink-0.0.1-SNAPSHOT.jar서버가 정상적으로 실행되면 다음과 같은 메시지가 표시됩니다:
Started ShiheunglinkApplication in X.XXX seconds
서버는 다음 주소에서 실행됩니다:
- Base URL:
http://localhost:3001/api - WebSocket:
ws://localhost:3001/api/ws
자세한 API 명세는 API_SPECIFICATION.md를 참고하세요.
POST /api/auth/login- 로그인POST /api/auth/register- 회원가입GET /api/auth/profile- 프로필 조회PUT /api/auth/profile- 프로필 수정GET /api/auth/stats- 사용자 통계
GET /api/posts- 게시글 목록 조회GET /api/posts/{id}- 게시글 상세 조회POST /api/posts- 게시글 작성PUT /api/posts/{id}- 게시글 수정DELETE /api/posts/{id}- 게시글 삭제POST /api/posts/{id}/like- 게시글 좋아요GET /api/posts/hot- 인기 게시글 조회
GET /api/posts/{postId}/comments- 댓글 목록 조회POST /api/posts/{postId}/comments- 댓글 작성DELETE /api/posts/{postId}/comments/{commentId}- 댓글 삭제
GET /api/chats- 채팅방 목록 조회POST /api/chats- 채팅방 생성GET /api/chats/{roomId}- 채팅방 상세 조회GET /api/chats/{roomId}/messages- 메시지 목록 조회POST /api/chats/{roomId}/messages- 메시지 전송POST /api/chats/{roomId}/read- 읽음 처리GET /api/chats/unread- 읽지 않은 메시지 수
GET /api/events- 행사 목록 조회 (외부 API)GET /api/events/db- DB에 저장된 행사 목록GET /api/events/{id}- 행사 상세 조회POST /api/events/sync- 외부 API 동기화 (관리자)
GET /api/lostfound- 분실물 목록 조회GET /api/lostfound/{id}- 분실물 상세 조회POST /api/lostfound- 분실물 등록PUT /api/lostfound/{id}- 분실물 수정PUT /api/lostfound/{id}/status- 상태 업데이트DELETE /api/lostfound/{id}- 분실물 삭제
GET /api/files/{filename}- 파일 다운로드DELETE /api/files/{filename}- 파일 삭제
GET /api/public/stats- 공개 통계 조회 (인증 불필요)
- 로그인 시 JWT 토큰이 발급됩니다
- API 요청 시
Authorization: Bearer {token}헤더를 포함해야 합니다 - 토큰 만료 시간: 24시간 (설정 가능)
- 토큰은
application.yml의jwt.secret으로 서명됩니다
- 최대 파일 크기: 10MB
- 업로드된 파일은
./uploads디렉토리에 저장됩니다 - 파일 접근:
http://localhost:3001/api/files/{filename}
- JPA는
ddl-auto: update모드로 실행됩니다 (자동 스키마 업데이트) - 초기 데이터는
data.sql에서 로드됩니다 - 프로덕션 환경에서는
ddl-auto: validate또는none을 사용하세요
- 경기도 문화행사 정보 API 연동
- API 키는
application.yml의external.culture-event.key에 설정됩니다 - 관리자 권한으로
/api/events/sync를 호출하여 데이터를 동기화할 수 있습니다
- WebSocket 엔드포인트:
/api/ws - STOMP 프로토콜 사용
- 실시간 채팅 기능 지원
프로덕션 환경에서는 환경 변수를 사용하는 것을 권장합니다:
application.yml에서 환경 변수 참조:
spring:
datasource:
url: ${DB_URL:jdbc:mysql://localhost:3306/shiheunglink}
username: ${DB_USERNAME:root}
password: ${DB_PASSWORD:1234}
jwt:
secret: ${JWT_SECRET:your-secret-key}- 실행 시 환경 변수 설정:
$env:DB_PASSWORD="your-password"
.\gradlew.bat bootRunapplication.yml에 로깅 레벨을 설정할 수 있습니다:
logging:
level:
com.example.shiheunglink: DEBUG
org.springframework.web: INFO
``'