本文发表于入职啦(公众号: ruzhila) 大家可以访问入职啦学习更多的编程实战。
RESTful 是当前前后端分离架构最重要的协议设计体系,每个后端人员都应该学会设计一个合理的 RESTful API。
在设计 RESTful API 的时候,参数设计是一个非常重要的环节,本文就来说说 HTTP API 的参数设计。
HTTP API请求的基本结构
HTTP API 请求的基本结构如上图所示,主要包括:
- 请求方法(METHOD):GET、POST、PUT、DELETE 等
- 请求路径(URL):API 的路径
- 请求体(BODY):API 的请求体
主要包括了三部分:METHOD
,URL
和Body
我们基于一个实际的需求来设计规范, 项目可以参考后端实战:多线程HTTP下载服务器, 我们摘要这里面的两个基本需求:
- 列出服务器上的文件
- 提交一个下载任务
今天不讲解如何选择METHOD
,根据需求,可以判断第一个需求可以优先选择GET
,第二个需求可以用PUT
或者POST
。
我们重点讲解如何设计URL
URL 参数设计
根据第一个需求:列出服务器一个目录的所有文件,并且可以根据文件名或者文件大小排序,那么我们需要的参数包括:
path
: 列出的路径,sort
: 排序方式, 可以选择name
或者size
, 按照文件名或者大小排序
根据需求,实际上的HTTP请求:
URL对应是/file/list
, 因为选择了GET
请求,那么就意味着不能通过BODY
提交数据。
所以,所有的参数都应该作为QUERY
出现,也就是?
后面的部分。
当METHOD为GET
的时候,参数都应该作为QUERY
出现,也就是?
后面的部分。
服务端对应的代码(以Java为参考):
服务端Gin框架对应的代码(以Go为参考):
QUERY参数的优缺点:
- 优点:简单,直观,可以直接在浏览器中输入, 并且accesslog能完整记录
- 缺点:参数长度有限制,不适合传递大数据,并且参数是可以重复的,比如
/file/list?path=/&path=/usr
,很容易引起歧义
BODY 参数设计
除了METHOD为GET
和OPTION
之外的所有请求,都建议使用BODY
来传递参数,可以传递更复杂的参数
根据第二个需求:提交一个下载任务,我们需要的参数包括:
url
: 下载的URLbtfile
: 可以提交一个bt种子文件,这个内容就可能会出现几M的情况
根据需求,实际上的HTTP请求:
这时候比第一个请求多了一个Header
Content-Type: application/x-www-form-urlencoded
,这个是告诉服务端,请求体是一个表单格式的数据。
当然可以支持的格式特别多,主流还是json
格式
服务端对应的代码(以Java为参考):
服务端Gin框架对应的代码(以Go为参考):
我们从代码上理解,已经从QUERY
参数转变为BODY
参数, 两种接受参数的方式是不一样的。
如果btfile
比较大,那么就可以通过multipart/form-data
来传递,这个是支持文件上传的。
BODY参数的优缺点:
- 优点:参数长度没有限制,可以传递大数据,参数不会重复
- 缺点:不直观,不能直接在浏览器中输入,accesslog不能完整记录
总结
GET
请求,参数都应该作为QUERY
出现,也就是?
后面的部分- 除了
GET
和OPTION
之外的所有请求,都建议使用BODY
来传递参数,可以传递更复杂的参数
不同的参数方式,服务器的代码就需要用不同的方式去接收参数,这个是需要注意的:
QUERY
参数,可以通过@RequestParam
来接收BODY
参数,可以通过@RequestBody
来接收
如果大家有更好的设计方式,欢迎加入我们的项目实战群一起讨论
关注公众号 入职啦,每日分享有用的知识