【Doma2】保守で初見「%expandって何？」SQLの意味と格納場所を解説

システム保守対応で、
急に Java で作られた既存システムのコードを見ることになりました。

システム保守対応で、
急遽、Java で作られた既存システムのコードを見ることになりました。

普段は別の言語や別の構成を触ることが多いので、

「とりあえず SQL を確認しよう」
「どんなデータを取っているのか見れば何とかなるだろう」

くらいの気持ちでコードを追い始めたのですが、
そこで 最初の壁 にぶつかります。

SQL を開いたら、見慣れない記述が出てきた
そもそも Doma2 という ORM が使われていた
/*%expand*/ は何をしているのか？（結論）
Entity と expand の関係
なぜ select * を使わないのか？
1. select * の問題点
2. expand を使うと
ここで次の疑問「そもそも SQL はどこにある？」
Doma2 の SQL の格納場所
1. 具体例
2. 実際の SQL ファイルはこんな感じ
保守で最初に知っておくと楽なこと
まとめ
おわりに

SQL を開いたら、見慣れない記述が出てきた

SQL ファイルを開くと、こんな記述がありました。

select
  /*%expand*/*
from
  EMPLOYEE

……。

*%expand* って何？

select * っぽく見える
でもコメントが付いている
コメントなのに、消したら動かなそう

正直、初見では 「これ本当に SQL？」 となりました。

そもそも Doma2 という ORM が使われていた

調べていくと、このプロジェクトでは
Doma2 という Java 向け ORM が使われていることが分かりました。

Doma2 の特徴は、

SQL を Java コードに埋め込まない
.sql ファイルとして外に出す
SQL をほぼそのまま書ける

という、SQL 主導の設計です。

そして、その SQL の中で使われるのが、

/*%expand*/
``

のような Doma 独自の制御構文です。

/%expand/ は何をしているのか？（結論）

結論から書きます。

/*%expand*/ は、Entity に定義されているカラム一覧を
SELECT 句に展開するための命令

です。

つまり、この SQL は

select
  /*%expand*/*
from
  EMPLOYEE

見た目は select * に近いですが、
実際には DB の全カラムではありません。

Entity と expand の関係

例えば、次のような Entity があったとします。

@Entity
public class Employee {
    @Id
    @Column(name = "EMP_ID")
    Integer empId;

    @Column(name = "EMP_NAME")
    String empName;

    @Column(name = "DEPT_ID")
    Integer deptId;
}

この Entity を戻り値にする Dao メソッドに対して
先ほどの SQL が使われると、実行時には次のような SQL になります。

select
  EMP_ID,
  EMP_NAME,
  DEPT_ID
from
  EMPLOYEE

✅ Entity に定義されているカラムだけが明示的に SELECT される

これが expand の役割です。

なぜ select * を使わないのか？

保守目線だと、ここが一番重要です。

select * の問題点

テーブルにカラムが追加されると、意図せず取得される
Entity に存在しないカラムが混ざる
将来的な影響範囲が読みにくい

expand を使うと

Entity に定義されたものだけ取得
DB 側のカラム追加の影響を受けにくい
Entity を正として SQL を組み立てる

👉 保守性重視の設計だと分かります。

ここで次の疑問「そもそも SQL はどこにある？」

expand の意味が分かっても、
保守ではもう一つハマりがちです。

「Java のコードを見ても、SQL が見当たらない…」

Doma2 の SQL の格納場所

Doma2 では、SQL は Java コードの中には書きません。

src/main/resources 配下に、
Dao の構造に合わせて配置されます。

具体例

Dao

package com.example.dao;

@Dao
public interface EmployeeDao {

    @Select
    List<Employee>

SQL の場所

src/main/resources/
└── com/
    └── example/
        └── dao/
            └

✅ パッケージ名 + Dao名 + メソッド名.sql

これが Doma の基本ルールです。

実際の SQL ファイルはこんな感じ

select
  /*%expand*/*
from
  EMPLOYEE
where
  EMP

/*%expand*/ → Doma の制御構文
/* id */ → バインド変数

それ以外は ほぼ普通の SQL なので、
DB 側の知識があれば問題なく読めます。

保守で最初に知っておくと楽なこと

SQL は Java コード内にはない
resources 配下を探す
Dao のメソッド名.sql を探す
/*%expand*/ は「怪しい記法」ではない

これだけ分かると、
Doma2 のコードは一気に追いやすくなります。

まとめ

/*%expand*/ は Doma2 の SQL 制御構文
Entity に定義されたカラム一覧を SELECT 句に展開する
select * の代替だが、思想は別物
SQL は src/main/resources 配下にあり、Dao と対応している
保守で初見だと「何これ？」となるのは普通

おわりに

保守対応で突然出会った /*%expand*/* と
「SQL がどこにあるのか分からない問題」。

最初は戸惑いましたが、

Doma2 の思想
SQL の配置ルール

が分かると、
むしろ保守しやすい構成だと感じました。

同じように Doma 初見で詰まった人の
ちょっとした助けになれば幸いです。