栏目分类:
子分类:
返回
名师互学网用户登录
快速导航关闭
当前搜索
当前分类
子分类
实用工具
热门搜索
名师互学网 > IT > 软件开发 > 后端开发 > Java

Restful风格的接口命名规范

Java 更新时间: 发布时间: IT归档 最新发布 模块sitemap 名妆网 法律咨询 聚返吧 英语巴士网 伯小乐 网商动力

Restful风格的接口命名规范

最近换了工作,入职以后写的代码review时被一直提及restful风格命名,被别人拿来无限鞭尸,今天做个总结,供参考!

REST是一个术语的缩写,REpresentational State Transfer,中文直译是“表征状态转移”。
REST是一套风格约定,RESTful是它的形容词形式。比如一套实现了REST风格的接口,可以称之为RESTful接口。

很多项目或公司要求用post 或get 放弃put、delete等,在效果上可以同样实现,但是无疑浪费了 HTTP 协议的潜力,而 REST 则充分利用了 HTTP 规范中的方法,达到接口描述的语义化。

restful风格命名可以分为两种思考方式,所以的都从这两种思路出发思考

  • 请求 API 的 URL 表示用来定位资源;
  • 请求的 METHOD 表示对这个资源进行的操作;

下面示例中的 get、create、search 等动词,都不应该出现在 REST 架构的后端接口路径中。比如:

/api/v1/getUser
/api/v1/createApp
/api/v1/searchResult
/api/v1/deleteAllUsers

总结:

首先加上了动词,肯定是使 URL 更长了;其次对一个资源实体进行不同的操作就是一个不同的 URL,造成 URL 过多难以管理。

其实当你回过头看“URL”这个术语的定义时,更能理解这一点。URL 的意思是统一资源定位符,这个术语已经清晰的表明,一个 URL 应该用来定位资源,而不应该掺入对操作行为的描述。其中 METHOD中的POST、GET、PUT、DELETE已经有了操作行为的描述

在 REST 架构的链接应该是这个样子:

  • URL 中不应该出现任何表示操作的动词,链接只用于对应资源;

  • URL 中应该单复数区分,推荐的实践是永远只用复数;比如GET /api/users表示获取用户的列表;如果获取单个资源,传入 ID,比如/api/users/123表示获取单个用户的信息;

  • 按照资源的逻辑层级,对 URL 进行嵌套,比如一个用户属于某个团队,而这个团队也是众多团队之一;那么获取这个用户的接口可能是这样:GET /api/teams/123/members/234 表示获取 id 为 123 的小组下,id 为234 的成员信息。

    按照类似的规则,可以写出如下的接口

    /api/teams (对应团队列表)

    /api/teams/123 (对应 ID 为 123 的团队)

    /api/teams/123/members (对应 ID 为 123 的团队下的成员列表)

    /api/teams/123/members/456 (对应 ID 为 123 的团队下 ID 未 456 的成员)

  1. 其他规范

    一些其他规范:
    规则1:URI结尾不应包含(/)
    规则2:正斜杠分隔符(/)必须用来指示层级关系
    规则3:应使用连字符( - )来提高URI的可读性
    规则4:不得在URI中使用下划线(_)
    规则5:URI路径中全都使用小写字母

  2. 附上总结的一些实例

    Restful 场景示例

    /api/v1/objects

    创建
    ●参数放于body。
    ●POST 方法。

    ●POST /api/v1/objects : 创建一个主资源
    ●POST /api/v1/objects/{objectId}/sub_objects : 创建一个子资源
    ●POST /api/v1/objects/{objectId}/sub_objects/{sub_objectId}/名词 : 对子资源做"名词"描述的动作,示例:
    ○/api/v1/enterprises/{enterpriseId}/week_reports/{weekReportsId}/comment 对企业下周报做评论(创建一个评论)
    ○/api/v1/enterprises/{enterprise}/members : 添加或邀请企业成员
    单个资源查询
    ●参数放于路径。
    ●GET 方法。

    ●GET /api/v5/enterprises/{enterprise}?access_token : 获取一个企业
    ●GET /api/v5/enterprises/{enterprise}/members/search?query_type=email&query_value=xxx : 获取企业成员信息(通过用户名/邮箱)
    ●GET /api/v5/enterprises/{enterprise}/week_reports/{id}?access_token=xxx : 获取某个企业下某个周报的详情
    更新
    ●参数放于body。
    ●PUT 方法。

    ●PUT /api/v1/users/{id} : 更新用户信息
    ●PUT /api/v5/enterprises/{enterprise}/week_reports/{id}: 更新企业下某个周报的信息
    删除
    ●DELETE 方法。

    ●DELETE /api/v5/enterprises/{enterprise}/week_reports/{id} :删除企业下某个周报
    列表查询(不带分页)
    ●参数放于路径。
    ●GET 方法。

    ●GET /api/v1/objects?access_token=xxx: 列出所有对象,如果数据量范围考虑不需要分页,则不分页

    分页查询(非模糊匹配)
    ●参数放于路径。
    ●GET 方法。

    ●GET /api/v5/enterprises/{enterprise}/week_reports/{id}/comments?access_token=xxx&page=1&limit=10 : 获取企业某个周报评论列表
    搜索(带模糊匹配,带分页)
    ●参数放于路径。
    ●GET 方法。

    ●GET /api/v5/search/users?access_token=xxx&page=1&limit=10&query_key=xxx&sort=xx_sort_type&order=desc/asc 搜索用户
     

转载请注明:文章转载自 www.mshxw.com
本文地址:https://www.mshxw.com/it/959700.html
我们一直用心在做
关于我们 文章归档 网站地图 联系我们

版权所有 (c)2021-2022 MSHXW.COM

ICP备案号:晋ICP备2021003244-6号