java - 如何在微服务架构(HAL、ALPS)中为 Restful 服务正确设置文档

Question

我已经阅读了很多关于如何正确设置微服务的文章，而且我一直对一些较新的概念很感兴趣，包括:HAL、ALPS 和 HAL 浏览器。我曾经记录过利用 Swagger UI 的事情，但是，我开始明白以 URL 为中心不是正确的方法，我应该围绕资源和链接组织文档，这正是新技术的目的。我在这些较新的概念方面存在很多知识空白，因此我想正确理解这些技术如何协同工作，以便在我了解每一项技术时能够将它们融入到这个难题中。

我目前的理解是:

HAL - 是 JSON 之上的一种附加格式，可让您通过链接在 API 中导航。

ALPS - 这是一种在 JSON 之上的附加格式，可以让我提供基于英语的描述来帮助描述我的资源

HAL 浏览器 - 以资源和链接为中心的文档的 Swagger UI 替换。与 HAL 和 ALPS 一起工作？

我目前对这些技术的理解在某些领域是准确的还是欠缺的？同样在实现方面，我并不完全理解 ALPS 和 HAL 如何相互作用。我知道 hal+json 格式和 alps+json 格式，但我还没有看到 hal+alps+json 格式。

我想澄清的最后一个方面是我应该如何公开这些资源。通常，我总是关注非常精简的 json 消息是围绕预期发送 hal+json 格式，还是我应该将这些端点托管在另一个 URL 上，专门用于类似于 swagger/HAL 浏览器的文档？

Answer 1

伙计!你想在这里看到的信息太多了。让我尝试逐步解释。

以文档为中心意味着服务之间的转换，是的，它应该被称为网络上的语义共享信息(或理解为数据类型)。

步骤:1 用于具有数据类型元数据和标准数据类型的服务的协议(protocol) (http) 可以是任何形式的超媒体，即 HTML、XML、JSON、HAL 等。 例如下面显示的 JSON，它是一个带有链接的根文档。 “todos”和“profile”都只是基于 HAL 的超媒体链接，而 HAL 只会增强您当前的 API。

{ "_links" : {
    "todos" : {
      "href" : "http://localhost:8080/todos"
    },
    "profile" : {
      "href" : "http://localhost:8080/alps"
    }
  }
}

请注意，它只是与可能指向资源语义的资源链接的链接。 HAL 的主要焦点只是通过链接、属性和/或嵌入来链接资源/模板。 上面解释的可供性主要是协议(protocol)级别的链接共享数据类型。

步骤:2 ALPS 是应用程序级别的启示，这意味着在上面的 JSON 中我知道 Todo 是什么但如何与之交互？要与 Todo 交互，需要有应用程序级别的状态转换。 考虑下面的“待办事项”JSON，它从链接导航并显示详细的额外关键字，例如“描述符”和“类型”(SEMANTIC、SAFE、UNSAFE 等)。

'id' 属性成为表示标识符。这些是应用独立 ALPS 状态和转换的集合或规则。

{ "version" : "1.0",
  "descriptors" : [ {
    "id" : "todo-representation",
    "descriptors" : [ {
      "name" : "description",
      "doc" : {
        "value" : "Details about the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "title",
      "doc" : {
        "value" : "Title for the TODO item",
        "format" : "TEXT"
      },
      "type" : "SEMANTIC"
    }, {
      "name" : "id",
      "type" : "SEMANTIC"
    } ]
  }, {
    "id" : "get-todos",
    "name" : "todos",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "create-todos",
    "name" : "todos",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "delete-todo",
    "name" : "todo",
    "type" : "IDEMPOTENT",
    "rt" : "#todo-representation"
  }, {
    "id" : "patch-todo",
    "name" : "todo",
    "type" : "UNSAFE",
    "rt" : "#todo-representation"
  }, {
    "id" : "get-todo",
    "name" : "todo",
    "type" : "SAFE",
    "rt" : "#todo-representation"
  } ]
}

一些链接值得详细查看slides about ALPS和 Rest Example .希望这有助于您理解。