Cowboy 用户指南 (十八) - REST 处理程序

REST 处理程序

REST在Cowboy中作为一个子协议实现。请求被作为一个状态机处理，其中包含许多描述资源和修改机器行为的可选回调。

REST处理程序是处理HTTP请求的推荐方法。

初始化

首先，调用init/2回调函数。这个回调对所有处理程序都是通用的。为了在当前请求中使用REST，这个函数必须返回一个cowboy_rest元组。

init(Req, State) ->
    {cowboy_rest, Req, State}.

然后Cowboy将切换到REST协议并开始执行状态机。

到达流程图末尾后，如果定义了terminate/3回调函数，则将调用它。

方法

REST组件有用于处理以下HTTP方法的代码:HEAD、GET、POST、PATCH、PUT、DELETE和OPTIONS。

其他方法也可以接受，但是此时它们没有为它们定义特定的回调。

回调

所有的回调都是可选的。根据其他定义的回调函数返回的结果，有些回调函数可能成为强制性的。下一章的各种流程图对于确定你需要哪些回调是很有用的。

所有的回调函数都接受两个参数，即Req对象和State，并返回一个包含三个元素的元组，其形式为{Value, Req, State}。

几乎所有的回调函数都可以返回{stop, Req, State}来停止请求的执行，也可以返回{{switch_handler, Module}， Req, State}或{{switch_handler, Module, Opts}， Req, State}来切换到不同的处理程序类型。例外是expires generate_etag, last_modified和variance。

下表总结了回调函数及其默认值。如果没有定义回调函数，则使用默认值。请看流程图，找出每个返回值的结果。

在下表中，“skip”表示如果回调函数没有定义，则完全跳过它，直接跳到下一步。类似地，"none"表示这个回调函数没有默认值。

回调名	默认值
allowed_methods	[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
allow_missing_post	true
charsets_provided	skip
content_types_accepted	none
content_types_provided	[{{ <<"text">>, <<"html">>, '*'}, to_html}]
delete_completed	true
delete_resource	false
expires	undefined
forbidden	false
generate_etag	undefined
is_authorized	true
is_conflict	false
known_methods	[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
languages_provided	skip
last_modified	undefined
malformed_request	false
moved_permanently	false
moved_temporarily	false
multiple_choices	false
options	ok
previously_existed	false
rate_limited	false
resource_exists	true
service_available	true
uri_too_long	false
valid_content_headers	true
valid_entity_length	true
variances	[]

如您所见，只要有可能，Cowboy都会使用经过深思熟虑的默认值继续处理请求。

除此之外，还可以通过content_types_accepted/2和content_types_provided/2指定任意数量的用户定义回调。它们可以使用任何名称，但是建议为每个函数的回调使用单独的前缀。例如，from_html和to_html在第一种情况下表示我们接受以HTML形式给出的资源，在第二种情况下表示我们以HTML形式发送一个资源。

元数据

Cowboy将在执行的各个点为Req对象设置信息值。您可以通过直接匹配Req对象来检索它们。下表定义了这些值:

Key	描述
media_type	为响应实体协商的content-type
language	为响应实体协商的语言。
charset	为响应实体协商的字符集。

它们可以用来发送适当的主体，以及对使用了HEAD或GET以外方法的请求的响应。

响应报头

Cowboy将在执行REST代码时自动设置响应报头。它们列在下表中。

报头名	说明
content-language	响应主体中使用的语言
content-type	响应主体的媒体类型和字符集
etag	资源的Etag
expires	资源的过期日期
last-modified	资源的最后修改日期
location	请求资源的相对或绝对URI
vary	可以更改资源表示形式的报头列表