Cowboy 用户指南 (十九) - 设计资源处理程序

设计资源处理程序

本章旨在为您提供一个问题列表，您必须回答这些问题才能编写一个好的资源处理器。它是一个可用的一步一步指南。

服务

服务会不可用吗?当它不可用时，我们能检测到它吗?例如，数据库连接问题可以及早检测到。我们也可能计划停用系统的全部或部分。实现service_available回调。

服务实现了哪些HTTP方法?我们需要更多的标准OPTIONS，HEAD, GET, PUT, POST, PATCH和DELETE吗?我们不用这些东西吗?实现known_methods回调函数。

资源处理程序的类型

我是为资源集合编写处理程序，还是为单个资源编写处理程序?

它们的语义是完全不同的。不应在同一个处理程序中混合集合和单一资源。

收集处理程序

如果不进行收集，请跳过本节。

集合是硬编码的还是动态的?例如，如果你将route /users用于用户集合，那么这个集合是硬编码的;如果你使用/forums/:category来收集线程，那么它就不是。当对集合进行硬编码时，可以安全地假定资源始终存在。

我应该实现哪些方法?

OPTIONS 用于获取关于集合的一些信息。即使您没有实现它，也建议允许它，因为Cowboy有一个内置的默认实现。

HEAD和GET用于检索集合。如果你允许GET，也允许HEAD，因为不需要额外的工作使它工作。

POST用于在集合中创建新资源。当资源在知道它们的URI之前就被创建时，通过在集合上使用POST来创建资源是很有用的，这通常是因为资源的部分是动态生成的。一种常见的情况是某种自动递增整数标识符。

接下来的方法很少被允许。

PUT用于创建一个新集合(当该集合不是硬编码的时候)，或替换整个集合。

DELETE用于删除整个集合。

PATCH用于使用请求体中给出的指令修改集合。补丁操作是原子性的。补丁操作可以用于诸如重新排序;添加、修改或删除集合的部分。

单一的资源处理程序

如果您正在进行收集，请跳过本节。

我应该实现哪些方法?

OPTIONS用于获取有关资源的一些信息。即使您没有实现它，也建议允许它，因为Cowboy有一个内置的默认实现。

HEAD和GET用于检索资源。如果你允许GET，也允许HEAD，因为不需要额外的工作使它工作。

POST用于更新资源。

PUT用于创建新资源(当它还不存在时)或替换资源。

DELETE用于删除该资源。

PATCH用于使用请求主体中给出的指令修改资源。补丁操作是原子的。补丁操作可以用于添加、删除或修改资源中的特定值。

资源

按照上面的讨论，实现allowed_methods回调函数。

资源是否一直存在?如果不能，则实现resource_exists回调函数。

我需要在客户端访问资源之前对其进行身份验证吗?我应该提供什么身份验证机制?这可能包括基于表单的(form-based)、基于令牌的(token-based)(在URL或cookie中)、HTTP basic、HTTP digest、SSL证书或任何其他形式的身份验证。实现is_authorized回调函数。

我需要细粒度的访问控制吗?如何确定它们是经过授权的访问?在你的is_authorized回调中处理它。

是否可以禁止对资源的访问，而不管访问是否被授权?一个简单的例子就是对资源的审查。实现禁止的回调。

对已认证用户的访问是否有速率限制?使用rate_limited回调函数。

资源URI的长度有限制吗?例如，URI可以用作存储中的键，并且可能有长度限制。实现uri_too_long。

代表

我提供什么媒体类型?如果基于文本，则提供什么字符集?我提供哪些语言?

实现强制的content_types_provided。为清晰起见，在回调函数前加上to_前缀。例如，to_html或to_text。对于没有实现GET或HEAD方法的资源，您仍然必须接受至少一种媒体类型，但您可以保留回调为未定义的，因为它永远不会被调用。

实现languages_provided或charsets_provided回调函数(如果适用的话)。

是否有其他的报头可能使资源的表示变化?实现variances回调。

根据您对缓存内容的选择，您可能希望实现一个或多个generate_etag、last_modified和expires回调函数。

我是否希望用户或用户代理主动选择可用的表示?在响应体中发送一个可用表示的列表，并实现multiple_choices回调。

重定向

我需要跟踪哪些资源被删除了吗?例如，您可能有一种机制，在移动资源时，会留下指向其新位置的重定向链接。实现先前存在的回调函数。

资源被移动了吗?移动是暂时的吗?如果它是显式临时的(例如由于维护原因)，则实现moved_temporary回调。否则，实现moved_permanent回调。

请求

您需要读取查询字符串吗?个人报头?实现malformed_request并在这个函数中执行所有的解析和验证。注意，此时不应该读取主体。

是否可以有一个请求主体?我能知道它的大小吗?我愿意接受的请求主体的最大size是多少?实现valid_entity_length。

最后，看看与您正在实现的方法相对应的部分。

OPTIONS 方法

默认情况下，Cowboy将返回一个允许的方法列表。我需要向响应添加更多信息吗?实现options方法。

GET 和 HEAD 方法

如果实现了GET和/或HEAD方法，则必须为content_types_provided回调返回的每个content-type实现一个content_types_provided回调。

PUT, POST 和 PATCH 方法

如果你实现了PUT, POST和/或PATCH方法，你必须实现content_types_accepted回调函数，并为它返回的每个内容类型实现一个AcceptCallback回调函数。为清晰起见，在AcceptCallback回调名称前加上from_作为前缀。例如，from_html或from_json。

我们是否要允许POST方法通过它们的URI(比如PUT)直接创建单个资源?实现allow_missing_post回调函数。在这些情况下，建议显式地使用PUT。

当使用PUT创建或替换资源时，是否会有冲突?我们是否要确保两个更新在同一时间不会互相取消?实现is_conflict回调函数。

DELETE 方法

如果你实现DELETE方法，你必须实现delete_resource回调。

当delete_resource返回时，资源是否完全从服务器删除，包括从任何缓存服务?如果没有，并且/或者删除是异步的，我们还无法知道它是否已经完成，那么实现delete_completed回调函数。