module Net

Constants

HTTPGatewayTimeOut

Gateway Timeout 响应（状态码 504）的响应类。

服务器充当网关或代理，但未及时收到来自上游服务器的响应。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPMovedTemporarily

Found 响应（状态码 302）的响应类。

Found 响应表明客户端应查看（浏览）另一个 URL。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPMultipleChoice

Multiple Choices 响应（状态码 300）的响应类。

Multiple Choices 响应表明服务器为该资源提供了多个选项，客户端可以从中选择。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPRequestEntityTooLarge

Payload Too Large 响应（状态码 413）的响应类。

请求的大小超出了服务器愿意或能够处理的范围。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPRequestTimeOut

Request Timeout 响应（状态码 408）的响应类。

服务器在等待请求时超时。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPRequestURITooLarge

URI Too Long 响应（状态码 414）的响应类。

提供的 URI 对服务器来说太长，无法处理。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPRequestURITooLong

URI Too Long 响应（状态码 414）的响应类。

提供的 URI 对服务器来说太长，无法处理。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPRequestedRangeNotSatisfiable

Range Not Satisfiable 响应（状态码 416）的响应类。

请求实体具有服务器或资源不支持的媒体类型。

此类还（间接）包含模块 Net::HTTPHeader，该模块允许访问其用于获取标头的方法。

参考

HTTPSession

类 Net::HTTP 提供了一个丰富的库，实现了使用 HTTP 请求-响应协议的客户端-服务器模型中的客户端。有关 HTTP 的信息，请参阅

关于示例

此处的示例假设已加载 net/http（这也将加载 uri）

require 'net/http'

这里的许多代码示例都使用了这些示例网站

一些示例还假定存在这些变量

uri = URI('https://jsonplaceholder.typicode.com/')
uri.freeze # Examples may not modify.
hostname = uri.hostname # => "jsonplaceholder.typicode.com"
path = uri.path         # => "/"
port = uri.port         # => 443

因此，示例请求可以这样编写

Net::HTTP.get(uri)
Net::HTTP.get(hostname, '/index.html')
Net::HTTP.start(hostname) do |http|
  http.get('/todos/1')
  http.get('/todos/2')
end

需要修改 URI 的示例首先会复制 `uri`，然后修改副本

_uri = uri.dup
_uri.path = '/todos/1'

策略

如果您只进行几次 GET 请求，请考虑使用 OpenURI。

如果您只进行几种类型的请求，请考虑使用此类中各种单例方便方法。以下每个方法都会自动启动和完成一个会话，发送单个请求

# Return string response body.
Net::HTTP.get(hostname, path)
Net::HTTP.get(uri)

# Write string response body to $stdout.
Net::HTTP.get_print(hostname, path)
Net::HTTP.get_print(uri)

# Return response as Net::HTTPResponse object.
Net::HTTP.get_response(hostname, path)
Net::HTTP.get_response(uri)
data = '{"title": "foo", "body": "bar", "userId": 1}'
Net::HTTP.post(uri, data)
params = {title: 'foo', body: 'bar', userId: 1}
Net::HTTP.post_form(uri, params)
data = '{"title": "foo", "body": "bar", "userId": 1}'
Net::HTTP.put(uri, data)

如果性能很重要，请考虑使用会话，它们可以降低请求开销。此会话包含对 HTTP 方法和 WebDAV 方法的多个请求

Net::HTTP.start(hostname) do |http|
  # Session started automatically before block execution.
  http.get(path)
  http.head(path)
  body = 'Some text'
  http.post(path, body)  # Can also have a block.
  http.put(path, body)
  http.delete(path)
  http.options(path)
  http.trace(path)
  http.patch(path, body) # Can also have a block.
  http.copy(path)
  http.lock(path, body)
  http.mkcol(path, body)
  http.move(path)
  http.propfind(path, body)
  http.proppatch(path, body)
  http.unlock(path, body)
  # Session finished automatically at block exit.
end

上面引用的方法是方便方法，它们通过少数参数提供对请求的最小控制。有关更多控制，请考虑使用请求对象。

URIs

在互联网上，URI（统一资源标识符）是一个标识特定资源的字符串。它包含以下部分或全部：方案、主机名、路径、查询和片段；请参阅 URI 语法。

Ruby 的 URI::Generic 对象表示一个互联网 URI。它提供了 `scheme`、`hostname`、`path`、`query` 和 `fragment` 等方法。

方案

互联网 URI 具有一个方案。

Net::HTTP 支持的两个方案是 `'https'` 和 `'http'`。

uri.scheme                       # => "https"
URI('http://example.com').scheme # => "http"

主机名

主机名标识可以发送请求的服务器（主机）。

hostname = uri.hostname # => "jsonplaceholder.typicode.com"
Net::HTTP.start(hostname) do |http|
  # Some HTTP stuff.
end

路径

特定于主机的路径标识主机上的资源。

_uri = uri.dup
_uri.path = '/todos/1'
hostname = _uri.hostname
path = _uri.path
Net::HTTP.get(hostname, path)

查询

特定于主机的查询会向 URI 添加名称/值对。

_uri = uri.dup
params = {userId: 1, completed: false}
_uri.query = URI.encode_www_form(params)
_uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com?userId=1&completed=false>
Net::HTTP.get(_uri)

片段

在 Net::HTTP 中，URI 片段没有影响；无论是否包含片段，都会返回相同的数据。

请求头

请求标头可用于将附加信息传递给主机，类似于在方法调用中传递的参数；每个标头都是一个名称/值对。

发送请求到主机的每个 Net::HTTP 方法都有一个可选参数 `headers`，其中标头表示为字段名/值对的哈希。

headers = {Accept: 'application/json', Connection: 'Keep-Alive'}
Net::HTTP.get(uri, headers)

请参阅请求字段中标准请求字段和常用请求字段的列表。主机也可能接受其他自定义字段。

HTTP 会话

会话是服务器（主机）和客户端之间的连接，它

由实例方法 Net::HTTP#start 开始。
可以包含任意数量的请求。
由实例方法 Net::HTTP#finish 结束。

有关示例会话，请参阅策略。

使用 Net::HTTP.start 的会话

如果您需要向单个主机（和端口）发出多个请求，请考虑使用带块的单例方法 Net::HTTP.start；该方法会通过以下方式自动处理会话：

在块执行之前调用 start。
执行块。
在块执行之后调用 finish。

在块中，您可以使用这些实例方法，每种方法都会发送单个请求。

HTTP 方法:
- get, request_get: GET。
- head, request_head: HEAD。
- post, request_post: POST。
- delete: DELETE。
- options: OPTIONS。
- trace: TRACE。
- patch: PATCH。
WebDAV 方法:
- copy: COPY。
- lock: LOCK。
- mkcol: MKCOL。
- move: MOVE。
- propfind: PROPFIND。
- proppatch: PROPPATCH。
- unlock: UNLOCK。

使用 Net::HTTP.start 和 Net::HTTP.finish 的会话

您可以使用 start 和 finish 方法手动管理会话。

http = Net::HTTP.new(hostname)
http.start
http.get('/todos/1')
http.get('/todos/2')
http.delete('/posts/1')
http.finish # Needed to free resources.

单请求会话

某些方便方法会自动处理会话，通过

创建 HTTP 对象。
启动会话。
发送单个请求。
结束会话。
销毁对象。

发送 GET 请求的此类方法

::get: 返回字符串响应体。
::get_print: 将字符串响应体写入 $stdout。
::get_response: 返回一个 Net::HTTPResponse 对象。

发送 POST 请求的此类方法

::post: 向主机发布数据。
::post_form: 向主机发布表单数据。

HTTP 请求和响应

上面许多方法都是方便方法，每种方法都会发送一个请求并返回一个字符串，而无需直接使用 Net::HTTPRequest 和 Net::HTTPResponse 对象。

但是，您也可以直接创建一个请求对象，发送请求，并检索响应对象；请参阅

遵循重定向

每个返回的响应都是 Net::HTTPResponse 子类的实例。请参阅响应类层次结构。

特别是，类 Net::HTTPRedirection 是所有重定向类的父类。这允许您创建一个 case 语句来正确处理重定向。

def fetch(uri, limit = 10)
  # You should choose a better exception.
  raise ArgumentError, 'Too many HTTP redirects' if limit == 0

  res = Net::HTTP.get_response(URI(uri))
  case res
  when Net::HTTPSuccess     # Any success class.
    res
  when Net::HTTPRedirection # Any redirection class.
    location = res['Location']
    warn "Redirected to #{location}"
    fetch(location, limit - 1)
  else                      # Any other class.
    res.value
  end
end

fetch(uri)

基本身份验证

基本身份验证根据 RFC2617 执行。

req = Net::HTTP::Get.new(uri)
req.basic_auth('user', 'pass')
res = Net::HTTP.start(hostname) do |http|
  http.request(req)
end

流式传输响应体

默认情况下，Net::HTTP 会将整个响应读入内存。如果您正在处理大文件或希望实现进度条，则可以改为将响应体直接流式传输到 IO。

Net::HTTP.start(hostname) do |http|
  req = Net::HTTP::Get.new(uri)
  http.request(req) do |res|
    open('t.tmp', 'w') do |f|
      res.read_body do |chunk|
        f.write chunk
      end
    end
  end
end

HTTPS

通过 Net::HTTP#use_ssl= 为 HTTP 连接启用 HTTPS。

Net::HTTP.start(hostname, :use_ssl => true) do |http|
  req = Net::HTTP::Get.new(uri)
  res = http.request(req)
end

或者，如果您只想发出 GET 请求，可以传入一个具有 HTTPS URL 的 URI 对象。如果 URI 对象具有 'https' URI 方案，Net::HTTP 会自动开启 TLS 验证。

uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com/>
Net::HTTP.get(uri)

代理服务器

HTTP 对象可以具有代理服务器。

您可以使用方法 Net::HTTP.new 或方法 Net::HTTP.start 创建一个带有代理服务器的 HTTP 对象。

代理服务器可以通过参数 `p_addr` 或环境变量 `'http_proxy'` 来定义。

使用字符串参数 `p_addr` 的代理

当参数 `p_addr` 是一个字符串主机名时，返回的 `http` 将给定的主机作为其代理。

http = Net::HTTP.new(hostname, nil, 'proxy.example')
http.proxy?          # => true
http.proxy_from_env? # => false
http.proxy_address   # => "proxy.example"
# These use default values.
http.proxy_port      # => 80
http.proxy_user      # => nil
http.proxy_pass      # => nil

也可以提供代理的端口、用户名和密码。

http = Net::HTTP.new(hostname, nil, 'proxy.example', 8000, 'pname', 'ppass')
# => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
http.proxy?          # => true
http.proxy_from_env? # => false
http.proxy_address   # => "proxy.example"
http.proxy_port      # => 8000
http.proxy_user      # => "pname"
http.proxy_pass      # => "ppass"

使用 `'ENV['http_proxy']'` 的代理

当环境变量 `'http_proxy'` 设置为 URI 字符串时，返回的 `http` 将具有该 URI 处的服务器作为其代理；请注意，URI 字符串必须具有协议，例如 `'http'` 或 `'https'`。

ENV['http_proxy'] = 'http://example.com'
http = Net::HTTP.new(hostname)
http.proxy?          # => true
http.proxy_from_env? # => true
http.proxy_address   # => "example.com"
# These use default values.
http.proxy_port      # => 80
http.proxy_user      # => nil
http.proxy_pass      # => nil

URI 字符串可以包含代理用户名、密码和端口号。

ENV['http_proxy'] = 'http://pname:ppass@example.com:8000'
http = Net::HTTP.new(hostname)
http.proxy?          # => true
http.proxy_from_env? # => true
http.proxy_address   # => "example.com"
http.proxy_port      # => 8000
http.proxy_user      # => "pname"
http.proxy_pass      # => "ppass"

过滤代理

使用方法 Net::HTTP.new（但不是 Net::HTTP.start），您可以使用参数 `p_no_proxy` 来过滤代理。

拒绝特定地址。

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
http.proxy_address # => nil

拒绝特定域或子域。

http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
http.proxy_address # => nil

拒绝特定地址和端口组合。

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234')
http.proxy_address # => "proxy.example"

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:8000')
http.proxy_address # => nil

使用逗号分隔拒绝上述类型的列表。

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
http.proxy_address # => nil

http = Net::HTTP.new('example.com', nil, 'my.proxy', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
http.proxy_address # => nil

压缩和解压缩

Net::HTTP 在发送前不压缩请求的 body。

默认情况下，Net::HTTP 将标头 `'Accept-Encoding'` 添加到新的请求对象。

Net::HTTP::Get.new(uri)['Accept-Encoding']
# => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"

这会请求服务器对响应体进行 zip 编码（如果存在）；服务器不要求这样做。

如果响应具有 `Content-Range` 标头，Net::HTTP 不会自动解压缩响应体。

否则，解压缩（或不解压缩）取决于标头 Content-Encoding 的值。

'deflate'、'gzip' 或 'x-gzip'：解压缩 body 并删除标头。
'none' 或 'identity'：不解压缩 body，但删除标头。
任何其他值：保持 body 和标头不变。

这里有什么

首先，其他内容。类 Net::HTTP

继承自 Object 类。

这是一个分类的方法和属性摘要。

Net::HTTP 对象

::new: 创建新实例。
#inspect: 返回 `self` 的字符串表示形式。

会话

::start: 在新的 Net::HTTP 对象中开始新会话。
#started?: 返回是否在会话中。
#finish: 结束活动会话。
#start: 在现有的 Net::HTTP 对象（`self`）中开始新会话。

连接

:continue_timeout: 返回 continue 超时。
#continue_timeout=: 设置 continue 超时秒数。
:keep_alive_timeout: 返回 keep-alive 超时。
:keep_alive_timeout=: 设置 keep-alive 超时。
:max_retries: 返回最大重试次数。
#max_retries=: 设置最大重试次数。
:open_timeout: 返回连接超时。
:open_timeout=: 设置连接超时。
:read_timeout: 返回读取超时。
:read_timeout=: 设置读取超时。
:ssl_timeout: 返回 SSL 超时。
:ssl_timeout=: 设置 SSL 超时。
:write_timeout: 返回写入超时。
write_timeout=: 设置写入超时。

请求

::get: 发送 GET 请求并返回字符串响应体。
::get_print: 发送 GET 请求并将字符串响应体写入 $stdout。
::get_response: 发送 GET 请求并返回响应对象。
::post_form: 发送带有表单数据的 POST 请求并返回响应对象。
::post: 发送带有数据的 POST 请求并返回响应对象。
::put: 发送带有数据的 PUT 请求并返回响应对象。
#copy: 发送 COPY 请求并返回响应对象。
#delete: 发送 DELETE 请求并返回响应对象。
#get: 发送 GET 请求并返回响应对象。
#head: 发送 HEAD 请求并返回响应对象。
#lock: 发送 LOCK 请求并返回响应对象。
#mkcol: 发送 MKCOL 请求并返回响应对象。
#move: 发送 MOVE 请求并返回响应对象。
#options: 发送 OPTIONS 请求并返回响应对象。
#patch: 发送 PATCH 请求并返回响应对象。
#post: 发送 POST 请求并返回响应对象。
#propfind: 发送 PROPFIND 请求并返回响应对象。
#proppatch: 发送 PROPPATCH 请求并返回响应对象。
#put: 发送 PUT 请求并返回响应对象。
#request: 发送请求并返回响应对象。
#request_get: 发送 GET 请求并创建一个响应对象；如果给定块，则使用该对象调用块，否则返回该对象。
#request_head: 发送 HEAD 请求并创建一个响应对象；如果给定块，则使用该对象调用块，否则返回该对象。
#request_post: 发送 POST 请求并创建一个响应对象；如果给定块，则使用该对象调用块，否则返回该对象。
#send_request: 发送请求并返回响应对象。
#trace: 发送 TRACE 请求并返回响应对象。
#unlock: 发送 UNLOCK 请求并返回响应对象。

响应

:close_on_empty_response: 返回在空响应时是否关闭连接。
:close_on_empty_response=: 设置在空响应时是否关闭连接。
:ignore_eof: 返回在具有 `Content-Length` 标头的响应体读取时是否忽略文件结尾。
:ignore_eof=: 设置在具有 `Content-Length` 标头的响应体读取时是否忽略文件结尾。
:response_body_encoding: 返回用于响应体的编码。
#response_body_encoding=: 设置响应体编码。

代理

:proxy_address: 返回代理地址。
:proxy_address=: 设置代理地址。
::proxy_class?: 返回 `self` 是否为代理类。
#proxy?: 返回 `self` 是否有代理。
#proxy_address: 返回代理地址。
#proxy_from_env?: 返回代理是否从环境变量获取。
:proxy_from_env=: 设置代理是否从环境变量获取。
:proxy_pass: 返回代理密码。
:proxy_pass=: 设置代理密码。
:proxy_port: 返回代理端口。
:proxy_port=: 设置代理端口。
#proxy_user: 返回代理用户名。
:proxy_user=: 设置代理用户。

Security

:ca_file: 返回 CA 证书文件的路径。
:ca_file=: 设置 CA 证书文件的路径。
:ca_path: 返回包含证书文件的 CA 目录的路径。
:ca_path=: 设置包含证书文件的 CA 目录的路径。
:cert: 返回用于客户端证书的 OpenSSL::X509::Certificate 对象。
:cert=: 设置用于客户端证书的 OpenSSL::X509::Certificate 对象。
:cert_store: 返回用于验证对等证书的 X509::Store。
:cert_store=: 设置用于验证对等证书的 X509::Store。
:ciphers: 返回可用的 SSL 密码。
:ciphers=: 设置可用的 SSL 密码。
:extra_chain_cert: 返回要添加到证书链的额外 X509 证书。
:extra_chain_cert=: 设置要添加到证书链的额外 X509 证书。
:key: 返回 OpenSSL::PKey::RSA 或 OpenSSL::PKey::DSA 对象。
:key=: 设置 OpenSSL::PKey::RSA 或 OpenSSL::PKey::DSA 对象。
:max_version: 返回最大 SSL 版本。
:max_version=: 设置最大 SSL 版本。
:min_version: 返回最小 SSL 版本。
:min_version=: 设置最小 SSL 版本。
#peer_cert: 返回会话套接字对等方的 X509 证书链。
:ssl_version: 返回 SSL 版本。
:ssl_version=: 设置 SSL 版本。
#use_ssl=: 设置新会话是否使用传输层安全性。
#use_ssl?: 返回 `self` 是否使用 SSL。
:verify_callback: 返回用于服务器证书验证的回调。
:verify_callback=: 设置用于服务器证书验证的回调。
:verify_depth: 返回证书链验证的最大深度。
:verify_depth=: 设置证书链验证的最大深度。
:verify_hostname: 返回在 SSL/TLS 会话开始时用于服务器证书验证的标志。
:verify_hostname=: 在 SSL/TLS 会话开始时设置用于服务器证书验证的标志。
:verify_mode: 返回在 SSL/TLS 会话开始时用于服务器证书验证的标志。
:verify_mode=: 在 SSL/TLS 会话开始时设置用于服务器证书验证的标志。

地址和端口

:address: 返回字符串主机名或主机 IP。
::default_port: 返回整数 80，用于 HTTP 请求的默认端口。
::http_default_port: 返回整数 80，用于 HTTP 请求的默认端口。
::https_default_port: 返回整数 443，用于 HTTPS 请求的默认端口。
#ipaddr: 返回连接的 IP 地址。
#ipaddr=: 设置连接的 IP 地址。
:local_host: 返回用于建立连接的字符串本地主机。
:local_host=: 设置用于建立连接的字符串本地主机。
:local_port: 返回用于建立连接的整数本地端口。
:local_port=: 设置用于建立连接的整数本地端口。
:port: 返回整数端口号。

HTTP 版本

::version_1_2? (别名为 ::version_1_2): 返回 true；为兼容性保留。

调试

#set_debug_output: 设置调试输出流。