HTTP API请求的基本结构

URL 参数设计

服务端对应的代码(以Java为参考):

服务端Gin框架对应的代码(以Go为参考):

QUERY参数的优缺点:

BODY 参数设计

服务端对应的代码(以Java为参考):

服务端Gin框架对应的代码(以Go为参考):

BODY参数的优缺点:

总结

一文说清楚HTTP API的参数设计

路奇

2024-04-25

🏷

知识点

本文发表于入职啦(公众号: ruzhila) 大家可以访问入职啦学习更多的编程实战。

RESTful 是当前前后端分离架构最重要的协议设计体系,每个后端人员都应该学会设计一个合理的 RESTful API。 在设计 RESTful API 的时候,参数设计是一个非常重要的环节,本文就来说说 HTTP API 的参数设计。

HTTP API请求的基本结构

http

HTTP API 请求的基本结构如上图所示,主要包括:

  • 请求方法(METHOD):GET、POST、PUT、DELETE 等
  • 请求路径(URL):API 的路径
  • 请求体(BODY):API 的请求体

主要包括了三部分:METHOD,URLBody

我们基于一个实际的需求来设计规范, 项目可以参考后端实战:多线程HTTP下载服务器, 我们摘要这里面的两个基本需求:

  1. 列出服务器上的文件
  2. 提交一个下载任务

今天不讲解如何选择METHOD,根据需求,可以判断第一个需求可以优先选择GET,第二个需求可以用PUT或者POST

我们重点讲解如何设计URL

URL 参数设计

根据第一个需求:列出服务器一个目录的所有文件,并且可以根据文件名或者文件大小排序,那么我们需要的参数包括:

  • path: 列出的路径,
  • sort: 排序方式, 可以选择name或者size, 按照文件名或者大小排序 根据需求,实际上的HTTP请求:

list

URL对应是/file/list, 因为选择了GET请求,那么就意味着不能通过BODY提交数据。 所以,所有的参数都应该作为QUERY出现,也就是?后面的部分。

METHODGET的时候,参数都应该作为QUERY出现,也就是?后面的部分。

服务端对应的代码(以Java为参考):

java

服务端Gin框架对应的代码(以Go为参考):

go

QUERY参数的优缺点:

  • 优点:简单,直观,可以直接在浏览器中输入, 并且accesslog能完整记录
  • 缺点:参数长度有限制,不适合传递大数据,并且参数是可以重复的,比如/file/list?path=/&path=/usr,很容易引起歧义

BODY 参数设计

除了METHODGETOPTION之外的所有请求,都建议使用BODY来传递参数,可以传递更复杂的参数

根据第二个需求:提交一个下载任务,我们需要的参数包括:

  • url : 下载的URL
  • btfile: 可以提交一个bt种子文件,这个内容就可能会出现几M的情况

根据需求,实际上的HTTP请求:

submit

这时候比第一个请求多了一个Header Content-Type: application/x-www-form-urlencoded,这个是告诉服务端,请求体是一个表单格式的数据。

当然可以支持的格式特别多,主流还是json格式

服务端对应的代码(以Java为参考):

java

服务端Gin框架对应的代码(以Go为参考):

go

我们从代码上理解,已经从QUERY参数转变为BODY参数, 两种接受参数的方式是不一样的。

如果btfile 比较大,那么就可以通过multipart/form-data来传递,这个是支持文件上传的。

BODY参数的优缺点:

  • 优点:参数长度没有限制,可以传递大数据,参数不会重复
  • 缺点:不直观,不能直接在浏览器中输入,accesslog不能完整记录

总结

  • GET请求,参数都应该作为QUERY出现,也就是?后面的部分
  • 除了GETOPTION之外的所有请求,都建议使用BODY来传递参数,可以传递更复杂的参数

不同的参数方式,服务器的代码就需要用不同的方式去接收参数,这个是需要注意的:

  • QUERY参数,可以通过@RequestParam来接收
  • BODY参数,可以通过@RequestBody来接收

如果大家有更好的设计方式,欢迎加入我们的项目实战群一起讨论

入群学习

友情链接:

Copyright© 2024 Ruzhila.cn 版权所有