一文说清楚HTTP API的参数设计
一文说清楚HTTP API的参数设计
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
: 下载的URL - btfile
: 可以提交一个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
来接收