markdown

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

この記事は、Spring Frameworkを使った業務系Webアプリケーション開発に興味があるJavaエンジニア、特にTERASOLUNAを使った開発を始めたいが環境構築で躓いている方向けに書きました。
TERASOLUNA Server Framework for Java（以下、TERASOLUNA）は、NTTデータが提供するSpringベースのフレームワークで、プロジェクト作成からデプロイまでのベストプラクティスが詰まった強力なツールです。
本記事を読むと、2025年1月時点での最新版（5.10.0）を使った「とにかく動く開発環境」の作り方が丸ごとわかります。既存のチュートリアルが古すぎて動かない、Mavenアーキタイプが見つからない、Tomcatのバージョンが合わない…そんな悩みを解消できます。

前提知識

  • Java 17の基本文法とオブジェクト指向の概念
  • MavenまたはGradleのCLI操作（mvn archetype:generateなど）
  • Spring BootのDI／AOPのアノテーションを目で追えるレベル
  • ローカルにDocker Desktopがインストール済みであること（Podman可）

TERASOLUNA最新版の魅力と注意点

2025年1月にリリースされたTERASOLUNA 5.10.0は、Spring Boot 3.2に対応し、仮想スレッド（Project Loom）やAOTネイティブイメージ生成を実験的にサポートしました。
従来のSpring MVCに加え、Spring WebFluxの共存が可能になり、リアクティブな実装を段階的に導入できます。
ただし、Java 8～11時代の古いチュートリアルがネット上に多く、MavenアーキタイプのgroupId／artifactIdが変わっているため、コピペでそのまま動かすと「アーキタイプが見つからない」エラーに遭遇します。
本稿では、これらの最新情報を踏まえた手順を解説します。

最新版TERASOLUNA開発環境を0から構築する

ステップ1：Java 17とMaven 3.9の準備

まず、TERASOLUNA 5.10.0が要求するJava 17以降をインストールします。
SDKMAN!を使うと複数バージョンの切り替えが楽です。

Bash

# SDKMAN!が未インストールなら
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# Java 17とMaven 3.9をインストール
sdk install java 17.0.10-tem
sdk install maven 3.9.6

# バージョン確認
java -version
mvn -version

次に、TERASOLUNAが公開している最新のMavenアーキタイプカタログを~/.m2/archetype-catalog.xmlに追記します。

Xml

<archetype-catalog>
  <archetypes>
    <archetype>
      <groupId>jp.terasoluna.server</groupId>
      <artifactId>terasoluna-server-web-blank-archetype</artifactId>
      <version>5.10.0</version>
      <repository>https://repo.terasoluna.org/maven2</repository>
    </archetype>
  </archetypes>
</archetype-catalog>

ステップ2：プロジェクト生成と依存解決

カタログを読み込んでブランクプロジェクトを生成します。
対話式でgroupIdなどを聞かれますが、チュートリアル用ならcom.example.todoなど適当に決めてEnter連打でOKです。

Bash

mvn archetype:generate \
  -DarchetypeCatalog=local \
  -DarchetypeGroupId=jp.terasoluna.server \
  -DarchetypeArtifactId=terasoluna-server-web-blank-archetype \
  -DarchetypeVersion=5.10.0

生成後、pom.xmlを開いてSpring Bootのバージョンが3.2.1になっていることを確認します。
ここで、社内リポジトリ経由で依存が解決できない場合は、~/.m2/settings.xmlにTERASOLUNAリポジトリを明示的に追加します。

Xml

<mirrors>
  <mirror>
    <id>terasoluna-central</id>
    <mirrorOf>central</mirrorOf>
    <url>https://repo.terasoluna.org/maven2</url>
  </mirror>
</mirrors>

ステップ3：データベースとIDE設定

TERASOLUNA 5.10.0のチュートリアルでは、デフォルトでH2 Databaseを使いますが、DockerでPostgreSQL 15を立ち上げて本番に近い構成にします。

Bash

docker run -d --name todo-postgres \
  -e POSTGRES_DB=todoapp \
  -e POSTGRES_USER=todo \
  -e POSTGRES_PASSWORD=todopass \
  -p 5432:5432 \
  postgres:15-alpine

src/main/resources/META-INF/spring/todo-infra.propertiesを以下のように書き換えます。

Properties

database.url=jdbc:postgresql://localhost:5432/todoapp
database.username=todo
database.password=todopass

IntelliJ IDEAを使う場合、標準のSpring Bootプラグインに加えて「TERASOLUNA Helper」プラグインをインストールすると、独自のアノテーション補完が効くようになります。VS Codeの場合は、Extension Pack for Javaに加えて「Spring Boot Extension Pack」を入れておけば十分です。

ハマった点：「Whitelabel Error Page」が出てスタイルが効かない

ブラウザでhttp://localhost:8080/todoにアクセスすると、真っ白なWhitelabel Error Pageが表示されることがあります。
これは、Spring Boot 3.xで静的リソースの扱いが変わったためで、src/main/webapp配下のリソースが/static/にマッピングされないことが原因です。

解決策

src/main/java/com/example/todo/app/welcome/WelcomeController.javaの@Controllerを@ControllerAdviceに変更するのではなく、まずapplication.propertiesに以下を追加します。

Properties

spring.web.resources.static-locations=classpath:/static/,classpath:/META-INF/resources/
spring.mvc.view.prefix=/WEB-INF/views/
spring.mvc.view.suffix=.jsp

次に、pom.xmlのspring-boot-starter-web依存に以下を追加します。

Xml

<dependency>
  <groupId>org.apache.tomcat.embed</groupId>
  <artifactId>tomcat-embed-jasper</artifactId>
  <scope>provided</scope>
</dependency>

これでJSPが正しくレンダリングされ、スタイルシートも/static/css/から読み込まれるようになります。

まとめ

本記事では、TERASOLUNA Server Framework for Java 5.10.0を使った最新の開発環境構築手順を解説しました。

  • 最新のアーキタイプが公開されているTERASOLUNAリポジトリをsettings.xmlに追加する
  • Java 17とMaven 3.9でarchetype:generateを実行し、プロジェクトを生成する
  • DockerでPostgreSQLを立ち上げ、プロパティファイルを書き換える
  • Spring Boot 3.xで静的リソースが読めない問題はstatic-locationsを明示することで解決する

この記事を通して、2025年でも通用する「とにかく動く」TERASOLUNA環境が手に入り、次のステップであるRESTful化やJPA移行、仮想スレッド対応などにスムーズに進めることができます。
次回は、生成されたCRUDサンプルをベースに、リアクティブな非同期処理を組み込む方法を紹介します。

参考資料