Fizz管理後臺使用教程

前言

Fizz Gateway 是一個基於 Java異步框架WebFlux開發的微服務網關，能夠快速幫助企業進行API服務治理、減少中間層膠水代碼以及降低編碼投入、提高 API 服務的穩定性和安全性。Fizz管理後臺是Fizz Gateway的配套系統，基於Java、Vue開發，提供友好的圖形化配置界面，支撐Fizz Gateway的熱服務編排、自動授權選擇、線上服務腳本編碼、在線測試、高性能路由、API審覈管理、自定義插件等功能的配置使用。本篇文章介紹Fizz管理後臺的使用。

功能

Fizz管理後臺包含如下功能：

網關管理
- 網關分組：對Fizz網關集羣內的機器進行邏輯上的分組，針對不同的分組可配置不同的路由策略。
- 插件管理：維護插件元數據，定義路由級別的自定義屬性、插件級別的自定義配置信息。
- appID管理：配置應用鑑權信息，可配置是否啓用簽名、是否啓用IP白名單，AppID級別的自定義配置供自定義插件使用。
- 路由管理：配置服務或API路由規則，支持按請求路徑轉發、轉發到指定後端服務兩種轉發規則，支持插件配置。
- 接口統計：Fizz網關接口訪問統計功能，以圖表的形式展示指定時間段內每日的接口總數、訪問次數，可查看接口的歷史訪問總次數以及最近請求時間。
服務編排
- 服務管理：聚合接口歸屬於服務，服務通過該功能維護，創建人自動獲得服務權限，服務權限可分配，擁有權限的用戶才能操作對應的接口列表。
- 接口列表：基於現有的業務微服務使用在線配置的方式快速的生成一個聚合接口，同時提供在線測試功能，發佈歷史版本查看。
- 操作日誌：查看聚合接口的新增、修改、發佈、下線、回滾、刪除操作日誌。
- 網關緩存：查看Fizz網關當前在線的實例列表以及對應實例本地緩存的已發佈接口信息。
發佈申請
- 我的申請：提交接口發佈|下線申請，審覈通過後可以對相關接口執行發佈|下線操作。
- 待審覈：審覈發佈|下線申請。
- 審覈日誌：查看審覈發佈|下線申請操作日誌。
權限管理
- 角色管理：維護角色數據，爲角色分配權限。
系統管理
- 用戶管理：維護用戶數據，爲用戶分配角色。

登錄

Fizz管理後臺使用賬號密碼登錄，登錄界面如圖所示。

輸入賬號、密碼、驗證碼後登錄後臺，後臺驗證成功後跳轉至後臺主界面，如圖所示。

網關管理

網關管理模塊主要用於維護Fizz Gateway的路由配置，本章節介紹網關管理下的路由管理功能的使用。

路由管理概述

路由管理功能用於維護網關的路由規則，支持按請求路徑轉發、轉發到指定後端服務兩種轉發規則，支持插件配置。

路由列表

菜單位置：網關管理 > 路由管理。點擊菜單後進入路由列表頁面，如圖所示。

manager_api_auth_list_query.png

新增路由

點擊新增按鈕彈出新增窗口，如圖所示。

網關分組：選取路由關聯的網關分組，只有屬於所選分組的網關實例路由規則纔會生效，必選；

服務：網關的請求路徑格式爲 http://{ip}:{port}/proxy/{service}{apiPath}，服務對應{service}段，當轉發選擇按請求路徑轉發時服務需要是聚合配置的服務或者是Eureka註冊的服務，當轉發選擇轉發到指定後端服務時服務不需要是實際存在的服務，只用於路徑匹配使用，長度不能超過50個字符，必填；

API方法：請求的method類型，可選GET|POST；

API Path：網關的請求路徑格式爲 http://{ip}:{port}/proxy/{service}{apiPath}，API Path對應{apiPath}段，使用前綴匹配原則，例如"/api/"將匹配"/api/"、"/api/1"、"/api/1/1"等路徑；

應用：選取路由關聯的應用，網關使用選取應用的信息進行鑑權，更多詳情請查看appID管理功能介紹；

訪問：可選允許|禁止，必選；

轉發：可選按請求路徑轉發|轉發到指定後端服務，當選擇按請求路徑轉發時，請求會按請求路徑轉發，例如網關請求 http://{ip}:{port}/proxy/my-service/api-path 將轉發到 http://my-service/api-path；當選擇轉發到指定後端服務時，需要添加轉發到的後端服務URL，請求會轉發到配置的後端服務，例如配置了服務爲 my-service，API Path爲空，後端服務URL爲 http://127.0.0.1:8080/forward-service/，網關請求 http://{ip}:{port}/proxy/my-service/api-path 將轉發到 http://127.0.0.1:8080/forward-service/api-path。

點擊添加插件按鈕爲路由添加插件，如圖所示。

配置插件路由級別的自定義配置，表單界面來自於插件的表單定義，更多詳情請查看插件管理功能介紹。

配置完成後點擊保存按鈕保存路由規則。

編輯路由

點擊編輯按鈕彈出編輯窗口，如圖所示。

刪除路由

點擊刪除按鈕彈出刪除確認窗口，如圖所示。

服務編排

服務編排模塊主要用於維護Fizz Gateway的熱服務編排配置，本章節介紹服務編排下的接口列表功能的使用。

接口列表概述

接口列表功能用於維護聚合接口，聚合接口從外部調用方角度看是一個簡單的接口，通過入參請求獲取響應結果，內部實現會調用多個底層後端服務，將多個調用結果聚合轉換成外部調用方想要的數據格式。

接口列表

菜單位置：服務編排 > 接口列表。點擊菜單後進入接口列表頁面，如圖所示。

新增接口

點擊新增按鈕彈出新增窗口，如圖所示。

基礎信息

所屬服務：接口所屬服務，更多詳情請查看服務管理功能介紹，必選；

接口名：接口名稱，用於展示使用，長度不能超過200個字符，必填；

方法：接口請求方法類型，可選GET|POST，必選；

路徑：接口請求路徑後綴，長度不能超過2000個字符，必填；

開發人員：接口對應負責的開發人員，長度不能超過200個字符；

描述：接口功能描述，長度不能超過2000個字符；

舉個例子，所屬服務設置my-test-service，方法設置POST，路徑設置test-aggregate-post，對應的聚合接口請求爲 POST http://{Fizz網關ip地址}:{port端口}/proxy/my-test-service/test-aggregate-post。

配置輸入

聚合接口的入參大部分是通過JSON Schema來定義的，下面先簡單地介紹下JSON Schema。

JSON Schema介紹

JSON Schema實際上也是JSON數據，用於標註和驗證JSON文檔，可以類比於XML Schema，當前最新版本2019-09。

作爲普通用戶，我們並不需要去了解JSON Schema的規範內容，只要能夠構建JSON Schema即可。

要理解JSON Schema，首先要理解什麼是JSON。JSON是JavaScript Object Notation的縮寫，一種簡單的數據交換格式。最初JSON是基於JavaScript，廣泛的應用於萬維網。由於其簡潔和清晰的層次結構、易於人閱讀等特性，使得越來越多的場景下被採用。

JSON包含以下數據結構：
object:
{ "key1": "value1", "key2": "value2" }
array:
[ "first", "second", "third" ]
number:
42
3.1415926
string:
"This is a string"
boolean:
true
false
null:
null
通過以上的簡單數據類型，就能構造複雜的結構化數據了。下面舉兩個例子：
{
  "name": "George Washington",
  "birthday": "February 22, 1732",
  "address": "Mount Vernon, Virginia, United States"
}
{
  "first_name": "George",
  "last_name": "Washington",
  "birthday": "1732-02-22",
  "address": {
    "street_address": "3200 Mount Vernon Memorial Highway",
    "city": "Mount Vernon",
    "state": "Virginia",
    "country": "United States"
  }
}
以上兩個例子都是有效的JSON數據，包含一樣的有效信息，但是當程序讀取數據時，需要準確的知道數據是怎麼組織的，比如哪些字段是必須，這些字段是什麼類型。這時候JSON Schema就派上用場了，看以下JSON Schema例子：
{
  "type": "object",
  "properties": {
    "first_name": { "type": "string" },
    "last_name": { "type": "string" },
    "birthday": { "type": "string", "format": "date" },
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city": { "type": "string" },
        "state": { "type": "string" },
        "country": { "type" : "string" }
      }
    }
  }
}
用以上JSON Schema驗證第一個例子時，驗證失敗；但是第二個例子驗證通過。

JSON Schema本身也是通過JSON編寫，其本身也是數據，不是一個計算機程序，只是一種“描述其它數據的結構”的聲明格式。這既是長處，也是弱點，JSON Schema可以簡潔地描述數據的結構並且自動驗證數據，但是對於數據元素間的關係表達就力不能及了。

更多JSON Schema知識可以閱讀Understanding JSON Schema。

請求頭部

定義聚合接口的請求Header參數。

舉個例子：

{
  "type": "object",
  "properties": {
    "headerParam1": {
      "type": "string",
      "title": "請求頭參數1",
      "titleEn": "headerParam1"
    }
  },
  "required": [
    "headerParam1"
  ]
}

以上例子定義了必傳請求頭參數headerParam1。

title字段用於驗證失敗時提示使用，例如請求接口時沒傳請求頭時會提示“請求頭參數1不能爲空”（錯誤提示輸出通過校驗結果配置，詳情請看後文介紹），如圖所示。

當定義了語言配置（詳情請查看後文的語言配置介紹）選項爲英文時會使用titleEn字段用於驗證失敗時提示使用，例如請求接口時沒傳請求頭時會提示“headerParam1 is missing but it is required”（錯誤提示輸出通過校驗結果配置，詳情請看後文介紹），如圖所示。

請求體

定義聚合接口的請求體參數。

舉個例子：

{
  "type": "object",
  "properties": {
    "bodyParam1": {
      "type": "string",
      "title": "請求體參數1",
      "titleEn": "bodyParam1"
    }
  },
  "required": [
    "bodyParam1"
  ]
}

以上例子定義了必傳請求體參數bodyParam1。

title字段用於驗證失敗時提示使用，例如請求接口時沒傳請求體參數時會提示“請求體參數1不能爲空”（錯誤提示輸出通過校驗結果配置，詳情請看後文介紹），如圖所示。

當定義了語言配置（詳情請查看後文的語言配置介紹）選項爲英文時會使用titleEn字段用於驗證失敗時提示使用，例如請求接口時沒傳請求體參數時會提示“bodyParam1 is missing but it is required”（錯誤提示輸出通過校驗結果配置，詳情請看後文介紹），如圖所示。

Query參數

定義聚合接口的Query參數。

舉個例子：

{
  "type": "object",
  "properties": {
    "queryParam1": {
      "type": "string",
      "title": "query參數1",
      "titleEn": "queryParam1"
    }
  },
  "required": [
    "queryParam1"
  ]
}

以上例子定義了必傳Query參數queryParam1。

title字段用於驗證失敗時提示使用，例如請求接口時沒傳Query參數時會提示“query參數1不能爲空”（錯誤提示輸出通過校驗結果配置，詳情請看後文介紹），如圖所示。

當定義了語言配置（詳情請查看後文的語言配置介紹）選項爲英文時會使用titleEn字段用於驗證失敗時提示使用，例如請求接口時沒傳Query參數時會提示“queryParam1 is missing but it is required”（錯誤提示輸出通過校驗結果配置，詳情請看後文介紹），如圖所示。

腳本校驗

對於JSON Schema規範無法覆蓋的校驗場景可以使用腳本對入參進行更加靈活的處理。

點擊新增按鈕後彈出腳本配置窗口，如圖所示。

腳本類型：可選javascript|groovy，必選；

腳本內容：所選的腳本類型語言編寫的入參驗證腳本，必填。

舉個例子：

// javascript腳本函數名不能修改
function dyFunc(paramsJsonStr) {
  // 上下文, 數據結構請參考 context.js
  var context = JSON.parse(paramsJsonStr)['context'];
  // common爲內置的上下文便捷操作工具類，詳情請參考common.js；例如：
  // var data = common.getStepRespBody(context, 'step2', 'request1', 'data');

  // do something
  var headerParam1 = common.getInputReqHeader(context, 'headerParam1');
  var bodyParam1 = common.getInputReqBody(context, 'bodyParam1');
  var queryParam1 = common.getInputReqParam(context, 'queryParam1');
  var result = new Array();
  if (headerParam1 != bodyParam1) {
    result.push("headerParam1與bodyParam1不一致");
  }
  if (queryParam1 != bodyParam1) {
    result.push("queryParam1與bodyParam1不一致");
  }
  if (headerParam1 != queryParam1) {
    result.push("headerParam1與queryParam1不一致");
  }

  // 返回結果爲Array或Object時要先轉爲json字符串
  return JSON.stringify(result);
}

以上例子使用javascript編寫參數校驗，限制入參headerParam1、bodyParam1、queryParam1必須一致，不一致將提示錯誤信息（錯誤提示輸出通過校驗結果配置，詳情請看後文介紹），如圖所示。

語言配置

聚合接口默認使用中文響應校驗失敗提示，通過配置可通過入參選擇不同的提示語言，目前支持中文、英文提示（已滿足我們的業務使用場景，有其他語言要求的小夥伴可以聯繫我們添加）。

字段：入參字段值，例如input.request.body.languageCode使用請求體參數languageCode的值來決定使用哪種語言；

中文：中文與入參字段值的映射關係，例如配置0，當請求入參字段值爲0時使用中文提示校驗結果；

英文：英文與入參字段值的映射關係，例如配置1，當請求入參字段值爲1時使用中文提示校驗結果。

配置步驟

聚合接口調用底層服務是通過多個step實現的，多個step串行執行，每個step包含多個request（對底層服務接口的調用），同個step裏的多個request並行執行，後執行的step可以獲取已執行step的執行結果，更多詳情請查看服務編排文章的介紹，下面介紹配置步驟的使用。

是否執行完此步驟後結束：勾選後實際請求只執行完該步驟後即響應結果，不執行後續步驟，用於調試使用；

請求方法：調用底層服務接口的請求類型，可選GET|POST，必選；

默認URL：調用底層服務接口的默認URL，當Fizz網關啓動環境沒有配置URL時使用該默認URL；

開發環境URL：開發環境調用底層服務接口的URL，當Fizz網關啓動使用spring.profiles.active=dev時使用該URL；

測試環境URL：測試環境調用底層服務接口的URL，當Fizz網關啓動使用spring.profiles.active=test時使用該URL；

預生產環境URL：預生產環境調用底層服務接口的URL，當Fizz網關啓動使用spring.profiles.active=pre時使用該URL；

生產環境URL：生產環境調用底層服務接口的URL，當Fizz網關啓動使用spring.profiles.active=prod時使用該URL；

超時時間(毫秒)：調用底層服務接口的超時時間，超時拋出異常，單位毫秒；

Fallback：可選stop|continue，控制當調用底層服務接口失敗後是否繼續執行後續操作；

請求預處理：勾選後可配置預處理腳本，預處理腳本返回true時才執行調用底層服務接口。

配置入參：配置調用底層服務接口的請求參數；

配置響應：配置調用底層服務接口的響應內容。

配置步驟結果：配置step執行完成後的響應內容。

配置輸出

配置聚合接口調用完成的響應內容。在響應體、響應頭配置中可以配置簡單的響應固定值、響應引用值，對於需要邏輯處理得到結果的響應可以通過腳本配置靈活處理，如圖所示。

校驗結果

配置聚合接口入參校驗失敗後的響應內容，在響應體、響應頭配置中可以配置簡單的響應固定值、響應引用值，對於需要邏輯處理得到結果的響應可以通過腳本配置靈活處理，如圖所示。

校驗結果有一個專用的引用值validateMsg,該引用值用於存放入參驗證錯誤提示信息。

保存接口

所有配置完成後點擊保存按鈕，完成聚合接口的配置。

導出接口

導出功能將聚合接口以配置文件的形式導出，導出的文件可通過導入功能重新導入系統，當我們的系統分多個環境時，可使用導出導入功能實現聚合接口的快速同步，下面介紹導出功能。

勾選想到導出的接口，點擊導出按鈕彈出確認窗口，如圖所示。

點擊確定按鈕，瀏覽器保存配置文件，如圖所示。

導入接口

導入功能將配置文件中的聚合接口轉化成後臺的持久化存儲，導入的文件可以通過導出功能獲取或者通過編寫好的聚合配置JSON文件轉化得到（轉換工具可以聯繫我們獲取）。當我們的系統分多個環境時，可使用導出導入功能實現聚合接口的快速同步，下面介紹導出功能。

點擊導入按鈕彈出導入配置窗口，如圖所示。

點擊選取文件按鈕後選取要導入的配置文件；

強制覆蓋：通過請求類型（GET|POST）、請求路徑（/proxy/{service}/{apiPath}）可以唯一確定一個聚合接口，當聚合接口已存在時，未勾選該選項時忽略該聚合接口導入，勾選該選項時覆蓋已存在的聚合接口配置；

點擊確定按鈕後導入聚合接口配置。

調試模式

調試模式用於對接口開發過程中的調試使用，當打開調試模式後，Fizz網關會將聚合接口調用底層服務接口的請求響應信息以及耗時、聚合結果、步驟上下文打印到日誌中，通過日誌可以清楚的瞭解聚合接口的實際執行情況。調試模式會對網關性能造成影響，因此不建議在生產環境打開調試模式，當調試完成後及時關閉調試模式，避免打印過多日誌造成資源浪費，下面介紹調試模式的使用。

勾選想要打開調試模式的接口，點擊打開調試模式按鈕彈出確認窗口，如圖所示。