web プロジェクトの設定⚓︎

web プロジェクトで必要な設定を解説します。

依存ライブラリの設定⚓︎

web プロジェクトで利用を推奨するライブラリは以下の通りです。

spring-boot-starter-webmvc：Spring MVC を使用して Web アプリケーションを構築するためのスターター
spring-boot-starter-actuator: ヘルスチェックを含めたアプリケーション監視・管理機能を構築するためのスターター
spring-boot-starter-log4j2: Spring Boot アプリケーションで Apache Log4j 2 （以降 log4j2 ）を使用するためのスターター
springdoc-openapi-starter-webmvc-ui：Spring Web MVC アプリケーション向けの、 OpenAPI 形式の API ドキュメントを生成するためのライブラリ
h2：テストやローカル実行で利用する組み込みの H2 データベース
spring-boot-starter-webmvc-test：Spring MVC アプリケーションをテストするためのスターター

上記のライブラリを依存ライブラリとして、以下のように build.gradle の dependencies ブロックに追加します。

web/build.gradle
dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-webmvc'
  implementation 'org.springframework.boot:spring-boot-starter-actuator'
  implementation 'org.springframework.boot:spring-boot-starter-log4j2'
  implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:x.x.x'
  implementation 'com.h2database:h2'

  testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
}

各依存ライブラリのバージョンの参照先

SpringDoc OpenAPI Starter WebMVC UI

依存プロジェクトの設定⚓︎

web プロジェクトは application-core 、 infrastructure 、 system-common を参照しています。そのため、 build.gradle で以下のように他のプロジェクトを依存関係に含めます。

web/build.gradle
dependencies {
  implementation project(':application-core')
  implementation project(':infrastructure')
  implementation project(':system-common')
}

Spring Boot の設定⚓︎

web プロジェクトに関する Spring Boot のプロパティ等を設定します。 web プロジェクトの src/main/resource 以下に application.properties もしくは application.yaml ファイルを作成して行います。設定できる項目については、以下を参照してください。

設定項目は多岐に渡るため、一般的に設定する項目について例示します。

データソース
- spring.datasource.hikari.driver-class-name： JDBC ドライバーの完全修飾名
- spring.datasource.hikari.url：データベースの JDBC URL
- spring.datasource.hikari.username：データベースのログインユーザー名
- spring.datasource.hikari.password：データベースのログインパスワード
データベース初期化設定
- spring.sql.init.mode：データベースの初期化有無
ロギング
- logging.xxx でロギングの各種設定が可能
MyBatis の設定
- mybatis.configuration.xxx で MyBatis の設定を記述可能
ヘルスチェック機能を含む Spring Boot Actuator に関する設定
- management.endpoints.web.base-path: エンドポイントパスのカスタマイズ
- management.endpoint.health.group.xxx.include: さまざまなサーバーの監視目的に合わせたヘルスチェックのプローブを作成可能

application.properties の設定例

開発環境での設定例（ H2 Database を使用する場合）
spring.datasource.hikari.driver-class-name=org.h2.Driver
spring.datasource.hikari.url=jdbc:h2:mem:データベースの名前
spring.datasource.hikari.username=データベースのログインユーザー名
spring.datasource.hikari.password=データベースのログインパスワード
spring.sql.init.mode=embedded
logging.level.web=DEBUG

本番環境での設定例（ PostgreSQL を使用する場合）
spring.datasource.hikari.driver-class-name=org.postgresql.Driver
spring.datasource.hikari.url=jdbc:postgresql://localhost:5432/データベースの名前
spring.datasource.hikari.username=データベースのログインユーザー名
spring.datasource.hikari.password=データベースのログインパスワード
spring.sql.init.mode=never

ロギングライブラリの除外設定⚓︎

依存関係に記載している org.springframework.boot:spring-boot-starter-webmvc ライブラリは、デフォルトで Logback 用のライブラリである org.springframework.boot:spring-boot-starter-logging が推移的依存で追加されます。

AlesInfiny Maia OSS Edition では、ロギングライブラリとして log4j2 を使用します。そのため、以下のようにデフォルトのロギングライブラリを依存関係から除外する設定を記述します。

web/build.gradle
configurations {
 all {
  exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging'
 }
}

不要な設定の削除⚓︎

こちらで、使用するテストフレームワークを集約管理しているため、 test タスクに関するブロックを削除します。

web/build.gradle
tasks.named('test') {
  useJUnitPlatform()
}

ログの設定⚓︎

src/main/resource に log4j2.xml ファイルを配置しログの設定を記述します。以下は、ログの設定例です。

log4j2.xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="error">

  <Appenders>
    <Console name="console" Target="SYSTEM_OUT">
      <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %c %-5p %pid %t %m%n" />
    </Console>

    <Console name="application.log.appender" Target="SYSTEM_OUT">
        <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %pid %t %m%n"/>
    </Console>
  </Appenders>

  <Loggers>
    <Logger name="application.log" level="debug" additivity="false">
        <AppenderRef ref="application.log.appender" />
    </Logger>

    <Root level="info">
        <AppenderRef ref="console" />
    </Root>
  </Loggers>

</Configuration>

log4j2.xml のタグの構成要素は以下の通りです。

Appenders

ログの出力先を指定します。ログイベントをどのリソース（コンソール、ファイル、データベースなど）に送信するかを決定します。
Loggers

ログのエントリーポイントを指定します。この設定では、どのレベルのメッセージをログに記録するかや、 Appenders のどの要素にメッセージを送信するかなどを指定します。

その他の詳細な設定については、公式ページを確認してください。

OpenAPI 仕様書の出力設定⚓︎

OpenAPI 仕様書のファイルがビルド時に出力されるようプロジェクトファイルを設定します。以下に、 application.properties と build.gradle への設定内容を例示します。 SpringDoc OpenAPI Gradle Plugin のバージョンはこちらを参照してください。

web/src/main/resource/application.properties
# springdoc-openapi用のURLを指定
springdoc.api-docs.path=/api-docs

web/build.gradle
plugins {
  // OpenAPI のプラグインを追加する。
  id 'org.springdoc.openapi-gradle-plugin' version 'x.x.x'
}

// OpenAPI 仕様書出力の作業ディレクトリを指定する。
afterEvaluate {
  tasks.named("forkedSpringBootRun") {
  workingDir("$rootDir/api-docs")
  }
}
// OpenAPI 仕様書の出力先を指定する。
openApi {
  apiDocsUrl.set("http://localhost:8080/api-docs")
  outputDir.set(file("$rootDir/api-docs"))
  outputFileName.set("api-specification.json")
}
// ビルド時に OpenAPI 仕様書の出力を行うよう設定する。
build.dependsOn("generateOpenApiDocs")

ここまでを実行した後に、適切にビルドが実行できるかを確認します。ターミナルを用いてルートプロジェクト直下で以下を実行してください。

web プロジェクトのビルド
./gradlew web:build

ここまでの手順を実行した際の web/build.gradle の例

web/build.gradle
plugins {
  id 'java'
  id 'org.springframework.boot' version 'x.x.x'
  id 'io.spring.dependency-management' version 'x.x.x'
  // OpenAPI のプラグインを追加する。
  id 'org.springdoc.openapi-gradle-plugin' version 'x.x.x'
}

group = 'プロジェクトのグループ名'
version = 'x.x.x-SNAPSHOT'
description = 'プロジェクトの説明'

java {
  toolchain {
    languageVersion = JavaLanguageVersion.of(x)
  }
}

repositories {
  mavenCentral()
}

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-webmvc'
  implementation 'org.springframework.boot:spring-boot-starter-actuator'
  implementation 'org.springframework.boot:spring-boot-starter-log4j2'
  implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:x.x.x'
  implementation 'com.h2database:h2'

  implementation project(':application-core')
  implementation project(':infrastructure')
  implementation project(':system-common')

  testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
  // その他、プロジェクトに必要な依存ライブラリは任意で追加してください。
}

configurations {
  all {
    exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging'
  }
}


// OpenAPI 仕様書出力の作業ディレクトリを指定する。
afterEvaluate {
  tasks.named("forkedSpringBootRun") {
    workingDir("$rootDir/api-docs")
  }
}

// OpenAPI 仕様書の出力先を指定する。
openApi {
  apiDocsUrl.set("http://localhost:8080/api-docs")
  outputDir.set(file("$rootDir/api-docs"))
  outputFileName.set("api-specification.json")
}

// ビルド時に OpenAPI 仕様書の出力を行うよう設定する。
build.dependsOn("generateOpenApiDocs")

CORS （クロスオリジンリソース共有）環境の設定⚓︎

Web API を公開するオリジンと、呼び出し元となるクライアントスクリプトを公開するオリジンが異なる場合（クロスオリジン）の設定は、こちらを参照してください。

メッセージ読み込みに関する設定⚓︎

他サブプロジェクトで管理されているメッセージを読み込む場合の設定は、こちらを参照してください。

H2 Database をサーバーモードで起動する設定⚓︎

開発環境において、 H2 Database をサーバーモードで起動する設定方法を解説します。

本設定は、開発環境で使用するデータベースが H2 Database であり、同一のデータベースへ同時にアクセスするアプリケーションが存在する場合に行います。同一のデータベースへ同時にアクセスするアプリケーションの例としては、サンプルアプリの Dressca のように、コンシューマー向けの EC サイトとその EC サイトで売られる商品を管理するアプリが挙げられます。

H2 Database には、 H2 Console というデータベース管理ツールがあります。 H2 Console のスタンドアロン版からアプリケーションが使用しているデータベースを操作する場合、アプリケーションと H2 Console が同じデータベースへ同時に接続できる必要があります。組み込みモードでは別プロセスから同じデータベースへ接続できないため、この場合も H2 Database はサーバーモードで起動する必要があります。

設定の対象は H2 Database をサーバーモードで起動するクラスと、開発環境におけるアプリケーションの設定などを行う application-dev.properties です。以下がそれぞれの設定例です。

H2 Database をサーバーモードで起動するクラスの例

定義するクラスには、 @Component と @Profile アノテーションを付与し、開発環境でのみ DI コンテナに Bean 登録されるように設定します。クラスには H2 Database を起動する処理と停止する処理をそれぞれ実装します。起動する処理は、アプリケーションが起動したタイミングで H2 Database を起動させるためにコンストラクタ内で行います。停止する処理は、アプリケーションが停止したタイミングで、 H2 Database を停止させるために @PreDestroy アノテーションを付与したメソッド内で行います。

/**
 * 開発環境で H2 Database をサーバーモードで立ち上げるためのクラスです。
 */
@Component
@Profile("local")
public class H2ServerLauncher {

  private Server tcpServer;
  private final Logger apLog = LoggerFactory.getLogger(SystemPropertyConstants.APPLICATION_LOG_LOGGER);

  /**
   * {@link H2ServerLauncher} クラスのインスタンスを初期化し、 H2 Database をサーバーモードで起動します。
   */
  public H2ServerLauncher() {
    try {
      this.tcpServer = Server.createTcpServer("-tcpPort", "9092", "-ifNotExists").start();
    } catch (SQLException e) {
      apLog.info("H2 Database は既にサーバーモードで起動しています。");
    }
  }

  /**
   * インスタンスを破棄する際に H2 Database を停止します。
   */
  @PreDestroy
  public void stop() {
    if (this.tcpServer != null) {
      this.tcpServer.stop();
    }
  }
}

application-dev.properties の例

spring.datasource.hikari.driver-class-name=org.h2.Driver

# DBをサーバーモードで起動する場合の接続先情報
spring.datasource.hikari.jdbc-url=jdbc:h2:tcp://localhost:9092/mem:データベースの名前
# 起動した H2 Database にデータを流し込む設定
spring.sql.init.mode=always

spring.datasource.hikari.username=
spring.datasource.hikari.password=