RESTful设计规则

已经有无数人写过类似的内容,基本内容也都差不多,这次我写点少数人写过的。


1. 基本规则:以资源为视角,固定操作方式

GET /books   #获取书目

GET /books/1  #获取某本书详情

GET /books/new  #显示添加新书的表单

POST /books  #添加新书

GET /books/1/edit  #显示编辑某本书的表单

PUT /books/1  #更新某本书

DELETE /books/1  #删除某本书

以上内容来自rails,也常常是大家写过无数遍的内容,对URL以资源的视角进行观察,每种资源都有其固定的URL模式,以模式映射对资源的固有操作方法。多数人的文章可能就收尾了,这个规则太简单,但现实世界更复杂一点,真实用户会碰上这个规则无法解决的冲突。


2. 子资源

子资源如同书和评论的类比,每本书都有自己的评论,评论作为一种资源从属于书。虽然可以把子资源提升为顶层资源,但肯定不是指的提倡的做法。

/books/1/comments

/books/1/comments/c1

子资源以 主资源+id+子资源+[子资源id] 的形式构造URL,以达到快速获取某主资源下子资源的目的。


3. 资源非标准行为

虽然标准的增删查改能覆盖绝大部分资源操作需求,但是总有一些时候,资源有特别的操作,或者是你想给资源的某个小操作赋予一个更有意义的名字,如对一本书进行 LIKE 操作。

把 LIKE 抽象成 likes 子资源是无意义的,这是一个操作行为,同时这个行为是针对用户资源而不是书这个资源。但我们可以把这个行为使用子资源的形式构建URL。

POST /books/1/like

这确实是参考了子资源的URL,能 work, 但是和子资源有语义冲突,我们应该想想更好的做法。


再从新想想非标准行为这个点:LIKE 是一个行为,可以抽象为一个资源,但是这个资源并不能归结成为子资源,但是如果是顶级资源的话,又不能算作纯粹的资源,如  /likes 这个顶级路径就很怪异。重要的是,他是和书相关的。

POST  /books/like/1

我们可以给这个顶级路径增加一个 namespace 来构建URL,既能区别于子资源模式,又能表达和书的相关性。


4. 资源子集操作行为

最后讲讲资源子集操作,实际上是某个顶级资源的集体对象的新的表现形式,或者批量修改操作。比如我想对图书资源再分别增加一个获取热门书目URL,一个搜索URL,类似这种获取资源子集的操作,应该怎么构建URL呢?

通过查询参数的方式来指定获取的资源子集,这有两个不足。第一,增加了controller的复杂性,里面的实现要 ifelse。第二,URL格式不好,我们就是想给URL起个好听一点的名字。

GET /books/hot

GET /books/search

这个模式其实不错,可读性和关联性都有了,但是有点和读取某本书详情的URL相冲突。

我觉得将子集查询抽象为新的只读资源可能更好,包括在controller的结构上。

GET /hot

GET /hot-books

GET /search


5. URL不是重点,重点是controller要完全符合第1条规则

我们不会在一个资源的controller上添加除了增删查改以外的任何方法,拿rails来讲也就是

index

show(id)

create

update(id)

delete(id)

所以当我想通过controller给资源增加非标准行为或者资源子集操作行为的时候,不管URL最后如何设计,我都会把这个行为抽象到一个新的controller中,让这个controller符合第1条规则。

controller严格符合规则的好处是,程序接口统一,框架能够在这个统一的框架下提供更好的支持。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 159,219评论 4 362
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 67,363评论 1 293
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 108,933评论 0 243
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 44,020评论 0 206
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 52,400评论 3 287
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 40,640评论 1 219
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,896评论 2 313
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 30,597评论 0 199
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 34,327评论 1 244
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 30,581评论 2 246
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 32,072评论 1 261
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 28,399评论 2 253
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 33,054评论 3 236
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 26,083评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,849评论 0 195
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 35,672评论 2 274
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 35,585评论 2 270

推荐阅读更多精彩内容