はじめに (対象読者・この記事でわかること)

本記事は、Javaでウェブアプリケーション開発を始めたばかりのエンジニア、特にTERASOLUNA Server Framework for Java（Web版）のチュートリアルを試す際にエラーに遭遇した方を対象としています。
この記事を読むことで、以下のことができるようになります。

  • チュートリアル実行時に出る典型的なビルドエラーの原因を特定できる
  • エラーメッセージの意味と、環境依存の落とし穴を把握できる
  • 実際に手元の環境でエラーを解消し、サンプルアプリを正常に起動できる

執筆のきっかけは、社内研修で受講生が同様のエラーに悩んでいたことです。そこで、再現手順と解決策をまとめました。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • Java 11 以上の基本的な文法とビルドツール（Maven/Gradle）の使い方
  • Spring Boot の概念と、application.yml の設定方法
  • Git と GitHub の基本操作、リポジトリのクローン方法

TERASOLUNA Webフレームワークとは？ ― 背景と概要

TERASOLUNA Server Framework for Java（Web版）は、金融系システムで広く採用されている「業務標準化」フレームワークです。Spring Boot の上に独自のアーキテクチャ（レイヤード構造や共通ユーティリティ）を提供し、開発のスピードと品質を向上させます。公式が提供するチュートリアルは、以下の流れで構成されています。

  1. プロジェクトの生成（terasoluna-sample-webapp）
  2. Maven でのビルド（mvn clean package）
  3. ローカルサーバー起動（java -jar target/*.jar）
  4. ブラウザで /hello エンドポイントにアクセス

しかし、実際に手元で実行すると「Failed to resolve dependencies」や「ClassNotFoundException」といったエラーが頻出します。原因は大きく分けて次の三点です。

  • Java バージョンの不整合：TERASOLUNA は Java 11 以上を前提にしていますが、JDK8 が残っているとビルドが失敗します。
  • Maven リポジトリの設定ミス：settings.xml に企業内部リポジトリが優先され、外部の repo1.maven.org が参照できないケースがあります。
  • Spring Boot のバージョン衝突：チュートリアルは spring-boot 2.6.x 系を想定していますが、プロジェクトで 2.7.x がデフォルトになると、依存関係の解決が失敗します。

以下では、実際に遭遇したエラーメッセージとその対処法を具体的に示します。

チュートリアル実行時のエラー対処フロー

ステップ1 　環境の確認と JDK の統一

まずは、インストールされている JDK のバージョンを確認します。

Bash

$ java -version
openjdk version "1.8.0_322"

TERASOLUNA が要求する Java 11 以上に満たない場合、以下手順で JDK をインストールし、JAVA_HOME と PATH を更新します（Ubuntu の例）。

Bash

$ sudo apt update
$ sudo apt install openjdk-11-jdk
$ sudo update-alternatives --config java   # 11 を選択
$ export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
$ export PATH=$JAVA_HOME/bin:$PATH

java -version が 11.x 系に変わったことを確認したら、再度ビルドを試みます。

ステップ2 　Maven 設定の見直し

次に、Maven が正しいリポジトリを参照できているか確認します。~/.m2/settings.xml に企業プロキシやミラーレポジトリが設定されている場合は、一時的にコメントアウトし、公式リポジトリだけを利用します。

Xml

<!--
<mirrors>
    <mirror>
        <id>company-mirror</id>
        <mirrorOf>*</mirrorOf>
        <url>http://repo.company.local/maven2</url>
    </mirror>
</mirrors>
-->

設定を保存したら、ローカルリポジトリをクリアしてから再度依存関係を取得します。

Bash

$ mvn dependency:purge-local-repository
$ mvn clean install -U

この操作で Failed to resolve dependencies が消えるはずです。

ステップ3 　Spring Boot バージョンの固定

pom.xml の spring-boot-starter-parent バージョンが想定外の場合は、明示的に 2.6.12 などチュートリアルに合わせたバージョンに書き換えます。

Xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6.12</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

バージョンを固定したら、再度ビルドします。

Bash

$ mvn clean package

エラーが解消し、target ディレクトリに *.jar が生成されたら成功です。

ハマった点やエラー解決

実装中に特に時間がかかったポイントは以下です。

発生したエラー 原因 当初の対策 最終的な解決策
java.lang.NoClassDefFoundError: org/springframework/boot/SpringApplication Spring Boot バージョン不一致 mvn clean install だけ実行 pom.xml のバージョン固定と mvn dependency:purge-local-repository
Failed to resolve dependencies: Could not find artifact com.example:terasoluna-web-common 社内ミラーが優先され外部リポジトリが遮断 プロキシ設定の見直し settings.xml のミラー設定をコメントアウトし、-U オプションで強制アップデート
Unsupported major.minor version 52.0 JDK8 でコンパイルされたクラスが実行時にロードされた JDK8 のまま実行 JDK11 に切り替え、JAVA_HOME を再設定

解決策のまとめ

上記の三つのステップ（JDKの統一、Maven 設定の見直し、Spring Boot バージョン固定）を順に実施することで、TERASOLUNA の公式チュートリアルはローカル環境でも問題なくビルド・起動できます。特に「Maven のミラーレポジトリ設定」は企業環境で頻出する落とし穴なので、デバッグ時には必ず確認しましょう。

まとめ

本記事では、TERASOLUNA Server Framework for Java（Web版）チュートリアル実行時に遭遇したビルドエラーの原因を体系的に分析し、具体的な解決手順を示しました。

  • JDK のバージョンを Java 11 以上に統一し、環境変数を正しく設定することが最重要。
  • Maven の設定ファイルを見直し、公式リポジトリを確実に参照させることで依存関係の取得失敗を回避。
  • Spring Boot のバージョンをチュートリアルに合わせて固定し、バージョン衝突を防止する。

この記事を通して、読者はエラーの根本原因を迅速に特定し、開発環境を整えることでスムーズにサンプルアプリを動かすことができるようになります。今後は、実際にカスタマイズした業務アプリへの拡張手順や、CI/CD パイプラインへの組み込みについても執筆予定です。

参考資料