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许可发布。
