RESTful Web Service Cookbook 笔记
内容提要
《RESTful Web Service Cookbook》是一本关于RESTful接口设计的指南。文章总结了书中提到的重点，包括HTTP方法的使用场景和解决方案，资源的创建和定位，复合资源的设计，HTTP响应的处理，查询结构的设计等。文章强调了设计RESTful接口时需要考虑的细节和注意事项。
延伸解读
资源设计应以客户端使用模式为导向
文章强调，资源对象的粒度应适合客户端使用模式，而非直接映射现有数据库或对象模型。这意味着设计时需从客户端交互出发，考虑如何降低修改频率、分离可变与不可变数据，并评估可缓存性。这种思路有助于避免接口与后端存储紧耦合，提升API的长期可维护性。
复合资源的权衡：可见性与性能
复合资源虽然能减少请求次数，但会降低统一接口的可见性，因为其表述中可能包含与其他资源重叠的数据。文章建议，若复合资源使用频率不高，可考虑用缓存替代；同时需评估网络开销是否会导致服务端吞吐量下降或延迟增加。设计者应在便利性与性能之间做出权衡。
错误响应应包含可追踪信息
对于客户端错误（4xx）和服务端错误（5xx），文章建议返回状态码和错误发生时间（Date），并在Body中描述错误。如果服务器记录了错误日志，应提供可找到该错误的标识符或链接，便于后期追踪和分析。这能显著提升API的调试效率和运维能力。
查询设计：避免范围查询与缓存难题
为提升缓存和性能，应尽量避免范围查询，可使用预定义查询或HTTP Range头。避免使用SQL、XPATH等通用查询语言，防止URI与数据存储紧耦合。对于参数较多的查询，可考虑POST，但POST不可缓存，Cache-Control和Expires头无效。解决方案是让POST创建临时资源并返回链接，前端后续用GET获取，从而利用缓存。
Q&A
RESTful接口设计中，GET方法的主要用途是什么？
GET方法用于安全与幂等的信息获取。
在RESTful设计中，POST方法适用于哪些场景？
POST方法适用于创建新资源、修改资源和执行需要大数据输入的查询。
如何设计复合资源以降低网络开销？
设计复合资源时需考虑可见性、网络开销和服务端吞吐量，且可考虑使用缓存。
在设计HTTP响应时，应该包含哪些信息？
HTTP响应应包含状态码、错误描述和可追踪的标识符。
为什么在设计查询结构时要避免范围查询？
避免范围查询是为了提高缓存和性能，建议使用预定义查询和HTTP Header。
PUT方法在RESTful接口中有什么限制？
PUT方法仅在客户端可以控制URI的构成时使用，适用于创建新资源。
