浅谈Spring Boot 开发REST接口最佳实践

本文介绍了Spring Boot 开发REST接口最佳实践,分享给大家,具体如下:

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 {
  Page<User> datas = 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接口文档效果图

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持我们。

(0)

相关推荐

  • 使用SpringBoot开发Restful服务实现增删改查功能

    在去年的时候,在各种渠道中略微的了解了SpringBoot,在开发web项目的时候是如何的方便.快捷.但是当时并没有认真的去学习下,毕竟感觉自己在Struts和SpringMVC都用得不太熟练.不过在看了很多关于SpringBoot的介绍之后,并没有想象中的那么难,于是开始准备学习SpringBoot. 在闲暇之余的时候,看了下SpringBoot实战以及一些大神关于SpringBoot的博客之后,开始写起了我的第一个SpringBoot的项目.在能够对SpringBoot进行一些简单的开发Re

  • Spring Boot集成springfox-swagger2构建restful API的方法教程

    前言 之前跟大家分享了Spring MVC集成springfox-swagger2构建restful API,简单写了如何在springmvc中集成swagger2.这边记录下在springboot中如何集成swagger2.其实使用基本相同. 方法如下: 首先还是引用相关jar包.我使用的maven,在pom.xml中引用相关依赖(原来我使用的是2.2.0的,现在使用2.4.0的): <dependency> <groupId>io.springfox</groupId&g

  • SpringBoot构建Restful service完成Get和Post请求

    一个基本的RESTfule service最进场向外提供的请求Method就是Get和Post. 在Get中,常用的都会在请求上带上参数,或者是路径参数.响应Json. 在Post中,常用的会提交form data或者json data作为参数,响应Json. 1. Get请求,url传参,返回json. 先准备一个请求后,响应的对象. package com.example.demo; public class Echo { private final long id; private fin

  • Spring Boot 实现Restful webservice服务端示例代码

    1.Spring Boot configurations application.yml spring: profiles: active: dev mvc: favicon: enabled: false datasource: driver-class-name: com.mysql.jdbc.Driver url: jdbc:mysql://localhost:3306/wit_neptune?createDatabaseIfNotExist=true&useUnicode=true&

  • 利用Spring Boot如何开发REST服务详解

    REST服务介绍 RESTful service是一种架构模式,近几年比较流行了,它的轻量级web服务,发挥HTTP协议的原生的GET,PUT,POST,DELETE. REST模式的Web服务与复杂的SOAP和XML-RPC对比来讲明显的更加简洁,越来越多的web服务开始采用REST风格设计和实现.例如,Amazon.com提供接近REST风格的Web服务进行图书查找:雅虎提供的Web服务也是REST风格的.REST 并非始终是正确的选择. 它作为一种设计 Web 服务的方法而变得流行,这种方

  • SpringBoot集成Swagger2实现Restful(类型转换错误解决办法)

    pom.xml增加依赖包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <

  • 详解SpringBoot restful api的单元测试

    现在我们来利用Spring Boot来构建一个RestFul API,具体如下: 1.添加Springboot测试注解 @RunWith(SpringRunner.class) @SpringBootTest public class UserControllerTest { } 2.伪造mvc环境 // 注入Spring 工厂 @Autowired private WebApplicationContext wac; //伪造mvc环境 private MockMvc mockMvc; @Be

  • 详解Spring Boot实战之Rest接口开发及数据库基本操作

    本文介绍了Spring Boot实战之Rest接口开发及数据库基本操作,分享给大家 1.修改pom.xml,添加依赖库,本文使用的是mysql <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <

  • 详解Spring Boot实战之Restful API的构建

    上一篇文章讲解了通过Spring boot与JdbcTemplate.JPA和MyBatis的集成,实现对数据库的访问.今天主要给大家分享一下如何通过Spring boot向前端返回数据. 在现在的开发流程中,为了最大程度实现前后端的分离,通常后端接口只提供数据接口,由前端通过Ajax请求从后端获取数据并进行渲染再展示给用户.我们用的最多的方式就是后端会返回给前端一个JSON字符串,前端解析JSON字符串生成JavaScript的对象,然后再做处理.本文就来演示一下Spring boot如何实现

  • 详解使用Spring Boot开发Restful程序

    一.简介 Spring Boot是由Pivotal团队提供的全新框架,其设计目的是用来简化新spring应用的初始搭建以及开发过程.该框架使用了特定的方式来进行配置,从而使开发人员不再需要定义样板化的配置.通过这种方式,Boot致力于在蓬勃发展的快速应用开发领域(rapid application development)成为领导者. 多年以来,Spring IO平台饱受非议的一点就是大量的XML配置以及复杂的依赖管理.在去年的SpringOne 2GX会议上,Pivotal的CTO Adria

随机推荐