阅读知识背景要求
- 熟悉HTTP/1.1协议以及MIME-types
- 熟悉RESTful
- 熟悉分布式事务处理模型
- 了解OAuth2协议
- 了解Kerberos (V5) 协议
- 了解Hash单向函数
修订历史
- 1.0.0 首次发布
背景与目标
编写背景
RESTful 是一个将HTTP传输协议以及JSON报文体相结合的RPC通信风格，但目前并不存在一个得到普遍认可和约束的工业技术规范。
由于RESTful风格形式简洁，工具链丰富，收到广大开发者的喜爱。同时也由于其落地实现的随意性，导致各大企业都有不同的落地实现方法，形成了不同形态的「方言」。无形之中增加了软件互联的成本，造成了有限的研发资源浪费。
编写目标
「书同文车同轨」，规范不同系统之间的技术标准，降低产品间的集成成本，提高研发效率，促进各产品规范、有序发展。
基本约定
- 本规范中涉及大量对HTTP/1.1 协议的标准引用，对于HTTP Header中各项规范定义，本规范以”X-RL-”作为前缀进行扩展，未扩展的遵循RFC所定义的含义。
限制条件
- 本规范主要的使用范围，主要位于后端服务之间的RPC通信。
- 对于每个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
- Consumer-Request
- 5 Types
- Commit
- Compensation
- Status
- Fetch
- Trace
- Request-Body
- 5 Types
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
- 5 Types
- 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在处理过程中，发生了未知错误。
