基于 Spring Boot 的 RESTful API 设计与实现

最新推荐文章于 2024-01-28 14:32:14 发布

ceshiren_com

最新推荐文章于 2024-01-28 14:32:14 发布

阅读量407

点赞数

分类专栏：软件测试技能文章标签： restful spring boot java

本文链接：https://blog.csdn.net/ceshiren_com/article/details/125071205

版权

软件测试技能专栏收录该内容

81 篇文章 1 订阅

订阅专栏

本文节选自霍格沃兹测试学院内部教材

RESTful 是一种规范，符合 RESTful 的 Api 就是 RESTful Api。简单的说就是可联网设备利用 HTTP 协议通过 GET、POST、DELETE、PUT、PATCH 来操作具有 URI 标识的服务器资源，返回统一格式的资源信息，包括 JSON、XML、CSV、ProtoBuf、其他格式。

RESTful 的核心思想是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /case 这个命令，GET 是动词，/case 是宾语。

RESTful API简介

简捷、快速：RESTful 由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了 http 最初的应用协议设计理念。
RESTful 架构遵循统一接口原则，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的 HTTP 方法如 GET ，PUT 和 POST ，并遵循这些方法的语义。

设计规范

HTTP 请求动词

常用的动词有以下 5 个

动词	说明
GET	从服务器取出资源（一项或多项）
POST	在服务器新建一个资源
PUT	在服务器更新资源（客户端提供改变后的完整资源）
PATCH	在服务器更新资源（客户端提供改变的属性）
DELETE	从服务器删除资源

HTTP 响应状态码

响应状态码	说明	适用的 HTTP 请求动词
200	OK-服务器成功返回用户请求的数据	GET
201	CREATED-用户新建或修改数据成功	POST/PUT/PATCH
400	INVALID REQUEST-用户发出的请求有错误，服务器没有进行新建或修改数据的操作	POST/PUT/PATCH
401	Unauthorized-表示用户没有权限	所有请求
403	Forbidden-表示用户得到授权（与 401 错误相对），但是访问是被禁止的	所有请求
404	NOT FOUND-用户发出的请求针对的是不存在的记录，服务器没有进行操作	所有请求
500	INTERNAL SERVER ERROR-服务器发生错误，用户将无法判断发出的请求是否成功	所有请求

详情见 https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Spring Boot 实现 RESTful API

我们可以通过 Spring Boot 注解来实现 RESTful API 。

Spring Boot 注解

现在需要编写的是对一个用户的增删改查操作，如下表是一个非 RESTful 和标准 RESTful 的对比表。

应用场景	注解	注解说明
处理请求	Controller	处理 Http 请求
处理请求	RestController	Controller 的衍生注解，详情见下文
路由请求	RequestMapping	路由请求可以设置各种请求方法，如 GET/POST/PUT/DELETE 等 http 请求方法
路由请求	GetMapping	GET 方法的路由
路由请求	PostMapping	POST 方法的路由
路由请求	PutMapping	PUT 方法的路由
请求参数	DeleteMapping	DELETE 方法的路由
请求参数	PathVariable	处理请求 url 路径中的参数 /user/{id}
请求参数	RequestParam	处理问号后面的参数
请求参数	RequestBody	请求参数以 json 格式提交
返回参数	ResponseBody	响应数据以 json 格式返回

下面我们着重介绍下以下两对注解。

Controller 与 RestController

Controller 一般应用在有返回界面的应用场景下。例如，管理后台使用了模板技术如 thymeleaf 开发，需要从后台直接返回 Model 对象到前台，那么这时候就需要使用 Controller 来注解。

RestController 一般应用在只有接口的应用场景下. 例如开发前后端分离的项目时，通过 Ajax 请求服务端接口，那么接口就使用 RestController 统一注解。

需要注意的是 RestController 是 Controller 的子集。RestController 是 Spring4 后新加的注解，从 RestController 注解源码可以看出 RestController 是 Controller 和 ResponseBody 两个注解的结合体，即Controller=RestController+ResponseBody。

RestController 注解源码

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {
    @AliasFor(
        annotation = Controller.class
    )
    String value() default "";
}

RequestMapping 与 GetMapping

RequestMapping 和GetMapping/PostMapping/PutMapping/DeleteMapping 作用一样，其实可以相互替换，后者是前者的简化版本。

GetMapping 其实就等于将 RequestMapping 注解的 method 属性设置为 GET，PostMapping 其实就等于将 RequestMapping 注解的 method 属性设置为 POST，PutMapping、DeleteMapping 其实就等于将 RequestMapping 注解的 method 属性分别设置为 PUT、DELETE。

也就是说GetMapping、PostMapping、PutMapping、DeleteMapping 是 RequestMapping 的子集。

我们来看看 RequestMapping 的源码：

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Mapping
public @interface RequestMapping {
    String name() default "";


    //请求URI
    @AliasFor("path")
    String[] value() default {};
    @AliasFor("value")
    String[] path() default {};
    //请求类型，如 GET、POST、PUT、DELETE 等
    RequestMethod[] method() default {};
    //请求参数中必须包含某些参数值，才让该方法处理。
    String[] params() default {};
    //请求参数中必须包含某些指定的header值，才能让该方法处理请求。
    String[] headers() default {};
    //请求的内容类型（Content-Type），例如application/json, text/html;
    String[] consumes() default {};
    //响应的内容类型，仅当 request 请求头中的( Accept )类型中包含该指定类型才返回；
    String[] produces() default {};
}

示例说明：

示例	说明
RequestMapping("/index")	默认为 GET 方法的路由 /index
RequestMapping(value="/index",method = RequestMethod.GET)	同上面一条
RequestMapping(value="/add",method = RequestMethod.POST)	路由为 /add 的 POST 请求
RequestMapping(value="/add",method = RequestMethod.POST),consumes="application/json"	路由为 /add 的 POST 请求，但仅仅处理 application/json 的请求
RequestMapping(value="/add",method = RequestMethod.POST),produces="application/json"	路由为 /add 的 POST 请求，强调返回为 JSON 格式
RequestMapping(value="/add",method = RequestMethod.POST),params="myParam=ceshiren"	路由为 /add 的 POST 请求，但仅仅处理头部包括 myParam=xyz 的请求
RequestMapping(value="/add",method = RequestMethod.POST),headers="Referer=http://www.ceshiren.com/"	路由为 /add 的 POST 请求，但仅仅处理来源为 www.ceshiren.com 的请求

API 形式

API 名称	非 RESTful	RESTful API
获取用户	/user/query/1	/user/1 GET
新增用户	/user/add	/user POST
更新用户	/user/edit	/user PUT
删除用户	/user/delete	/user DELETE

示例代码

新增 2 个文件：dto/UserDto.java 和 controller/HogwartsTestUserController.java ，其中 UserController 类中包括了对用户的 4 个操作增删改查。

public class UserDto {


    private String name;
    private String pwd;


    public String getName() {
        return name;
    }


    public void setName(String name) {
        this.name = name;
    }


    public String getPwd() {
        return pwd;
    }


    public void setPwd(String pwd) {
        this.pwd = pwd;
    }
}

/**
 * RESTful API 风格示例 对资源 user 进行操作
 * 本示例没有使用数据库，也没有使用 service 类来辅助完成，所有操作在本类中完成
 * */
@Api(tags = "霍格沃兹测试学院-用户管理模块", hidden = true)
@RestController
@RequestMapping("/api/user")
public class HogwartsTestUserController {


    /**
     * 查询用户列表，返回一个JSON数组
     * */
    @ApiOperation("查询用户列表")
    @GetMapping("/users")
    @ResponseStatus(HttpStatus.OK)
    public Object getUsers(){
        List<UserDto> list = getData();
        return list;
    }


    /**
     * 查询用户信息，返回一个新建的JSON对象
     * */
    @ApiOperation("查询用户信息")
    @GetMapping("/users/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Object getUser(@PathVariable("id") Long id){


        if(Objects.isNull(id)){
            return null;
        }


        List<UserDto> list= getData();
        UserDto userDto = getUserDto(id, list);


        return userDto;
    }


    /**
     * 新增用户
     * */
    @ApiOperation("新增用户")
    @PostMapping("/users")
    @ResponseStatus(HttpStatus.CREATED)
    public Object addUser(@RequestBody UserDto user){


        List<UserDto> list= getData();
        list.add(user);//模拟向列表中增加数据
        return user;
    }


    /**
     * 编辑用户
     * */
    @ApiOperation("编辑用户")
    @PutMapping("/users/{id}")
    @ResponseStatus(HttpStatus.CREATED)
    public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){
        List<UserDto> list = getData();
        for (UserDto userDto:list) {
            if(id.equals(userDto.getId())){
                userDto = user;
                break;
            }
        }


        return user;
    }


    /**
     * 删除用户
     * */
    @ApiOperation("删除用户")
    @DeleteMapping("/users/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public Object deleteUser(@PathVariable("id") Long id){
        List<UserDto> list = getData();
        UserDto userDto = getUserDto(id, list);
        return  userDto;
    }


    /**
     * 模拟数据
     * */
    private List<UserDto> getData(){
        List<UserDto> list=new ArrayList<>();


        UserDto userDto = new UserDto();
        userDto.setId(1L);
        userDto.setName("admin");
        userDto.setPwd("admin");
        list.add(userDto);


        userDto = new UserDto();
        userDto.setId(2L);
        userDto.setName("HogwartsTest1");
        userDto.setPwd("HogwartsTest1");
        list.add(userDto);


        userDto = new UserDto();
        userDto.setId(3L);
        userDto.setName("HogwartsTest2");
        userDto.setPwd("HogwartsTest2");
        list.add(userDto);


        userDto = new UserDto();
        userDto.setId(4L);
        userDto.setName("HogwartsTest3");
        userDto.setPwd("HogwartsTest3");
        list.add(userDto);


        return  list;
    }


    /**
     *  模拟根据id查询列表中的数据
     * @param id
     * @param list
     * @return
     */
    private UserDto getUserDto( Long id, List<UserDto> list) {
        UserDto UserDto = null;
        for (UserDto user : list) {
            if (id.equals(user.getId())) {
                UserDto = user;
                break;
            }
        }
        return UserDto;
    }
}

使用 Postman 测试

获取全部资源获取所有用户

GET http://127.0.0.1:8081/api/user/users/

响应参数

[
  {
    "id": 1,
    "name": "admin",
    "pwd": "admin"
  },
  {
    "id": 2,
    "name": "HogwartsTest1",
    "pwd": "HogwartsTest1"
  },
  {
    "id": 3,
    "name": "HogwartsTest2",
    "pwd": "HogwartsTest2"
  },
  {
    "id": 4,
    "name": "HogwartsTest3",
    "pwd": "HogwartsTest3"
  }
]

获取单个资源获取用户

GET http://127.0.0.1:8081/api/user/users/3

新增一个资源新增一个用户

POST http://127.0.0.1:8081/api/user/users

请求参数

{
  "id": 4,
  "name": "HogwartsTest5",
  "pwd": "HogwartsTest5"
}

编辑更新一个资源

PUT http://127.0.0.1:8081/api/user/users/3

请求参数

{
  "name": "HogwartsTest6",
  "pwd": "HogwartsTest6"
}

删除一个资源

DELETE http://127.0.0.1:8081/api/user/users/3

常用配置项

下面介绍一些 Spring Boot 常用配置项，通过这些常用配置项，我们可以修改 Spring Boot 的一些默认配置。

修改服务默认端口：

server:
  port: 8093

指定服务名称：

spring:
  application:
    name: aitest

多环境配置

spring:
  profiles:
    active: dev

如上图新建 application-dev.yml、application-test.yml、application-uat.yml、application-prod.yml 四套配置文件环境，我们在四套配置文件中将设置服务端口号分别设置为 8091/8092/8093/8094。

然后启动服务，可以看到服务的端口号会和 application.yml 中激活的环境配置信息一致。

获取更多相关资料：请添加vx,ceshiren001
https://qrcode.ceba.ceshiren.com/link?name=article&project_id=qrcode&from=csdn&timestamp=1653961768&author=MM

ceshiren_com

关注

0
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
基于 Spring Boot 的 RESTful API 设计与实现

本文节选自霍格沃兹测试学院内部教材RESTful 是一种规范，符合 RESTful 的 Api 就是 RESTful Api。简单的说就是可联网设备利用 HTTP 协议通过 GET、POST、DELETE、PUT、PATCH 来操作具有 URI 标识的服务器资源，返回统一格式的资源信息，包括 JSON、XML、CSV、ProtoBuf、其他格式。RESTful 的核心思想是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /case 这个命令，GET 是动词，/cas...
复制链接

扫一扫