DIの対象となるクラスはどこに置けばいい？初心者向けSpringパッケージ構造解説

新人と先輩の会話形式で理解しよう

新人

「SpringのDIを使うとき、対象のクラスはどこに置けばいいんですか？」

先輩

「DIの対象になるクラスは、Springが管理できるように正しいパッケージに配置する必要があるんだよ。」

新人

「正しいパッケージって、具体的にはどんな場所ですか？」

先輩

「それはアプリケーションのエントリポイントから見て、Springのコンポーネントスキャンの範囲に含まれる場所だよ。順番に説明していこうか。」

1. DI（依存性注入）の対象となるクラスとは？

DI（依存性注入）の対象となるクラスとは、Springフレームワークが自動的にインスタンスを生成して管理してくれるクラスのことです。Springでは、@Component、@Service、@Repository、@Controllerなどのアノテーションを付与したクラスがこの対象になります。

これらのクラスは、SpringのIoCコンテナに登録され、必要な場所で自動的に注入されます。例えば、@Serviceを付けたクラスをControllerで使いたい場合、@Autowiredやコンストラクタ注入を使えば、開発者がnewでインスタンスを作る必要はありません。

実際の例を見てみましょう。以下のコードでは、UserServiceクラスがDIの対象となっています。


import org.springframework.stereotype.Service;

@Service
public class UserService {
    public String getUserName() {
        return "Taro Yamada";
    }
}

このUserServiceをControllerで呼び出すときは、次のように書きます。


import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/name")
    public String showName() {
        System.out.println(userService.getUserName());
        return "nameView";
    }
}

このように、SpringのDIを使えばクラスの依存関係を明確に保ちながら、コードの可読性や保守性を高めることができます。

2. なぜクラスの配置場所が重要なのか（パッケージ構造の基本）

DIの対象となるクラスは、Springのコンポーネントスキャンで見つけられる場所に配置しなければなりません。Spring Bootでは通常、アプリケーションのエントリポイントクラス（@SpringBootApplicationが付いたクラス）のパッケージとその配下が自動でスキャンされます。

例えば、以下のようなパッケージ構造の場合、com.example.demo配下にあるクラスはすべてスキャン対象となります。


com.example.demo
 ├── DemoApplication.java  // @SpringBootApplication
 ├── controller
 │     └── UserController.java
 ├── service
 │     └── UserService.java
 └── repository
       └── UserRepository.java

もしDIの対象クラスをこのパッケージ外に置いてしまうと、Springはそのクラスを認識できず、No qualifying bean of typeというエラーが発生します。これを防ぐためには、必ずエントリポイントのパッケージ配下に配置しましょう。

特に初心者が間違えやすいのは、別のプロジェクトや別パッケージにクラスを置いてしまうケースです。この場合、@ComponentScanを使ってスキャン範囲を明示的に指定する必要がありますが、最初はパッケージ構造をシンプルにしておくのがおすすめです。

例えば、次のように指定すれば、他のパッケージのクラスもスキャンできます。


import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.demo", "com.other.package"})
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

しかし、これはプロジェクトの規模が大きくなったり、外部モジュールを取り込む場合に使う方法です。初心者が学習する段階では、パッケージ構造を正しく整理してDI対象クラスを配置することが、エラーを減らし、開発効率を高めるポイントになります。

3. Springにおけるコンポーネントスキャンとクラス配置の関係

Springではコンポーネントスキャンという仕組みを使って、アプリケーションの起動時に特定のパッケージ内のクラスを自動的に検出し、DIの対象として登録します。このスキャンは、@SpringBootApplicationや@ComponentScanによって定義されたパッケージ階層を基準に行われます。

例えば、エントリポイントのクラスがcom.example.demoにある場合、その配下のすべてのクラスがスキャン対象です。そのため、DI対象のクラスは必ずこの配下に配置するのが基本です。これを守らないと、SpringがそのクラスをBeanとして認識できず、依存性注入が機能しません。

コンポーネントスキャンの範囲は、特に意識しないときはエントリポイントのパッケージ配下全体ですが、@ComponentScanを使えばスキャンするパッケージを限定したり追加できます。しかし初心者のうちは構造をシンプルにし、標準のスキャン範囲内にすべてのDI対象クラスを置くのが安全です。


@SpringBootApplication
@ComponentScan(basePackages = {"com.example.demo"})
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

このように明示的に記述することもできますが、特別な理由がなければ省略しても問題ありません。重要なのは、パッケージ構造を正しく設計し、すべてのDI対象クラスがスキャン範囲内にあることです。

4. @Component、@Service、@Repositoryを付けるクラスの配置例

DIの対象クラスには目的に応じて@Component、@Service、@Repositoryなどのアノテーションを付与します。これらはすべてSpringのコンポーネントとして認識されますが、用途によって使い分けることでコードの意図を明確にできます。

@Component：汎用的なBeanで、特定の役割を持たないクラス
@Service：ビジネスロジックを担当するサービス層のクラス
@Repository：データベースアクセスを担当するクラス

例えば以下のようにパッケージごとに役割を整理すると、SpringのDIが正しく機能しやすくなります。


com.example.demo
 ├── DemoApplication.java
 ├── controller
 │     └── UserController.java  // @Controller
 ├── service
 │     └── UserService.java     // @Service
 └── repository
       └── UserRepository.java  // @Repository

この構造では、ControllerからService、ServiceからRepositoryへと依存関係が流れる形になります。この依存関係をSpringのDIが自動的に解決してくれるため、開発者はインスタンス生成や管理を意識する必要がありません。


@Service
public class UserService {
    private final UserRepository userRepository;
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
    public List<User> getAllUsers() {
        return userRepository.findAll();
    }
}

5. パッケージ構造のベストプラクティス

初心者がSpringでアプリケーションを構築する際、パッケージ構造はシンプルかつ役割ごとに整理されていることが望ましいです。特にDI対象クラスを正しく配置するためには、以下のポイントを守るとよいでしょう。

アプリケーションのエントリポイントクラスをルートパッケージに置く
Controller、Service、Repositoryをそれぞれ専用のパッケージに分ける
DI対象のクラスは必ずエントリポイントの配下に配置する
共通処理やユーティリティクラスはutilパッケージにまとめる

推奨される構造例は次の通りです。


com.example.demo
 ├── DemoApplication.java
 ├── controller
 │     ├── UserController.java
 │     └── ProductController.java
 ├── service
 │     ├── UserService.java
 │     └── ProductService.java
 ├── repository
 │     ├── UserRepository.java
 │     └── ProductRepository.java
 └── util
       └── DateUtil.java

このような構造にしておくと、Springがコンポーネントスキャンで自動的にすべてのクラスを検出でき、DIによる依存性解決がスムーズに行われます。また、後からプロジェクトに参加する開発者も役割ごとのクラスをすぐに見つけられるため、保守性が高まります。

特にGradle＋Pleiades環境では、パッケージ構造が崩れていると依存関係の追加やビルド時にクラスが認識されないことがあります。初心者はまずこの基本構造を習得し、必要に応じてパッケージを増やすのが良いでしょう。

6. クラス配置ミスで発生するよくあるエラーとその解決方法

SpringでDI（依存性注入）を使う場合、クラスの配置場所を間違えるとアプリケーション起動時にエラーが発生します。特に初心者が遭遇しやすいのは、パッケージ構造の外にクラスを置いてしまうケースです。

例えば、エントリポイント@SpringBootApplicationがあるcom.example.demo配下ではなく、com.example.serviceなど全く別のルートパッケージに@Serviceクラスを置いた場合、Springのコンポーネントスキャンでそのクラスが検出されず、次のようなエラーになります。


No qualifying bean of type 'com.example.service.UserService' available

このエラーを解決する方法は次の通りです。

DI対象クラスを必ずエントリポイント配下に移動する
どうしても別パッケージに置く場合は、@ComponentScanでスキャン対象に追加する
アノテーション（@Component、@Serviceなど）の付け忘れがないか確認する

特にPleiades＋Gradle環境では、パッケージ構造を変更した後はGradleのリフレッシュを行うことで正しくビルドされるようになります。

7. 実際のアプリケーションでのクラス配置例（Controller・Service・Repository）

ここでは、初心者でも理解しやすいSpringの標準的なパッケージ構造の例を示します。Controller、Service、Repositoryを役割ごとに分けて配置することで、SpringのDIがスムーズに動作します。


com.example.demo
 ├── DemoApplication.java
 ├── controller
 │     └── UserController.java  // @Controller
 ├── service
 │     └── UserService.java     // @Service
 └── repository
       └── UserRepository.java  // @Repository

例えば以下のように、ControllerからServiceを呼び出し、ServiceからRepositoryを呼び出す流れにします。


@Controller
public class UserController {
    private final UserService userService;
    public UserController(UserService userService) {
        this.userService = userService;
    }
    @GetMapping("/users")
    public String getUsers(Model model) {
        model.addAttribute("users", userService.getAllUsers());
        return "userList";
    }
}


@Service
public class UserService {
    private final UserRepository userRepository;
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
    public List<User> getAllUsers() {
        return userRepository.findAll();
    }
}


@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

このように役割ごとのクラスを明確に配置すると、Springがコンポーネントスキャンで自動的にBeanとして登録し、依存性注入を正しく行えるようになります。

8. 初心者がDI対象クラスを正しく配置するためのチェックリスト

最後に、DI対象クラスの配置で迷ったときに確認できるチェックリストを紹介します。特にPleiades＋Gradle環境でSpringアプリケーションを開発する際に役立ちます。

エントリポイントクラス（@SpringBootApplication）はルートパッケージに置いているか
DI対象のクラス（@Component、@Service、@Repository、@Controller）はエントリポイントの配下にあるか
パッケージ名が正しく設定されているか（スペルミスや意図しない階層構造がないか）
必要なアノテーションを付け忘れていないか
別パッケージのクラスを使う場合は@ComponentScanを設定しているか
パッケージ構造変更後はGradleのリフレッシュを行っているか

このチェックリストを守れば、SpringのDI機能が正しく動作しやすくなります。特に初心者のうちは、まずは推奨構造に沿って開発を進め、慣れてきたらプロジェクトの規模や要件に応じて調整するとよいでしょう。