백엔드 개발 환경

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'

프로파일

local/test/prod/docker 네 프로파일이 있다. 프로파일별 DB 구성은 데이터베이스 문서를 참고한다.

자주 쓰는 명령

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

패키지 구조

Directorybiz.mintchoco.dictionary/
- Directoryconfig/ SecurityConfig, WebConfig, OpenApiConfig 등
  - …
- Directoryentity/ JPA 엔티티 (AbstractEntity가 감사 컬럼 자동 세팅)
  - …
- Directoryinterfaces/ 외부 사전 API 연동 (StdictClient, KrdictClient)
  - …
- Directoryapi/
  - Directory<feature>/ auth / board / code / column / config / dictionary / domain / file / menu / search / tools
    Directorycontroller/
    …
    Directorydto/
    …
    Directoryrepository/
    …
    Directoryservice/
    …
- Directorycommon/ AbstractController, 예외 처리, 인가(AuthorizationInterceptor), 유틸
  - …

레이어별 세부 규칙과 DTO 네이밍은 패키지 가이드 참고.

인가 정책

기본은 화이트리스트(fail-closed) 방식이라, @PublicApi가 없는 API는 모두 로그인이 필요하다.

게스트 계정(guest_yn = 'Y')은 @GuestForbidden이 붙은 API를 호출하면 403으로 거부된다. 주로 생성/수정/삭제 API에 붙지만, 파일 다운로드와 tools 기능처럼 게스트에게 노출하기 민감한 조회 API에도 붙어 있다. 세션을 만들고 검사하는 코드는 세션 정보 참조 가이드 참고.

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를 쓴다.

전체 규칙과 표준 동사에 없는 액션 메소드 처리 방법은 REST API 개발 가이드 참고.