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、一般简单路由中不需要带动词，除非是比较复杂的情况