目录端点中HATEOAS链接rel属性的命名规范咨询

结论 #

方案1的写法是符合HATEOAS行业标准的正确做法——列表中每个子资源对象的rel="self"指向该子资源的独立获取端点，顶层的rel="self"指向当前列表资源的端点。

核心规则依据 #

Web链接的核心规范明确了self关系的定义：self指向的是直接包含该链接的资源的标识URL。拆解来说：

• 顶层的_links属于整个列表资源（也就是host/resources返回的集合），所以它的self指向列表本身的URL；
• 每个子项里的_links属于单个具体资源（比如ID为1的资源），所以它的self必须指向该单个资源的独立获取地址（host/resources/1）。

主流实现参考 #

像HAL这种被广泛使用的HATEOAS序列化格式，完全遵循这个规则，标准的集合资源响应写法如下：

{
  "_links": {
    "self": { "href": "host/resources" }
  },
  "_embedded": {
    "resources": [
      {
        "id": 1,
        "_links": {
          "self": { "href": "host/resources/1" }
        }
      },
      {
        "id": 2,
        "_links": {
          "self": { "href": "host/resources/2" }
        }
      }
    ]
  }
}

子资源的self链接明确指向自身的独立资源地址，这是行业内的通用写法。

方案2的问题 #

用details作为rel虽然能实现跳转功能，但不符合HATEOAS的语义规范：

• self是标准化的关系类型，客户端可以直接依赖这个通用标识识别资源的自身地址，自定义的details需要额外的团队约定，会增加客户端的理解和对接成本；
• 违背了“链接关系语义对应资源身份”的原则，单个资源的自身标识就应该用self，details这种命名会模糊资源的身份指向，不符合HATEOAS“通过链接暴露资源关系”的核心思想。

内容的提问来源于stack exchange，提问作者Antonio Gamiz Delgado