V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
Vimax
V2EX  ›  Java

RESTful 接口如何设计好?

  •  
  •   Vimax · 2020-07-03 15:38:21 +08:00 · 3448 次点击
    这是一个创建于 1364 天前的主题,其中的信息可能已经有所发展或是发生改变。

    新项目打算用 RESTful 风格设计 API 接口。请问如果设计符合 RESTful 风格规范的 API ?

    比如分页查询,之前都是将分页信息放在 URL 参数中,现在使用 RESTful 风格,如何将分页信息传递给后端接收。

    如果是用 josn 接收,那么每个分页查询的实体对象是否都做扩展,增加分页参数属性?

    请问 RESTful 风格接口的最佳实践是什么?

    17 条回复    2020-12-28 17:17:42 +08:00
    xuanbg
        1
    xuanbg  
       2020-07-03 15:46:41 +08:00
    spring 可以用实体类接收 url 参数,这是一个小技巧
    abbycin
        2
    abbycin  
       2020-07-03 15:50:20 +08:00 via Android   ❤️ 4
    最佳实践就是不用 restful
    baiyi
        3
    baiyi  
       2020-07-03 15:58:06 +08:00
    月经贴
    baiyi
        4
    baiyi  
       2020-07-03 15:59:38 +08:00   ❤️ 1
    @baiyi #3 RESTful 的最佳实践我投 Github 一票,包括主楼提到的分页
    Rwing
        5
    Rwing  
       2020-07-03 16:05:05 +08:00
    很简单,参考国外大厂
    xingheng
        6
    xingheng  
       2020-07-03 16:17:21 +08:00
    普通的分页请求不存在写操作,RESTful 只是建议用 GET 吧,请求参数就应该放在 url query path 里面。如果是比较复杂的分页,参数比较复杂或者在业务层上将存在写操作的请求才需要调整成 POST 或者其他的吧。

    没有必要纠结参数应该用什么方式回传的,应该先定义用什么请求方法体。规范就是干这事儿的,说错了请纠正我。
    ChanKc
        7
    ChanKc  
       2020-07-03 16:44:29 +08:00 via Android   ❤️ 2
    最佳实践是 hateoas
    分页的话,使用 HTTP 的 link 头来给客户端返回上一页,下一页,第一页和最后一页的链接。让客户端根据 link 的关系,也就是 rel 属性自己找去
    libook
        8
    libook  
       2020-07-03 18:01:17 +08:00   ❤️ 2
    我是 REST 原教主义的,REST 本身只是一套风格和思想,可以用于指导设计出适合自己系统的 API 标准。

    没有银弹。建议从实际需求出发,而不是照搬任何现有的 REST 案例,当然如果能找到适合自身业务的一站式的解决方案也可以。

    所以像分页这种需求,得看有多少种方案可以选,然后分析每一种对你们的实际情况来说是否是最合适的。
    REST 本身对于分页并没有具体的设计,将分页参数放在哪里完全看在业务上你把这些参数归为哪一类,是资源的查询条件还是资源本身或是体系之外的无关信息,你可以继续以 Querystring 的方案来实现,也可以通过在 Header 里传 Range/Content-Range 的方式来实现。REST 要求 API 无状态,所以基于 Cookie 、Session 的翻页就不推荐了。

    当然,如果确实找到了一套别人的实践经评估非常适合自己项目的需求,也可以作为第一版方案先用上,等日后再根据项目发展逐步改进。

    然后 REST 只是众多 API 设计思想中的一种,有其使用的范畴,也有不适用的范畴,建议不要为了上 REST 而强上,如果业务可以拆分模块的话,也可以考虑不同模块使用不同的 API 方案,比如后台接口用 REST,前台接口用 GraphQL 。
    hantsy
        9
    hantsy  
       2020-07-03 18:07:03 +08:00
    日经
    hantsy
        10
    hantsy  
       2020-07-03 18:18:16 +08:00   ❤️ 3
    我谈过好多次了,不想再聊这个话题了,伤神。

    最有效的方法,买本权威的看一下,系统的学习一下, 如:rest in practice.

    简单的参考资料,RestCookbook http://restcookbook.com/ ,Restful API 好几个网站等。

    REST API 设计的质量,可以参考 Richarson Mature Model 。https://martinfowler.com/articles/richardsonMaturityModel.html

    REST 设计的典范,Github API,Heroku 的 API 。

    Pagiantions 基本所有的教程,深入一点文章都是讲到,Header Links, 或者 Query Params 。

    在没被污染前看一下, 马上反 REST 水军,公司胡来 API 有理的 估计冲上来了。
    hantsy
        11
    hantsy  
       2020-07-03 18:27:02 +08:00   ❤️ 1
    Vimax
        12
    Vimax  
    OP
       2020-07-04 12:01:32 +08:00
    @libook 感谢分享和提供的思路。
    Vimax
        13
    Vimax  
    OP
       2020-07-04 12:02:52 +08:00
    @hantsy 谢谢。吸收并采纳。
    Vimax
        14
    Vimax  
    OP
       2020-07-04 12:06:56 +08:00
    @ChanKc 谢谢,很棒很赞。学习采纳。
    EastLord
        15
    EastLord  
       2020-07-04 16:25:35 +08:00
    自己查查吧,老哥 这个问题真的被问过太多遍了
    thinkmore
        16
    thinkmore  
       2020-07-06 09:25:47 +08:00
    https://juejin.im/post/5d8485e36fb9a06b0936543c 可以看看这个关于 restful 接口的命名
    MrByte
        17
    MrByte  
       2020-12-28 17:17:42 +08:00
    @Rwing 看了 ins 和 youtube 的接口设计,比如关注和订阅,也是 follow/unfollow 和 subscribe/unsubcribe
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5942 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 34ms · UTC 02:04 · PVG 10:04 · LAX 19:04 · JFK 22:04
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.