本文发表于入职啦(公众号: 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 : 下载的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来接收
如果大家有更好的设计方式，欢迎加入我们的项目实战群一起讨论
