【Spring】Spring Bootのディレクトリ構成とアノテーションの基礎

Java
2025.10.02

こんにちは、かつコーチです。

Spring Initializrでプロジェクトを作成すると、いくつものフォルダとファイルが最初から用意されています。
何がどこにあるのか分からないまま進めると、後で「このファイルはどこに置けばいいんだろう」と迷子になりがちです。
この記事では、Spring Bootの標準的なディレクトリ構成と、コードのあちこちに登場するアノテーションの基礎を整理します。

Spring Bootのディレクトリ構成とは？

標準的なフォルダ構成

Spring Initializrで生成したプロジェクトは、次のような構成になっています。

demo/
├── pom.xml                      # Mavenのビルド設定ファイル
├── src/
│   ├── main/
│   │   ├── java/com/example/demo/
│   │   │   └── DemoApplication.java   # アプリの起動クラス
│   │   └── resources/
│   │       ├── application.properties # アプリの設定ファイル
│   │       ├── static/                # CSS・JS・画像などの静的ファイル
│   │       └── templates/             # Thymeleafなどのテンプレート
│   └── test/
│       └── java/com/example/demo/
│           └── DemoApplicationTests.java

src/main/java配下がJavaのソースコード、src/main/resources配下が設定ファイルや画面テンプレートといった「コード以外」のリソースです。
src/test配下はテストコードの置き場所で、本番コードとは明確に分離されています。

実務ではさらにパッケージを分割する

学習用の最小構成ではDemoApplication.javaが1つあるだけですが、実際の開発ではこの中に以下のようなパッケージ（フォルダ）を作り、役割ごとにクラスを分けていくのが一般的です。

  • controller：リクエストを受け取る入り口
  • service：ビジネスロジック
  • repository：データベースとのやり取り
  • entity（またはmodel）：データの構造を表すクラス
com.example.demo/
├── DemoApplication.java
├── controller/
├── service/
├── repository/
└── entity/

Java基礎編で学んだパッケージの考え方がそのまま活きる部分なので、「役割ごとにフォルダを分ける」という感覚を持っておくと構成がすんなり頭に入ります。

アノテーションの基礎

アノテーションとは何か

アノテーションとは、@から始まる記述で、クラスやメソッドに「特別な意味・役割」を付け加える仕組みです。
Javaの標準機能ですが、Spring Bootはこのアノテーションを大量に活用することで、XMLでの設定を書かずに済むようにしています。

例えば、前回登場した@SpringBootApplicationというアノテーションを見てみましょう。

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@SpringBootApplicationは、実は次の3つのアノテーションをまとめたものです。

アノテーション役割
@SpringBootConfigurationこのクラスが設定用クラスであることを示す
@EnableAutoConfiguration自動設定機能を有効にする
@ComponentScan同じパッケージ配下のクラスを自動で検出する

つまり@SpringBootApplicationが付いたクラスを起点に、Spring Bootは「同じパッケージ以下を全部スキャンして、必要なクラスを自動で登録する」という動作をしています。

なぜアノテーションが重要なのか

昔ながらのSpring Frameworkでは、「このクラスをどう扱うか」をXMLファイルに1つずつ記述していました。
アノテーションを使うことで、その設定をクラス自体に直接書き込めるようになり、設定ファイルとコードが離れてしまう問題を解消できます。

コードを見れば「このクラスが何の役割を持つか」が一目で分かるようになるため、可読性の面でも大きなメリットがあります。
Spring Bootの学習は、アノテーションの意味を1つずつ理解していく作業と言い換えても過言ではありません。

つまずきやすい設定・注意点

@ComponentScanの対象範囲を意識していないと動かない

@ComponentScanは「同じパッケージ配下」を自動でスキャンする仕組みですが、この範囲を意識しないと思わぬエラーに遭遇します。

❌ Before
com.example.demo.DemoApplication がある一方で、
別のパッケージ com.other.controller に @Controller クラスを作ってしまい、
起動時にコントローラが見つからず404エラーになる

筆者も実際に、起動クラスとは別のトップレベルパッケージにコントローラを配置してしまい、「なぜかリクエストが404になる」という現象に何時間も悩まされたことがあります。
原因は@ComponentScanのスキャン範囲外にクラスを置いてしまっていたことでした。

✅ After
起動クラス（@SpringBootApplicationが付いたクラス）と同じパッケージ、
またはそのサブパッケージにすべてのクラスを配置する
com.example.demo.DemoApplication
com.example.demo.controller.HelloController

起動クラスの位置を「アプリ全体のルート」として意識し、その配下にすべてのクラスをまとめる、という原則を覚えておくと、このつまずきを避けられます。

応用・一歩先の使い方

パッケージ構成が大きくなってきた場合、@ComponentScanにスキャン対象のパッケージを明示的に指定することもできます。

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.demo", "com.example.shared"})
public class DemoApplication {
    // ...
}

複数モジュールにまたがるプロジェクトや、共通処理を別パッケージに切り出したい場合には、こうした明示的な指定が役立ちます。
最初のうちは「起動クラスの配下にまとめる」で十分ですが、こういう選択肢があることも覚えておきましょう。

まとめ

この記事のポイント

  • src/main/javaにコード、src/main/resourcesに設定・画面テンプレートを置く
  • 実務ではcontroller・service・repository・entityのようにパッケージを分割する
  • アノテーションはクラスに役割を与える仕組みで、XML設定を大幅に削減してくれる
  • @ComponentScanは起動クラスと同じパッケージ配下しかスキャンしない点に注意する

次に読むべき記事

ディレクトリ構成とアノテーションの基礎が分かったら、次は実際のアプリ動作を細かく制御する「application.propertiesの基本設定」を見ていきましょう。

タグ: Spring Boot, 初心者向け, 入門

タイトルとURLをコピーしました