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

语言: CN / TW / HK

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 方法如 GET ,PUT 和 POST ,并遵循这些方法的语义。

设计规范

常用的动词有以下 5 个

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

Spring Boot 实现 RESTful API

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

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

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

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/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 {};

} ```

示例说明:\ \

  • 新增 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;
}

} ```

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

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 中激活的环境配置信息一致。

更多技术文章

喜欢软件测试的小伙伴们,如果我的博客对你有帮助、如果你喜欢我的博客内容,请 “点赞” “评论” “收藏” 一键三连哦