版權(quán)聲明：轉(zhuǎn)載時(shí)請(qǐng)以超鏈接形式標(biāo)明文章原始出處和作者信息及本聲明http://phoenixtoday.blogbus.com/logs/45855234.html

最近小組里有一些關(guān)于REST API設(shè)計(jì)的討論，有些收獲，打算在這里寫(xiě)一下。通常來(lái)講設(shè)計(jì)第一個(gè)版本的REST API并不難，難點(diǎn)在于將來(lái)你要改變了這些API，而客戶那里已經(jīng)有對(duì)應(yīng)的客戶端實(shí)現(xiàn)， 那么你怎么保證兼容？或者，至少，你應(yīng)當(dāng)讓這些東西失效吧，這樣客戶才能知道。所以基本上就是兩個(gè)問(wèn)題。

1，在最初設(shè)計(jì)時(shí)，如何盡量保證向后兼容？（這里不提倡過(guò)度設(shè)計(jì)噢，我們是搞敏捷的，哈哈）

2，如果API發(fā)生了改變，該怎么通知已有實(shí)現(xiàn)？

對(duì)于第一個(gè)問(wèn)題，答案相對(duì)而言簡(jiǎn)單一些：支持必要的，但是最少的東西，而且層次不要太多。為什么？用下面的xml，舉個(gè)例子來(lái)說(shuō)



<person>

<name>phoenix</name>

<job>softerware developer</job>

<company>ThoughtWorks</company>

</person>



第一層，指的是這個(gè)xml具體針對(duì)什么，第二層有三個(gè)屬性，分別是name，job和company，這是一個(gè)嵌套層次很好的，而且也沒(méi)有包含過(guò)多的信息。但是如果我們?cè)谝婚_(kāi)始再加上address屬性（假設(shè)它并非必要），那么如果客戶構(gòu)建了一個(gè)客戶端也的確包含了address屬性，那么在下一個(gè)版本的API中，你把這個(gè)屬性去掉了。問(wèn)題是不是出現(xiàn)了？客戶的軟件無(wú)法工作了。反過(guò)來(lái)，如果最開(kāi)始的版本不包含address，但是有客戶強(qiáng)烈要求下一個(gè)版本要支持，那么怎么辦？簡(jiǎn)單！在下一個(gè)版本加上就好了，對(duì)于已有的客戶端，多一行冗余數(shù)據(jù)而已，也不會(huì)導(dǎo)致客戶的軟件無(wú)法工作。好了，這個(gè)問(wèn)題解決了，那么，什么是嵌套層次不要太多。舉個(gè)反例



<person>

<name>phoenix</name>

<job>softerware developer</job>

<company>

<name>ThoughtWorks</name>

<locations type="array">

<city>beijing</city>

<city>san francisco</city>

</locations>

<products>

<product>

<name>mingle</name>

</product>

<product>

<name>cruise</name>

</product>

<product>

<name>twist</name>

</product>

</products>

</company>

</person>



這叫層次太多！一個(gè)company里，包含了太多的嵌套信息，其中l(wèi)ocation還算說(shuō)的過(guò)去（因?yàn)橹皇且粋€(gè)簡(jiǎn)單的數(shù)組），但是products里包含了子對(duì)象就不對(duì)了，這就是第三層對(duì)象了，具體的解決方案可以利用url來(lái)替換掉。世界終于清靜啦！

可是我還不能清靜，因?yàn)橐卮鸬诙€(gè)問(wèn)題：API改變了，該怎么通知已有實(shí)現(xiàn)？這是一個(gè)很頭疼的問(wèn)題，如果能避免回答我絕對(duì)會(huì)避免，可惜，不能！通常有兩種解決方案，但目的都是為了讓客戶的軟件失效（我知道，我知道，這會(huì)讓客戶抓狂，可是我們也沒(méi)轍啊！所以還是能不動(dòng)，則不動(dòng)，打死也不動(dòng)，打不死嘛......就按如下辦）a，使用帶有版本號(hào)的API URL（這是現(xiàn)在最經(jīng)常使用的一種方法），例如api/v2/projects/members.xml前面的api不說(shuō)也明白，v2就是version 2版本2的意思，如果更換了，就變v3，客戶的軟件不能用了，也就知道了；b，利用HTTP header 里的ACCEPT來(lái)解決（別說(shuō)你寫(xiě)了這么多年程序，連HTTP有HEAD都不知道啊！會(huì)被鄙視的！），ACCEPT可以設(shè)置接受的文件，你可以將版本信息放在里面。技術(shù)細(xì)節(jié)不多說(shuō)了，給個(gè)鏈接，供大家參考 http://barelyenough.org/blog/2008/05/versioning-rest-web-services/ 其實(shí)我是比較贊成這種方式的，比較優(yōu)雅，但缺點(diǎn)就是它還不是標(biāo)準(zhǔn)，對(duì)方的程序員也可能不知道HTTP有HEAD，所以做起來(lái)，對(duì)人家可能會(huì)有點(diǎn)復(fù)雜，這里就不再多說(shuō)了。

總之昵～～，小初（想必盯我博客很久的人，也都知道我姓甚名誰(shuí)了，以后我就用真名了）的技術(shù)博客在沉寂了，這么久之后，又回來(lái)了（我胡XX又回來(lái)啦！哈哈），有太多東西要寫(xiě)了，以后會(huì)陸續(xù)帶給大家的，多謝捧場(chǎng)！

PS:為啥Blogbus不支持<pre>標(biāo)簽?zāi)?#xff0c;讓我的xml這么丑的出現(xiàn)在博客里？慚愧呀！

轉(zhuǎn)載于:https://www.cnblogs.com/hnrainll/archive/2011/08/16/2140445.html

總結(jié)

以上是生活随笔為你收集整理的关于REST API设计的一些小经验的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。