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, "[***]"
  end

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

由于mu.semte.ch项目通常包含mu-cl-resources，mu.semte.ch项目的默认蓝图mu-semtech/mu-project已集成mu-cl-resources。

通过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使用括号()进行内容分组。括号后接单词通常表示组的内容；无单词时通常为列表。其他字符如反引号（`）或逗号（,）建议从示例中复制使用。

lisp
(define-resource person ()
  :class (s-url "[***]")
  :properties `((:name :string ,(s-url "[***]")))
  :resource-base (s-url "[***]")
  :on-path "people")

一个简单的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：

lisp
(define-resource person ()
  :class (s-prefix "foaf:Person")
  :properties `((:name :string ,(s-prefix "foaf:name")))
  :resource-base (s-url "[***]")
  :on-path "people")

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

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

lisp
(define-resource person ()
  :class (s-prefix "foaf:Person")
  :properties `((:name :string ,(s-prefix "foaf:name"))
                (:age :number ,(s-prefix "foaf:age")))
  :resource-base (s-url "[***]")
  :on-path "people")

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

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

lisp
(define-resource account ()
  :class (s-prefix "foaf:OnlineAccount")
  :properties `((:name :string ,(s-prefix "foaf:accountName")))
  :resource-base (s-url "[***]")
  :on-path "accounts")

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

lisp
(define-resource person ()
  :class (s-prefix "foaf:Person")
  :properties `((:name :string ,(s-prefix "foaf:name"))
                (:age :number ,(s-prefix "foaf:age")))
  :has-many `((account :via ,(s-prefix "foaf:account")
                       :as "accounts"))
  :resource-base (s-url "[***]")
  :on-path "people")

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

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

lisp
(define-resource account ()
  :class (s-prefix "foaf:OnlineAccount")
  :properties `((:name :string ,(s-prefix "foaf:accountName")))
  :has-one `((person :via ,(s-prefix "foaf:account")
                     :inverse t
                     :as "owner"))
  :resource-base (s-url "[***]")
  :on-path "accounts")

完整的user和account设置如下：

lisp
(define-resource person ()
  :class (s-prefix "foaf:Person")
  :properties `((:name :string ,(s-prefix "foaf:name"))
                (:age :number ,(s-prefix "foaf:age")))
  :has-many `((account :via ,(s-prefix "foaf:account")
                       :as "accounts"))
  :resource-base (s-url "[***]")
  :on-path "people")

(define-resource account ()
  :class (s-prefix "foaf:OnlineAccount")
  :properties `((:name :string ,(s-prefix "foaf:accountName")))
  :has-one `((person :via ,(s-prefix "foaf:account")
                     :inverse t
                     :as "owner"))
  :resource-base (s-url "[***]")
  :on-path "accounts")

/configuration/repositories.lisp

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

lisp
(add-prefix "foaf" "[***]")

生成的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属性、描述语义模型）。

json
{
  "version": "0.1",
  "resources": {
    "people": {
      "name": "person",
      "class": "[***]",
      "attributes": {
        "name": {
          "type": "string",
          "predicate": "[***]"
        }
      },
      "new-resource-base": "[***]"
    }
  }
}

使用前缀简化配置：

json
{
  "version": "0.1",
  "prefixes": {
    "foaf": "[***]"
  },
  "resources": {
    "people": {
      "name": "person",
      "class": "foaf:Person",
      "attributes": {
        "name": {
          "type": "string",
          "predicate": "foaf:name"
        }
      },
      "new-resource-base": "[***]"
    }
  }
}

添加多个属性（如age）：

json
{
  "version": "0.1",
  "prefixes": {
    "foaf": "[***]"
  },
  "resources": {
    "people": {
      "name": "person",
      "class": "foaf:Person",
      "attributes": {
        "name": {
          "type": "string",
          "predicate": "foaf:name"
        },
        "age": {
          "type": "number",
          "predicate": "foaf:age"
        }
      },
      "new-resource-base": "[***]"
    }
  }
}

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

json
{
  "version": "0.1",
  "prefixes": {
    "foaf": "[***]"
  },
  "resources": {
    "people": {
      "name": "person",
      "class": "foaf:Person",
      "attributes": {
        "name": {
          "type": "string",
          "predicate": "foaf:name"
        },
        "age": {
          "type": "number",
          "predicate": "foaf:age"
        }
      },
      "relationships": {
        "accounts": {
          "predicate": "foaf:account",
          "target": "account",
          "cardinality": "many"
        }
      },
      "new-resource-base": "[***]"
    },
    "accounts": {
      "name": "account",
      "class": "foaf:OnlineAccount",
      "attributes": {
        "name": {
          "type": "string",
          "predicate": "foaf:accountName"
        }
      },
      "relationships": {
        "owner": {
          "predicate": "foaf:account",
          "target": "person",
          "cardinality": "one",
          "inverse": true
        }
      },
      "new-resource-base": "[***]"
    }
  }
}

组合domain.lisp和domain.json

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

lisp
(in-package :mu-cl-resources)

(read-domain-file "users.json")
(read-domain-file "publications.lisp")

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

使用domain.json配置设置

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

lisp
(in-package :mu-cl-resources)

(read-domain-file "domain.json")

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

参考

在Lisp中定义资源

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

lisp
(define-resource person ()
  :class (s-prefix "foaf:Person")
  :properties `((:name :string ,(s-prefix "foaf:name")
                       :required)
                (:age :number ,(s-url "[***]")))
  :has-one `((location :via ,(s-prefix "foaf:based_near")
                       :as "location"))
  :has-many `((account :via ,(s-prefix "foaf:account")
                       :as "accounts")
              (document :via ,(s-prefix "foaf:publications")
                        :as "publications"))
  :features '(include-uri)
  :resource-base (s-url "[***]")
  :on-path "people")

关键字概述

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