This is a cache of http://dbflute.seasar.org/ja/lastaflute/howto/action/larestfulapi.html. It is a snapshot of the page at 2024-11-13T01:04:22.365+0000.
規約縛りのRESTful API | LastaFlute

規約縛りのRESTful API

LastaFlute
素早さのJSON API
開拓の例外ハンドリング
LastaFluteのタイプセーフProperties

LastaでのRESTful API

LastaFlute-1.2.1 よりサポートしています。

※合わせて、LastaMeta-0.5.1, UTFlute-0.9.3 以上を利用しましょう

ざっくり概要

@RestfulActionアノテーション付けて、LastaFluteの規約に沿ってメソッド定義していきます。

前提となる設定
ActionAdjustmentProviderでRestfulRouterを設定
Action
Actionクラスに@RestfulActionアノテーションを付ける
HTTP Method
Executeメソッドにget$index()とHTTP Methodを付ける
リストと一件
リストと一件だけはOverloadメソッドで、どちらもget$index()
ネストリソース
リソース名をクラス名でつなげて、パスパラメーターは順番で引数に
ハイフンつなぎ
@RestfulActionのhyphenate属性で指定
EventSuffix
@RestfulActionのallowEventSuffix=trueにしてget$sea()
HTTP Status
規約ベースやアノテーション属性指定などいろいろ

ざっくりExample

ひとまず、Actionクラスはこのような感じになります。

Exampleプロジェクトである lastaflute-example-maihamaサービスの maihama-showbaseアプリにてExampleがありますので、そちらもご覧ください。

maihama-showbase - ProductsAction.java | Github
maihama-showbase - ProductsPurchasesAction.java | Github
e.g. RESTful action for /products/ @Java
@RestfulAction
public class ProductsAction extends ShowbaseBaseAction {

    @Execute
    public JsonResponse<List<ProductsResult>> get$index(ProductsSearchForm form) {
    ...
    @Execute
    public JsonResponse<ProductsResult> get$index(Integer productId) {
    ...
    @Execute
    public JsonResponse<Void> post$index(ProductsPostBody body) {
    ...

RESTful API の Action

RestfulRouterが設定されていることが前提です。(デフォルト設定では動作しません)

this - RestfulRouterの設定

@RestfulActionを付与

Actionには、@RestfulActionアノテーションを付けます。 

e.g. action with @RestfulAction annotation for /products/ @Java
@RestfulAction
public class ProductsAction extends ShowbaseBaseAction {

@ExecuteメソッドにはHTTP Methodを付与

メソッド名の先頭で HTTP Method を表現します。小文字で付けて $ (だらー) で区切ります。

LastaFlute の Action - HTTP Method Restriction

$以降の業務的なメソッド名は(基本的に)index固定です。(ただし特殊利用方法あり、後述) 

e.g. action execute with HTTP method for /products/ @Java
@Execute
public JsonResponse<ProductsResult> get$index(Integer productId) {
...
@Execute
public JsonResponse<Void> post$index(ProductsPostBody body) {
...

リストと一件だけはOverloadメソッドで

通常LastaFluteの@ExecuteメソッドではOverloadはできませんが、RESTfulのリスト検索と一件検索のメソッドだけは、Overloadができます。 つまり、get$index()を二つ定義することができます。 

e.g. you can use overload method for get$index() /products/ @Java
@Execute
public JsonResponse<List<ProductsResult>> get$index(ProductsSearchForm form) {
...
@Execute
public JsonResponse<ProductsResult> get$index(Integer productId) {
...

ネストリソースは？ e.g. /products/1/purchases/2/

ネストリソースのときは、リソース名の途中に挟み込まれるパスパラメーターを気にせず、リソース名でクラス名を構築します。 そして、パスパラメーターは引数で左から順番に定義していきます。

Actionクラス名
ProductsPurchasesAction
Executeメソッド
get$index(Integer productId, Long purchaseId)
e.g. you can handle nest resources /products/1/purchases/2/ @Java
@RestfulAction
public class ProductsPurchasesAction extends ShowbaseBaseAction {

    @Execute
    public JsonResponse<List<ProductsPurchasesResult>>
            get$index(Integer productId, ProductsPurchasesSearchForm form) {
    ...
    @Execute
    public JsonResponse<ProductsPurchasesResult>
            get$index(Integer productId, Long purchasesId) {
    ...

つまり、通常のActionでの /products/purchases/1/2/ に相当する定義をします。

ActionのExampleコード

ルートリソースのExample e.g. /products/

例えば、/products/ というリソースがひとつの場合のActionの実装Exampleです。 

e.g. action for root resource e.g. /products/ @Java
@RestfulAction
public class ProductsAction extends ShowbaseBaseAction {

    // ===================================================================================
    //                                                                           Attribute
    //                                                                           =========
    @Resource
    private ProductsCrudAssist productsCrudAssist;
    @Resource
    private ProductsMappingAssist productsMappingAssist;

    // ===================================================================================
    //                                                                             Execute
    //                                                                             =======
    @Execute
    public JsonResponse<List<ProductsResult>> get$index(ProductsListForm form) {
        validate(form, messages -> {});
        List<Product> productList = productsCrudAssist.selectProductList(form);
        List<ProductsResult> listResult = productsMappingAssist.mappingToListResult(productList);
        return asJson(listResult);
    }

    @Execute
    public JsonResponse<ProductsResult> get$index(Integer productId) {
        Product product = productsCrudAssist.selectProductById(productId);
        ProductsResult singleResult = productsMappingAssist.mappingToSingleResult(product);
        return asJson(singleResult);
    }

    @Execute
    public JsonResponse<Void> post$index(ProductsPostBody body) {
        validate(body, messages -> {});
        ...
        return JsonResponse.asEmptyBody();
    }

    @Execute
    public JsonResponse<Void> put$index(Integer productId, ProductsPutBody body) {
        validate(body, messages -> {});
        ...
        return JsonResponse.asEmptyBody();
    }

    @Execute
    public JsonResponse<Void> delete$index(Integer productId) {
        ...
        return JsonResponse.asEmptyBody();
    }

    ...
}

ネストリソースのExample e.g. /products/1/purchases/

例えば、/products/1/purchases/ というリソースがふたつの場合のActionの実装Exampleです。 

e.g. action for nest resource /products/1/purchases/ @Java
@RestfulAction
public class ProductsPurchasesAction extends ShowbaseBaseAction {

    // ===================================================================================
    //                                                                           Attribute
    //                                                                           =========
    @Resource
    private ProductsPurchasesCrudAssist productsPurchasesCrudAssist;
    @Resource
    private ProductsPurchasesMappingAssist productsPurchasesMappingAssist;

    // ===================================================================================
    //                                                                             Execute
    //                                                                             =======
    @Execute
    public JsonResponse<List<ProductsPurchasesResult>>
            get$index(Integer productId, ProductsPurchasesSearchForm form) {
    ...
    @Execute
    public JsonResponse<ProductsPurchasesResult>
            get$index(Integer productId, Long purchasesId) {
    ...
  • メソッド名の前の改行は、単にドキュメントのデザインの都合上、横長だと見づらいので入れてるだけ

ハイフンつなぎリソース名

通常のLastaFluteのActionではハイフンつなぎの単語をサポートしていませんが、 RESTful APIではurlの形式に縛りがあるため、ハイフンを使いたくなる場面が増えると想定し、サポートしています。

hyphenate属性でハイフンつなぎを設定

例えば、/ballet-dancers/1/studios/2/ のとき、@RestfulActionのhyphenate属性にてハイフンでつないだときの表現である ballet-dancers を設定します。Actionのクラス名では、ハイフン区切りをキャメルケースにします。 

e.g. action for hyphenated resource /ballet-dancers/1/studios/2/ @Java
@RestfulAction(hyphenate="ballet-dancers")
public class BalletDancersStudiosAction extends ShowbaseBaseAction {

パッケージは、普通のLastaFluteの規約通り、Actionのクラス名にそのまま相当する構成にします。 

e.g. package for hyphenated resource /ballet-dancers/1/studios/2/ @Directory
app.web
 |-ballet
 |  |-dancers
 |  |  |-studios
 |  |  |  |-BalletDancersStudiosAction.java

ハイフンつなぎが複数ある場合

例えば、/ballet-dancers/1/favorite-studios/2/ のとき、hyphenate属性で二つ設定します。 

e.g. action for hyphenated resource /ballet-dancers/1/favorite-studios/2/ @Java
@RestfulAction(hyphenate={"ballet-dancers", "favorite-studios"})
public class BalletDancersFavoriteStudiosAction extends ShowbaseBaseAction {

一文字のハイフンつなぎの場合

例えば、/a-dancers/1/b-studios/2/ のとき、Actionのクラス名で大文字が連続します。 

e.g. action for hyphenated resource /a-dancers/1/b-studios/2/ @Java
@RestfulAction(hyphenate={"a-dancers", "b-studios"})
public class ADancersBStudiosAction extends ShowbaseBaseAction {

同じ組み合わせがもう一度登場する場合

例えば、/ballet-dancers/1/favorite-ballet-dancers/2/ のときでも、それぞれ設定します。 

e.g. action for hyphenated resource /ballet-dancers/1/favorite-ballet-dancers/2/ @Java
@RestfulAction(hyphenate={"ballet-dancers", "favorite-ballet-dancers"})
public class BalletDancersFavoriteBalletDancersAction extends ShowbaseBaseAction {

hyphenate属性の検証

Action生成時に、LastaFlute内でhyphenate属性が厳しく検証されます。

  • hyphenate属性で利用できない文字 (e.g. 小文字半角英数ハイフン以外) があれば例外
  • hyphenate属性で指定したリソース名が、クラス名になかったら例外

EventSuffixでの回避

デフォルトでは[HTTP Method]$index()のみ

基本的に、ActionのExecuteメソッドは、必ず [HTTP Method]$index() で固定です。$より右はindex以外の名前を使うことはできません。

イベントごとのジレンマ

ただ、RESTfulの思想からは外れても(外れるのかどうか厳密にはわからないですが)、同じ HTTP Method の処理でも、どうしても業務で発生するイベントごとにメソッドを分けたくなった場合...例えば会員テーブルに対してイベントごとに検索条件も検索結果も大きく変わるような場合、get$index(Form) に集約すると巨大な最小公倍数のFormやJsonResultになってしまうかもしれません。 (パフォーマンスもそうですし、わかりやすさの面からメンテナンス性の低下が想定されます)

MaihamaDB

もしくは、以下のようにイベントごとに更新する項目が違うような場合、patch$index(Body) に集約すると巨大な最小公倍数のBodyになってしまうかもしれません。

  • 正式会員になったとき、正式会員日時に現在日時を入れて会員ステータスを正式会員にする
  • 会員情報編集の生年月日の入力で、生年月日に値が入る

put$index(body)で単に受け取ったままを更新するだけという風にしてイベントを意識しないやり方もありますが、それだとDBの業務ルールを呼び出しサービスに依存させてしまうことになるので、それが許容できなければなりません。 (DBのルールを散財させるとDB変更がしづらくなると想定されます)

EventSuffixでの回避

それぞれ、集約したままでも色々な回避策はあります。 検索に関しては、取捨選択するようなパラメーターを受け取るようにしたり、諦めたりなど。 更新に関しては、イベントを表現するパラメーターを受け取るようにしたり、そもそもそういうジレンマが発生しないようなDB設計をしたりなど。

ただもし、urlを分けてメソッドも分けることで解決するのであれば、@RestfulAction の allowEventSuffix を true にすることで、get$sea() や get$land() というようなメソッドを作ることができます。

get$index(form)
/products/ (そのまま)
get$sea(form)
/products/sea/
get$land(form)
/products/land/
get$index(Integer)
/products/1/ (そのまま)
get$sea(Integer)
/products/1/sea/
get$land(Integer)
/products/1/land/
e.g. action for nest resource /products/1/my-purchases/ @Java
@RestfulAction(allowEventSuffix=true)
public class ProductsAction extends ShowbaseBaseAction {

    @Execute
    public JsonResponse<List<ProductsResult>> get$sea(ProductsSeaSearchForm form) {
    ...

    @Execute
    public JsonResponse<List<ProductsResult>> get$land(ProductsLandSearchForm form) {
    ...

さきほどの、会員の更新の例だと...

patch$formalized(body)
/members/1/formalized/ (正式会員になったときの更新)
patch$birthdate(body)
/members/1/birthdate/ (生年月日情報の更新)

というように分けることになります。名前や粒度をどうするかはアプリでの慣習次第です。

EventSuffixが使えるかはrouter次第

ただし、この機能は RestfulRouter の実装に依存します。選択する Router によっては動作しません。 例えば、文字列のパスパラメーターを許容する Router だと、EventSuffixがパスパタメーターと区別が付かなくなり動作しません。 なので、パスパラメーターは必ず数値であることが前提になります。

RESTのCRUD枠にユースケースを当てはめてるのか？

そもそも、そのJSON APIは、CRUD要件のものなのか？ユースケース要件のものなのか？

例えば、"会員を登録する" というユースケースがあって、DB的には "会員" に加え "会員セキュリティ" と "会員サービス" などの関連テーブルinsertしないといけない場合、POST /members/ では何をするのか？

呼び出しサービスで、会員と会員セキュリティと会員サービスとリソースごとにリクエストを飛ばし、DBのトランザクションは諦めるか？自前でロールバックする仕組みを導入するか？ などの工夫をするのであれば、その JSON API はCRUD要件のものと言え、RESTのCRUDにマッチしやすいので特に迷うことは少ないでしょう。 ただもちろん、その手前のレイヤにてユースケースやDBルールを解決するサービスが必要です。 (その呼び出しサービスの方で、ごちゃごちゃしないように注意を)

一方で、POST /members/ を会員登録とみなし、その中でそのユースケースに関するDBの処理をすべて行うのであれば、その JSON API はユースケース要件のものと言え、RESTのCRUD枠にユースケースに当てはめていると言えるでしょう。

その場合は、イベントごとのジレンマが発生しやすいと想定しています。いびつにならないように、気をつけて実装ポリシーを決めていきましょう。 jfluteとしては、引数リモコンパターンのようなAPIにならないことを望みます。

メンテ不能の強者、引数リモコンパターン | jfluteの日記

リソースはDBそのもの？DBインターフェース？

先ほど、正式会員になったときの更新、membersのPATCHではなく、formalizeds(造語)のPOSTとも言えるかもしれません。

リソースがDB構造が一致 (リソースはDBそのもの)
会員テーブルの更新だから、あくまで PATCH /members/1/(formalized/) で更新
でもDB変更で MEMBER_FORMALIZED というテーブルに切り出されたらAPIも変更する？
リソースはDB構造と似てるだけ (リソースはDBインターフェース)
内部的には会員テーブルの更新だけど、外向けには formalizeds というリソースがあるつもりで POST /members/1/formalizeds/ で登録(更新)
DB変更で切り出されてもAPIに影響なし。ただし、DBの構造に似てるとはいえ、リソース設計は独立してしっかりやる必要あり

この辺のニュアンスも、イベントごとのジレンマに影響しそうですね。

DBFluteとしては、あまりDB変更がしづらくなる構成はオススメではありません。

HTTP Statusの設定

成功系のHTTP Statusの設定方法

まず、デフォルトでは、成功系はすべて200です。

例えば、POSTの場合は201で、PUTやDELETEなどで戻りがない場合に204を戻したいなら...

規約ベース方式
ActionHookでExecuteメソッドの構造から自動で判別するように
アノテーション方式
Executeアノテーションで successHttpStatus属性を指定

規約ベース方式

規約ベース方式なら、TypicalStructuredSuccessHttpStatusHandlerというクラスが用意されています。これは ActionHook の hookFinally() で使うと良いでしょう。(もし、アプリ要件に合うのであれば) 

e.g. TypicalStructuredSuccessHttpStatusHandler in hookFinally() @Java
@Override
public void hookFinally(ActionRuntime runtime) {
    super.hookFinally(runtime);

    // for RESTful HTTP status as conventional way e.g. POST:201, DELETE(no return):204
    new TypicalStructuredSuccessHttpStatusHandler().reflectHttpStatusIfNeeds(runtime);
}

組み込みのHandlerが合わなければ、自前で似たような実装をすると良いでしょう。

ただ、SwaggerUIの情報と同期をするためには、SwaggerActionのSwaggerGeneratorのoptionにて、そのHandlerを連携させてあげる必要があります。 (詳しくは、SwaggerOptionクラスのコードにて)

アノテーション方式

アノテーション方式なら、Executeアノテーションで successHttpStatus属性を指定します。ただし、こちらはつどつど指定することになるので、ケアレスミスは発生しやすくなります。 

e.g. successHttpStatus on @Execute annotation @Java
@Execute(successHttpStatus = @HttpStatus(value = 201, desc = "new product is created"))
public JsonResponse<Void>s post$index(ProductsPostBody body) {

かなりゴツゴツしているのは、説明(desc)を必須にしているからです。明示的に指定するということは、何かしら説明が必要なケースであろうと想定されるためです。

という "ゴツゴツさ" から、すべてをアノテーション方式だけでやるというのはオススメしません。規約ベース方式の中で、特殊ケースのときにだけ使うというのが良いでしょう。

SwaggerUIの情報とは自動的に同期されます。

asJson方式???

asJson(...).httpStatus(201)のメソッドはオススメしません。 Executeメソッド内での設定なので動的な変化などには対応しやすいですが、レアな要件だと想定されますし、SwaggerUIの情報とは同期が取れませんので、RESTful API で HTTP Status にこだわっているのであれば、使わないほうが良いと思われます。

例外系のHTTP Statusの設定方法

まず、LastaFluteのデフォルトでは、業務例外とクライアント例外はすべて400 (一部404) となり、システム例外はすべて500ですが、ApiFailureHookの実装次第で、そのロジックを自由に調整できます。

例えば、例外時レスポンスのJSONポリシーが "Failure統一クライアントメッセージ" で TypicalFaicliApiFailureHook を利用している場合は、setupBusinessHttpStatusMap()をオーバーライドすることで、特定の例外クラスに対して特定のHTTPステータスを関連付けることができます。

JSON API, Failure統一クライアントメッセージ
JSON API, Failure統一ハイブリッドメッセージ
e.g. override setupBusinessHttpStatusMap of TypicalFaicliApiFailureHook @Java
@Override
protected void setupBusinessHttpStatusMap(Map<Class<?>, Integer> failureMap) {
    // you can add mapping of failure status with exception here
    failureMap.put(AccessTokenUnauthorizedException.class, HttpServletResponse.SC_UNAUTHORIZED);
    failureMap.put(AccessUnderstoodButRefusedException.class, HttpServletResponse.SC_FORBIDDEN);
}

RestfulRouterの設定

ActionAdjustmentProviderにてrouterを

LastaFluteは、デフォルトではRestfulActionに対応していません。

ActionAdjustmentProvider の customizeActionurlMapping() と customizeActionurlReverse() で RestfulRouterを設定する必要があります。

ActionやJSONの微調整

Exampleプロジェクトである lastaflute-example-maihamaサービスの maihama-showbaseアプリにてExampleがありますので、そちらを参考に設定しましょう。

maihama-showbase - ShowbaseActionAdjustmentProvider.java | Github
maihama-showbase - ShowbaseActionOptionAgent.java | Github

どのRestfulRouterを使う？

RestfulRouterは、実装方法に選択肢があるため、アプリの要件にあったものを選びます。

NumericBasedRestfulRouter
IDが必ず数値であることを前提
PairBasedRestfulRouter
リソース名とIDがペアで構成されることを前提

例えば、NumericBasedRestfulRouterの方は、IDが必ず数値である必要がありますが、EventSuffixを使うことができます。 一方で、PairBasedRestfulRouterは、EventSuffixは使えませんが、文字列のIDを利用することができます。

その他細かい挙動の違いがあるので、必要に応じてコードを読みましょう。 (2021/06/06時点では、NumericBasedRestfulRouterの方に力を入れています)

lastaflute - NumericBasedRestfulRouter.java | Github
lastaflute - PairBasedRestfulRouter.java | Github