超媒体契约

前言

REST（Representational State Transfer）自2000年由Roy Fielding博士提出以来，已经成为事实上的API开发标准方案。其中HATEOAS（Hypermedia as the Engine of Application State）对资源的导航和发现做了详尽定义——但说实话，26年过去了，这套规范虽然依然广泛应用，但在一些细节上已经有些跟不上现代需求了。

举个例子，核心约束HATEOAS本意是实现资源的自发现和导航，可实际用处相当有限。一些严谨的系统会在返回中增加导航链接，但大部分系统基本忽略了这个机制。即便是那些尊重导航链接的API实现，返回的链接也往往缺乏通用性，局限性很明显。

本规范试图在这个基础上，对资源进行概念性的细分和明确定义，从而描述一套完整的资源自发现规则，让前端可以通过API获取完整且详尽的资源列表和资源定义。这样一来，前端完全可以采用一个通用的、固定的框架来处理任意的REST资源定义。符合本规范的情况下，后端可以随时调整API内容，前端则无需任何变更，自动适应后台的最新API。

需要说明的是，超媒体契约（RHC）并不适合所有场景。它的理想目标是：后端API可以任意快速迭代变更，前端无需做任何修改即可体现后端API的效果——解决的是前后端耦合过紧导致开发流程冗长缓慢的问题。在这个场景下，API的调用方称为前端，也就是一个最终的端点，没有后续的业务依赖。

对于不适用超媒体契约的场景，典型例子：后端A提供的API由后端B调用，那么后端B的相关业务甚至它提供的API都可能依赖于后端A的API。这种情况下，完全自动的API自发现、自适应可能会带来风险蔓延、业务断层等危险。这时候更适用文档化、固化不变的API定义。

超媒体契约最经典的应用场景是管理后台，尤其是硬件类、后台服务类的运维管理。这种场景下，前端是比较确定的网页应用，不存在下一步的业务依赖。另一个典型应用是为AI提供服务——API接口自带说明，给AI调用带来极大便利性。

核心思想

REST将一切用途统一为资源，所有操作都是针对资源的标准化操作。这种高层抽象让不同类型的应用都能用清晰一致的思路来解决问题。

超媒体契约（RHC）则是在这一层上做进一步的拆分和定义。它把REST中单一的资源概念细分为

和。空间是容器，实体是原有的资源概念。如果打个比方，空间就好比目录，实体就好比文件——而原有的REST只定义了全路径的文件这一个概念。

具体来说，在REST中一个API端点可能是 /api/v1/erm/account，这个全路径就是一个完整的端点。但从超媒体契约来看，这个全路径里的 /api、/api/v1、/api/v1/erm 都是空间，都有含义。

在RHC中，实体依然是原有的概念（这意味着完整兼容REST）。但对于空间，超媒体契约将其定义为包含子空间和实体的容器，且支持统一的枚举操作。换句话说，你可以直接访问空间API /api/v1/erm/，它会统一返回该空间下的所有子空间和实体，比如 user、account、order、flow，以及 finance（namespace）、salary（namespace）等等。

额外补充一点：超媒体契约需要一个

的概念，可以理解为根目录。从这个根开始，通过读取空间就能获得所有下一级的空间和资源——就像从根目录开始，你可以用 ls、cd 来发现并查看任意文件一样。因此，超媒体契约中需要明确定义根到底是 /api、/api/v1 还是 /api/v1/erm，只有明确了根，才能开始发现所有实体资源。而对REST来说，只需要一个完整路径 /api/v1/erm/account，从哪儿开始完全不关心。

概念定义

根或根空间

超媒体契约的起点位置。前端从这儿开始发现所有资源。根必然是空间，因此叫根空间，理解上可以视为根目录。

空间或空间资源

空间是实体的容器。空间本身只具备一个统一的操作：枚举其包含的内容（可能是其他空间，也可能是实体）。理解上可以视为文件夹、目录。空间的定义让REST更加层次化——通过空间将API分组，概念上更清晰。调用空间URL的API，可以有一套通用且标准化的行为，比如返回空间的详情，包括包含哪些子API等。这个是不受业务约束的顶层通用维度。如果是业务相关的，则可以自定义分组的规则在空间API上，比如权限控制、分组策略等。

实体或实体资源

等同于REST的资源概念。

资源类型和执行操作

RFC2616、7231、5789、9110中定义的HTTP方法共八种：GET、POST、PUT/PATCH、DELETE、HEAD、OPTIONS、TRACE、CONNECT。REST没有明确定义方法，但基于“万物皆资源”的思想，绝大多数研发设计人员都会把它往CRUD上靠，并对齐到POST、GET、PUT/PATCH、DELETE四个方法上。这种对齐简单可靠，事实上也能解决99%以上的问题。

但仍有一些很拗口、很生硬的资源化例子，比如登录/注销、转账、上车、下车。这些操作很难用合理、可理解且有基本共识的资源去做映射。当前绝大多数系统为了尊重REST，都生造了一个资源去映射——结果反而因为难以理解，从事实上违背了REST要达成简单思想共识的目标。

超媒体契约提出一个新规范建议：新增一种基本的方法类型为

。有些业务功能本身就是操作，硬要抽象成资源反而更难理解，那就单独定义一种类型：执行。登录/注销、转账就是本身的 login、logout、transfer，语义明确清晰，只是类型明确定义为 executable，不能用CRUD的方法去操作，唯一的操作就是直接调用执行。

这个思路显然简单清晰，但绝大多数人一开始这么想时总会犹豫或存疑：这算RESTful吗？从概念上可以澄清一下：如果万物都是资源，资源就可以是文件。熟悉操作系统底层机制的朋友都知道，“万物皆文件（句柄）”是现代操作系统的无上利器。既然万物都可以是文件，资源又有什么例外？而文件有一个基本属性：是否可执行。可执行的就是命令，不可执行的才是图片、文本等。所有文件类型之前，先分一个大类：是否可执行。Windows用扩展名区分，Linux更纯粹，直接给一个标记位 x。操作系统中，所有文件读取到系统首先也必须区分是否是可执行文件，然后单独分区标记并做安全检查。

我们只需要将REST的资源（RHC的实体资源）增加一个类型的定义，大类就是是否可执行，就可以完美解决类似登录/注销这类RESTful语义混淆的问题。也可以认为CRUD用作业务处理不够，需要加一个X——CURDX才能完整表征业务。可执行资源类型的定义将完善REST的细节，让API定义更合理化。

规则说明

完整的API自发现机制

对前端来说，唯一需要知道的就是后端API的根URL。由于根URL是空间资源，调用它就能获得下一级的空间和实体资源，如此遍历下去就可以发现全部API资源定义。

注1：空间的发现和枚举机制可以用通用的库实现，与业务无关。后台API只需按照固定的容器形式创建或配置API，即可自动支持枚举和发现。

注2：前端同样可以用通用库，获得根URL后自动展开API细节并适配参数。

CRUD之外的X

对于HTTP API来说，CRUD的操作平面目前已有比较通用且普遍接受的映射：POST、GET、PUT、DELETE。这些映射不仅被浏览器、网关广泛支持，也符合操作平面的幂等性和安全性要求。对于X来说，其幂等性和安全性都是最难的——常规HTTP method中，没有特别适合的映射。如果只考虑幂等性和安全性，唯一可以对应的是POST。当然，也可以扩展定义单独的方法来表示X的操作平面。下面分别展开。

方法1：单独定义一个EXECUTE的HTTP method

实现起来相当简单明了：在POST、GET、PUT、DELETE之外新增一个EXECUTE。存在的问题是，新增的自定义方法不在相关规范内，要注册成标准需要很长时间的讨论和定义，短期内无法成为标准。非标准的EXECUTE方法可能存在的隐患主要在复杂网络环境中适配性低——虽然绝大部分路由、网关、服务器不会拦截，但一些袋里、应用层网关、防火墙等有可能拦截非标准方法。在简单网络环境中，扩展EXECUTE是非常简单且实用的方法，对大部分应用来说足够。如果环境比较复杂，就要考虑兼容性和可用性了。

方法2：借用已有的POST，外加Content-Type约束

首先，适用于EXECUTE的常用HTTP method中，只有POST在幂等性和安全性上最符合。但POST常规上已被映射到CRUD的C，所以要细分。同时细分机制最好在HTTP标准规范中借用，这样兼容性最佳，可以无障碍运行于任何环境。向响应者增加自定义的HTTP header是最简单直接的方法，但需要自定义，同样会遇到方法1的兼容性问题，所以还不如用方法1。

在已有的HTTP header中，Content-Type无论从含义还是用法上，都非常接近资源类型的设定。因此可以从标准的HTTP header里的Content-Type中，选取规范化定义好的MIME类型来表示可执行的API资源类型。Content-Type（也叫media type）标准规范中定义的类型非常多（完整列表见IANA），其中符合可执行的标准类型有两个：application/prs.implied-executable 和 application/vnd.microsoft.portable-executable。另外要注意，Content-Type的内容比较灵活，即使填入自定义的类型，绝大多数系统也是兼容的。因此从严格标准化的角度，可以选用上述两个标准类型；一般情况下，自行定义一个 executable 也足够用。

参考引用

https://mimetype.io/all-types

https://www.iana.org/assignments/media-types/media-types.xhtml

https://www.iana.org/assignments/media-types/application/vnd.microsoft.portable-executable

https://www.iana.org/assignments/media-types/application/prs.implied-executable

[^safetysecurity]: Safety安全性和Security安全性. https://srs.pub/thinking/safety-security.html