7.7 KiB
7.7 KiB
title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, status, confidence, created, last_reviewed
| title | source_type | url | archive_url | vendor | related_branches | related_projects | tags | status | confidence | created | last_reviewed | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| official-doc / Spring Boot — Structuring Your Code (패키지 구조 공식 권고) | official-doc | https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html | Spring / VMware Broadcom |
|
|
|
raw | high | 2026-05-28 | 2026-05-28 |
Spring Boot — Structuring Your Code (패키지 구조 공식 권고)
Layer:
raw/official-docs/— Spring Boot 공식 레퍼런스 문서의 verbatim 발췌. 검증된 요약은/ingest후wiki/concepts/에 별도 작성.
Parent / 활용 branch
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-skeleton-package-blueprint-contract | @SpringBootApplication 을 dev.caskeleton.bootstrap (root package) 하위에 배치하고 다른 module은 sibling package로 두는 결정의 공식 근거 — component scan default base package 정책 |
출처 / Source
- 원본 URL: https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
- 아카이브 URL: (미등록)
- 저자 / 조직: Spring Team / VMware Broadcom
- Spring Boot 버전: 4.0.6 (meta name="version" content="4.0.6" — 2026-05-28 기준 latest)
- 마지막 확인일: 2026-05-28
왜 저장했는지 / Why archived
ca-tmpl skeleton 의 @SpringBootApplication 위치 결정(dev.caskeleton.bootstrap) 과 module 내부 package scan 범위 제한 정책의 공식 근거로 필요. Spring Boot 공식 문서가 root package 배치를 명시적으로 권고하고 default package 사용을 금지함으로써, 이 결정이 프로젝트 취향이 아닌 공식 권고임을 증명한다.
핵심 인용 / Key quotes (verbatim, 5개)
[§ Locating the Main Application Class] "We generally recommend that you locate your main application class in a root package above other classes." — line 1350
[§ Locating the Main Application Class] "The
@SpringBootApplicationannotation is often placed on your main class, and it implicitly defines a base "search package" for certain items." — line 1351
[§ Locating the Main Application Class] "Using a root package also allows component scan to apply only on your project." — line 1353
[§ Using the "default" Package] "The use of the "default package" is generally discouraged and should be avoided." — line 1329
[§ Structuring Your Code — preamble Tip] "If you wish to enforce a structure based on domains, take a look at Spring Modulith." — line 1317
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SB-STRUCT-C1 | Spring Boot 공식 문서는 main 애플리케이션 클래스를 다른 클래스보다 상위의 root package에 위치시키도록 권고한다 | [§ Locating the Main Application Class] "We generally recommend that you locate your main application class in a root package above other classes." | official-vendor-doc |
Spring Boot 애플리케이션 모든 버전 (특히 4.x 기준) | 멀티모듈 프로젝트에서 각 모듈의 패키지 루트 분리 방식까지 규정하지는 않음 |
| SB-STRUCT-C2 | @SpringBootApplication 은 main 클래스에 선언하며, 해당 클래스의 패키지가 암묵적인 component search base package로 사용된다 |
[§ Locating the Main Application Class] "The @SpringBootApplication annotation is often placed on your main class, and it implicitly defines a base "search package" for certain items." |
official-vendor-doc |
@SpringBootApplication 사용 시 (auto-configuration + component scan 묶음) |
@ComponentScan(basePackages=...) 로 수동 오버라이드한 경우에는 이 default 동작이 적용되지 않음 |
| SB-STRUCT-C3 | root package에 main 클래스를 두면 component scan이 프로젝트 내부에만 적용된다 | [§ Locating the Main Application Class] "Using a root package also allows component scan to apply only on your project." | official-vendor-doc |
@SpringBootApplication 기본 설정을 그대로 사용하는 경우 |
외부 라이브러리의 빈이 scan에서 완전히 제외되는지 여부는 라이브러리가 어떤 방식으로 패키징되었는지에도 의존 |
| SB-STRUCT-C4 | Spring Boot는 default package(package 선언 없는 클래스) 사용을 명시적으로 금지한다 | [§ Using the "default" Package] "The use of the "default package" is generally discouraged and should be avoided." | official-vendor-doc |
@ComponentScan, @ConfigurationPropertiesScan, @EntityScan, @SpringBootApplication 을 사용하는 모든 Spring Boot 앱 |
이 권고가 강제 컴파일 오류를 유발하지는 않음 — 런타임 문제(모든 jar의 모든 클래스 스캔)를 경고하는 것 |
| SB-STRUCT-C5 | 도메인 기반 구조 강제가 필요하면 Spring Modulith를 검토하도록 권고한다 | [§ Structuring Your Code — Tip] "If you wish to enforce a structure based on domains, take a look at Spring Modulith." | official-vendor-doc |
Spring Boot 애플리케이션에서 module boundary 검증이 필요한 경우 | Spring Modulith가 모든 multi-module 프로젝트에 필수라는 뜻은 아님 — "take a look" 수준의 권고 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
SB-STRUCT-C1: root package에 main 클래스를 두는 것이 Spring 공식 권고임SB-STRUCT-C2:@SpringBootApplication의 암묵적 base package 동작 (수동 지정 없을 때)SB-STRUCT-C3: root package 배치가 component scan을 프로젝트 범위로 제한한다는 공식 설명SB-STRUCT-C4: default package 사용이 공식적으로 금지(discouraged)됨SB-STRUCT-C5: Spring Modulith가 도메인 기반 구조 강제의 공식 권고 대안임
- 이 자료가 증명하지 않는 것:
- Gradle multi-module 구조에서 각 하위 모듈의 root package를 어떻게 분리해야 하는지
app-bootstrap모듈에@SpringBootApplication을 두어야 한다는 것 (문서는 단일 모듈 기준 설명)@SpringBootApplication의 scanBasePackages 커스텀 설정이 필요한 시점
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl multi-module 구조에서
app-bootstrap의dev.caskeleton.bootstrappackage가domain-core,adapter-web등의 sibling module classes를 scan 범위에서 자동 포함하는지 여부 → 실제 빌드 + integration test로 검증 필요 @SpringBootApplication(scanBasePackages = "dev.caskeleton")설정이 필요한지 아닌지
- ca-tmpl multi-module 구조에서
메모 / Notes
- 공식 문서 버전은 4.0.6 (2026-05-28 기준 latest). Spring Boot 3.x 에서도 동일 정책이 적용됨 (3.x reference 별도 확인 권장).
“/”는 HTML left/right double quotation mark. 인용 내"search package"는 원문의 curly quote를 straight quote로 표기한 것.- Spring Modulith 권고(C5)는 "take a look at" 수준이며 강제 요건이 아님. feature-skeleton-package-blueprint-contract에서 Spring Modulith를 기본값이 아닌 후속 검토 후보로 둔 것과 일치.
- 추가로 봐야 할 동일 출처 페이지:
using-the-springbootapplication-annotation.html(scanBasePackages 속성 설명 포함)
Related / 관련
- raw/official-docs/modulith-spring-official-doc — Spring Modulith 공식 문서 (SB-STRUCT-C5 의 권고 대상)
- raw/branch-notes/feature-skeleton-package-blueprint-contract — 이 자료를 사용한 package/module blueprint 결정 branch