walder
v4.1.3
Walder提供了一種簡單的方法，可以在分散的知識圖上設置網站或Web API。知識圖將數據與該數據的含義結合在一起。即使不同的獨立各方維護或託管了多個知識圖，也可以將數據組合起來。知識圖可以通過實心吊艙，SPARQL端點，三模式片段接口，RDF文件等託管。使用內容談判，Walder通過HTML，RDF和JSON-LD可以為客戶提供這些知識圖中的數據。用戶在數據Walder使用的配置文件中定義以及如何處理此數據。找出在這裡使用Walder構建的API。
目錄
通過yarn global add walder在全球安裝Walder。
為了開發，請執行以下步驟：
yarn install安裝依賴項。$ yarn global add file:$(pwd)在全球安裝Walder。 Walder可作為CLI和JavaScript庫。
Usage: walder [options]
Options:
-v, --version output the version number
-c, --config < configFile > YAML configuration file input
-p, --port [portNumber] server port number (default: 3000)
-l, --log [level] enable logging and set logging level (one of [error, warn, info, verbose, debug]) (default: " info " )
--no-cache disable Comunica default caching
--lenient turn Comunica errors on invalid data into warnings
-h, --help output usage information // From the root directory
const Walder = require ( '.' ) ;
const configFilePath = 'path/to/configfile' ;
const port = 9000 ; // Defaults to 3000
const logging = 'info' ; // Defaults to 'info'
const cache = false ; // Defaults to true
const lenient = true ; // Defaults to false
const walder = new Walder ( configFilePath , { port , logging , cache , lenient , cwd } ) ;
walder . activate ( ) ; // Starts the server
walder . deactivate ( ) ; // Stops the server在OpenAPI 3.0規範之後，您在YAML中編寫一個配置文件。配置文件必須具有以下結構：
openapi : 3.0.2
info : # OpenAPI metadata
title : ' Example site '
version : 0.1.0
x-walder-resources : # Directories used by Walder - OPTIONAL
root : # Path to the root folder of the directories used by Walder (absolute or relative to the directory containing the config file) - OPTIONAL (default: .)
views : # Path to directory containing view template files (absolute or relative to the root folder) - OPTIONAL (default: views)
pipe-modules : # Path to directory containing local pipe modules (absolute or relative to the root folder) - OPTIONAL (default: pipe-modules)
public : # Path to directory containing all files that should be available statically (e.g. stylesheets) (absolute or relative to the root folder) - OPTIONAL (default: public)
layouts : # Path to directory containing all layout template files that can be used by view template files (absolute or relative to the root folder) - OPTIONAL (default: layouts)
x-walder-datasources : # Default list of data sources
- ... # E.g. link to SPARQL endpoint or a GraphQL-LD query
paths : # List of path entries
path-entry-1 :
...
path-entry-2 :
...
x-walder-errors : # Default error page views - status codes with files containing the HTML view template (absolute path or relative to the views directory)
404 : ...
500 : ...
... 配置文件的x-walder-resources鍵包含Walder使用的目錄的路徑。此鍵及其值是可選的。如果用戶不提供路徑，則Walder使用以下默認值相對於配置文件的目錄。
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts為了防止Walder公開錯誤的文件，當用戶沒有通往public字段的路徑時，如果Walder在當前的工作目錄中找不到此目錄並使用該目錄，則public會創建新的目錄。
路徑條目定義了路線，並具有以下結構：
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
json-ld-context : ... # The JSON-LD corresponding to the GraphQL query
sparql-query : ... # One or more SPARQL queries
json-ld-frame : ... # A JSON-LD frame that should be applied to the result of a SPARQL query
options : # Global options that will be applied to all the graphql-queries of this path (OPTIONAL)
datasources : # Query specific datasources (OPTIONAL)
additional : ... # Boolean stating that the following datasources are meant to be used on top of the default ones
sources : # List of query specific datasources
- ... # E.g. link to SPARQL endpoint
x-walder-postprocessing : # The (list of) pipe modules used for postprocessing
module-id : # Identifier of the pipe module
source : ... # Path leading to source code of the pipe module (absolute path or relative to the pipe-modules directory)
parameters : # the parameters for the pipe module (OPTIONAL)
- _data # (DEFAULT) this gives all the data, but all paths in the data object are supported (e.g. _data.0.employee)
- ... # Additional parameters if your function supports those (OPTIONAL)
responses : # Status codes with files containing the HTML view template (absolute path or relative to the views directory)
200 : ... # (REQUIRED)
500 : ... # (OPTIONAL)以下命令使用示例配置文件在端口3000（默認）上啟動服務器。
$ walder -c example/config.yaml
這將在localhost:3000 ，並使用以下路線：
在上面的路徑條目中，用戶將options定義為Walder在該路徑的每個查詢中使用的全局（可選）標識符。我們有兩個可以選擇的選項： sort和remove-duplicates 。具有給定的語法：
options :
sort : # Enable sorting on the data (OPTIONAL)
object : # JSONPath to the object you want to sort for
selectors : # The values inside the object over which you want to sort
- ... # The default option when you want ascending order, just give the value (JSONPath notation supported for further nesting)
- value : ... # When you want descending order, specify the value/order (JSONPath notation supported for further nesting)
order : desc
remove-duplicates : # Enable the removal of duplicates of the data (OPTIONAL)
object : ... # The JSONPath tot the object that you want to compare
value : ... # The value that has to be compared to determine whether it's duplicate (JSONPath notation is also supported for further nesting)如果您不希望options成為整個路徑的全局，則可以定義每個查詢的options 。
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
name :
query : ... # The GraphQL query
options : # options that will be applied only to this specific graphql-query (OPTIONAL)
...以下命令使用此配置文件啟動服務器。
$ walder -c example/config-sorting-duplicates.yaml
這將在localhost:3000 ，並使用以下路線：
您可以使用$ref關鍵字將配置文件拆分在多個文件中。我們遵循OpenAPI 3.0規格，該規範說明瞭如何使用引用。
首次引用時，您需要使用從配置文件目錄開始的路徑，但是如果引用文件具有引用本身，則可以使用相對於其自己的位置的路徑，如下所示。
實際配置文件引用其路徑
openapi : 3.0.2
info :
title : ' Example site '
version : 0.1.0
x-walder-resources :
path : ./
views : views
pipe-modules : pipeModules
public : public
x-walder-datasources :
- http://fragments.dbpedia.org/2016-04/en
paths :
/music/{musician} :
$ref : ' ./paths/music_musician.yaml '
/movies/{actor} :
$ref : ' ./paths/movies_actor.yaml '
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html下面您可以看到./example/paths/movies_actor.yaml paths/movies_actor.yaml，帶有相對於自己的位置的路徑
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : path
name : actor
required : true
schema :
type : string
description : The target actor
x-walder-query :
$ref : ' ../walderQueryInfo/movies_actor_info.yaml '
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
使用內容協商，Walder可提供以下輸出格式：
Walder使用GraphQl-LD-Comunica執行GraphQl查詢， @Comunica/Query-Sparql執行SPARQL查詢。 GraphQL-LD查詢的結果是JSON數據。 Walder首先將其轉換為JSON-LD。這可以在內容協商期間轉換為其他RDF格式。 SPARQL查詢的結果是四邊形。如果指定了JSON-LLD幀，則四分之一將轉換為JSON-LD。由於內容談判的重要性，僅支持構造查詢。
Walder使用合併自動檢索給定模板的相應引擎。這意味著受支持的模板引擎取決於合併。
您可以將不同的模板引擎用於不同的路線，例如，pug呈現一個路線的HTML，而車把呈現另一個路線的HTML。 Walder通過查看給定模板的文件擴展來完成這一切。
模板可以在視圖和佈局中使用。因此，我們將它們命名為查看模板和佈局模板以區分。
路由的配置文件中指定的查詢結果可在視圖模板中作為數據渲染。
data的對象。在GraphQl-LD查詢的情況下，除非查詢被單數化，否則每個對象將是一個數組。 Songs.Handlebars是此配置文件中路由/music/{musician}中單個查詢結果消耗的示例。 sonse_movies.handlebars是該配置文件中/artist/{artist}中兩個查詢結果消耗的示例。
在SPARQL查詢的情況下，如果未指定JSON-LD框架，則每個對像都是四元組。否則它將是一個JSON-LD對象。
使用佈局是避免在路由特定的視圖模板中重複重複的好方法。可重複使用的HTML結構，例如標題，頁腳，導航欄和其他內容，旨在出現在多個路由中，在佈局文件中可以選擇。
可以在視圖模板文件中指定佈局模板文件，該文件通過前後元數據字段layout 。它應包含一個文件名，可在配置文件中定義的layouts位置可用。它可能包含文件名前方的相對路徑。
示例查看模板文件指定佈局：
---
layout: my-layout.pug
---
// view template continues here
Walder將從視圖模板文件生成的內部HTML內容作為命名content的對象轉發到佈局模板文件的數據。
佈局模板文件是另一個模板。它通常會在其選擇位置擴展這些內部HTML內容。
一個簡單的哈巴狗示例（請注意!{content} ）：
doctype html
html(lang="en")
head
title I'm based on a layout
body !{content}
除了查詢結果外，Walder還添加了視圖模板中指定的前結物元數據，作為數據的附加屬性。
每個附加屬性的名稱都等於提供的元數據字段名稱。保留以下元數據字段： layout ， content ， data以及分配給具有多個查詢路由的查詢的名稱（請參見上文）。
這些屬性可用於視圖模板以及它指的是所指的佈局模板（如果有）。
示例查看模板文件指定前結物元數據字段並讀取該字段（請注意#{a1} ）：
--
a1: Value for FrontMatter attribute a1!
---
doctype html
html(lang="en")
body
main a1: #{a1}
示例查看模板文件，指定佈局模板和另一個前結物元數據字段：
---
layout: layout-fm.pug
a2: Value for FrontMatter attribute a2!
---
main Lorem ipsum
示例對應的佈局模板（layout-fm.pug）讀取該字段（請注意#{a2} ）：
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
在解析配置文件時，Walder還驗證了輸入的正確性和完整性。當Walder解析整個配置文件並發現錯誤時，Walder會返回所有錯誤和退出。
目前，沃爾德（Walder）驗證以下內容：
200~x-walder-input-text/html條目中提及現有文件。 Walder將錯誤頁面綁定到某個HTTP狀態代碼。您可以通過將它們添加到相應的路徑條目中的responses密鑰中來定義默認錯誤頁面，也可以通過路徑特定的錯誤頁面進行定義。
404 ：找不到頁面500 ：內部服務器錯誤500 ：無法應用給定的管道模塊404 ：未給出預期變量500 ：無法執行給定查詢當您使用以下命令運行walder時：
$ walder -c example/config-errors.yaml
以下途徑導致錯誤：
404 （全局：找不到頁面）500 （管道模塊：無法應用給定的管道模塊）500 （graphql-d：無法執行給定查詢）以下配置文件摘錄將使用路徑特定的moviesServerError.handlebars視圖模板在導航到/movies時導致狀態代碼500的錯誤。
當未傳遞所需的查詢參數actor時，Walder將返回狀態代碼404 。 Walder將使用默認error404.html文件，因為配置文件沒有針對相應狀態的路徑特定的HTML視圖模板。
...
paths :
/movies :
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : query
name : actor
schema :
type : string
minimum : 0
description : The actor from whom the movies are requested
required : true
x-walder-query :
graphql-query : >
{
id @single
... on Film {
starring(label: $actor) @single
}
}
json-ld-context : >
{
"@context": {
"Film": "http://dbpedia.org/ontology/Film",
"label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@language": "en" },
"starring": "http://dbpedia.org/ontology/starring"
}
}
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
500 :
description : internal movie server error
x-walder-input-text/html : moviesServerError.handlebars
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html 在開發網站的同時，您可能希望您的網站重新加載，同時更改config.yaml 。您可以使用NPM-watch輕鬆執行此操作。請參閱下面的package.json 。
{
"watch" : {
"run" : " config.yaml "
},
"scripts" : {
"run" : " walder -c config.yaml --no-cache " ,
"watch" : " npm-watch "
},
"dependencies" : {
"walder" : " ^2.0.1 "
},
"devDependencies" : {
"npm-watch" : " ^0.7.0 "
}
}運行npm run watch ，Walder重新加載每個config.yaml更改！
| 圖書館 | 執照 |
|---|---|
| @comunica | 麻省理工學院 |
| 接受 | 麻省理工學院 |
| 軸 | 麻省理工學院 |
| 柴 | 麻省理工學院 |
| 指揮官 | 麻省理工學院 |
| 合併 | 麻省理工學院 |
| 偵錯 | 麻省理工學院 |
| 表達 | 麻省理工學院 |
| 前象 | 麻省理工學院 |
| FS-Extra | 麻省理工學院 |
| GraphQL-LD | 麻省理工學院 |
| GraphQl-LD-Comunica | 麻省理工學院 |
| 車把 | 麻省理工學院 |
| is-html | 麻省理工學院 |
| 翡翠到手柄 | 麻省理工學院 |
| JSON-RFS | 麻省理工學院 |
| jsonld | BSD-3-C-sause |
| JSONPATH | 麻省理工學院 |
| Markdown-it | 麻省理工學院 |
| 摩卡 | 麻省理工學院 |
| 摩根 | 麻省理工學院 |
| N3 | 麻省理工學院 |
| 對象路徑 | 麻省理工學院 |
| 帕格 | 麻省理工學院 |
| 超級 | 麻省理工學院 |
| TMP | 麻省理工學院 |
| 溫斯頓 | 麻省理工學院 |
| yaml | ISC |
您是否構建了一些Walder並想將其添加到列表中？請創建拉動請求！
該代碼是Ghent University（IMEC）版權所有的©2019–2020，並根據MIT許可發布。
