llm-wiki/raw/official-docs/spring-boot-structuring-your-code.md

---
title: "official-doc / Spring Boot — Structuring Your Code (패키지 구조 공식 권고)"
source_type: official-doc
url: https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
archive_url:
vendor: Spring / VMware Broadcom
related_branches: [feature-skeleton-package-blueprint-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, architecture, spring-boot, component-scan, package-structure, multi-module]
status: raw
confidence: high
created: 2026-05-28
last_reviewed: 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 `@SpringBootApplication` annotation 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.bootstrap` package가 `domain-core`, `adapter-web` 등의 sibling module classes를 scan 범위에서 자동 포함하는지 여부 → 실제 빌드 + integration test로 검증 필요
  - `@SpringBootApplication(scanBasePackages = "dev.caskeleton")` 설정이 필요한지 아닌지

## 메모 / 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