API-Platform实现Richardson Maturity Model level3相关问题咨询

云上老周

2026-10-5

API-Platform适配Richardson Maturity Model Level3解决方案

规范适配判断

Richardson Maturity Model Level3（HATEOAS级）要求响应中包含当前资源所有可执行操作的入口链接，仅返回资源自身URI的"@id": "/api/users/87"不符合完整规范要求，必须额外补充删除、更新、关联资源跳转等操作的对应链接才算达标。

配置问题修复

首先卸载willdurand/hateoas-bundle，API Platform已原生内置HATEOAS支持，第三方bundle会与内置逻辑冲突，导致链接生成失效。
406 Not Acceptable错误是由于请求头未匹配你配置的返回格式导致，请求时需要在Accept头指定application/hal+json，也可以调整api_platform.yaml配置兼容多格式避免错误，配置参考：

api_platform:
    formats:
        jsonhal: ['application/hal+json']
        json: ['application/json']
    patch_formats:
        json: ['application/merge-patch+json']

操作链接无需手动配置，API Platform会自动根据你在实体类中#[ApiResource]注解声明的操作，生成对应HATEOAS链接。正确请求后返回的_links字段会自动包含所有允许的操作入口，示例返回如下：

{
  "@context": "/api/contexts/User",
  "@id": "/api/users/87",
  "@type": "User",
  "id": 87,
  "username": "test",
  "_links": {
    "self": {
      "href": "/api/users/87"
    },
    "patch": {
      "href": "/api/users/87"
    },
    "delete": {
      "href": "/api/users/87"
    },
    "collection": {
      "href": "/api/users"
    }
  }
}