README

高级HTTP客户端和(Slim)服务工具。
客户端提供响应验证和模拟。
服务提供标准化和可预测的响应。

▹ 客户端

请求选项

HttpClient->request() 方法接受它自己的选项
以及底层 RestMini 客户端的选项。

自己的选项

(bool) debug_dump：记录请求和响应
(bool|arr) cacheable：缓存响应/从缓存加载响应
(bool|arr) validate_response：将响应体与验证规则集进行验证
(bool|arr) mock_response：不发送请求，返回预定义的模拟响应
(int) retry_on_unavailable：毫秒；在出现 503 服务不可用|主机未找到|连接失败时重试
要求响应头
(arr) require_response_headers：需要响应头键的列表
(bool) err_on_endpoint_not_found：在 404 + HTML 响应时出错
(bool) err_on_resource_not_found：在 204 或 404 + JSON 响应时出错
(arr) log_warning_on_status：键是状态码，值是 true

选项处理

除了直接传递给 HttpClient->request() 的选项外
还可能有针对 Config 的设置

provider：服务主机
service：一组端点
endpoint：实际端点
method：字面HTTP方法或别名（如GET别名index和retrieve）

在请求准备过程中，设置和选项会合并，因此
– 选项覆盖方法设置，方法设置覆盖端点设置，以此类推。（你自己理解）。
听起来像很多工作，但实际上并不是。

▹▹ 客户端 CLI 命令

(远程) 服务配置

# Show provider settings.
php cli.php config-get -a global http-provider.prvdr

# Show service settings.
php cli.php config-get -a global http-service.prvdr.example-service

# Show endpoint settings.
php cli.php config-get -a global http-endpoint.prvdr.example-service.ndpnt

# Show method settings.
php cli.php config-get -a global http-method.prvdr.example-service.ndpnt.GET

验证规则集

# Show cached validation rule set.
php cli.php cache-get http-response_validation-rule-set prvdr.example-service.ndpnt.GET

# Delete cached validation rule set.
php cli.php cache-delete http-response_validation-rule-set prvdr.example-service.ndpnt.GET

模拟响应

# Show cached mock response.
php cli.php cache-get http-response_mock prvdr.example-service.ndpnt.GET

# Delete cached mock response.
php cli.php cache-delete http-response_mock prvdr.example-service.ndpnt.GET

▹▹ 客户端错误代码

对于每个错误代码，都有一个等效的预制安全且用户友好的（可本地化）错误消息。

unknown：整体错误回退
local-unknown：本地错误回退
local-algo：包内的逻辑错误
local-use：无效参数等
local-configuration：配置变量错误
local-option：选项变量错误
local-init：RestMini 客户端或 cURL 无法请求
host-unavailable：DNS或实际上没有这样的主机
service-unavailable：状态 503 服务不可用
too-many-redirects：重定向太多
timeout：cURL 504
timeout-propagated：状态 504 网关超时
response-none：cURL 500 (RestMini 客户端 'response-false')
remote：状态 500 内部服务器错误
remote-propagated：远程表示 502 网关错误
malign-status-unexpected：不支持的 5xx 状态
endpoint-not-found：状态 404 + 内容类型不是 JSON（可能是 HTML）；没有这样的端点
resource-not-found：状态 204，状态 404 + 内容类型 JSON；没有这样的资源（对象）
remote-validation-bad：400 请求错误
remote-validation-failed：412 预先条件失败，422 无法处理实体
response-type：内容类型不匹配
response-format：解析错误
benign-status-unexpected：不支持的非5xx状态
header-missing：设置/选项 require_response_headers
response-validation：响应体验证失败；服务将发送 X-Http-Response-Invalid 标头

▹ 服务

生成服务响应并不像请求远程服务那么困难，
因此 Http 的服务部分不如客户端部分丰富。
假设只是简单地回显某些内容并发送一些标头——或者使用 Slim 这样的服务框架Slim。

HttpServiceSlim 类提供了与 Slim 交互的方法，并且 Http 包含了一个简单的示例。@todo
并且 Http 还提供了一些其他的服务实用工具。

允许跨源请求

最好只在开发网站上。当开发基于 Angular 的前端时是必要的。

在文档根目录中放置一个 .cross_origin_allow_sites 文本文件，包含允许的站点列表，例如
https://:4200,http://my-project.build.local.host:80

▹▹ 服务错误代码

对于每个错误代码，都有一个等效的预制安全且用户友好的（可本地化）错误消息。

unknown：总体回退
request-unacceptable：（某种）不良请求；HttpResponseRequestUnacceptable
unauthenticated：认证（登录）失败；HttpResponseRequestUnauthenticated
unauthorized：授权（权限）失败；HttpResponseRequestUnauthorized
request-validation：请求标头/参数验证失败；HttpResponseRequestInvalid
frontend-response-format：仅前端；解析错误
frontend-response-validation：仅前端；响应验证失败

服务和客户端结合

标准化的包装响应体

服务请求者永远不应该怀疑其对服务的请求是否完全成功。
HttpClient->request() 返回 HttpResponse 对象

状态 int：建议发送给请求者的状态
标头 array：建议发送的标头
主体 HttpResponseBody
- success bool
- status int：从远程服务接收到的状态
- data mixed|null：实际数据（在成功时）
- message string|null：安全且用户友好的消息（在失败时）
- code int：错误代码（在失败时），或者可选的其他标志（在成功时）
originalHeaders array：接收到的标头——不要发送给请求者
validated bool|null：响应是否已验证，以及验证结果

一般想法是始终发送包含关于操作进程的 元数据 的响应体——成功、状态、代码。
并且——在失败时——一个预制安全且用户友好的消息，客户端可以使用它来通知访客
（而不是默默地/不优雅地失败）。

当公开一个执行远程请求的服务时，该服务应有权访问有关远程请求/响应的更详细信息
——因此进一步将其包装在表示状态和标头（等）的对象中。

▹ 服务响应标头

Http 使用多个自定义响应标头，以向客户端标记一些内容。
其中一些在每次远程请求时由 HttpClient 发出（原始/最终状态）。
其他只有在服务使用/发送预制 HttpResponse 扩展之一时才会发出。

^(int)X-Http-Original-Status：从远程服务接收到的状态（或相同解释）
^(int)X-Http-Final-Status：要发送给客户端的最终状态
X-Http-Response-Invalid：响应验证失败；HttpResponseResponseInvalid
X-Http-Mock-Response：HttpClient 永远没有调用远程服务；使用预制模拟响应
X-Http-Request-Invalid：请求头/参数验证失败；HttpResponseRequestInvalid
X-Http-Request-Unacceptable：（某种）无效请求；HttpResponseRequestUnacceptable
X-Http-Request-Unauthenticated：认证（登录）失败；HttpResponseRequestUnauthenticated
X-Http-Request-Unathorized：授权（权限）失败；HttpResponseRequestUnauthorized

需求

建议

Slim

simplecomplex / http

维护者

详细信息