Query String VS Path Parameter

概要

Query String 一般是类似这样的URL:/api/resource?parameter=value,Path Parameter 一般是类似:/api/resource/parameterValue.今天工作开发分享链接的过程中遇到了这个疑问是要把shareId这个参数放在 Query String 还是放在 Path Parameter, 所以跑去 Google 了一波.

标准

目前关于这部分的最佳实践应该没有一个统一的文档规范和标准,所以这个标准仅仅是一些别人的建议,并不是真正的业界标准(因为不存在).

first

一般建议,如果是为了定位一个资源(resource)就推荐使用 Path Parameter, 但是如果是为了过滤数据或者是排序之类的作用就推荐使用 Query String. 如果不给这个 parameter或者给一个错误 value 的 parameter, 你的服务器的处理方式是返回一个404那么一般来说推荐使用 Path Parameter.比如今天开发的 share 连接的 GET 接口,本来我是写成了/projects/:project_id/shares?share_id=value这种形式去做的一个 查找 id为这个 value 的操作,但是这个地方是定位资源的,同时如果这个 id 不给或者错误是会返回404的,所以这种情况下我就改成了/projects/:project_id/shares/:share_id(这里面的冒号是 play 框架的 routes 文件中特有的编写方式,意思就是这个变量是个 Path Parameter)

second

如果没有找到 parameter 的值你的服务器处理程序就打算返回一个空列表或者空值,那么这个时候会建议你去使用 Query String,这个其实基本印证了first里头提到的,如果是为了过滤数据或者排序之类的作用是推荐使用 Query String 的.比如说分页时候的页码变量,再比如说时间范围的 interval 变量,这些变量都推荐使用 Query String, 因为他们不存在或者他们的值出问题并不会妨碍到我们定位资源,也不(应该)会被返回404(因为返回什么 status code 取决于开发人员)

last

如果一个 parameter 会影响接下来整个 URL 子树那么推荐使用 Path Parameter. 比如说一个 language 参数应该使用/en/document/foo.txt这种形式而不是使用/document/foo.txt?language=en

wrapping up

URI 参数位置或者命名这种东西仅仅是为了帮助你提升你的工作效率,帮助你和别人协同开发的时候迅速理解对方在路由上的意图,你也完全可以自己设计各种各样的路径规则,只是可能会使URL 变得很复杂,别人理解这些部分内容也需要花费大量的时间

月月说要给我打赏,就还是放了二维码,😝