プロジェクトにパッケージを作って機能ごとに整理しよう！Java初心者向けクラス構成の基本

プロジェクトにパッケージを作って機能ごとに整理しよう

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

新人

「Springのプロジェクトを作るとき、クラスがどんどん増えてきて、どこに何があるか分からなくなってしまいます……」

先輩

「それはよくある悩みだね。Javaでは、パッケージを使ってクラスを整理するのが基本なんだよ。」

新人

「パッケージって具体的に何ですか？どう使えばいいんでしょうか？」

先輩

「じゃあまずは、Javaにおけるパッケージの基本から説明していこう！」

1. パッケージとは何か？Javaにおける基本的な意味

Javaにおけるパッケージとは、クラスを分類・整理するための「フォルダ」のようなものです。大量のクラスファイルを見やすく管理し、役割ごとにまとめるために使われます。

たとえば、Springプロジェクトでは@Controllerクラス、@Serviceクラス、@Repositoryクラスなど、さまざまな役割を持つクラスが存在します。これらをすべて同じ場所に置いてしまうと、後から見たときに非常に分かりにくくなります。

そこで、次のように役割ごとにフォルダ（＝パッケージ）を分けて整理します。


com.example.demo
├── controller
│   └── HelloController.java
├── service
│   └── HelloService.java
├── repository
│   └── HelloRepository.java

このように分けておけば、たとえば「コントローラーはcontrollerパッケージ」「データ処理はrepositoryパッケージ」など、目的のクラスをすぐに見つけることができます。

また、クラスの先頭にはpackage文を書いて、どのパッケージに属するかを示します。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;

@Controller
public class HelloController {
    // コントローラーの処理
}

このようにpackageを指定することで、JavaのコンパイラやIDE（今回のPleiadesなど）が自動的にクラスを整理・認識してくれます。

2. なぜパッケージでクラスを整理する必要があるのか？

JavaやSpringでアプリケーションを開発していると、プロジェクトが大きくなるにつれて、クラスの数もどんどん増えていきます。もし全てのクラスを1つのパッケージに置いたままだと、次のような問題が起きてしまいます。

どのクラスが何をしているか分かりづらくなる
同じような名前のクラスが混在し、混乱を招く
再利用性や保守性が下がる

パッケージを使えば、機能や役割ごとに整理ができ、次のようなメリットがあります。

クラスの役割が一目で分かる
チーム開発で他の人が構造を把握しやすい
将来的な拡張や修正がしやすくなる

特にSpringプロジェクトでは、クラスごとの責務を明確に分けることが推奨されています。コントローラーはリクエストを処理し、サービスはロジックをまとめ、リポジトリはデータベースとやりとりします。これらをパッケージに分けておけば、クラスの整理がしやすくなるだけでなく、Springのコンポーネントスキャンの対象にもなりやすくなります。

実際に、PleiadesでGradleプロジェクトを作成した場合、基本となるsrc/main/java以下に、次のような構成を取るのがおすすめです。


src/main/java
└── com/example/demo
    ├── controller
    ├── service
    ├── repository
    └── model

このように整理することで、機能単位でクラスが把握でき、開発効率が大幅に向上します。Springの学習を始めたばかりの初心者でも、パッケージによる整理を習慣づけることで、後の学習や実務にスムーズにつなげることができます。

3. パッケージ構成の例（controller、service、repository、modelなど）

ここでは、Java初心者でも理解しやすいように、実際のSpringプロジェクトで使われる代表的なパッケージ構成を紹介します。PleiadesでGradleプロジェクトを作成したあと、src/main/javaの下にパッケージを追加していきましょう。

たとえば、次のような構成にすると役割ごとの整理が明確になります。


com.example.demo
├── controller       // リクエストを受け取るクラス
│   └── HelloController.java
├── service          // ビジネスロジックを記述するクラス
│   └── HelloService.java
├── repository       // データベースとやりとりするクラス
│   └── HelloRepository.java
└── model            // エンティティやDTOなどのデータ構造を定義するクラス
    └── Hello.java

それぞれのパッケージが持つ主な役割は以下の通りです。

controller：ユーザーからのリクエストを受け取り、適切なサービス処理へ渡す役割。
service：アプリケーションのビジネスロジック（処理の本体）を担うクラス。
repository：データベースとの接続・取得・保存を担当。
model：データ構造を表すクラス。エンティティやDTOなどがここに含まれる。

この構成は、Springでアプリケーションを開発する際のベーシックな設計です。初学者がよく混乱するのが、どのクラスをどこに配置すればいいかという点ですが、このように役割に応じた整理を行えば、見通しのよいプロジェクトになります。

以下は、それぞれの役割を簡単なコードで見てみましょう。


// controller/HelloController.java
package com.example.demo.controller;

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

@Controller
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }
}


// service/HelloService.java
package com.example.demo.service;

import org.springframework.stereotype.Service;

@Service
public class HelloService {
    public String getMessage() {
        return "こんにちは、Spring！";
    }
}


// repository/HelloRepository.java
package com.example.demo.repository;

import org.springframework.stereotype.Repository;

@Repository
public class HelloRepository {
    // データベース処理の仮実装
}


// model/Hello.java
package com.example.demo.model;

public class Hello {
    private String message;
    
    public Hello(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

これらのパッケージはすべてcom.example.demoを基準とした構成です。プロジェクトが大きくなっても、構造を保ちやすく、誰が見てもクラスの役割がわかるというのがこの方法のポイントです。

4. 各パッケージにクラスを分けるとどんなメリットがあるのか？

JavaでSpringアプリケーションを開発するうえで、クラスの役割ごとにパッケージを分けることには多くのメリットがあります。特に、Pleiadesを使用した開発環境では、IDEの機能と連携してコードの構成を視覚的に管理できるため、初心者にもおすすめの方法です。

それでは、パッケージを明確に分けておくことで得られる代表的なメリットを見てみましょう。

① コードが見やすくなる

役割ごとにクラスを分類することで、どのクラスが何を担当しているかが明確になります。「これはコントローラー」「これはデータベース用」など、構成がひと目で分かるため、後から読み返す際にも迷いません。

② チーム開発でのトラブルを防げる

複数人で開発する際、パッケージで整理されていないと「どのクラスを編集すべきか」「新しいクラスはどこに作るべきか」が曖昧になります。きちんと分類されていれば、誰が見てもすぐに理解でき、ミスや重複を防ぐことができます。

③ Springのコンポーネントスキャンがスムーズになる

Springでは、アノテーション（@Controller、@Service、@Repositoryなど）を使ってクラスを自動的に読み込みます。パッケージ構成が整理されていれば、Springのコンポーネントスキャン機能が正しく動作し、クラスの登録ミスを防げます。

④ 保守・拡張がしやすくなる

パッケージごとにクラスを分けておけば、新しい機能を追加したり、既存のコードを修正したりする際にも、影響範囲をすぐに把握できます。「controllerにあるこのクラスだけ修正すればいい」と判断しやすくなり、開発の効率が大きく向上します。

⑤ Java初心者でも学習がしやすくなる

Javaを学び始めたばかりの人にとって、構造が整ったコードを見ることはとても大切です。役割ごとに整理されたパッケージ構成は、アプリケーション全体の流れや仕組みを理解する手助けになります。

このように、パッケージ構成を意識するだけで、プロジェクト全体が整理され、品質の高いコードを書く土台を作ることができます。PleiadesでSpringプロジェクトを作成する際は、最初にパッケージの設計から考える習慣を身につけましょう。

5. よくある間違いと注意点

Springアプリケーションの開発で、初心者が最初につまずきやすいのが「パッケージの使い方」です。正しく整理されていないと、せっかくの設計も台無しになってしまいます。ここでは、よくある間違いとその対処法を紹介します。

① すべてのクラスを同じパッケージに入れてしまう

Java初心者にありがちなのが、com.example.demoの中にすべてのクラスを置いてしまうことです。一見シンプルに見えるかもしれませんが、プロジェクトが大きくなると一気にごちゃごちゃになってしまい、クラスの役割が見えにくくなります。

② クラスの責務が曖昧になる

コントローラーの中にビジネスロジックを書いたり、サービスクラスがデータベース操作まで行ったりするなど、役割の境界があいまいになると、コードの保守性が下がります。パッケージを分ける目的は、まさにこの「責務の分離」を実現するためです。

③ クラス名に役割が反映されていない

クラス名だけ見ても何をしているのかわからないと、読み手が混乱します。たとえばDataManagerなど、抽象的すぎる名前は避け、「HelloService」「UserController」のように、役割と機能がすぐに分かる名前を使いましょう。

④ Springのアノテーションを正しく使えていない

@Controller、@Service、@Repositoryなどを正しく使わないと、Springのコンポーネントスキャンで認識されず、実行時にエラーが出ることがあります。必ず適切なパッケージに配置し、アノテーションを忘れずに付けましょう。

このようなミスを防ぐには、パッケージ構成に一貫性を持たせることが大切です。クラスを追加するたびに「このクラスの責任は何か？」を考える習慣を身につけましょう。

6. クラスをパッケージに分けた設計を活かすためのコツ

パッケージにクラスを整理しただけでは、設計を活かしきれません。Springプロジェクトで設計を活かすには、いくつかのコツがあります。

① 一つのクラスには一つの責務だけを持たせる

クラスには、できるだけ一つの責任だけを持たせるようにしましょう。たとえば「リクエストの受け取り」と「画面遷移の指示」を行うのは@Controllerの役割であり、そこにデータ処理のロジックまで書いてはいけません。

② サービス層とリポジトリ層の関係を意識する

サービスは複数のリポジトリを使って処理を組み立てることがあります。例えば「会員登録処理」では、UserRepositoryでユーザーを保存しつつ、MailServiceを使ってメールを送信するなど、処理の中心を担うのがサービス層です。

③ コントローラーはなるべくシンプルに

初心者がやりがちなのは、コントローラーにロジックを書きすぎてしまうことです。リクエストを受け取ったら、すぐにサービスへ処理を渡すようにしましょう。

④ Springのスキャン対象を意識する

パッケージの配置によっては、Springのコンポーネントスキャンから漏れてしまう場合があります。@SpringBootApplicationのあるクラスよりも下のパッケージにすべての構成要素を配置すれば、スキャン対象に含まれます。

このようなポイントを押さえておくことで、パッケージ整理によって生まれた構造を最大限に活かすことができ、結果的に保守性・拡張性の高い設計になります。

7. 初心者が最初に取り組むべきパッケージ整理のステップ

Springアプリケーションを初めて作成する初心者の方は、「どこから手をつければよいのか」と迷うことが多いでしょう。ここでは、初心者でも実践できる具体的なパッケージ整理のステップを紹介します。

ステップ①：基本パッケージ構成を決める

まずはcontroller、service、repository、modelの4つを基本として、Pleiades上でパッケージを作成します。これだけでも「役割ごとに整理された構成」になります。


com.example.demo
├── controller
├── service
├── repository
└── model

ステップ②：クラスを正しいパッケージに配置する

次に、作成する各クラスを、適切なパッケージへ配置しましょう。たとえば「画面からのリクエストを受けるクラス」はcontrollerに、「データを操作するクラス」はrepositoryに入れます。

ステップ③：アノテーションを忘れずに付ける

各クラスには、@Controller、@Service、@Repositoryなど、Springが認識するためのアノテーションを忘れずに付けましょう。これにより、Springが自動的にクラスを管理してくれます。

ステップ④：依存関係はサービス層に集約する

データベース処理などのリポジトリや外部サービスとの連携は、なるべくserviceに集めて管理しましょう。コントローラーが直接リポジトリを使うと、責務が混在してしまいます。

ステップ⑤：プロジェクトが成長してきたら細分化する

最初は基本構成でも十分ですが、機能が増えてきたらuserやproductなど、機能単位でさらに細かくパッケージを分けることを検討しましょう。これにより、さらに見通しのよい構成に進化させることができます。

以上のステップを丁寧に進めていけば、初心者の方でも「役割ごとに整理されたパッケージ構成」「責務が明確な設計」「Springらしい構成」が実現できます。まずは小さなプロジェクトで練習しながら、徐々にパッケージ設計の感覚を身につけていきましょう。