接口怎么命名 - youngperson/study-100 GitHub Wiki

接口怎么取名字

一个好的接口名字很重要,别人一看就知道是要做什么事情

准守restful的规范，会事半功倍，让一个资源可以被识别，URL可以看成就是资源的地址，给接口取名字就是给项目中的功能取合理的名词，然后对调用方暴露

取名字中的一些规范

  • 使用_或者-让URL的可读性更好点

多个单词组成的名字,名字直接可以用_或-隔开。比如http://xxxxx/news/38119/oschina-translate-reward-plan

  • 使用/来表示资源的层级关系

比如 /repos/:owner/:repo/projects、 /orgs/:org/projects

  • 使用?用来过滤

大多数人把?就是当做参数传递用，很容易造成URI变得复杂、不好理解。

?用于对资源的过滤（通常对应的是一些特定条件的查询结果或算法运算结果）

  • 使用,或者;表示同级资源的关系

比如是批量查询,传入的数据之间用,或者;分割

gitlab接口的例子

  • GET

/events （公共的资源）

/repos/:owner/:repo/events (某些层级下的资源)

/repos/:owner/:repo/issues/events

/feeds

/notifications

/repos/:owner/:repo/notifications

/repos/:owner/:repo/check-runs/:check_run_id

/repos/:owner/:repo/check-runs/:check_run_id/annotations (资源下面还有子类资源,可以继续往下分)

/gists/starred (资源列表,可以用?去搜索/往下加层级)

/gists/:gist_id/commits

/search/projects (?q 搜索条件 sort用来排序的字段 order: asc/desc,sort字段是升序还是降序)

  • POST

/repos/:owner/:repo/check-runs

/user/migrations

  • PATCH

/repos/:owner/:repo/check-runs/:check_run_id

/gists/:gist_id

  • DELETE

/gists/:gist_id

/gists/:gist_id/star

小结

  • 资源名词用复数形式(加s)
  • GET方式表示获取列表/单个(select)，获取列表的参数用?去传递
  • POST方式表示添加数据(insert)，参数传递可以采用json
  • DELETE方式表示删除数据(update)，参数传递可以采用json
  • PATCH方式用来更新数据(update)，参数传递可以采用json
  • 项目中的功能做好拆分，拆分出一个个的资源名词出来
  • 接口的名字不要对外暴露任何的实现细节部分，多要资源名词去命名
  • URI命名：域名/service-name/(资源)版本号/资源(属于上一级资源的子类)
  • 项目中搜索相关的全部放到 域名/service-name/search/下面
  • 项目中通知相关的全部放到 域名/service-name/notifications/下面

参考文章