本文档描述了用于发送HTTP请求和接收HTTP响应的通用接口。
本文档中的关键词“必须”,“必须”,“必需”,“应该”,“不应该”,“应该”,“不应该”,“推荐”,“可以”和“可选”按照RFC 2119中的描述进行解释。
1 目标
此PSR的目标是允许开发人员创建与HTTP客户端实现分离的库。这将使库更可重用,因为它减少了依赖项的数量并降低了版本冲突的可能性。
第二个目标是可以根据Liskov替换原则替换HTTP客户端。这意味着所有客户端在发送请求时必须以相同的方式运行。
2 定义
- 客户端 - 客户端是实现此规范的库,用于发送与PSR-7兼容的HTTP请求消息并将与PSR-7兼容的HTTP响应消息返回到呼叫库。
- 调用库 - 调用库是使用客户端的任何代码。它没有实现此规范的接口,而是使用实现它们的对象(客户端)。
3 客户端
客户端是实现ClientInterface的对象。
客户端可以:
- 选择从提供的HTTP请求发送更改的HTTP请求。例如,它可以压缩传出消息体。
- 选择在将其返回到调用库之前更改收到的HTTP响应。例如,它可以解压缩传入的消息体。
如果客户端选择更改HTTP请求或HTTP响应,则必须确保对象保持内部一致。例如,如果客户端选择解压缩消息体,那么它还必须删除Content-Encoding头并调整Content-Length头。
请注意,因此,由于PSR-7对象是不可变的,因此调用库绝不能假定传递给ClientInterface :: sendRequest()的对象将是实际发送的相同PHP对象。例如,异常返回的Request对象可能与传递给sendRequest()的对象不同,因此无法通过引用(===)进行比较。
客户必须:
- 重新组合多步HTTP 1xx响应本身,以便返回到调用库的是状态代码200或更高的有效HTTP响应。
3 错误处理
客户端不得将格式正确的HTTP请求或HTTP响应视为错误条件。例如,400和500范围内的响应状态代码不得导致异常,并且必须正常返回到调用库。
当且仅当客户端根本无法发送HTTP请求或者无法将HTTP响应解析为PSR-7响应对象时,客户端必须抛出Psr \ Http \ Client \ ClientExceptionInterface的实例。
如果由于请求消息不是格式正确的HTTP请求或缺少某些关键信息(例如主机或方法)而无法发送请求,则客户端必须抛出Psr \ Http \ Client \ RequestExceptionInterface的实例。