Cowboy 用户指南 (十二) - Request details
请求对象
Req对象是一个变量，用于获取关于请求的信息、读取请求体或发送响应。
在面向对象的意义上，它并不是一个真正的对象。它是一个简单的映射，可以在调用cowboy_req模块的函数时直接访问或使用。
Req对象是几个不同章节的主题。在本章中，我们将了解Req对象，并了解如何检索有关请求的信息。
Direct access
Req映射包含许多文档化的字段，可以直接访问这些字段。它们是直接映射到HTTP的字段:
使用的HTTP版本;
有效的URI组件scheme, host, port, path 和 qs;
请求头;
连接对端地址和端口;
和TLS证书（如适用）。
请注意，version字段可用于确定连接是否使用HTTP/2。
要访问一个字段，只需在函数头中进行匹配。下面的示例在方法为GET时发送一个简单的“Hello world!”响应，否则发送405错误。
init(Req0=#{method := <<"GET">>}, State) ->
Req = cowboy_req:reply(200, #{
<<"content-type">> => <<"text/plain">>
}, <<"Hello world!">>, Req0),
{ok, Req, State};
init(Req0, State) ->
Req = cowboy_req:reply(405, #{
<<"allow">> => <<"GET">>
}, Req0),
{ok, Req, State}.任何其他字段都是内部的，不应该被访问。它们可能在未来的版本(包括维护版本)中发生变化，而不另行通知。
允许修改Req对象，但是在修改现有字段时必须格外小心。但是，您可以根据需要添加任意数量的新字段。只要确保命名空间字段名，这样就不会与未来的Cowboy更新或第三方项目发生冲突。
cowboy_req接口的介绍
cowboy_req模块中的函数提供了对请求信息的访问，还提供了处理HTTP请求时常见的各种操作。
以动词开头的所有功能都表示一个动作。其他函数只是返回相应的值(有时确实需要构建该值，但操作的成本等同于检索值)。
一些cowboy_req函数返回更新后的Req对象。它们是read、reply、set和delete函数。尽管忽略返回的请求不会导致其中一些请求的错误行为，但强烈建议始终保留并使用最后一个返回的请求对象。cowboy_req的手册详细说明了这些函数以及对Req对象所做的修改。
对cowboy_req的一些调用有副作用。这就是read和reply函数的情况。当函数被调用时，Cowboy立即读取请求主体或回复。
如果出了问题，所有的函数都会崩溃。通常不需要捕捉这些错误，Cowboy将根据崩溃发生的位置发送适当的4xx或5xx响应。
请求方法
可以直接检索请求方法:
#{method := Method} = Req.或者使用函数:
Method = cowboy_req:method(Req).该方法是区分大小写的二进制字符串。标准方法包括GET、HEAD、OPTIONS、PATCH、POST、PUT或DELETE。
HTTP 版本
HTTP版本只是信息。这并不表明客户端很好地或完全地实现了协议。
通常不需要根据HTTP版本改变行为:Cowboy已经为您做了。
但在某些情况下，它是有用的。例如，人们可能想重定向HTTP/1.1客户端而使用Websocket，而HTTP/2客户端继续使用HTTP/2。
HTTP版本可以直接检索:
#{version := Version} = Req.或使用函数:
Version = cowboy_req:version(Req).Cowboy定义了“HTTP/1.0”、“HTTP/1.1”和“HTTP/2”版本。自定义协议可以将它们自己的值定义为原子。
有效的请求URI
有效请求URI的方案、主机、端口、路径和查询字符串组件均可直接检索:
#{
scheme := Scheme,
host := Host,
port := Port,
path := Path,
qs := Qs
} = Req.或使用相关功能:
Scheme = cowboy_req:scheme(Req),
Host = cowboy_req:host(Req),
Port = cowboy_req:port(Req),
Path = cowboy_req:path(Req).
Qs = cowboy_req:qs(Req).scheme和host是不区分小写的二进制字符串。端口是一个代表端口号的整数。路径和查询字符串都是区分大小写的二进制字符串。
Cowboy只定义了<<"http">>和<<"https">>方案。选择它们，对于安全HTTP/1.1或HTTP/2连接上的请求，方案将只为<<"https">>。
有效的请求URI本身可以重构cowboy_req:uri/1,2函数。默认情况下，返回一个绝对URI:
%% scheme://host[:port]/path[?qs]
URI = cowboy_req:uri(Req).可以禁用或替换部分或全部组件。各种URIs或URI格式可以通过这种方式生成，包括原始形式:
%% /path[?qs]
URI = cowboy_req:uri(Req, #{host => undefined}).协议相关形式:
%% //host[:port]/path[?qs]
URI = cowboy_req:uri(Req, #{scheme => undefined}).不带查询字符串的绝对URI:
URI = cowboy_req:uri(Req, #{qs => undefined}).一个不同的主机:
URI = cowboy_req:uri(Req, #{host => <<"example.org">>}).以及其他的组合。
绑定
绑定是您在定义应用程序的路由时选择提取的主机和路径组件。它们只有在路由后才可用。
Cowboy提供了检索一个或所有绑定的函数。
检索单个值:
Value = cowboy_req:binding(userid, Req).当试图检索未绑定的值时，将返回undefined。可以提供不同的默认值:
Value = cowboy_req:binding(userid, Req, 42).检索所有被绑定的内容:
Bindings = cowboy_req:bindings(Req).它们作为映射返回，键是原子。
Cowboy路由器也允许你捕捉许多主机或路径段，使用…限定符。
检索从主机名捕获的段:
HostInfo = cowboy_req:host_info(Req).路径部分:
PathInfo = cowboy_req:path_info(Req).如果…没有在路由上使用,Cowboy将返回undefined。
查询参数
Cowboy提供了两个函数来访问查询参数。您可以使用第一个参数来获取整个参数列表。
QsVals = cowboy_req:parse_qs(Req),
{_, Lang} = lists:keyfind(<<"lang">>, 1, QsVals).Cowboy只解析查询字符串，不做任何转换。因此，这个函数可能返回重复的参数名，或者没有关联值的参数名。返回的列表的顺序没有定义。
当查询字符串为key=1&key=2时，返回的列表将包含名为key的两个参数。
在尝试使用php风格的后缀[]时也是如此。当查询字符串为key[]=1&key[]=2时，返回的列表将包含名称key[]的两个参数。
当查询字符串只是key时，Cowboy将返回列表[{<<"key">>， true}]，使用true表示参数key已定义，但没有值。
Cowboy提供的第二个函数允许您只匹配感兴趣的参数，同时使用约束执行所需的任何后处理。这个函数返回一个map。
#{id := ID, lang := Lang} = cowboy_req:match_qs([id, lang], Req).约束可以自动应用。当id参数不是整数或lang参数为空时，以下代码片段将崩溃。同时，id的值将被转换为整数项:
QsMap = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req).也可以提供默认值。如果没有找到lang键，将使用默认值。如果找到了键但键值为空，则不使用该键。
#{lang := Lang} = cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req).如果没有提供默认值，且缺少该值，则该查询字符串将被视为无效，进程将崩溃。
当查询字符串为key=1&key=2时，key的值为列表[1,2]。参数名称不需要包含php风格的后缀。可以使用约束来确保只传递了一个值。
报头
报头值可以作为二进制字符串检索，也可以解析为更有意义的表示形式。
获取原始值:
HeaderVal = cowboy_req:header(<<"content-type">>, Req).Cowboy希望所有标题名都以小写二进制字符串的形式提供。无论底层协议是什么，请求和响应都是如此。
当请求中缺少标头时，将返回undefined。可以提供一个不同的默认值:
HeaderVal = cowboy_req:header(<<"content-type">>, Req, <<"text/plain">>).所有的报头都可以被一次直接获取:
#{headers := AllHeaders} = Req.或使用函数:
AllHeaders = cowboy_req:headers(Req).Cowboy提供了等效的函数来解析各个报头。没有函数可以一次解析所有的报头。
解析一个特定的报头
ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req).如果不知道如何解析给定的报头，或者该值无效，则会抛出异常。已知的报头列表和默认值可以在手册中找到。
当报头丢失时，将返回undefined。您可以修改默认值。注意，它应该是直接解析的值:
ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req,
{<<"text">>, <<"plain">>, []}).Peer(对等)
对等网络，即对等计算机网络，是一种在对等者（Peer）之间分配任务和工作负载的分布式应用架构，是对等计算模型在应用层形成的一种组网或网络形式。参考：https://baike.baidu.com/item/%E5%AF%B9%E7%AD%89%E7%BD%91%E7%BB%9C/5482934?fr=aladdin
可以直接或使用函数检索连接的对等地址和端口号。
直接检索对等者:
#{peer := {IP, Port}} = Req.以及使用函数:
{IP, Port} = cowboy_req:peer(Req).请注意，对等点对应于连接到服务器的远程端，这可能是客户端本身，也可能不是。它也可以是代理或网关。