聊聊RESTful - 接口设计篇（二）

原文链接：https://howardwchen.com/2017/09/25/talk-about-restful-popular-api-design-2/
（本文为“聊聊RESTful”系列文章第三篇，其他文章可通过篇尾链接查看）

大家好，欢迎大家来到“就浩这口”，我们继续上一篇的话题，接着跟大家聊聊，RESTful的接口设计。虽然标题是接口设计，但我其实是希望通过每一个接口设计规则来分析它背后的架构设计思想。是葫芦是瓢得捞出来看，没准还能捞到惊喜。
上篇文章发表之后，收到一些反馈，说文章篇幅较长，其实我自己在最后通读时也有这样的感觉，篇幅太长，读起来会有些吃力，所以从本期开始，我会尽量缩减一下篇幅。

今天的话题是消息体格式。

消息体格式

媒体类型与字符编码

媒体类型是一个容易被大家忽略的概念，因在api开发中，往往只有一种媒体类型，而在web开发中，不管是客户端还是服务端似乎都对媒体类型有很好的处理，以至于开发人员可以无视它的存在。

我这里讲媒体类型，并不是因为它会决定我们接口设计的成败，而是因为，我们可以花非常低的成本，就能实现对媒体类型的正确使用（很可能你已经通过某些框架正确的使用它了）。比如，我开发的接口均使用Json格式，那么我会对客户端有两点要求：

1. 要求客户端请求时必须携带请求头Content-Type: application/json，这样我根据请求头就可以直接拒绝掉非Json的请求而无需解析消息体来判断。
2. 如果客户端请求中包含请求头Accept，那么它的值也必须包含application/json，这样如果未来有一天我们需要支持XML等其他格式的时候，就不会存在客户端误用媒体类型而导致的兼容问题。

以上这些就算不做也几乎不会对你的接口产生任何影响，但我们只需要花很少的成本就能做到它，何乐而不为呢。对于字符编码也是同样的道理，绝大多数接口都已经限定了字符编码为UTF-8，那就在接口文档与实现中真的这么去做吧。

包装与可见性

其实包装并不是一个独立的问题，而是由其他问题引起的一个错误结果，我们仍旧以图书信息为例，我们来看以下两种格式：