semtech/mu-cl-resources

mu-cl-resources：JSONAPI与SPARQL的双向转换

mu-cl-resources提供符合JSONAPI规范的接口，用于访问配置中指定的内容。大部分配置在configuration/domain.json或configuration/domain.lisp文件中进行（可选择其一），本仓库中提供了相关示例。

大部分配置在领域文件中完成。参见configuration/domain.json和configuration/domain.lisp了解入门知识。该文件定义了JSON世界与RDF世界之间的连接。定义模型时，需明确两个世界的结构。

本文档内容并非详尽无遗。该组件可处理多种用例，并支持实验性的特殊功能（可能在后续版本纳入核心功能）。因此，本README未涵盖组件的所有功能。

domain.json格式仍在发展中，部分配置参数只能在Lisp版本中设置。可组合使用两种格式，参见教程：组合domain.lisp和domain.json。

教程

将mu-cl-resources添加到栈中

在docker-compose.yml的services块中添加以下片段：

yml
services:
  resource:
    image: semtech/mu-cl-resources:1.20.0
    links:
      - db:database
    volumes:
      - ./config/resources:/config

接下来，将本仓库examples/文件夹中的配置文件复制到项目的./config/resources文件夹中。需复制JSON配置文件examples/domain.json或Lisp配置文件examples/domain.lisp和examples/repository.lisp。

最后，在项目的./config/dispatcher/dispatcher.ex的调度器配置中添加新规则，将/themes的请求转发到新的资源服务：

yml
  get "/themes/*path", @any do
    forward conn, path, "http://resource/themes/"
  end

运行docker-compose up -d启动栈。假设标识符在80端口发布，向http://localhost/themes发送请求应返回来自mu-cl-resources的空数组。

由于mu.semte.ch项目通常包含mu-cl-resources，mu.semte.ch项目的默认蓝图https://github.com/mu-semtech/mu-project%E5%B7%B2%E9%9B%86%E6%88%90mu-cl-resources%E3%80%82

通过domain.lisp配置介绍

该服务由domain.lisp文件驱动，需根据领域需求调整该文件。本节简要说明各部分如何协同工作，以及如何快速启动API。

mu-cl-resources由domain.lisp文件驱动。该文件描述JSONAPI与语义模型之间的连接。其次是repository.lisp文件，可在其中定义新前缀以简化领域描述。本仓库的examples文件夹中提供了这两个文件的示例。

/configuration/domain.lisp

domain.lisp包含应用中每种资源类型的定义。这些定义提供三向连接：

• 在domain.lisp文件中命名事物以建立连接
• 描述通过JSON API可见的属性
• 描述用于实现JSON API的语义模型

每个资源定义都是这三种视图的组合。假设使用foaf示例，建模一个拥有一个或多个在线账户的Person。可使用WebVOWL可视化该模型。

补充说明：mu-cl-resources主要通过Lisp配置。Lisp使用括号()进行内容分组。括号后接单词通常表示组的内容；无单词时通常为列表。其他字符如反引号（`）或逗号（,）建议从示例中复制使用。

CODE_TOKEN_2

一个简单的person定义使用foaf词汇表描述person和person name。

• 第1行：define-resource person表示创建一个新端点，在文件中命名为person（通常使用单数形式）。
• 第2行：指定三元组存储中person所属的RDF类为foaf:Person。
• 第3行：指定person的单个属性。JSONAPI将string类型的内容存储在data.attributes.name中（因:name），该值通过三元组存储中的谓词foaf:name与资源连接。注意属性名可包含连字符，但不区分大小写（忽略大写字母）。
• 第4行：创建此类新资源时在三元组存储中使用的URI前缀，会追加UUID。
• 第5行：指定可列出/创建/更新资源的端点，此处/people请求映射到该资源。

假设定义了foaf前缀，可简化示例，使用s-prefix：

CODE_TOKEN_3

此代码与上述示例功能相同，但更易读。

可添加多个属性，例如添加age属性（数字类型）：

CODE_TOKEN_4

通过此修改，person支持name和age属性。

大多数资源链接到其他资源。首先定义第二个资源OnlineAccount：

CODE_TOKEN_5

account资源的定义与person类似。使用:has-many关键字将person链接到多个account：

CODE_TOKEN_6

第5-6行指定person可链接到多个account类型的资源。在三元组存储中，通过foaf:account谓词查找链接。该关系通过JSON API的关系名称"accounts"暴露，因此GET /people/42/accounts将返回UUID为42的person的账户。

使用:has-one关键字获取链接到account的person，并添加:inverse t选项表示沿相反方向跟踪关系：

CODE_TOKEN_7

完整的user和account设置如下：

CODE_TOKEN_8

/configuration/repositories.lisp

上述示例使用foaf前缀表示类和属性。/configuration/repositories.lisp允许定义自定义前缀，常用缩写可参考prefix.cc。

CODE_TOKEN_9

生成的API

支持JSONAPI规范，常见调用示例：

• # GET /people

• # GET /people/0b29a57a-d324-4302-9c92-61958e4cf250/accounts

• # GET /people?filter=John

• # GET /people?filter[age]=42

• # GET /people?include=accounts

• # GET /people?filter[:exact:name]=John%20Doe

• # GET /people?sort=age

• # GET /accounts?sort=-person.age

• # POST /people/0b29a57a-d324-4302-9c92-61958e4cf250

• # PATCH /people/0b29a57a-d324-4302-9c92-61958e4cf250

• # PATCH /people/0b29a57a-d324-4302-9c92-61958e4cf250/relationships/accounts

• # DELETE /people/0b29a57a-d324-4302-9c92-61958e4cf250/relationships/accounts

• # DELETE /people/0b29a57a-d324-4302-9c92-61958e4cf250

更多配置选项

• mu-cl-resources选项：通过domain.lisp文件中的顶级defparameter表达式指定。
• 资源特定选项：与:class同级的:features关键字可指定修改特定资源行为的选项。
• 属性选项：单个属性定义后的符号可提供关于属性使用方式的额外信息。

通过domain.json配置介绍

mu-cl-resources通过domain.json文件驱动，该文件描述JSONAPI与语义模型之间的连接。本仓库的examples文件夹中提供了示例文件。

/configuration/domain.json

domain.json包含应用中每种资源类型的定义，提供三向连接（命名事物、描述JSON属性、描述语义模型）。

CODE_TOKEN_10

使用前缀简化配置：

CODE_TOKEN_11

添加多个属性（如age）：

CODE_TOKEN_12

定义关系（如person拥有多个account）：

CODE_TOKEN_13

组合domain.lisp和domain.json

对于大型应用，可将领域定义分散到多个文件。根领域文件必须为Lisp格式，包含的文件可以是Lisp或JSON格式。在domain.lisp顶部添加read-domain-file语句：

CODE_TOKEN_14

重启服务后，mu-cl-resources将加载额外配置文件。

使用domain.json配置设置

若使用domain.json定义资源，需创建domain.lisp文件并添加：

CODE_TOKEN_15

在domain.lisp中添加设置，重启服务后生效。

参考

在Lisp中定义资源

define-resource结构用于定义资源，示例：

CODE_TOKEN_16

关键字概述

• :class：设置实例所属的RDF类。
• :properties：描述资源属性（对应JSON attributes）。
• :has-one：描述最多一个的关系。
• :has-many：描述零个或多个的关系。
• :features：资源使用的可选功能（如include-uri返回URI）。
• :resource-base：新资源的URI前缀。
• **