翻译进度
5
分块数量
2
参与人数

PSR-18 HTTP 客户端

这是一篇协同翻译的文章,你可以点击『我来翻译』按钮来参与翻译。

HTTP 客户端

这个文档描述了发送 HTTP 请求和接收 HTTP 响应的共同接口。

本文件中的 「必须」,「不得」,「需要」,「应」,「不应」,「应该」,「不应该」,「推荐」,「可能」 和 「可选」 等能愿动词按照 RFC 2119 中的描述进行解释。

目标

这个 PSR 的目标就是让开发者能够开发一个于 HTTP 客户端解耦的程序库。它使得程序库可重用性更高,因为它降低了依赖的数量以及降低了版本冲突的可能性。

第二个目标是 HTTP 客户端可以按照 里氏替换原则 进行替换。这意味着所有的客户端在发送请求时行为都是一样的。

定义

  • 客户端 - 客户端是实现了本规范的一个程序库,它能否发送符合 PSR-7 标准的 HTTP 请求,同时能够返回一个符合 PSR-7 标准的 HTTP 响应给调用方。
  • 调用方 - 调用方就是使用客户端的代码。它不用实现本规范,但是它使用了一个实现了本规范的对象(客户端)。
cloes 翻译于 2周前

Client

A Client is an object implementing ClientInterface.

A Client MAY:

  • Choose to send an altered HTTP request from the one it was provided. For example, it could compress an outgoing message body.
  • Choose to alter a received HTTP response before returning it to the calling library. For example, it could decompress an incoming message body.

If a Client chooses to alter either the HTTP request or HTTP response, it MUST ensure that the object remains internally consistent. For example, if a Client chooses to decompress the message body then it MUST also remove the Content-Encoding header and adjust the Content-Length header.

Note that as a result, since PSR-7 objects are immutable, the Calling Library MUST NOT assume that the object passed to ClientInterface::sendRequest() will be the same PHP object that is actually sent. For example, the Request object that is returned by an exception MAY be a different object than the one passed to sendRequest(), so comparison by reference (===) is not possible.

A Client MUST:

  • Reassemble a multi-step HTTP 1xx response itself so that what is returned to the Calling Library is a valid HTTP response of status code 200 or higher.

Error handling

A Client MUST NOT treat a well-formed HTTP request or HTTP response as an error condition. For example, response status codes in the 400 and 500 range MUST NOT cause an exception and MUST be returned to the Calling Library as normal.

A Client MUST throw an instance of Psr\Http\Client\ClientExceptionInterface if and only if it is unable to send the HTTP request at all or if the HTTP response could not be parsed into a PSR-7 response object.

If a request cannot be sent because the request message is not a well-formed HTTP request or is missing some critical piece of information (such as a Host or Method), the Client MUST throw an instance of Psr\Http\Client\RequestExceptionInterface.

If the request cannot be sent due to a network failure of any kind, including a timeout, the Client MUST throw an instance of Psr\Http\Client\NetworkExceptionInterface.

Clients MAY throw more specific exceptions than those defined here (a TimeOutException or HostNotFoundExceptionfor example), provided they implement the appropriate interface defined above.

Interfaces

ClientInterface

namespace Psr\Http\Client;

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

interface ClientInterface
{
    /**
     * Sends a PSR-7 request and returns a PSR-7 response.
     *
     * @param RequestInterface $request
     *
     * @return ResponseInterface
     *
     * @throws \Psr\Http\Client\ClientExceptionInterface If an error happens while processing the request.
     */
    public function sendRequest(RequestInterface $request): ResponseInterface;
}

ClientExceptionInterface

namespace Psr\Http\Client;

/**
 * Every HTTP client related exception MUST implement this interface.
 */
interface ClientExceptionInterface extends \Throwable
{
}

RequestExceptionInterface

namespace Psr\Http\Client;

use Psr\Http\Message\RequestInterface;

/**
 * Exception for when a request failed.
 *
 * Examples:
 *      - Request is invalid (e.g. method is missing)
 *      - Runtime request errors (e.g. the body stream is not seekable)
 */
interface RequestExceptionInterface extends ClientExceptionInterface
{
    /**
     * Returns the request.
     *
     * The request object MAY be a different object from the one passed to ClientInterface::sendRequest()
     *
     * @return RequestInterface
     */
    public function getRequest(): RequestInterface;
}

NetworkExceptionInterface

namespace Psr\Http\Client;

use Psr\Http\Message\RequestInterface;

/**
 * Thrown when the request cannot be completed because of network issues.
 *
 * There is no response object as this exception is thrown when no response has been received.
 *
 * Example: the target host name can not be resolved or the connection failed.
 */
interface NetworkExceptionInterface extends ClientExceptionInterface
{
    /**
     * Returns the request.
     *
     * The request object MAY be a different object from the one passed to ClientInterface::sendRequest()
     *
     * @return RequestInterface
     */
    public function getRequest(): RequestInterface;
}

本文章首发在 Laravel China 社区
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

参与译者:2
讨论数量: 0
发起讨论


暂无话题~