zoukankan      html  css  js  c++  java
  • Java Web API 接口规范

    参考资料:

    https://www.in28minutes.com/microservices-and-restful-services-with-spring-boot-for-beginners 

    https://spring.io/guides/tutorials/bookmarks/

    一、Controller  对于 Post接口写法

    旧写法:

    新写法:

    模型写法:

    修改后swagger展示效果:

    说明:

    1、@ApiImplicitParam 中的东西显得多余  

    2、在RESTFUL风格中,从资源角度考虑的话,@PostMapping 本身表示的就是要添加一个资源,其后可以不添加路由  

    3、@RequestBody 中的 @ApiParam 显的多余  

    4、在BdAreaRegion模型类中加入@ApiModelProperty 可以让前端swagger显示更清晰

    说明:

    1、类似这种输入参数的空值判断可以在架构层面利用切面统一来处理 或者用 @Valid 注解来校验

    二: Controller 中对于 delete 接口写法

    旧写法:

    新写法:

    说明:

    1、删除的话用 @DeleteMapping 能更清晰的表示此操作

    2、一般操作的话都是通过主键进行删除

    3、在设计上应该注意此删除的话是应该从数据库中进行硬删除还是只是做个标记进行软删除

    三: Controller 中对于 put 接口写法

    旧写法:

    新写法:

    说明:

    1、更新单个信息最好具体明确要更新的唯一标识,然后加上更新后的数据

    2、数据验证判断应该用切面或者是其他方式来做

    四:Controller 中对于批量更新 put接口写法

    旧写法:

    新写法:

    说明:

    1、最好的话就不应该用Map 来进行入参传递, 应该用类列表或数组来进行传递

    2、对于参数入参应尽量表达清楚信息否则以后难以维护,特别在前后端分离的开发方式下

    五: Controller 中 get 接口写法

    旧方法:

    新方法;

    说明:

    1、修改路由名: 因为根据RESTFUL 风格, 在路由中一般是不包含动词,只是包含资源, 动词一般用Get/Post/Put/Delete等Http中的操作符表示, 这也是为什么RESTFUL风格很好利用了HTTP协议的一种体现

    2、一般Get方法的简单数据传递用参数传递或者路径传递,不用Body传递

    旧方法:

    说明:

    1、一般在函数传参的过程中形参数量超过5个需要用类包装起来

    2、如果用类把形参包装起来之后那@ApiImplicitParams 这些注释就可以不需要, 直接在类中写

    3、为了更好的区分概念和共用的意图, 可以把分页(current/pageSize)两个字段封装成Pager类,用来表达分页的概念,这样其它所有的查询分页相关的函数都可以用Pager表达

    4、一般简单路由中不需要带动词,除非是比较复杂的情况

  • 相关阅读:
    BZOJ 2653 middle
    BZOJ 3207 花神的嘲讽计划Ⅰ
    BZOJ 3689 异或之
    BZOJ 3037 创世纪
    BZOJ [1264] [ AHOI2006]基因匹配Match
    BZOJ 2186 [Sdoi2008]沙拉公主的困惑
    BZOJ 3362 Navigation Nightmare
    BZOJ 3209 花神的数论题
    BZOJ 1411 ZJOI2009 硬币游戏
    【HDU1573】X问题
  • 原文地址:https://www.cnblogs.com/PengQuanfeng/p/9882595.html
Copyright © 2011-2022 走看看