PlayフレームワークでのRAMLルーティング

Playフレームワークは非常に柔軟なツールですが、インターネット上のルートファイルの形式を変更する方法に関する情報はほとんどありません。 ルートファイルに基づく標準のルート記述言語をRAML形式の説明に置き換える方法について説明します。 このために、独自のSBTプラグインを作成する必要があります。



RAML（RESTful API Modeling Language）に関する簡単な説明です。 プロジェクトのメインページで非常に正確に述べられているように、この言語はライフサイクル全体を通じてアプリケーションAPIの操作を大幅に簡素化します。 簡潔で、再利用が簡単で、最も重要なのは、機械と人が同じように読みやすいことです。 つまり、1つのアーティファクト（RAMLスクリプト）が開発プロセスのすべての参加者（アナリスト、テスター、プログラマー）のエントリポイントになるときに、ドキュメントをコードアプローチとして実装できます。

問題の声明

私たちのチームは、大規模で複雑なオンラインバンキングシステムに取り組んでいます 。 インターフェイスとテストのドキュメントに特に注意が払われます。 テスト、ドキュメント、およびコード生成を組み合わせることができるかどうか疑問に思いました。 これはある程度まで可能であることが判明しました。 しかし、最初に、なぜそれが必要なのかについてのいくつかの言葉。



大規模なプロジェクトでは、インターフェイスのドキュメント化が特に重要です。 アナリスト、サービス、およびクライアントアプリケーションの開発者は、作業しているAPIシステムの説明が必要です。 アナリストはドキュメントを読みやすい方法で扱い、プログラマーは最終的にインターフェイスをコードで記述し、異なるチームは異なる言語でコードを記述します。 情報は何度も複製されるため、同期が難しくなります。 多数のコマンドがある場合、異なるAPI形式の互換性を手動で保証することはほとんど不可能です。 そのため、この問題の解決に徹底的に取り組みました。



まず、API記述のすべてのチームに統一された記述形式を選択しました。 RAMLになりました。 次に、サービスが説明どおりであり、クライアントアプリケーションが説明されているサービスで動作することを（可能な限り）保証する必要があります。 これを行うには、別の記事で説明するテストツールを使用します。 最後のステップは、RAMLのデータに基づいてコードを作成するコード生成の導入でした。 今日は、サーバープロジェクトで使用されるコード生成ツールについて説明します。



通常、ドキュメントには、RESTエンドポイントに関する情報、リクエストのパラメーターと本文の説明、HTTPコード、および応答の説明が含まれています。 同時に、多くの場合、上記のすべての要素の例が示されています。 この情報は、エンドポイントの操作性をテストするのに十分です。サンプルのリクエストを受け取ってサーバーに送信するだけです。 エンドポイントにパラメーターがある場合、それらの値も例から取得する必要があります。 受け取った回答を回答の例と比較するか、ドキュメントに基づいてJSONスキームを検証します。 サンプルの回答がサーバーの応答に対応するためには、データベース内の正しいデータを処理する必要があります。 したがって、テストデータと、応答の説明とリクエストの例が記載されたAPIサービスのドキュメントを含むデータベースがある場合、サービスの状態を簡単にテストできます。 完全を期すために、ドキュメント、テストシステム、およびデータベースについては既に説明しましたが、それらについてはまた別の機会に説明します。 ここでは、そのようなドキュメントに基づいて、できるだけ多くの有用なサーバーコードを生成する方法について説明します。



私たちのサーバーはPlay 2.5で書かれており、顧客にREST APIを提供しています。 データ交換形式はJSONです。 Playフレームワークの標準API記述はconf / routeファイルにあります。 この説明の構文は単純で、エンドポイントの名前とそのパラメーターの説明、およびルートファイル内のコントローラーメソッドへのエンドポイントのバインドに限定されています。 私たちの目標は、標準構文をRAML形式の説明に置き換えることです。 これには次のものが必要です。

1. Playでのルーティングの仕組みと、ルートファイルの処理方法を理解します。
2. RAMLを使用するメカニズムで標準ルーティングメカニズムを置き換えます。
3. 結果を見て、結論を導きます:)

順番に取得しましょう。

Playフレームワークでのルーティング

Playフレームワークは、ScalaとJavaの2つの言語で使用するように設計されています。 したがって、ルートを記述するために、フレームワークの作成者は特定の言語に基づいたDSLを使用せず、独自の言語とそのコンパイラを作成しました。 次に、Scalaについて説明しますが、Javaについてはすべてが真実です。 playアプリケーションはSBTを使用して構築されています。 プロジェクトのアセンブリ中に、ルートファイルがScalaまたはJavaでファイルにコンパイルされ、コンパイル結果がアセンブリ中に使用されます。 SBTプラグインcom.typesafe.play.sbt-pluginは、ルートファイルの処理を担当します。 仕組みを見てみましょう。 しかし、最初に、SBTについて一言。



SBTの基本概念が重要です。 キーには、TaskKeyとSettingsKeyの2つのタイプがあります。 最初のタイプは、関数を保存するために使用されます。 このキーを呼び出すたびに、この関数が呼び出されます。 2番目のタイプのキーは定数を保存し、1回計算されます。 コンパイルはTaskKeyであり、実行の過程で、コード生成とソースファイルの作成のために別のTaskKey、sourceGeneratorsを呼び出します。 実際に、SBTプラグインはsource-Generatorsにルートファイル処理機能を追加します。



通常、ルートに基づいて2つの主要なアーティファクトが作成されます-ファイルtarget / scala-2.11 / routes / main / router / Routes.scalaおよびtarget / scala-2.11 / routes / main / controllers / ReverseRoutes.scala。 Routesクラスは、着信要求をルーティングするために使用されます。 ReverseRoutesは、コントローラーコードからエンドポイントを呼び出し、エンドポイントの名前で表示するために使用されます。 上記を例で説明しましょう。



conf /ルート

GET /test/:strParam   @controllers.HomeController.index(strParam)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ここで、パラメーター化されたエンドポイントを宣言し、HomeController.indexメソッドにマップします。 このファイルをコンパイルすると、次のScalaコードが生成されます。



ターゲット/ scala-2.11 /ルート/メイン/ルーター/ Routes.scala

 class Routes(   override val errorHandler: play.api.http.HttpErrorHandler,   HomeController_0: javax.inject.Provider[controllers.HomeController],   val prefix: String ) extends GeneratedRouter {   ...   private[this] lazy val controllers_HomeController_index0_route = Route("GET",       PathPattern(List(           StaticPart(this.prefix),           StaticPart(this.defaultPrefix),           StaticPart("test/"),           DynamicPart("strParam", """[^/]+""",true)       ))       )   private[this] lazy val controllers_HomeController_index0_invoker = createInvoker(       HomeController_0.get.index(fakeValue[String]),HandlerDef(           this.getClass.getClassLoader,           "router","controllers.HomeController","index",           Seq(classOf[String]),"GET","""""",this.prefix + """test/""" + "$" + """strParam<[^/]+>""")       )   def routes: PartialFunction[RequestHeader, Handler] = {       case controllers_HomeController_index0_route(params) =>           call(params.fromPath[String]("strParam", None)) { (strParam) =>               controllers_HomeController_index0_invoker.call(HomeController_0.get.index(strParam))           }       } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このクラスは、着信要求をルーティングします。 引数として、コントローラー（より正確にはインジェクターですが、必須ではありません）への参照と、構成ファイルで構成されたパスURLプレフィックスが渡されます。 さらにこのクラスでは、ルーティングマスクcontrollers_HomeController_index0_routeが宣言されています。 マスクは、HTTP動詞とルートパターンで構成されます。 後者は、それぞれがパスURL要素に対応する部分で構成されます。 StaticPartはパスの不変部分のマスクを定義し、DynamicPartはパラメーターURLのパターンを設定します。 各着信リクエストはroutes関数に分類され、そこで使用可能なマスク（この場合は1つ）にマッピングされます。 一致するものが見つからない場合、クライアントは404エラーを受け取ります。それ以外の場合、対応するハンドラーが呼び出されます。 この例では、1つのハンドラーはcontrollers_HomeController_index0_invokerです。 ハンドラーの役割には、目的のパラメーターセットを使用してコントローラーメソッドを呼び出し、この呼び出しの結果を変換することが含まれます。



ターゲット/ scala-2.11 /ルート/メイン/コントローラー/ ReverseRoutes.scala

 package controllers {   class ReverseHomeController(_prefix: => String) {       ...        def index(strParam:String): Call = {           import ReverseRouteContext.empty           Call("GET", _prefix + { _defaultPrefix } +               "test/" +               implicitly[PathBindable[String]].unbind("strParam", dynamicString(strParam)))       }   } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このコードにより、対応する関数を介して、たとえばビューでエンドポイントにアクセスできます。



そのため、ルート記述の形式を変更するには、Routesファイルジェネレーターを作成するだけです。 サービスはJSONを提供し、ビューを持たないため、ReverseRoutesは必要ありません。 ジェネレータを機能させるには、電源をオンにする必要があります。 ジェネレータのソースコードを必要な各プロジェクトにコピーしてから、build.sbtに接続できます。 ただし、ジェネレーターをSBTのプラグインとして設計する方が適切です。

SBTプラグイン

SBTプラグインは、ドキュメントに徹底的に記述されています。 ここで、私の意見では、主要なポイントに言及します。 プラグインは追加機能のセットです。 通常、プラグインはプロジェクトに新しいキーを追加し、既存のキーを展開します。 たとえば、sourceGeneratorsキーを拡張する必要があります。 一部のプラグインは他のプラグインに依存する場合があります。たとえば、com.typesafe.play.sbt-pluginプラグインをベースとして使用し、必要なものだけを変更できます。 つまり、プラグインはcom.typesafe.play.sbt-pluginに依存しています。 SBTがプラグインのすべての依存関係を自動的に接続するには、 AutoPluginである必要があります 。 最後に、互換性の問題のため、プラグインはScala 2.10で記述されています。



そのため、RAMLファイルに基づいてRoutes.scalaを生成する必要があります。 このファイルをconf / api.ramlと呼びます。 RAML形式のドキュメントをルーティングに使用するには、リクエストの受信時に呼び出す必要があるコントローラーメソッドをエンドポイントごとに何らかの方法で指定する必要があります。 私たちが使用するRAML 0.8には、そのような情報を示す手段がないため、ダーティハックを作成する必要があります（RAML 1.0は注釈を使用してこの問題を解決しますが、執筆時点では、このバージョンの標準は未加工です）。 呼び出されるコントローラーメソッドに関する情報を、各エンドポイントの最初の説明行に追加します。 前章のRAML形式の例は次のようになります。

 /test/{strParam}:   uriParameters:       strParam:       description: simple parameter       type: string       required: true       example: "some value"   get:       description: |           @controllers.HomeController.index(strParam)       responses:           200:               body:                   application/json:                       schema: !include ./schemas/statements/operations.json                       example: !include ./examples/statements/operations.json
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

RAML解析の詳細については説明しません。raml.orgのパーサーを使用できるとしか言えません。 解析の結果、ルールのリストを取得します-エンドポイントごとに1つ。 ルールは、次のクラスによって定義されます。

 case class Rule(verb: HttpVerb, path: PathPattern, call: HandlerCall, comments: List[Comment] = List())
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

フィールドの名前とタイプは、それ自体を物語っています。 これで、ルールごとに、Routes.scalaファイルのroute関数でマスク、ハンドラー、およびケース要素を作成できます。 この問題を解決するには、ルールのリストに基づいてコードRoutes.scalaを含む行を手動で生成するか、マクロを適用します。 ただし、Play開発者も好む中間オプションを選択する方が良いでしょう。テンプレートエンジンを使用してください。 PW Playはtwirl template engineを使用しており、それも使用しています。 ルート関数を生成するプラグインのテンプレートは次のとおりです。

 def routes: PartialFunction[RequestHeader, Handler] = @ob   @if(rules.isEmpty) {   Map.empty   } else {@for((dep, index) <- rules.zipWithIndex){@dep.rule match {   case route @ Rule(_, _, _, _) => {       case @(routeIdentifier(route, index))(params) =>           call@(routeBinding(route)) @ob @tupleNames(route)               @paramsChecker(route) @(invokerIdentifier(route, index))                   .call(@injectedControllerMethodCall(route, dep.ident, x => safeKeyword(x.name)))@cb       }   }}}@cb
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

少し分かりにくいように見えますが、よく見るとすべてがはっきりしています。 @で始まる式は、ディレクティブとテンプレート変数です。 @obおよび@cb変数は、それぞれ{and}で展開されます。 また、たとえば、 @（routeIdentifier（ルート、インデックス））は次の規則に従って展開されます。

 def routeIdentifier(route: Rule, index: Int): String = route.call.packageName.replace(".", "_") +   "_" + route.call.controller.replace(".", "_") +   "_" + route.call.method + index + "_route"
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これで、RAMLに基づいてRoutes.scalaを生成するコードの記述方法と、それをアセンブリに接続する方法が明確になりました。 プラグインのソースコードはGithubにあります。

今後の計画

プラグインにより、ドキュメントをサーバーのソースコードとして使用できました。 ただし、コード生成では、RAMLファイルから入手可能なすべての情報を使用するわけではありません。 つまり、リクエストとレスポンスのタイプに関する情報は使用しません。 Playでは、コントローラーメソッドでリクエストの解析と応答の生成が行われますが、このコードを自動的に生成する必要があります。 さらに、バージョンRAML 1.0を使用する予定です。



今日は以上です。見てくれてありがとう！