Perl HTTP事件驱动模块-AnyEvent::HTTP
2019-06-10 08:59:20 
阿炯
AnyEvent::HTTP - simple but non-blocking HTTP/HTTPS client，一个简单的非阻塞的 HTTP/HTTPS 客户端。使用此模块是基于AnyEvent，需要用户确保使用并运行受支持的事件循环系统。
该模块实现了一个简单、无状态和无阻塞的HTTP客户端。它支持GET、POST和其它请求方法、cookie等，所有这些都处于非常低的级别方法。它可以遵循重定向，支持代理，并自动将连接数限制为RFC中指定的值。
它通常应该是一个“好客户机”，足以完成大多数HTTP任务。简单的任务应该很简单，但是复杂的任务仍然可以胜任，因为用户保留了对请求和响应头的控制。
调用者负责身份验证管理、cookie、referer和其他高级协议细节，此模块仅提供有限的支持。
基本调用方法
http_get $url, key => value..., $cb->($data, $headers)
Executes an HTTP-GET request. See the http_request function for details on additional parameters and the return value.
执行一个HTTP-GET请求,查看http_request 函数对于细节在额外的参数和返回值。
http_head $url, key => value..., $cb->($data, $headers)
Executes an HTTP-HEAD request. See the http_request function for details on additional parameters and the return value.
执行一个HTTP-HEAD 请求, 查看http_request 函数得到额外的参数和返回值
http_post $url, $body, key => value..., $cb->($data, $headers)
Executes an HTTP-POST request with a request body of $body. See the http_request function for details on additional parameters and the return value.
执行一个HTTP-POST 请求以请求body, 查看http_request函数得到额外的参数和返回值
http_request $method => $url, key => value..., $cb->($data, $headers)
Executes a HTTP request of type $method (e.g. GET, POST). The URL must be an absolute http or https URL.
执行一个HTTP 请求类型的方法,URL必须是一个绝对的http或者https
当被调用在空的上下文没有返回。在其他情况下,http_request 返回一个 “cancellation guard”。
你必须应该保持对象至少alive 直到回调get被调用。如果对象gets被摧毁在回调被调用前, 请求会被取消。
回调函数会被调用带上响应body 数据作为第一个参数(或者undef如果一个错误发生),一个hash-ref 带上一个响应header 作为第2个参数。所有的header 在那个hash里是小写的，除了响应头,伪头(大写来避免可能冲击可能的响应头),状态和原因包含HTTP状态行的3个部分,如果一个错误发生在一个请求的body阶段，那么原始的状态和原因之从header是可用的作为原始状态和原始原因。
伪标头URL 包含实际的URL( 不同于请求的URL当跟随者重定向，比如你可能得到一个错误的你的URL scheme 是不支持的 尽管你的URL 是一个正确的http URL 因为它重定向到一个ftp URL，在这种情况下你可以看看URL伪报头，伪头重定向只存在当 请求是一个内部的重定向的结果。在那种情况下, 它是一个array 引用带有(data, headers) 从重定向的响应。
注意：这个响应是一个重定向本身的结果如果server 多次发送一个header,它们的内容会被连接在一起用','，作为HTTP规范。
如果发生内部错误，例如无法解析主机名，那么$data将被取消定义，$headers->status将为590-599，伪头包含错误消息。当前使用以下状态代码：
595 - errors during connection establishment, proxy handshake.
596 - errors during TLS negotiation, request sending and header processing.
597 - errors during body receiving or processing.
598 - user aborted request via on_header or on_body.
599 - other, usually nonretryable, errors (garbled URL etc.).
可选参数是键值对，它们包括：
recurse => $count (default: $MAX_RECURSE)
是否是递归请求,如重定向,认证和其他重试等等如何做，只有重定向到http和https URL是支持的,当常用的重定向格式是被处理整个在模块里,一些请求使用额外的URI 模块。如果它是需要的但是缺少了, 那么请求会失败。
headers => hashref
请求头使用, 当前的http_request 可能提供它自己的主机,Content-Length:, Connection: and Cookie:和Cookie: headers会提供默认值。
timeout => $seconds
超时用于各种阶段,每个连接尝试会reset timeout, 会读或者写activity,即不是整体超时 默认是5分钟。
proxy => [$host, $port[, $scheme]] or undef
使用给定的http proxy 用于所有的请求, 或者没有proxy时undef 被使用。
body => $string
请求体, 通常是空的,会被发送(这个模板的将来的版本可能提供更多的选项)
cookie_jar => $hash_ref
传递这个参数启用 cookie-processing, 基于原netscape规范。
tls_ctx => $scheme | $tls_ctx
session => $string
on_prepare => $callback->($fh)
tcp_connect => $callback->($host, $service, $connect_cb, $prepare_cb)
on_header => $callback->($headers)
on_body => $callback->($partial_body, $headers)
want_body_handle => $enable
persistent => $boolean
keepalive => $boolean
handle_params => { key => value ... }
DNS 缓存
AnyEvent::HTTP 使用 AnyEvent::Socket::tcp_connect 函数发起TCP连接的实际功能，这将使用AnyEvent::DNS还解析主机名。原有的没有缓存，如果你想要你的DNS被缓存，目前有提供你自己的默认冲突解决程序（$AnyEvent::DNS::RESOLVER可以提供此功能）或你自己的tcp_connect回调。
全局函数与变量
AnyEvent::HTTP::set_proxy "proxy-url"
AnyEvent::HTTP::cookie_jar_expire $jar[, $session_end]
$date = AnyEvent::HTTP::format_date $timestamp
$timestamp = AnyEvent::HTTP::parse_date $date
$AnyEvent::HTTP::MAX_RECURSE
$AnyEvent::HTTP::TIMEOUT
$AnyEvent::HTTP::USERAGENT
$AnyEvent::HTTP::MAX_PER_HOST
$AnyEvent::HTTP::PERSISTENT_TIMEOUT
$AnyEvent::HTTP::ACTIVE
使用过程中可能的问题
$VAR1 = {
'Status' => 596,
'URL' => 'https://me.freeoa.net/auth/authorize',
'Reason' => 'TLS support not available on this system'
};
经查证：需要 Net::SSLeay 与 AnyEvent::TLS 模块。由于后者已经安装好了，只能安装Net::SSLeay模块，安装完成后问题解决。
最新版本：2.24
项目主页：
http://home.schmorp.de/
https://metacpan.org/release/AnyEvent-HTTP