- 追加された行はこの色です。
- 削除された行はこの色です。
* 前提条件 [#q5fb98a5]
OpenAPIの定義がある状況で、管理画面を早く正確に作ることがゴールである場合の手法について考察してみる。
管理画面は、ユーザが使うものではないから、デザインはそこそこのレベルがあればいい。
画面までの自動生成であれば、データベースのテーブル作成も範囲に含めてならば、jhipsterがいい感じにCRUDを行える画面作成までやってくれる。
しかし、DBは既存であり、しかもそこには、API経由でしかアクセスできない場合、どのような手法が考えられるだろうか？
まずは半自動でもいいので考える。作業量が減って正確であればいいのだから。
** 一覧表示系の画面を効率よく作成するパターンについて考える [#haf69728]
アイデアとしては、APIでGET系のレスポンスの構造を解析し、それをJDLで記述するというやり方だ。
JHipsterで生成されたコードの修正箇所は、まずDB関係のコードは不要になるだろうし、
そのDBにアクセスしに行っている箇所を差し替えなくてはならない。
差し替える用のコードは、openapi-generatorでクライアント用のコードを生成したものと差し替える必要がまずはあるだろう。
ここまでが自動生成のほうが早くて、自動化できそうな箇所であろう。
そこまで行ったならば、こんどは、openapi-generatorで生成したコードが外部のAPIから読み込んだデータを、jhipsterで生成したDAOとして取得するように修正する必要がある。
この手法は、おそらく毎回似たような対応で済むだろうから、知見が増えやすいと思う。
** 新規作成・更新系の画面は、どうだろうか？これは、openapiの定義のメソッドの種類で、POST、PUTのリクエストパラメータを分析して、JDLを作成するというのでどうだろうか？ [#bb5885ab]
jhipsterで生成したコードのうち、saveメソッドでＤＢを更新しに行っている箇所を以下のもので差し替える作業となるであろう。
差し替えるものは、openapi-generatorで生成したクライアント用コードである。
ここまでが自動生成したコードであり、あとの作業としては、
openapi-generatorで生成したコードが外部のAPIに更新しに行く修正である。
** openapiからjdlを生成するツールの要件を考える [#qb2c1e1c]
open-apiを解析しjdlを生成するというのを手作業でやると、apiの数が膨大な場合
詰んでしまう。なので何らかのツールがあったらよいということになる。
まず、apiがgetメソッドの場合は、レスポンスを解析してJDLを生成する機能が欲しい。
次にapiがpost、putメソッドの場合は、クエリパラメータを解析してJDLを生成する機能が欲しい。
** エンティティが重複してしまう課題 [#u0b51ecf]
APIの定義が、ER図のように正規化されていないのが原因で、
例えばテーブルというかエンティティがAPI1とAPI2でかぶってしまう場合がある可能性がある。
** JDLから生成されるのはCRUDのうち１つのメソッドしか対応できない課題。 [#v310e04d]
generatorから生成されるのはCRUDのうち１つのメソッドという可能性もある。
提供されているAPIがきれいにCRUDに対応していることは、無い前提で考えていかないといけないだろう。
ただし、対応してそうな場合は、極力対応させたほうがいいとも思える。
*** 解決案 [#l8d28dd7]
生成する画面のコードは、JHipsterのデフォルトではCRUDに対応したものであるが、
それぞれ、GET用、POST用、DELETE用に分けてテンプレートを用意しておき、
生成されたコードを必要に応じてコピーするようにしてみてはどうだろうか？
できれば、JDLを拡張し、各エンティティにメソッドの種別をアノテーションで指定できるように改造する必要があると思う。
改造が難しいのならば、全メソッド用のコードをJHipsterが行い、必要なメソッドのコードをコピーするスクリプトを作るのも代替え案としては有りかと思う
*** openapi-generatorの調査対象 [#wa603dc9]
openapiのyamlをパースした後、パラメータについてのコードを生成している箇所とレスポンスを生成している箇所について調査が必要と考える。
** 懸念 [#t961234b]
このやり方で進めていっても、結局はswaggerで出力される画面の劣化版みたいなものを作るだけになってるのではないだろうか？
結局JHipsterは、データベースのテーブルのCRUD操作ができる画面を生成するのが優れているわけである。なので、もっと本質的な課題は、openapiの定義を、いかにER図に寄せることができるかどうかであろう。
** 仮説 [#n466ffd0]
DBに直接アクセスできないプロジェクトがあるという前提ですが、以下の仮説をかんがてみました。
APIで定義されたGETメソッドをJDLに置き換えた世界では履歴テーブル的な構造で定義すると収まりがよい説
理由は、リモートのDBにアクセスできないからといって、ローカルに検索結果を格納していけば、なんか使えそうな情報になったりしないだろうか？という考え。
これまで、ログファイルに何でも書き込んで置けば、あとでAIとかで解析するときにつかえるのでは？という安直な考えでなんでも大量にログに出していたかと思いますが、あらかじめ検索結果の構造がわかっているわけだし、DBに格納してしまえば解析の前処理が不要になる分、データマイニングがはかどるのではないかと思います。
この流れを生むには、これまで外部のAPIを直接たたきに行く仕組みをBFFという中継サーバを経由する実装に置き換える必要が出てくるわけです。
** ER図と、想定ER図 [#gf5cb1f3]
説明のため「想定ＥＲ図」の言葉の定義をする。実際のＥＲ図とは異なり、openapiの定義から想定されるＥＲ図のことである。
実際のＥＲ図に近いものができると思うが、openapiとの親和性を重視したものになる。ER図がリモートのAPI提供者から公開されていない場合も、自分で定義するわけだから当然使える。
ERは、正規化されすぎている。なので実際にユーザが使う場合、画面項目定義書でマッピングを設計する必要がある。
もしopenapiからER図をだしたい場合、さらに、少ない工数で、管理画面を実装するにあたって、有益なコードを生成する状況において、どうすれば効率がよいだろうか？
とりあえず、無邪気に案を出してみる。
たとえば、ER図はER図として、出力しておいて、APIから推定されるER図を出しておく。
APIを動かしたらAPIから推定されるER図には、適切に結果を格納する場所はAPIから推定したわけだから、結果を格納する場所は用意することは容易だ。そこまでは自動化できると思う。
あとは、そのタイミングでER図から生成したテーブルに書き込むにはどうするか？ということになる。
なぜER図に書き込みたいのかという説明がまだであった。
ここでの前提は、外部のDBには接続できないものの、ER図は公開されているという前提である。
ER図が公開されていない場合は、推定するER図に書き込むだけである。
ER図に書き込みたい理由としては、データが正規化されている。おそらく、閲覧しやすいと思われる。
ただし、初期段階ではテーブルを開いても値は何もはいっていない。データを入れるには、どのAPIを使う必要があるかという疑問がユーザはもつだろうから、そこには対応するAPIのリンクがあるべきである。
** 既存のER図上のリレーションと、テーブルとAPIとのリレーション [#g5ada066]
既存のERとはいっても、実際の外部のDBには直接接続できないから、テーブルという器はつくれるが値は空っぽである。
そこに、対応するAPIはなんであるのか、記述できるDSLが必要になってくるのではないだろうか？
*** openapi上にER図の情報を追記する案 [#x847a60f]
openapiのyamlにはdescriptionというコメントを書く比較的自由度の高いフィールドがある。
そこに対応するＥＲのカラムの情報を、特定のルールを決めて記述しておくというアイデアだ。
できれば、別途定義するカラムを増やしてほしい。おそらくＤＢのスキーマの定義も別途行うところが増えるとは思うが、自動化の効率が進み、生産性は飛躍的に上がるはずだ。
ただし、この場合もとのopenapiの定義書に変更があった場合、対応がつらいことになる
*** 画面項目定義書からなんらかのパース可能な定義書を生成し、openapiの定義書と合体させる案 [#s2fe4cbe]
openapi定義書を修正しなくていいので、openapi定義書が更新するばあいでも影響が少ない。
openapiの変更の差分を把握できるようにしておく必要があると思う。
そういえば、画面項目定義書ってopenapiのような定義書ってあるんだろうか？
*** 画面項目定義書とは [#q4854a78]
ここでいう画面項目定義書の役割について、再考してみる。
何を決めているのかというと、ありがちなのは、以下のような項目をエクセルで書いているものをよく見かける
- テキストボックスとかの種類
- 必須かどうか
テキストボックスであれば、
- 表示桁数
- 表示位置
- 入力桁数
しかし、これだけだと、しょぼい画面になる。
デザインツールを使った例を以下にリンクをはるが、リンク先の３分の動画をみて比較してみれば、言わんとすることはわかっていただけると思う。
https://youtu.be/gVl-wuldf4E
** デザインすることを否定してみる [#h873edc2]
いや、そうではない。デザインしたいわけではない。たしかにデザインして、美しい画面ができれば、さぞいいだろうとおもうかもしれない。しかし製造コストが高くなりすぎて、現実での解にならない。
なので、デザインはしない。するとしても１つだけデザインしてあとは使いまわす。１００個のAPIごとに画面をデザインするわけにはいかないのだ。そんな時間はない。
** 初期の目標 [#v081ea4b]
まずは、openapiのGETメソッドだけを対象として、レスポンスをもとにJDLを作成する。
JDL作成は、ツール化を試みる。
次にJDLにGETメソッドであることを認識させるアノテーションを改造して追加する
JHIPSTERで生成したコードから必要な箇所だけ抜粋するスクリプトを作成する。
JHipsterのテンプレートを改造する
*** 作業の進め方 [#q0212bc1]
それぞれのgithubからforkし、改造ポイントがわかるようにするのが見やすいかもしれない。
