GUI設計指針

Qmnonus ApiFrontでSPAをデプロイするには、大きくSPAとConfigファイルの開発が必要です。

本章では、QmonusApiFrontが果たすWebサーバ機能の概要を説明するとともに、その実現に必要な資材について解説します。

 

基本開発指針

全体の構成について

各ディレクトリの開発

---

基本開発指針

ApiFrontを用いてSPAをホスティングした際の構成図を示します。
図にあるようにQmonus ApiFrontでは

• SPAホスティングをする機能
• API Proxyや認証認可機構を用いて連携サービスとの疎通を可能にする機能

の2つが大きく存在します。

QmonusでのGUI開発では、開発者は主に2点を意識する必要があります。
① SPAの開発
② コンフィグのセットアップ

 

① SPA開発（ SPA開発者 ）

実際に使用するSPAを作成します。Configファイルを用いて、SPA開発とホスティング設定を分離しているため、SPA開発者は、認証認可やAPI Proxyをほとんど意識することなくSPA開発に注力することが可能です。
GUI試験では、開発支援フレームワークFrontTesterを併せて使用することで、資材管理や外部実行などQmonusでの一元的な管理が可能となります。
 

② Configのセットアップ（ プロダクト管理者 ）

ApiFrontの起動パラメータを保存するjsonファイルを作成します。Configファイルには、対向先の認証情報やリリース時の設定を記述するため、プロダクト管理者が管理することを推奨しています。
詳細は、各ディレクトリの開発 > Configファイルにあります。

# 環境ごとにファイルを用意
.
├── config.dev.yml        # dev環境用のcasvalのconfig
├── config.stg.yml        # stg環境用
└── config.prod.yml       # prod環境用

 

全体の構成について

GUI開発では専用のリポジトリを用意いただきます。リポジトリ内の推奨ディレクトリ構成は下記の通りです。各ディレクトリの詳細は次の章で説明します。

.
├── README.md
├── build
│   └── Dockerfile
├── client                # SPAの資材置き場 (ファイル構成はSDP次第)
│   ├── package-lock.json
│   ├── package.json
│   ├── public
│   │   ├── ...
│   ├── src
│   │   ├── ...
│   └── vue.config.js
├── config.dev.yml        # dev環境用のcasvalのconfig
├── config.stg.yml        # stg環境用
├── config.prod.yml       # prod環境用
├── e2e_test              # E2E試験の資材置き場 (ファイル構成はSDP次第)
│   ├── 001sample
│   │   ├── 00_login.js
│   │   ├── ...
│   │   └── index.json
│   └── _common_util.js
├── plugin                # 拡張機能の置き場
│   ├── ...

 

各ディレクトリの開発

上述のようにQmonus ApiFrontによるSPAホスティングでは、主に2つの構成要素があります。

• SPA
• Configファイル

開発者には基本的にこの2点を作成していただきます。
なお、SPAとConfigファイルの作成についてはチュートリアルで解説しています。SPA開発経験のある方も一度目を通していただき、実際の実装イメージを確認ください。
 

client （ ① SPA開発 ）

SPAそのものです。SPAの開発はVueなどご自身で任意のフレームワークが選択可能です。SPA開発者がナレッジのある方法で開発を行ってください。
留意いただきたい点は下記になります。
 

遷移図や画面イメージの作成[プロダクト管理者]

SPA開発者と開発イメージを合わせるため、画面のイメージやボタン押下時のリクエスト内容などの資料をご用意ください。
また、各ページでのユーザのフロー図などがあると、試験シナリオが明確になります。

出力するメッセージ一覧作成[プロダクト管理者]

SPA開発者と開発イメージを合わせるため、画面出力するメッセージの文言の一覧を用意することを推奨します。
英語対応の必要ある場合は、英語版もご用意ください。

API Spec[プロダクト管理者]

GUI開発にあたり、APIリクエストを記述する際に必要になります。
また、GUI開発時のMock作成にも役に立つため、API開発チームと協力して早い段階でご用意ください。

Session APIについて

ApiFrontでは、/sessionでユーザ情報を取得可能なAPIを提供しています。
ユーザ情報によってSPAを変更する場合、このResponseBodyを確認ください。また、トークンのリフレッシュなども可能になります。
その他、backendを確認することで、プロキシpathの取得が可能です。
その他APIに関しては、こちらにあります。

 

Configファイル （ ② Configのセットアップ ）

Qmonus ApiFrontの起動パラメータを設定するファイルです。
構成図では、環境ごとにconfig.dev.yml , config.stg.yml ,config.prod.yml を用意しています。
ApiFrontの設定はGUIを介さず、起動時オプション（起動パラメータ）で決定します。起動パラメータを用いることで、認証認可、クッキー、APIプロキシー等の機能の設定が変更可能です。
Configファイルを環境ごとに用意することで、環境に合った起動方法を提供します。
各起動パラメータの詳細は、こちらにあります。

###############################################################
## 基本設定（商用環境設定）
## snippetsやauth情報はリリースする媒体によって必要性や設定内容が異なります。
##
###############################################################

## アプリケーション名 
appname : Sample

## ポート番号
appport: 8081

## httpsモード
secure  : false

## productionモード
production : true

## baseURL（ValueStream or Lab で自動挿入）
baseURL : https://console-sample-sdp.com

## Cookieの設定
session:
	## クッキーのSecure属性
  cookieSecure: true
	## クッキーのSameSite属性
  cookieSameSite: lax

## コンテンツ設定
content : 
  
  ## ブラウザタイトル
  title  : Sample

  ##CSP設定
  securityPolicy : self

  # スニペットの埋め込み設定
  # サービスリリースフレームワークで必要な設定があれば記述
  snippets:
    css:
      - https://sample-framework-gui/test/css/examle.css
    js:
      - https://sample-framework-gui/test/js/header_footer.js
    favicon:
      - https://sample-framework-gui/test/assets/img/favicon.png
    script:
      -  
    style:
      - body { margin:0px; position:absolute; top:70px;  width:100%; height:calc( 100% - 100px) !important; }
      - header.test-header { position:fixed; top:0px; width:100%; z-index:30; } 
      - footer.test-footer { position:fixed; bottom:0px; height:39px; width:100%; } 

  ## ランディングパス
  route : "/"
  ## コンテンツ ベースディレクトリ
  base   : "./client/dist"
  ## コンテンツ メインファイル
  main   :  "index.html"
  ## フレーム描画モード
  isFrame: false
  ## SPAのhistoryモードを有効化
  enableHistory: true

## CORS設定など
pushheaders:
  'Access-Control-Allow-Origin': 'https://example.com'
  'Access-Control-Allow-Credentials': true

## バックエンドAPI設定(proxypathの指定がない場合、CORSアクセス)
backend:
  proxypath: /apis
  target: https://api-test.com

## 認証・認可
authentication:
    # mandatory
    strategy             : "openid"

    # トークン(X-Auth-Token)をProxy時に自動付与
    transparentTokens    : true

    #追加分
    httpTimeout          :  30000

    # 認証パラメータ（ロジックによって項目は異なる）
    options              :
      providerURL        : 'https://auth.test.com/auth/*'

      profile            : true

      ## discoverの通信量削減のため、事前に設定
      discover:
        match            : 'https://auth.test.com/auth/*'
        endpoint         : 'https://auth.test.com/auth/server'

    # 認証プロバイダー(任意)
    provider             : 'custom_auth'
    provider_plugin      :  ./plugin/auth_v5 .js

    # 認証トークンジェネレータ(任意)
    generator            : 'custom_token'
    generator_plugin     :  ./plugin/token_v5.js
    
    # プロバイダープロパティ
    properties           :
      # token 取得先
      token_endpoint   : 'https://token.test.com'
      token_password  : "${KEYSTONE_PASSWORD}"

 

パラメータのうち、特筆すべき2点について記述します。

認証認可

Qmonus ApiFrontでは起動パラメータによって認証ストラテジーを設定することが可能です。
Qmonus SDK Labからデプロイする場合は、Qmonus SDK Portalの認証認可機能(qmonus)が選択され、Lab上で自動でinjectionされます。qmonusの場合、カスタムプラグインは不要です。
下記はLabから自動投入される起動パラメータの例になります。

authentication: 
        strategy: qmonus
        transparentTokens: false
	      cacheTokens: false
        httpTimeout: 30000
        generator: qmonus
        options:
            base_url: https://portal-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.sdk-lab.qmonus.net
            pass_code: xxxxxxxxxx
            pass_phrase: xxxxxxxxxx
            enableSLO: true,
            - callbackURL: https://api-front-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.sdk-lab.qmonus.net/auth/qmonus/callback
            - realm: https://api-front-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx.sdk-lab.qmonus.net/

 

Backend Proxy

API Proxyの利用は必須ではありませんが、SPAからはSameSiteのAPIとしてバックエンドのAPIが扱えるため、バックエンド側でのCORS設定は不要になる点や、開発したアプリケーションの障害対応時に、ApiFrontのログでアクセス履歴が追えるメリットがあります。

backend:
  proxypath: /apis
  target: http://apigw:9000

Qmonus SDK Labからデプロイした場合の設定は上記で、以下のようにproxyが張られます。

/apis/v1/hogefuga => http://apigw:9000/v1/hogefuga

proxyにはHeaderやスクリプトのinjection機能もあります。詳細は起動パラメータ一覧をご覧ください。

 

その他ディレクトリ

e2e_test

E2Eテストファイルを置くディレクトリです。Qmonus開発支援ツールであるFrontTesterを使用する場合、ここに配置することを推奨します。
FrontTesterはローカル/Qmonus SDK Portal上でE2E試験の記述と実行ができるツールです。
詳細は、下記をご確認ください。
E2E Testerチュートリアル
Qmonus FrontTester Document
FrontTester チュートリアル(E2E作成例)
 

build

staging以降でデプロイするために使用するDockerfileを配置します。
 

plugin

ApiFrontから参照するユーザカスタムの認証認可フローやinjectionスクリプトなどを配置します。ユーザの構成によってカスタムファイルが存在しない場合、不要です。