SpringBoot开发REST接口的示例分析
小编给大家分享一下SpringBoot开发REST接口的示例分析,相信大部分人都还不怎么了解,因此分享这篇文章给大家参考一下,希望大家阅读完这篇文章后大有收获,下面让我们一起去了解一下吧!
成都创新互联是一家专业提供澄海企业网站建设,专注与成都网站设计、成都网站建设、H5响应式网站、小程序制作等业务。10年已为澄海众多企业、政府机构等服务。创新互联专业网络公司优惠进行中。
具体如下:
HTTP动词与SQL命令对应
GET
从服务器获取资源,可一个或者多个,对应SQL命令中的SELECT GET /users 获取服务器上的所有的用户信息 GET /users/ID 获取指定ID的用户信息
POST
在服务器上创建一个新资源,对应SQL命令中的CREATE POST /users 创建一个新的用户
PUT
在服务器上更新一个资源,客户端提供改变后的完整资源,对应SQL命令中的UPDATE PUT /users/ID 更新指定ID的用户的全部信息
DELETE
从服务器上删除一个资源,对应SQL命令中的DELETE DELETE /users/ID 删除指定ID的用户信息
PATCH
在服务器更新一个资源的部分属性,对应SQL命令中的UPDATE PATCH /users/ID 更新指定ID的用户的某个属性
URL中的约定
URL中名词使用复数形式
URL中的名称是使用单数还是使用复数的问题,争议由来已久。URL中的名词一般对应数据库中的表,表中存储的是同类数据, 在实践中我是强制使用复数形式 ,看上去更舒服些。
/users /users/1 /roles /roles/1
至于一些不规则的、不可数的名词就见仁见智吧。
/heroes /heroes/1 /people /people/1 /foots /foots/1 /feet /feet/1
版本
讲版本号加入到URL中以应对不兼容的和破坏性的更改。发布新API时,客户端可以自如的迁移到新API,不会因调用完全不同的新API而陷入窘境。使用直观的“V”前缀来表示后面的数字是版本号,不需要次级版本号,不应该频繁的发布API版本。
/edu/v1/users /edu/v1/roles
对可选的、复杂的参数使用查询字符串
为了让URL更小、更简洁,为资源设置一个基本URL,讲可选的、复杂的参数用查询字符串表示。
/edu/v1/users?enabled=1&roleid=1
提供分页信息
一次性返回数据库中的所有的资源不是一个好主意,因此需要提供分页机制。通常使用数据库中众所周知的参数offset和limit
/edu/v1/users?enabled=1&offset=1&limit=15
如果客户端没有传递这些参数,则应使用默认值,通常offset=0,limit=10。
非资源请求使用动词
有时API调用并不涉及资源,在这种情况下,服务器执行一个操作病将结果返回给客户端。
/edu/v1/calc?p=100
考虑特定资源和跨资源搜索
提供对特定止缘的搜索很容易,只需要使用相应的资源集合,并将搜索字符串附加到查询参数中即可。
/edu/v1/users?username=李庆海
如果需要对所有资源提供全局搜索,则需要使用其他方法。
/edu/v1/search?key=李庆海
响应结果
使用小驼峰命名法作为属性标识符
通常,RESTful Web服务将被JavaScript编写的客户端使用。客户端会将JSON响应转换为JavaScript对象,然后调用其属性。因此,最好遵循JavaScript代码通用规范。
person.year_of_birth // 不推荐,违反JavaScript代码通用规范 person.YearOfBirth // 不推荐,JavaScript构造方法命名 person.yearOfBirth // 推荐
提供分页信息
返回结果比较多时,应提供分页信息。
{ "page": 0, "size": 10, "total": 3465, "obj": [ ] }
Spring MVC开发REST接口
常用注解
@RestController
@RestController是@ResponseBody和@Controller的组合注解。
@RequestMapping
此注解即可以作用在控制器的某个方法上,也可以作用在此控制器类上。当控制器在类级别上添加@RequestMapping注解时,这个注解会应用到控制器的所有处理器方法上。处理器方法上的@RequestMapping注解会对类级别上的@RequestMapping的声明进行补充。
@PostMapping
组合注解,是@RequestMapping(method =RequestMethod.POST)的缩写。
@PutMapping
组合注解,是@RequestMapping(method = RequestMethod.PUT)的缩写。
@PatchMapping
组合注解,是@RequestMapping(method = RequestMethod.PATCH)的缩写。
@DeleteMapping
组合注解,是@RequestMapping(method = RequestMethod.DELETE)的缩写。
@GetMapping
组合注解,是@RequestMapping(method = RequestMethod.GET)的缩写。
@PathVariable
获取url中的数据。
@RequestParam
获取请求参数的值。
REST接口及Swagger 编写API文档示例
关于Swagger的使用可参考Spring Boot 项目中使用Swagger2 。方法体中的代码不重要,重要的是方法的签名以及与HTTP动词的映射。
import java.util.Date; import javax.persistence.EntityNotFoundException; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.domain.Page; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PatchMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import cn.com.infcn.jianshu.Service.UserService; import cn.com.infcn.jianshu.exception.BizException; import cn.com.infcn.jianshu.exception.LoginNameOrPasswordErrorException; import cn.com.infcn.jianshu.exception.ResourceExistsException; import cn.com.infcn.jianshu.model.User; import cn.com.infcn.jianshu.util.JsonResult; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; /** * 系统用户Controller * * @author 李庆海 * */ @Api(value = "系统用户接口", tags = "系统管理") @RestController @RequestMapping("/v3/edu/users") public class UserController { @Autowired private UserService userService; /** * 添加用户,注册 * * @param loginName * 登录账号 * @param userName * 用户名称 * @param password * 登录密码 * @param roleId * 用户角色 * @return * @throws ResourceExistsException */ @ApiOperation(value = "添加用户") @PostMapping("/") public JsonResult create( @ApiParam(name = "loginName", value = "登录账号", required = true) @RequestParam(required = true) @RequestBody String loginName, @ApiParam(name = "userName", value = "用户名称", required = true) @RequestParam(required = true) @RequestBody String userName, @ApiParam(name = "password", value = "登录密码", required = true) @RequestParam(required = true) @RequestBody String password, @ApiParam(name = "roleId", value = "用户角色编号", required = true) @RequestParam(required = true) @RequestBody String roleId) throws ResourceExistsException { boolean exists = this.userService.exists(loginName); if (exists) { throw new ResourceExistsException(loginName); } User user = userService.create(loginName, password, userName, roleId); return JsonResult.success(user); } /** * 用户凭借登录账号和登录密码进行登录 * * @param loginName * 登录账号 * @param password * 登录密码 * @throws EntityNotFoundException */ @ApiOperation(value = "根据用户编号查询用户信息") @GetMapping("/login") public JsonResult login( @ApiParam(name = "loginName", value = "登录账号", required = true) @RequestParam(required = true) String loginName, @ApiParam(name = "password", value = "登录密码", required = true) @RequestParam(required = true) String password) throws LoginNameOrPasswordErrorException { User user = this.userService.login(loginName, password); if (null == user) { throw new LoginNameOrPasswordErrorException(); } return JsonResult.success(user); } /** * 根据用户编号查询用户信息 * * @param id * 用户编号 * @throws EntityNotFoundException */ @ApiOperation(value = "根据用户编号查询用户信息") @GetMapping("/{id}") public JsonResult read( @ApiParam(name = "id", value = "用户编号,主键", required = true) @PathVariable(required = true) String id) throws EntityNotFoundException { User user = this.userService.getOne(id); return JsonResult.success(user); } /** * 账户注销,不删除用户的数据 * * @param userId * 用户编号 * @return */ @ApiOperation(value = "注销账户") @PatchMapping("/{id}") public JsonResult cancel( @ApiParam(name = "id", value = "用户编号,主键", required = true) @PathVariable(required = true) String id) throws EntityNotFoundException { this.userService.cancel(id); return JsonResult.success(); } /** * 重置密码 * * @param id * 用户编号 * @param password * 新登录密码 * @return */ @ApiOperation(value = "重置密码") @PatchMapping("/") public JsonResult updatePassword( @ApiParam(name = "id", value = "用户编号,主键", required = true) @RequestParam(required = true) String id, @ApiParam(name = "password", value = "新登录密码", required = true) @RequestParam(required = true) String password) { this.userService.updatePassword(id, password); return JsonResult.success(); } /** * 多条件组合查询 * * @param userName * 用户名称 * @param roleId * 用户角色 * @param start * 开始日期 * @param end * 结束日期 * @param page * 分页,从0开始 * @param size * 每页的行数,默认10 * @return * @throws BizException */ @ApiOperation(value = "用户信息查询") @GetMapping("/") public JsonResult query( @ApiParam(name = "userName", value = "用户名称,查询关键词", required = false) @RequestParam(required = false) String userName, @ApiParam(name = "roleId", value = "用户角色编号", required = false) @RequestParam(required = false) String roleId, @ApiParam(name = "start", value = "用户角色编号", required = false) @RequestParam(required = false) Date start, @ApiParam(name = "end", value = "用户角色编号", required = false) @RequestParam(required = false) Date end, @ApiParam(name = "page", value = "分页,第几页,从1开始", defaultValue = "1", required = true) @RequestParam(defaultValue = "1", required = true) int page, @ApiParam(name = "size", value = "每页的行数,正整数", defaultValue = "10", required = true) @RequestParam(defaultValue = "10", required = true) int size) throws BizException { Pagedatas = this.userService.findDatas(userName, roleId, start, end, page, size); if (null == datas || null == datas.getContent() || datas.getContent().isEmpty()) { throw new BizException("用户不存在"); } return JsonResult.success(datas); } }
Swagger2接口文档效果图
以上是“SpringBoot开发REST接口的示例分析”这篇文章的所有内容,感谢各位的阅读!相信大家都有了一定的了解,希望分享的内容对大家有所帮助,如果还想学习更多知识,欢迎关注创新互联行业资讯频道!
网站栏目:SpringBoot开发REST接口的示例分析
文章来源:http://myzitong.com/article/gjcdsj.html