백엔드 개발 환경

dictionary-api 저장소 기준입니다. 이 저장소는 참조용으로만 클론하고, 실제 작업은 dictionary-api 저장소 자체에서 진행합니다.

기술 스택

런타임/빌드

Java 26 (toolchain) · Spring Boot 4.1.0 · Gradle

데이터

Spring Data JPA · QueryDsl(Jakarta) · Flyway

인증

spring-session-jdbc 기반 DB 세션(JWT 아님)

문서화

springdoc-openapi (Swagger UI)

환경 설정

로컬 개발에는 MySQL을 사용한다. src/main/resources/config/local/application-local.yaml에서 접속 정보를 확인한다.

데이터베이스와 계정을 생성한다.

create database dictionary;
create user 'user'@'%' identified by 'password';
grant all privileges on dictionary.* to 'user'@'%' with grant option;
flush privileges;

Flyway가 resources/db/migration/mysql/{ddl,data}의 마이그레이션을 적용해 테이블/데이터를 만든다 — 별도 DDL 실행 불필요, 애플리케이션 기동 시 자동 적용.

local 프로파일로 기동한다.

./gradlew bootRun --args='--spring.profiles.active=local'

프로파일

프로파일	DB	용도
`local`	MySQL	개발자 로컬 개발
`test`	H2(in-memory)	테스트 실행
`prod`	H2(in-memory)	무료 호스팅 데모 배포
`docker`	MySQL(컨테이너)	`docker-compose` 전체 스택 실행

자주 쓰는 명령

명령	설명
`./gradlew build`	빌드 (compileJava가 자동으로 `spotlessApply` 실행)
`./gradlew test`	단위/통합 테스트 (mock 기반, 실제 네트워크 호출 없음)
`./gradlew integrationTest`	실제 외부 사전 API를 호출하는 `@Tag("integration")` 테스트만 실행
`./gradlew spotlessApply`	Google Java Format(AOSP)으로 포맷팅

패키지 구조

biz.mintchoco.dictionary
├── config          # SecurityConfig, WebConfig, OpenApiConfig 등
├── entity           # JPA 엔티티 (AbstractEntity가 감사 컬럼 자동 세팅)
├── interfaces        # 외부 사전 API 연동 (StdictClient, KrdictClient)
├── api/<feature>      # auth / board / dictionary / domain / menu / search / tools
│   └── {controller,dto,repository,service}
└── common            # AbstractController, 예외 처리, 인가(AuthorizationInterceptor), 유틸

인가 정책

기본은 화이트리스트(fail-closed) — @PublicApi가 없는 모든 API는 로그인이 필요하다. 게스트 계정(guest_yn = 'Y')은 @WriteApi가 붙은 생성/수정/삭제 요청만 403으로 추가 거부된다.

API 경로 규칙

모든 경로는 /v1/<feature> 기준, kebab-case만 사용(camelCase/snake_case/대문자 금지).
경로 세그먼트는 컨트롤러 메소드명과 1:1 대응(find-by-page → findByPage).
조회는 find로 시작, 쓰기는 create/update/delete로 고정.
필터·페이지 조건을 JSON 바디로 받는 조회(find-all, find-by-page)는 GET이 아니라 POST를 쓴다.

자세한 내용은 dictionary-api 저장소의 .claude/CLAUDE.md/README.md를 참고한다.