EnhancedREST 1.0.0 规范

阅读知识背景要求

  • 熟悉HTTP/1.1协议以及MIME-types
  • 熟悉RESTful
  • 熟悉分布式事务处理模型
  • 了解OAuth2协议
  • 了解Kerberos (V5) 协议
  • 了解Hash单向函数

修订历史

  • 1.0.0 首次发布

背景与目标

编写背景

RESTful 是一个将HTTP传输协议以及JSON报文体相结合的RPC通信风格,但目前并不存在一个得到普遍认可和约束的工业技术规范。

由于RESTful风格形式简洁,工具链丰富,收到广大开发者的喜爱。同时也由于其落地实现的随意性,导致各大企业都有不同的落地实现方法,形成了不同形态的「方言」。无形之中增加了软件互联的成本,造成了有限的研发资源浪费。

编写目标

「书同文车同轨」,规范不同系统之间的技术标准,降低产品间的集成成本,提高研发效率,促进各产品规范、有序发展。

基本约定

  1. 本规范中涉及大量对HTTP/1.1 协议的标准引用,对于HTTP Header中各项规范定义,本规范以”X-RL-”作为前缀进行扩展,未扩展的遵循RFC所定义的含义。

限制条件

  1. 本规范主要的使用范围,主要位于后端服务之间的RPC通信。
  2. 对于每个Client/Server具有唯一性标识生成能力的要求。

修订计划

  • 补充TCC模式技术规范
  • 在对本规范进行实现之后,进行部分的内容修订

分布式事务的RPC模式简介

Commit-Compensation (CC)

「提交-补偿」模式:要求提供方提供对原请求的补偿(也称作撤销,反向)操作能力。

双方可依照5个操作进行RPC通信: * Commit 提交 * Compensation 补偿 * Status 状态 * Fetch 获取 * Trace 跟踪

Try-Confirm/Cancel (TCC)

「尝试-确认/取消」模式:要求提供方提供资源预留、资源确认消费,资源预留取消的操作能力;要求提供方具备进行尝试操作后,自动针对「未确认操作」进行自动「取消」的能力。

双方可依照6个操作进行RPC通信: * Try 尝试 * Confirm 确认 * Cancel 取消 * Status 状态 * Fetch 获取 * Trace 跟踪

Event Sourcing (ES)

「事件溯源」模式:要求事件产生方(事件源)对消息根据时间排序;要求事件消费方根据事件发生顺序有序处理;要求在事件消费方(也就是DDD模型中的聚合根)对来自多个事件源的事件进行处理时,具备复杂事件处理(CEP)的能力。

由于事件产生方与事件消费方采用异步消息模式进行通信,因此本规范暂时不对ES模式进行技术规范的约束。

EnhancedREST-CC模式

Client Side 技术标准

Client Side 请求结构

  • Consumer-Agent
    • Client Group (MUST)
    • Client Name (MUST)
    • Client Version (SHOULD)
    • Cluster Group (MUST)
    • Cluster Name (MUST)
    • InstanceId (MUST)
  • Request-Metadata
    • Consumer
      • Consumer Group (MUST)
      • Consumer Name (MUST)
      • Consumer Version (MUST)
    • MessageId (MUST)
    • RequestId (MUST)
    • TransactionId (SHOULD)
    • Content-Type (SHOULD)
      • Serialization Method (MUST)
      • Data Structure Version (SHOULD)
    • InstanceId (SHOULD)
    • Accept (COULD)
    • Access Token (Security Considerations)
      • Client Access Token
      • Consumer Access Token
    • Request HMAC (Security Considerations)
    • Timeout (COULD)
  • Consumer-Request
    • 5 Types
      • Commit
      • Compensation
      • Status
      • Fetch
      • Trace
    • Request-Body

Client Side 概念定义

  • Consumer Consumer

是指请求的实际产生者,不包括自然人。

  • Consumer Group Consumer Group

是Consumer所属分组的唯一标识,一般为系统所属域。

  • Consumer Name Consumer Name

是Consumer的名称,在Consumer Group内具备唯一性,一般为系统名。

  • Consumer Version Consumer Version

指Consumer的所包含功能的具体介质发布版本,一般的Release版本在物理介质上必须保证唯一性。(发布版本、介质、介质SHA1/MD5/SHA256,需要保持一致,有条件的还需要进行代码签名)

  • Consumer-Agent Consumer-Agent

是指用户行为的代理执行者。

  • Client 物理概念 Client

是Consumer-Agent的物理实现,一般为承载请求的运行时容器。

  • Client Group Client Group

是Client所属分组的标识,一般为容器提供者的唯一标识。

  • Client Name Client Name

是Client的名称,在Client Group 内具备唯一性。

  • Client Version Client Version

指Client的具体发布版本,一般的Release版本在物理介质上必须保证唯一性。(发布版本、介质、介质SHA1/MD5/SHA256,需要保持一致,有条件的还需要进行代码签名)

  • Cluster Group Cluster Group 是指Client 和Consumer的可部署介质,在目标运行环境中所属分类,一般对应到域。
  • Cluster Name Cluster Name 是指Client

和Consumer的可部署介质,在目标运行环境中的具体集群名称,一般对应到一组相同功能实例,即集群。

  • InstanceId InstanceId是指Client

和Consumer的可部署介质,在目标运行环境中的具体集群中,被分配的唯一序列号。其唯一性的范围,至少在集群内部,也可以是全局。

  • Request-Metadata

逻辑概念Request-Metadata 是请求中元信息的总称。

  • MessageId MessageId

是每个消息(报文)的唯一标识,由Client运行期即时生成。对于Client或Consumer发起的重试行为,需要提供不同的MessageId。

  • RequestId RequestId

是每个请求的唯一标识,由Consumer运行期即时生成。

  • TransactionId TransactionId

是每个请求的全链路标识,用于关联最源端开始的完整调用过程。

  • Content-Type

逻辑概念Content-Type 是用于说明客户端请求的报文体序列化方法的总称。

  • Serialization Method

Serialization Method 是指请求报文的序列化方法。一般使用MIME-types (RFC2045)

  • Data Structure Version Data Structure Version

是请求报文内数据结构的版本。

  • InstanceId InstanceId

是指Client在物理部署后,进程在集群内的唯一标识。

  • Access Token

逻辑概念Access Token是访问令牌的总称。

  • Client Access Token

Client Access Token是表明客户端合法身份的标识,一般通过安全算法生成,并具备时效性。

Consumer Access Token可以与Kerberos协议相结合。

  • Consumer Access Token

Consumer Access Token是表明消费合法身份的标识,一般通过安全算法生成,并具备时效性。

Consumer Access Token可以与OAuth2协议相结合。

  • Request HMAC Request

HMAC是通过Hash函数、Consumer持有的私有秘钥、请求报文内容的摘要、盐,所生成的安全校验码,具备放篡改能力。

  • Timeout Timeout

是指Consumer所限定的超时时间。

HTTP/1.1 协议映射

HTTP Method 概念映射
  • Commit —> HTTP PUT
  • Compensation —> HTTP PATCH
  • Status —> HTTP HEAD
  • Fetch —> HTTP GET
  • Trace —> HTTP TRACE
HTTP Header 概念映射
  • User-Agent

<Consumer Group>-<Consumer Name> / <Consumer Version> (<Server Group>-<Server Name>/<Server Version>)

  • From

<MessageId>@<InstanceId>.<Cluster Name>.<Cluster Group>

  • Content-Type

<Serialization Method> 

  • Referer Upstream

<RequestId & RequestURL>

  • X-RL-CC-C-TID

<TransactionId>

  • X-RL-C-DSV

<Data Structure Version>

  • X-RL-C-INST

<InstanceId>

  • X-RL-C-CLAT

<Client Access Token>

  • X-RL-C-COAT

<Consumer Access Token>

  • X-RL-C-HMAC

Request HMAC

  • X-RL-C-TIMEOUT

<Timeout>

URL 概念映射
  • RequestId & RequestURL http(s)://<domain>/<path>/<RequestId>

Server Side 技术标准

Server Side 响应结构

  • Provider-Agent
    • Server Group (MUST) Server Name (MUST)
    • Server Version (SHOULD)
  • Response-Metadata
    • Status Code (MUST)
    • MessageId (MUST)
    • ResponseId (MUST)
    • RequestId (MUST)
    • Content-Type (SHOULD)
      • Serialization Method (MUST)
      • Data Version (SHOULD)
    • InstanceId (SHOULD)
    • Response HMAC (Security Considerations)
    • Message Date
    • Response Date
    • Retry-After
    • Expires
  • Provider-Response
    • 5 Types
      • Commit: Commit Result
      • Commit: Compensation Result
      • Status: Request Current Status only
      • Fetch: Final Result
      • Trace: Commit, Compensation & Sub RPC call Trace
  • Response-Body

Server Side 概念定义

  • Provider Provider

是指响应的实际产生者,不包括自然人。

  • Server 物理概念 Server

是Provider-Agent的物理实现,一般为处理请求、作出应答的运行时容器。

  • Server Group Server Group

是Server所属分组的标识,一般为容器提供者的唯一标识。

  • Server Name Server Name

是Server的名称,在Server Group 内具备唯一性。

  • Server Version Server Version

指Server的具体发布版本,一般的Release版本在物理介质上必须保证唯一性。(发布版本、介质、介质SHA1/MD5/SHA256,需要保持一致,有条件的还需要进行代码签名)

  • Cluster Group Cluster Group

是指Server 和Provider的可部署介质,在目标运行环境中所属分类,一般对应到域。

  • Cluster Name Cluster Name

是指Server和Provider的可部署介质,在目标运行环境中的具体集群名称,一般对应到一组相同功能实例,即集群。

  • InstanceId InstanceId

是指Server 和Provider的可部署介质,在目标运行环境中的具体集群中,被分配的唯一序列号。其唯一性的范围,至少在集群内部,也可以是全局。

  • Response-Metadata

逻辑概念Response-Metadata 是响应中元信息的总称。

  • Status Code Status Code

是每个响应的状态编码,一般情况下遵循HTTP/1.1协议的标准。

  • MessageId MessageId

是每个消息(报文)的唯一标识,由Server运行期即时生成。

  • ResponseId RequestId

是每个响应的唯一标识,由Provider运行期即时生成。

  • Content-Type

逻辑概念Content-Type是用于说明客户端请求的报文体序列化方法的总称。

  • Serialization Method

Serialization Method 是指响应报文的序列化方法。一般使用MIME-types (RFC2045)

  • Data Structure Version

Data Structure Version

是响应报文内数据结构的版本。

  • InstanceId InstanceId

是指Server在物理部署后,进程在集群内的唯一标识。

  • Response HMAC Response

HMAC是通过Hash函数、Consumer持有的私有秘钥、请求报文内容的摘要、盐,所生成的安全校验码,具备放篡改能力。参见RFC对ETag的定义。

  • Message Date Message

Date是响应消息的生成时间,由Server给定。参见RFC对Date的定义。

  • Response Date Response

Date是响应内容的生成时间,由Server给定。参见RFC对Last-Modified的定义。

  • Expire Date Expire

Date是Commit操作结果的过期时间,由Provider给定。当Consumer在Expire Date时间之后提交Compensation操作,有可能得到的是Compensation操作失败的结果。其他内容,参见RFC对Expires的定义。

  • Retry-After Expire

Date是响应内容的过期时间,由Server给定。参见RFC对Retry-After的定义。

HTTP/1.1 Header 概念映射

  • Status Code

参见上一节「HTTP Status Code 映射」

  • Server

<Server Group>-<Server Name>/<Server Version>  <Provider Group>-<Provider Name> / <Provider Version> <Cluster Group>-<Cluster Name>/<InstanceId>

  • X-RL-CC-S-MID

<MessageId>

  • X-RL-S-RESID

<ResponseId>

  • X-RL-S-REQID

<RequestId>

  • Content-Type

<Serialization Method> 

  • X-RL-S-DSV

<Data Structure Version>

  • ETag

<Response HMAC>

  • Date

<Message Date>

  • Last-Modified

<Response Date>

  • Retry-After

HTTP-date / delay-seconds

响应 Commit 操作

针对Commit操作,允许返回以下响应码

  • 201 Created 正常处理,并成功。
  • 400 Bad Request 指Consumer提供的请求不符合约定的规格。
  • 401 Unauthorized 指Consumer未提供可供Provider进行合法性验证的身份信息。
  • 402 Payment Required 指Consumer所执行的请求,超过约定的流量限额。
  • 403 Forbidden 指Consumer没有权限执行这项操作。
  • 408 Request Timeout 指Consumer没有在Provider能够接受的请求报文接收时长内接收到完整报文。
  • 409 Conflict 指Server所接受到的报文存在冲突。即相同的RequestId,所对应的Request HMAC不一致。
  • 413 Payload Too Large 指Client对Consumer所提供的报文,在进行序列化之后的长度,超过Server能够接受的最大长度。
  • 414 URI Too Long 指Client所提供的URI,超过Server能够接受的最大长度。
  • 500 Internal Server Error 指Server在处理过程中,发生了未知错误。
  • 503 Service Unavailable 指Provider在处理过程中,发生了未知错误。

响应 Compensation 操作

针对Compensation操作,允许返回以下响应码

  • 400 Bad Request

指Consumer提供的请求不符合约定的规格。

  • 401 Unauthorized

指Consumer未提供可供Provider进行合法性验证的身份信息。

  • 402 Payment Required

指Consumer所执行的请求,超过约定的流量限额。

  • 403 Forbidden

指Consumer没有权限执行这项操作。

  • 404 Not Found

指Provider根据Consumer指定的RequestId没有找到相关的Commit请求。

  • 408 Request Timeout

指Consumer没有在Provider能够接受的请求报文接收时长内接收到完整报文。

  • 409 Conflict
指Server所接受到的报文存在冲突。即相同的RequestId,所对应的Request
HMAC不一致。
  • 410 Gone

处理补偿操作,并成功。

  • 413 Payload Too Large

指Client对Consumer所提供的报文,在进行序列化之后的长度,超过Server能够接受的最大长度。

  • 414 URI Too Long

指Client所提供的URI,超过Server能够接受的最大长度。

  • 500 Internal Server Error

指Server在处理过程中,发生了未知错误。

  • 503 Service Unavailable

指Provider在处理过程中,发生了未知错误。

响应 Status 操作

HTTP/1.1 不对HTTP Status Method提供请求体以及响应体的支撑。

  • 201 Created

处理提交操作,并成功。仅在Commit操作正常完整之后返回。

  • 410  Gone

处理补偿操作,并成功。仅在Compensation操作正常完整之后返回。

响应 Fetch 操作

对于一个正常请求,以及后续可能出现的补偿请求,在Provider可能会产生多个响应结果,Fetch操作只会产生最后的操作结果。当Provider没有补偿操作进行时,返回的是Commit操作的结果;当Provider执行成功执行过Compensation操作时,返回的是Compensation操作结果。

  • 200 OK

返回Provider处理结果的内容。

  • 400 Bad Request

指Consumer提供的请求不符合约定的规格。

  • 401 Unauthorized

指Consumer未提供可供Provider进行合法性验证的身份信息。

  • 402 Payment Required

指Consumer所执行的请求,超过约定的流量限额。

  • 403 Forbidden

指Consumer没有权限执行这项操作。

  • 404 Not Found

指Provider根据Consumer指定的RequestId没有找到相关的Commit请求。

  • 408 Request Timeout

指Consumer没有在Provider能够接受的请求报文接收时长内接收到完整报文。

  • 414 URI Too Long

指Client所提供的URI,超过Server能够接受的最大长度。

  • 500 Internal Server Error

指Server在处理过程中,发生了未知错误。

  • 503 Service Unavailable

指Provider在处理过程中,发生了未知错误。

响应 Trace 操作

对于一个Provider,在处理 Commit操作的过程中,一方面可能依赖下游的其他Provider;另一方面后续可能还会出现 Compensation操作。因此,对于一次请求,处理的结果会产生一系列的处理轨迹。

Trace操作,需要使用HTTP/1.1 Multipart响应机制对结果进行返回。

  • Content-Type

<Serialization Method>  (Multipart Content-Type)

  • 200 OK

返回Consumer处理结果的内容。

  • 400 Bad Request

指Consumer提供的请求不符合约定的规格。

  • 401 Unauthorized

指Consumer未提供可供Provider进行合法性验证的身份信息。

  • 402 Payment Required

指Consumer所执行的请求,超过约定的流量限额。

  • 403 Forbidden

指Consumer没有权限执行这项操作。

  • 404 Not Found

指Provider根据Consumer指定的RequestId没有找到相关的Commit请求。

  • 408 Request Timeout

指Consumer没有在Provider能够接受的请求报文接收时长内接收到完整报文。

  • 414 URI Too Long

指Client所提供的URI,超过Server能够接受的最大长度。

  • 500 Internal Server Error

指Server在处理过程中,发生了未知错误。

  • 503 Service Unavailable

指Provider在处理过程中,发生了未知错误。