前后端 页面 url 与 api url 如何统一命名风格.

[dnjat]

• 打算把页面 url,与 api url 做一个风格统一,查了许多大佬的文章和分析,最后常用的有 rest,rpc 风格,因为才接触这些风格,恐未掌握其精髓,所以下面定义用了似 rest 风格.希望得到大家的建议与使用经验,哪种风格更适合监控,更加适合应付生产线上碰到的一些 url 问题.

• rest,用 get,post,put,delete 来定义动作,围着一个地址,好处,简洁.但多语义比较乏力.

• rpc, 完全用 url 定义作用.

前端页面

url	-
/content/{id:123}	内容详细页
/contents?order=create_time,desc	内容列表页
/contents/query?create_time=2023/09/01,2023/10/01	搜索
/content/{id:123}/edi	内容编辑页
/content/create	内空创建
/content/edit?id=123	创建编辑页为同一个页面

供前端调用 api - 似 rpc 风格

method	url	-
get	/content/get	单条详细,
get	/content/lists?order=file,desc	列表
get	/content/query?type=best	查询
post	/content/create	新建
post	/content/update	更新
post	/content/delete	删除
post	/content/favorite	收藏

供前端调用 api - 似 rest 风格

method	url	-
get	/contents/{id:123}	单条详细
get	/contents?order=file,desc	列表
get	/contents/query?type=best	查询
post	/contents	新建
put	/contents/{id:123}	更新
delete	/contents/{id:123}	删除
post	/contents/{id:123}/favorite	收藏

[xiang0818]

这个其实无所谓。只是要记得在使用幂等 method 的时候，nginx 默认会超时重试。。。

[caisanli]

可以在 API 前加个前缀，避免在 history 模式下前端路由和 API 地址冲突。

[javaisthebest]

老老实实地用 RPC Style 吧 Rest 可以滚进教科书里面了

就打个比方

/account/query?

你们产品要求新用户自动创建一个账号 并且在用户侧也提供了隐私&法律信息

你们前端 后端该怎么理解这个 URL ？

到底是写接口还是查接口？

[justdoit123]

@javaisthebest 哈哈~~ 太真实。 让我想起了 DELETE /user/session/123123123 。 说到底，rest 还是不适合复杂情景。

[thinkershare]

楼上一群说 RESTful API 缺陷的，你们到底理不理解这个东西究竟是什么，解决的问题是什么。先学会正确使用这个东西才来谈它的缺陷。
如果你的 API 是面向浏览器而且是自包含的，我仍然建议你上 RESTful API 。如果你们的团队完全不理解基于资源的 URI Schema 设计. 那就选择 RPC 吧，比较这个玩意不需要动脑子。

[zidian]

老老实实 rpc 吧，rest 都最后都是一团糟。

[dddd1919]

rest 的前提是先搞懂 rest ，表格里的列表和查询本就是一个接口/content ，如果需要搜索或排序的话直接在接口上加参数就可以了
rest 的请求方法定义的是动作，url 对应的是资源，组成一个动宾结构的接口形式，当语义复杂的情况只要定义好资源是什么，很方便就能定义出 url 的格式，如果前后端无法达成对 rest 一致的认知，那趁早放飞，免得进退两难

[dnjat]

@xiang0818 是的,只是一个路径风格而已,到了服务器都是一样的. 幂等是要注意的,网络是不能相信的😆

[dnjat]

@caisanli /content/create 与/api/content/create 的区分 谢谢提醒

[dnjat]

@javaisthebest 这个又到了比写代码还花时间的时候了,我应该把他放在哪合适.我应该叫他什么名字.

[dnjat]

@thinkershare 看到的许多博文,大部分都是根据 rest 方式做的分析.所以很想知道这种方式的优势. 如果 api 是面向的还有 app,小程序之类的,也适合 RESTful API 风格吗.

[dnjat]

@zidian 之前都是用的似 rpc 方式,感觉换成 rest,像改变行为习惯一样. 没弄好,是会弄得一团糟.😂

[dnjat]

@dddd1919 谢谢指出,短短几句比看几篇博文用处更大. 刚又重翻了一篇 rest 看了下, 更感觉这个 rest 像分了类的 graphql. 如果是复杂的语义,只要对参数下手就行了

[thinkershare]

@dnjat 如果对你来说，HTTP 协议只是一个传输协议，就像 GRPC 使用 HTTP2 一样，那么这种风格对你来说没什么用处。RESTful API 是个很复杂的东西，它涉及到了最初 HTTP 协议的思想和 WWW 最初诞生的一切都是超链接的理想状态。URI 的设计其实是个复杂的话题，远非很多人想的那么简单。RESTful API 是 HTTP 协议最初的设计者希望人们使用 HTTP 的方式。理想很丰满，显示很骨感，大家都抛弃了 HTTP 本身的很多特性，决定 POST 一把梭，甚至没几个完整看过 MDN 的 HTTP 协议的介绍。如果要想要搞清楚这个问题，需要先研究 HTTP 协议（ MDN 的内容就已经够了），如果还想深入理解，最好去看 RESTful API 作者的博士论文。
另外如果你的程序并不是面向资源，而是本质上就是一个 RPC 模式，前端就是一个 Application,目的就是要发送执行命令调用，用谓词结构的确是最节约时间的。
如果你的 API 有很多消费者，是面向大众的，有很多客户需要消费你的 API, 那无论是否使用 RESTful API ，你都要好好考虑怎么设计一个文档的 API URI.

[impaul]

作为一个前端程序员，我发现我写的后端接口是 RPC 风格的，因为 PHP 有两个很好用的超级变量 $_GET $_POST 而并没有什么 $_PUT 😂

[dnjat]

@thinkershare 非常谢谢,我再去深入了解下 rest 起源. 和名字挂边的最麻烦了😄

[dnjat]

@impaul put 也是用的 post body 传输方式,delete 用的 url 传值方式.😄 没用过 php,猜想应该也能用$_GET 和$_POST 获取

[YuJianrong]

我的建议是有条件直接上 Graphql 。
不要理睬那些 Resuful 原教旨主义者。

[dnjat]

@YuJianrong 好早啊,莫非在看 ti?😅 一看你就是 graphql 的受益者,当时一看到 graphql 的统一入口就惊呆了,心想这得多麻烦,全放到一个入口路由.不过他的自由查询还是很喜欢的.

[AquanllR]

个人主观提倡：RESTful API