リテラル変数コメントのドキュメントを追加

Author: nakamura-to

docs/sources/sql.rst

@@ -221,6 +221,51 @@ Dao インタフェースのメソッドと対応する SQL の例は次のと
   where
   salary = /* dto.getTaxedSalary() */1234
 
+リテラル変数コメント
+--------------------
+
+リテラル変数を示す式コメントを *リテラル変数* コメントと呼びます。
+リテラル変数は、 SQLのリテラルの形式に変換された後にSQLに埋め込まれます。
+リテラルの形式に変換とは、文字列型をシングルクォートで囲むなどを指します。
+この変換にはSQLインジェクション対策としてのエスケープ処理は含まれません。
+
+SQL インジェクションを防ぐため、リテラル変数の値にシングルクォテーションを含めることは禁止しています。
+
+リテラル変数は ``/*^～*/`` というブロックコメントで囲んで示します。
+リテラル変数の名前はDaoメソッドのパラメータ名に対応します。
+対応するパラメータの型は :doc:`basic` もしくは :doc:`domain` でなければいけません。
+リテラル変数コメントの直後にはテスト用データを指定する必要があります。
+ただし、テスト用データは実行時には使用されません。
+
+Dao インタフェースのメソッドと対応する SQL の例は次のとおりです。
+
+.. code-block:: java
+
+   Employee selectByCode(String code);
+
+.. code-block:: sql
+
+   select * from employee where code = /*^ code */'test'
+
+Dao の呼び出し例は次の通りです。
+
+.. code-block:: java
+
+  EmployeeDao dao = new EmployeeDaoImpl();
+  List<Employee> list = dao.selectByCode("abc");
+
+発行される SQL は次のようになります。
+
+.. code-block:: sql
+
+  select * from employee where code = 'abc'
+
+記法が異なることを除けば、使い方はバインド変数コメントと同様です。
+
+.. note::
+
+  リテラル変数コメントは、実行計画を固定するなどあえてバインド変数の使用を避けたい場合に利用できます。
+
 埋め込み変数コメント
 --------------------