テンプレートファイルの配置場所と命名ルールを初心者向けにやさしく解説！

テンプレートファイルの配置場所と命名ルール

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

新人

「先輩、SpringでWebアプリを作ってるんですが、テンプレートファイルってどこに置けばいいんですか？」

先輩

「テンプレートファイルの配置場所はresources/templatesだよ。命名にも少しルールがあるから、そこも一緒に覚えておこう。」

新人

「なるほど……テンプレートって具体的に何を指してるんですか？」

先輩

「じゃあ、テンプレートファイルとは何か、基本から説明するね！」

1. テンプレートファイルとは何か（役割や概要）

テンプレートファイルとは、Webページの表示を定義するHTMLファイルのことです。Springでは、Thymeleafというテンプレートエンジンを使って、HTMLの中にJavaの変数や条件分岐などを組み込むことができます。

たとえば、Javaの@Controllerから渡した名前をHTMLに表示したいとき、次のように記述します。


<p>こんにちは、<span th:text="${userName}">ゲスト</span>さん！</p>

このようにth:textなどの属性を使って、動的にデータを表示できるのがテンプレートファイルの特徴です。画面表示の見た目を担当するため、「ビュー」とも呼ばれます。

テンプレートファイルは、通常のHTMLとほぼ同じ構文で書けるため、初心者にも非常に扱いやすいです。

2. Springでテンプレートを使う理由（@Controllerとの関係）

SpringのWebアプリケーションでは、@Controllerが画面表示の制御を担当します。具体的には、ユーザーのリクエストを受け取って、テンプレートファイル（HTML）に必要なデータを渡します。

以下は、テンプレートファイルを表示するためのシンプルな@Controllerの例です。


@Controller
public class SampleController {

    @GetMapping("/greeting")
    public String showGreeting(Model model) {
        model.addAttribute("userName", "鈴木");
        return "greeting";
    }
}

このコードでは、Modelを使って「userName」という名前で「鈴木」という値をテンプレートに渡しています。そして、戻り値の"greeting"がテンプレートファイル名になります。

テンプレートファイルの配置場所

テンプレートファイルは、下記のようにresources/templatesフォルダに配置します。


src/
└── main/
    └── resources/
        └── templates/
            └── greeting.html

このように配置しておけば、Springが自動的にテンプレートファイルを探してくれます。ファイル名のgreeting.htmlと、コントローラーの戻り値"greeting"が一致することがポイントです。

初心者が注意すべきポイントとして、拡張子は含めず、テンプレートのファイル名だけを文字列として返すようにしましょう。たとえばreturn "greeting";で、.htmlは書かなくて大丈夫です。

テンプレートとコントローラーの連携を覚えることで、画面の作成がスムーズになります。テンプレートファイルの配置場所と命名ルールは、Springアプリ開発においてとても大切な基礎知識です。

3. テンプレートファイルの配置場所（src/main/resources/templates）

テンプレートファイルの配置場所は、Springプロジェクトにおいて非常に重要です。Pleiadesを使ってGradleプロジェクトを作成すると、src/main/resourcesというディレクトリが自動的に作成されます。この中のtemplatesフォルダにテンプレートファイルを保存するのが基本ルールです。

例えば、次のような構成になります。


src/
└── main/
    └── resources/
        └── templates/
            └── greeting.html

テンプレートファイルはこのtemplatesフォルダ内に置くことで、Springの@Controllerクラスから正しく参照されます。Springはこのフォルダを自動的にテンプレートの検索対象として認識しているため、特別な設定をしなくてもHTMLを表示できます。

このようなルールに従って配置することで、初心者でも混乱せずに画面設計ができるようになります。Gradle構成であっても、Pleiadesでプロジェクトを作成すればこの構成が自動で用意されるため、まずはこのテンプレート構成を覚えることが大切です。

4. ファイル配置のパターンと階層構造（例：fragments、pagesディレクトリなど）

プロジェクトが大きくなると、テンプレートファイルが増えてきます。そこで重要になるのが、テンプレートファイルの整理方法です。Springのテンプレート管理では、目的に応じてサブディレクトリを分けることがよくあります。

代表的なパターンとしては、次のような構成です。


templates/
├── fragments/
│   └── header.html
│   └── footer.html
├── pages/
│   └── home.html
│   └── about.html
└── login.html

fragmentsフォルダには、共通部品（ヘッダーやフッター、メニューなど）を配置します。これらは複数のページで使い回されるため、テンプレートの再利用性を高める役割があります。

pagesフォルダには、個別の画面を構成するHTMLファイルを分類して配置します。例えば、home.htmlはトップページ用、about.htmlは会社概要ページ用など、機能別に分けることで管理しやすくなります。

共通テンプレートの読み込み例

ヘッダーやフッターのような共通部分は、th:replaceやth:includeを使って読み込みます。以下はfragments/header.htmlを読み込む例です。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>サンプル</title>
    <th:block th:replace="fragments/header :: header"></th:block>
</head>
<body>
    <h1>ホームページ</h1>
</body>
</html>

このように書くことで、共通部品のテンプレートを別ファイルから読み込むことができます。:: headerは、読み込むテンプレート内に定義された名前付き要素（例：th:fragment="header"）を指定しています。

この方法を使えば、テンプレートファイルのコードをすっきり保てる上に、メンテナンスもしやすくなります。初心者の方も、はじめからfragmentsやpagesというディレクトリ構成を意識しておくと、後々プロジェクトが拡大したときに困りません。

@Controllerとの連携とパスの指定

テンプレートファイルをサブディレクトリに配置した場合は、@Controllerから返す文字列にもパスを含める必要があります。例えば、pages/home.htmlを表示したい場合は、以下のように指定します。


@Controller
public class PageController {

    @GetMapping("/home")
    public String showHome() {
        return "pages/home";
    }
}

このように、テンプレートの階層に合わせて正しくパスを記述することで、Springがテンプレートファイルを正しく読み込みます。ディレクトリ名とファイル名の区切りには「/」を使い、拡張子（.html）は省略するのがルールです。

このルールを理解しておくと、複数画面を持つ大規模なWebアプリケーションでも、テンプレート構成をすっきり整理して管理できます。初心者の方は、はじめは1階層から始めて、徐々にfragmentsやpagesを活用する構成に慣れていきましょう。

特にPleiadesのような統合開発環境を使っている場合、ディレクトリ構成がわかりやすく表示されるため、テンプレートの配置場所や命名ルールを守ることで、開発効率がぐっと上がります。

5. 命名ルールの基本（ファイル名のつけ方、拡張子、わかりやすさ）

テンプレートファイルの命名ルールを正しく理解することは、初心者がSpring開発でつまずかないためにとても重要です。まず、ファイル名は.htmlという拡張子で保存する必要があります。これはThymeleafのテンプレートエンジンがHTMLファイルを処理するためです。

例えば、次のようにファイル名をつけましょう。


login.html
home.html
userList.html

命名はできるだけ機能や画面の内容がわかるようにし、短くても意味の伝わる名前にするのがポイントです。例えば、ユーザー一覧画面のテンプレートにlist.htmlとつけるのではなく、userList.htmlのようにしておくと、後から見返したときに内容をすぐに思い出せます。

ファイル名の先頭は小文字で始め、単語の区切りにはキャメルケース（例：userList）やアンダースコア（例：user_list）を使うことが一般的です。どちらかに統一することで、プロジェクト全体の可読性が上がります。

6. よくある間違いとその対処法

初心者がテンプレートファイルを扱うときに、よくある間違いをいくつか紹介し、その対処法を解説します。

① templatesフォルダ以外に配置してしまう

よくあるミスとして、テンプレートファイルをsrc/main/resourcesの直下や、staticフォルダなどに置いてしまうことがあります。しかしSpringでは、templatesフォルダ内のファイルだけがテンプレートとして認識されます。


誤った例：
src/
└── main/
    └── resources/
        └── login.html ← 認識されない

この場合は、必ず正しいパスに修正してください。


正しい例：
src/
└── main/
    └── resources/
        └── templates/
            └── login.html

② @Controllerの戻り値とファイル名が一致しない

テンプレートファイル名と@Controllerの戻り値が一致しないと、画面が表示されずエラーになります。


@Controller
public class LoginController {

    @GetMapping("/login")
    public String showLogin() {
        return "loginForm"; // login.html が存在しない場合、エラー
    }
}

この場合は、テンプレートファイル名をloginForm.htmlにするか、戻り値を"login"に修正しましょう。


return "login"; // login.html と一致させる

③ HTMLファイルの拡張子を忘れる

Pleiadesで新規ファイルを作成する際に、ファイル名だけを入力して拡張子.htmlをつけ忘れるケースがあります。この場合、テンプレートとして認識されません。


誤：login　→　ファイル形式が不明になる
正：login.html　→　テンプレートとして認識される

ファイル名の拡張子を確認する習慣をつけましょう。

7. 実務で使えるテンプレート管理のコツ

最後に、実際の業務で役立つテンプレートファイル管理のコツを紹介します。プロジェクトが大きくなると、テンプレートファイルもどんどん増えていきます。その中で、わかりやすく保守しやすい構成を作るためには、いくつかの工夫が必要です。

① ディレクトリ分けを活用する

テンプレートファイルを機能別にフォルダで分類しましょう。例えば、管理者用画面はadmin/、ユーザー向け画面はuser/などに分けると見やすくなります。


templates/
├── admin/
│   └── dashboard.html
├── user/
│   └── profile.html
└── login.html

@Controllerでテンプレートを呼び出すときには、階層にあわせてパスを指定する必要があります。


return "admin/dashboard";

② 共通パーツは fragments にまとめる

ヘッダー、フッター、メニューなど複数のテンプレートで共通に使う要素は、fragmentsディレクトリにまとめて管理すると便利です。これにより、変更があった場合にも1箇所修正すればすべてに反映されるため、メンテナンス性が向上します。

③ 命名は統一性を重視する

同じ機能に関するテンプレートファイル名は、接頭語や接尾語を統一してつけましょう。


userList.html
userDetail.html
userEdit.html

このようにすることで、目的のテンプレートを探しやすくなり、作業ミスを防げます。

このような命名ルールとテンプレート構成の工夫を積み重ねることで、実務でも通用する見やすく整ったテンプレート管理が実現できます。

初心者の方も、最初のうちからこのような命名や構成の考え方を意識することで、プロジェクトの拡張やチーム開発にも対応しやすくなります。

PleiadesとGradleを使用したSpring開発環境でも、これらのテンプレートファイルの命名ルールと配置の知識を守ることで、エラーの少ないスムーズな画面作成ができるようになります。