HTMLファイルを作って画面表示する基本の流れを完全解説！初心者向けSpring Boot入門

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

新人

「先輩、HTMLファイルを作って画面に表示するって、どうやるんですか？Spring Bootを使うと簡単って聞いたんですが…」

先輩

「その通りだよ。Spring BootとThymeleafを使えば、HTMLファイルをブラウザで簡単に表示できるんだ。」

新人

「でも、HTMLって静的なページっていうイメージがあるんですけど、動きがある画面も作れるんですか？」

先輩

「もちろん！Spring BootでThymeleafを使えば、JavaのデータをHTMLに埋め込んで、動的に画面を作れるんだよ。まずは基本の仕組みから一緒に見ていこうか。」

1. Webアプリケーションとは？HTMLで画面を作る理由

Webアプリケーションとは、インターネットを通じて操作するアプリケーションのことです。たとえば、ショッピングサイトやブログ、会員制サイトなどが該当します。

このようなWebアプリケーションでは、ユーザーがブラウザで見る画面を作るためにHTMLファイルが使われます。HTMLは、画面の見た目や構造を定義するための言語です。

たとえば、「こんにちは、○○さん」と表示したいときには、HTMLで見出しや段落を作り、その中にテキストを埋め込むことで、ブラウザに内容を表示できます。

HTMLファイル表示を行うには、ファイルを正しい場所に置き、URLと連携させて動かす必要があります。この動きを支援するのがSpring Bootです。

2. Spring BootでHTMLファイルを画面に表示する基本の仕組み

Spring Boot HTML 表示の基本的な流れは以下の通りです。

PleiadesでSpring Bootプロジェクトを作成（Gradle形式）
Thymeleafの依存関係を追加（チェックボックスでOK）
@Controllerを使ってURLとHTMLを紐づけ
templatesフォルダにHTMLファイルを置く

たとえば、「/hello」というURLにアクセスしたときに「hello.html」が表示されるようにするには、以下のように@Controllerを作成します。


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";
    }
}

次に、以下のようなHTMLファイルをsrc/main/resources/templatesに配置します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Hello Page</title>
</head>
<body>
    <h1>こんにちは！Spring Bootの世界へようこそ！</h1>
</body>
</html>

この状態でSpring BootアプリケーションをPleiadesから起動し、ブラウザでhttp://localhost:8080/helloにアクセスすれば、作成したHTMLファイルが表示されます。

3. 静的HTMLと動的HTMLの違い（テンプレートの基本概念）

HTMLには「静的HTML」と「動的HTML」の2つの使い方があります。

静的HTML：ファイルに書かれた内容がそのまま表示される。毎回同じ内容。
動的HTML：Javaなどで処理した値をHTMLに埋め込んで、その都度変化する内容を表示。

Spring Bootでは、Thymeleafというテンプレートエンジンを使って、動的HTMLを作成できます。テンプレートエンジンとは、HTMLの中にプレースホルダ（${変数}のような形式）を書いておき、そこにJavaで用意したデータを差し込む仕組みです。

たとえば、以下のようにコントローラでデータを渡すことができます。


@GetMapping("/message")
public String message(Model model) {
    model.addAttribute("name", "佐藤さん");
    return "message";
}

そして、テンプレート側では次のように書くと、${name}に「佐藤さん」が埋め込まれて表示されます。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>動的ページ</title>
</head>
<body>
    <p th:text="'こんにちは、' + ${name} + '！'">こんにちは！</p>
</body>
</html>

このように、Spring Boot HTML 表示を行う際にThymeleafを使えば、動的に値を変えて、ユーザーごとに異なるメッセージを表示することができます。

テンプレートを使うことで、HTMLファイルの再利用性が高まり、開発効率が大幅にアップします。これが、Spring BootでHTMLを表示するときにテンプレートエンジンを使う大きな理由です。

4. プロジェクトの作成手順（Pleiadesでの操作手順）

それでは、実際にSpring Bootを使ってHTMLファイルを画面に表示するためのプロジェクトを作成してみましょう。ここでは、Pleiades（プレアデス）という日本語対応のEclipseベースIDEを使って、初心者でも迷わず操作できるようにステップ形式で紹介します。

Pleiadesを起動し、メニューから「ファイル → 新規 → Spring スターター・プロジェクト」を選択します。
プロジェクト名やパッケージ名を入力し、「次へ」をクリックします。
ビルドツールの選択画面では必ず「Gradle」を選びます。Mavenは今回使用しません。
次の「依存関係」の画面で、チェックボックスから以下の2つを選択してください：
- Spring Web
- Thymeleaf
最後に「完了」をクリックすると、Spring Bootの基本構成が整ったプロジェクトが生成されます。

これで、ThymeleafとWeb機能があらかじめ組み込まれた状態のプロジェクトが作成されます。このあとHTMLファイルの表示や、@Controllerでの処理がすぐに試せる準備が整います。

5. Spring BootにThymeleafを設定する（starter追加とbuild.gradle記述）

先ほどPleiadesでプロジェクトを作成した際に、Thymeleaf starterをチェックで追加しました。これはGradleの依存関係として設定されており、プロジェクト内のbuild.gradleファイルに自動で記述されます。

念のため、build.gradleファイルのdependenciesセクションを確認してみましょう。以下のようになっていればOKです。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

この2つのstarterを追加することで、Spring Boot HTML 表示の準備が整います。Thymeleaf starterを含めることで、Spring Bootがresources/templatesにあるHTMLファイルをテンプレートとして認識し、自動的に処理してくれます。

また、Web starterを入れることで、@Controllerを使ったルーティング（URLと画面の対応）も可能になります。

6. コントローラの作成とHTMLテンプレートの連携の基本

プロジェクトと依存関係の設定が完了したら、次は@Controllerを使ってHTMLテンプレートと連携する方法を学びましょう。

ここでは「welcome」というHTMLファイルをブラウザで表示する例を紹介します。

① コントローラクラスの作成

まずは、下記のようにJavaクラスを作成します。src/main/java配下にパッケージを作成し、その中にコントローラを作りましょう。


package com.example.demo.controller;

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

@Controller
public class WelcomeController {

    @GetMapping("/welcome")
    public String welcome(Model model) {
        model.addAttribute("username", "高橋さん");
        return "welcome";
    }
}

このコードでは、@Controllerを使って「/welcome」というURLにアクセスがあったときに、「welcome.html」というテンプレートを表示するようにしています。また、model.addAttribute()でJavaの値をHTMLに渡しています。

② HTMLテンプレートの作成

次に、HTMLファイルを作成します。テンプレートは必ずsrc/main/resources/templatesに配置します。ここではwelcome.htmlという名前で作成します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Welcome Page</title>
</head>
<body>
    <h1 th:text="'ようこそ、' + ${username} + '！'">ようこそ！</h1>
</body>
</html>

このテンプレートでは、th:text属性を使って、Java側から渡された「username」の値をHTMLに表示しています。Thymeleafの構文では、${変数}で受け取った値を使うことができます。

③ ブラウザで確認

Pleiadesでプロジェクトを右クリックして「実行 → Java アプリケーション」を選ぶと、Spring Bootアプリケーションが起動します。

その状態でブラウザを開き、次のURLにアクセスしてください：

http://localhost:8080/welcome

以下のような画面が表示されていれば成功です。


ようこそ、高橋さん！

このように、Thymeleaf starterを導入し、コントローラでreturnするだけで、簡単にHTMLファイル表示ができるのがSpring Bootの大きなメリットです。テンプレートエンジンとの連携も非常にスムーズで、複雑な設定は不要です。

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

Spring BootでHTMLを表示するには、HTMLファイルを正しいフォルダに配置する必要があります。Thymeleafを使う場合、テンプレートファイルはsrc/main/resources/templatesというディレクトリに置くのがルールです。

Thymeleaf テンプレート場所としてこのフォルダがあらかじめ設定されているため、開発者が特に設定を変更しなくても、Spring Bootが自動的にテンプレートを探してくれる仕組みになっています。

テンプレートファイルの拡張子は.htmlにする必要があります。たとえば「home.html」や「index.html」などです。

また、ファイル名にはJava側の@Controllerで指定するreturn値と一致させる必要があります。たとえば、次のようにreturn "home";と書いた場合は、「home.html」というテンプレートファイルを作っておく必要があります。


@GetMapping("/home")
public String home() {
    return "home"; // ファイル名は home.html
}

ファイルの命名は基本的に英数字で構成すれば問題ありません。日本語やスペースは避けましょう。

8. ブラウザでの表示確認手順

テンプレートを正しく配置し、コントローラとURLの設定が完了したら、いよいよSpring Boot HTML 表示の動作確認を行いましょう。以下は、実行からブラウザで確認するまでの手順です。

PleiadesのプロジェクトエクスプローラーでDemoApplication.javaなどのメインクラスを右クリックします。
「実行 → Java アプリケーション」を選択すると、コンソールに起動ログが表示されます。
「Started DemoApplication in ～」というメッセージが表示されたら、Spring Bootアプリケーションは正常に起動しています。
ブラウザを開いて、URLバーにhttp://localhost:8080/homeなど、コントローラで定義したURLを入力してアクセスします。

テンプレートが正しく表示されれば、HTMLファイルの画面表示が成功しています。

たとえば、以下のようなテンプレートを用意していた場合：


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Home</title>
</head>
<body>
    <h1>トップページへようこそ！</h1>
</body>
</html>

ブラウザには次のように表示されます。


トップページへようこそ！

このようにして、自分で作成したHTMLファイルがブラウザに表示されるかを簡単に確認することができます。

9. 初心者がよくやるミスと対策

ここでは、Spring BootとThymeleafを使ってHTMLファイル表示を行う際に、初心者がつまずきやすいポイントをまとめて紹介します。

① テンプレートの配置場所を間違える

ミスの内容：HTMLファイルをresources/staticやsrc/main/javaに置いてしまう。

対策：テンプレートファイルは必ずsrc/main/resources/templatesに置いてください。Thymeleaf テンプレート場所は決まっているので、それ以外の場所では動作しません。

② コントローラの`return`に拡張子をつけてしまう

ミスの内容：return "home.html";と書いてしまう。

対策：@Controllerでテンプレートを返すときは拡張子を含めず、ファイル名だけを指定します。


return "home"; // 正しい書き方

③ HTMLの拡張子が間違っている

ミスの内容：home.htmやhome.textなど、間違った拡張子にしてしまう。

対策：テンプレートの拡張子は必ず.htmlにしましょう。

④ HTMLにThymeleafの名前空間を指定していない

ミスの内容：テンプレートファイルでth:textを使っているのに、xmlns:th="http://www.thymeleaf.org"を書いていない。

対策：テンプレートファイルの<html>タグに次のように記述してください。


<html xmlns:th="http://www.thymeleaf.org">

⑤ URLと`@GetMapping`のパスが一致していない

ミスの内容：ブラウザで/helloにアクセスしているが、コントローラは/welcomeになっている。

対策：アクセスURLは@GetMapping()に定義したパスと一致させましょう。

⑥ Javaファイルを実行していない

ミスの内容：HTMLだけ作ってJavaのアプリケーションを起動していない。

対策：PleiadesでDemoApplicationを右クリックし、「Javaアプリケーションとして実行」を選んでください。

これらのミスを避けることで、初心者でもスムーズにSpring Boot HTML 表示を行うことができるようになります。