RESTXの紹介

1.概要

このチュートリアルでは、軽量のJava RESTフレームワークhttp://restx.io/[RESTX]について説明します。

2.特徴

RESTful APIを構築することはRESTXフレームワークで非常に簡単です。 JSON、クエリとパスのパラメータ、ルーティングとフィルタリングのメカニズム、使用状況の統計、モニタリングなど、RESTフレームワークから期待できるすべてのデフォルトがあります。

RESTXには、直感的な管理Webコンソールとコマンドラインインストーラが付属しているので、簡単にブートストラップできます。

また、Apache License 2に基づいてライセンスされており、開発者コミュニティによって管理されています。 RESTXの最小Java要件はJDK 7です。

3.設定

  • RESTXには、Javaプロジェクトを素早くブートストラップするのに便利な便利なシェル/コマンドアプリが付属しています。

先に進む前に、まずアプリをインストールする必要があります。詳しいインストール手順はhttp://restx.io/docs/install.html[こちら]から入手できます。

4.コアプラグインのインストール

今度は、シェル自体からアプリを作成できるようにするために、コアプラグインをインストールします。

RESTXシェルで、次のコマンドを実行しましょう。

shell install

その後、インストール用のプラグインを選択するように促されます。 io.restx:restx-core-shell を指す番号を選択する必要があります。インストールが完了すると、シェルは自動的に再起動します。

5.シェルアプリのブートストラップ

RESTXシェルを使用すると、新しいアプリをブートストラップするのが非常に便利です。ウィザードベースのガイドを提供します。

まずシェルで次のコマンドを実行します。

app new

このコマンドはウィザードを起動します。その後、デフォルトのオプションを使用するか、または要件に従って変更することができます。

リンク:/uploads/shell-app-bootstrap-100x80.png%20100w[]

__pom.xmlを生成することにしたので、プロジェクトは標準のJava IDEに簡単にインポートできます。

いくつかのケースでは、http://restx.io/docs/ide.html[IDE設定]を微調整する必要があるかもしれません。

次のステップはプロジェクトを構築することです。

mvn clean install -DskipTests
  • ビルドが成功したら、IDEから AppServer クラスをJavaアプリケーションとして実行できます。これにより、管理コンソールでサーバーが起動し、ポート8080で待機します。

__http://127.0.0.1:8080/api/@/ui __にアクセスして、基本的なUIを確認してください。

  • //で始まるルートは、RESTコンソールで予約されているパスである管理コンソールに使用されます。

  • 管理コンソールにログインするには、デフォルトのユーザー名「admin __」 __とアプリ作成時に指定したパスワードを使用できます。

コンソールを試す前に、コードを調べて、ウィザードが何を生成したのかを理解しましょう。

6. RESTXリソース

経路は< __main package> .rest.HelloResource____クラスで定義されています。

@Component
@RestxResource
public class HelloResource {
    @GET("/message")
    @RolesAllowed(Roles.HELLO__ROLE)
    public Message sayHello() {
        return new Message().setMessage(String.format("hello %s, it's %s",
          RestxSession.current().getPrincipal().get().getName(),
          DateTime.now().toString("HH:mm:ss")));
    }
}

RESTXがセキュリティおよびRESTバインディングにデフォルトのJ2EEアノテーションを使用することはすぐに明らかです。ほとんどの場合、それは依存性注入のためにそれ自身のアノテーションを使います。

RESTXはhttp://restx.io/docs/ref-core.html[リクエストへのメソッドパラメータのマッピング]についても多くの妥当なデフォルト値をサポートします。

  • そして、これらの標準的な注釈に加えて @ RestxResource があり、これはそれをRESTXが認識するリソースとして宣言します。

ベースパスは src/main/webapp/WEB-INF/web.xmlに追加されています。ここでは /api なので、GETリクエストを http://localhost:8080/api/message__に送信できます適切な認証を前提としています。

Message クラスは、RESTXがJSONにシリアル化する単なるJava Beanです。

ブートストラップによって生成された HELLO ROLE を使用して RolesAllowed__アノテーションを指定することによってユーザーアクセスを制御します。

7.モジュールクラス

前述のように、RESTXは @ Named のようなJ2EE標準の依存性注入アノテーションを使用し、必要に応じて独自のものを作成します。おそらく、 @ Module および @Provides. についてDaggerフレームワークからヒントを得ます。

  • アプリケーションのメインモジュールを作成するためにこれらを使用します。これはとりわけadminパスワードを定義します。

@Module
public class AppModule {

    @Provides
    public SignatureKey signatureKey() {
        return new SignatureKey("restx-demo -44749418370 restx-demo 801f-4116-48f2-906b"
            .getBytes(Charsets.UTF__8));
    }

    @Provides
    @Named("restx.admin.password")
    public String restxAdminPassword() {
        return "1234";
    }

    @Provides
    public ConfigSupplier appConfigSupplier(ConfigLoader configLoader) {
        return configLoader.fromResource("restx/demo/settings");
    }

   //other provider methods to create components
}

_ @ Module は、Daggerの @ Module やSpringの _ @ Configurationと同様に、他のコンポーネントを定義できるクラスを定義します。

@ Provide は、Daggerでの 提供、またはSpringでの @ Bean のように、プログラムによってコンポーネントを公開します。

そして最後に、 @ Named アノテーションを使用して、作成されたコンポーネントの名前を示します。

AppModule は、クライアントに送信されたコンテンツに署名するために使用される SignatureKey も提供します。たとえば、サンプルアプリのセッションを作成している間に、設定されたキーで署名されたCookieが設定されます。

HTTP/1.1 200 OK
...
Set-Cookie: RestxSessionSignature-restx-demo="ySfv8FejvizMMvruGlK3K2hwdb8="; RestxSession-restx-demo="..."
...

そしてhttp://restx.io/docs/ref-factory.html[RESTXのコンポーネントファクトリ/依存性注入ドキュメント]をチェックしてください。

8.ランチャークラス

そして最後に、 AppServer クラスを使用して、埋め込みJettyサーバーで標準のJavaアプリケーションとしてアプリケーションを実行します。

public class AppServer {
    public static final String WEB__INF__LOCATION = "src/main/webapp/WEB-INF/web.xml";
    public static final String WEB__APP__LOCATION = "src/main/webapp";

    public static void main(String[]args) throws Exception {
        int port = Integer.valueOf(Optional.fromNullable(System.getenv("PORT")).or("8080"));
        WebServer server =
            new Jetty8WebServer(WEB__INF__LOCATION, WEB__APP__LOCATION, port, "0.0.0.0");
        System.setProperty("restx.mode", System.getProperty("restx.mode", "dev"));
        System.setProperty("restx.app.package", "restx.demo");
        server.startAndAwait();
    }
}

ここでは、 dev モードを開発フェーズで使用して、開発フィードバックループを短縮する自動コンパイルなどの機能を有効にします。

  • アプリケーションを war (Webアーカイブ)ファイルとしてパッケージ化して、スタンドアロンのJ2EE Webコンテナにデプロイできます。

次のセクションでアプリのテスト方法を見つけましょう。

9.スペックを使った統合テスト

RESTXの強力な機能の1つは、その「スペック」の概念です。 spec のサンプルは次のようになります。

title: should admin say hello
given:
  - time: 2013-08-28T01:18:00.822+02:00
wts:
  - when: |
      GET hello?who=xavier
    then: |
      {"message":"hello xavier, it's 01:18:00"}

テストはhttp://yaml.org/[YAML]ファイル内のhttps://en.wikipedia.org/wiki/Given-When-Then[Given-When-Then]構造に書かれています。システムの現在の状態( given )が与えられると、APIは特定の要求( when )に応答( then )します。

src/test/resources HelloResourceSpecTest クラスは上記の仕様で書かれたテストを起動します。

@RunWith(RestxSpecTestsRunner.class)
@FindSpecsIn("specs/hello")
public class HelloResourceSpecTest {}

RestxSpecTestsRunner クラスはhttps://www.baeldung.com/junit-4-custom-runners[カスタムJUnitランナー]です。これにはカスタムJUnitルールが含まれています。

  • 組み込みサーバーをセットアップする

  • システムの状態を準備します(の中の given セクションに従って)。

スペック) ** 指定された要求を出す

  • 期待される回答を確認する

@ FindSpecsIn アノテーションは、テストが実行されるべきスペックファイルのパスを指します。

  • 仕様は統合テストを書くのを助け、APIドキュメントに例を提供します** 仕様はhttp://restx.io/docs/ref-specs.html[模擬HTTPリクエストとレコードリクエスト/レスポンスのペア]にも役立ちます。

10.手動テスト

HTTP経由で手動でテストすることもできます。まずログインする必要があります。そのためには、RESTXコンソールで管理者パスワードをハッシュする必要があります。

hash md5 <clear-text-password>

そしてそれを /sessions エンドポイントに渡します。

curl -b u1 -c u1 -X POST -H "Content-Type: application/json"
  -d '{"principal":{"name":"admin","passwordHash":"1d528266b85cf052803a57288"}}'
  http://localhost:8080/api/sessions

(Windowsユーザーは最初にhttps://curl.haxx.se/windows/[download]curlする必要があることに注意してください。)

それでは、 /message リクエストの一部としてセッションを使用すると、

curl -b u1 "http://localhost:8080/api/message?who=restx"

それでは、次のようになります。

{"message" : "hello admin, it's 09:56:51"}

11.管理者コンソールを調べる

管理コンソールはアプリを制御するための便利なリソースを提供します。

http://127.0.0.1:8080/admin/@/ui を参照して、主な機能を見てみましょう。

11.1. APIドキュメント

APIドキュメントセクションには、すべてのオプションを含むすべての利用可能なルートが一覧表示されます。

リンク:/uploads/admin-api-docs-100x54.png%20100w[]

そして、個々のルートをクリックして、それらをコンソール自体で試してみることができます。

リンク:/uploads/admin-api-docs-2-100x54.png%20100w[]

11.2. モニタリング

  • JVM Metrics ** セクションには、アクティブセッション、メモリ使用量、およびスレッドダンプを含むアプリケーションメトリックが表示されます。

リンク:/uploads/admin-monitoring-100x59.png%20100w[]

  • Application Metrics ** の下には、デフォルトで監視される主に2つのカテゴリの要素があります。

  • BUILD はアプリケーションコンポーネントのインスタンス化に対応します

  • HTTP はRESTXによって処理されるHTTPリクエストに対応します

11.3. 統計

RESTXを使用すると、ユーザーはアプリケーションに関する匿名の統計情報を収集して共有し、RESTXコミュニティに情報を提供できます。 ** restx-stats-admin モジュールを除外することで簡単にオプトアウトできます。

統計は、基礎となるOSやJVMのバージョンなどを報告します。

リンク:/uploads/admin-stats-100x60.png%20100w[]

これらとは別に、管理コンソールも役立ちます。

  • サーバーログをチェックする(Logs)

  • 発生したエラーを表示する(エラー)

  • 環境変数を確認する(Config)

12.承認

  • RESTXエンドポイントはデフォルトで保護されています。

@GET("/greetings/{who}")
public Message sayHello(String who) {
    return new Message(who);
}

認証なしで呼び出されると、デフォルトで __401 __byが返されます。

エンドポイントを公開するには、メソッドレベルまたはクラスレベルで @ PermitAll アノテーションを使用する必要があります。

@PermitAll
@GET("/greetings/{who}")
public Message sayHello(String who) {
    return new Message(who);
}
  • クラスレベルでは、すべてのメソッドはpublicです。

さらに、このフレームワークでは、 @ RolesAllowed アノテーションを使用してユーザーロールを指定することもできます。

@RolesAllowed("admin")
@GET("/greetings/{who}")
public Message sayHello(String who) {
    return new Message(who);
}

この注釈により、RESTXは認証されたユーザーに管理者ロールも割り当てられているかどうかを確認します。管理者の役割を持たない認証済みユーザーがエンドポイントにアクセスしようとすると、アプリケーションは 401 ではなく____403を返します。

  • デフォルトでは、ユーザーの役割と資格はファイルシステムの別々のファイルに保存されます。

そのため、暗号化されたパスワードを持つユーザーIDは /data/credentials.json ファイルの下に格納されます。

{
    "user1": "$2a$10$iZluUbCseDOvKnoe",
    "user2": "$2a$10$oym3Swr7pScdiCXu"
}

そして、ユーザーロールは /data/users.json ファイルに定義されています。

----[    {"name":"user1", "roles":["hello"]},
    {"name":"user2", "roles":[]}]----

サンプルアプリでは、ファイルは FileBasedUserRepository クラスを介して AppModule にロードされます。

new FileBasedUserRepository<>(StdUser.class, mapper,
  new StdUser("admin", ImmutableSet.<String> of("** ")),
  Paths.get("data/users.json"), Paths.get("data/credentials.json"), true)

StdUser クラスはユーザーオブジェクトを保持します。カスタムユーザークラスにすることもできますが、JSONにシリアル化できる必要があります。

もちろん、別のhttps://raw.githubusercontent.com/restx/restx/master/restx-security-basic/src/main/java/restx/security/UserRepository.java[ UserRepository ]実装を使用できますデータベースにヒットしたもの。

…… ……

13.結論

このチュートリアルでは、軽量のJavaベースのRESTXフレームワークの概要を説明しました。

フレームワークはまだ開発中であり、それを使用していくつかの大まかなエッジがあるかもしれません。詳細についてはhttp://restx.io/docs/[the official documentation]をチェックしてください。

サンプルブートストラップアプリケーションは、https://github.com/eugenp/tutorials/tree/master/restx[GitHubレポジトリ]にあります。