网站导航
> 文章列表 > 一文详解RESTful风格API设计

一文详解RESTful风格API设计

网友: 文章列表 2024-03-21 16:59:34

一文详解RESTful风格API设计

RESTful风格是一种基于HTTP协议设计Web API的软件架构风格，由Roy
Fielding在2000年提出。它强调使用HTTP动词来表示对资源的操作（GET、POST、PUT、PATCH、DELETE等），并通过URI表示资源的唯一标识符。

一、RESTful API的设计原则

RESTful API的设计遵循以下几个原则：

  1. 基于资源：将数据和功能抽象成资源，并通过URI来唯一标识资源。例如，一个用户资源可以通过URL“/users/{id}”来访问，其中“{id}”表示该用户的唯一标识符。
  2. 使用HTTP动词：使用HTTP动词来表示对资源的操作，如GET（获取资源）、POST（创建资源）、PUT（更新资源）和DELETE（删除资源）等。
  3. 无状态：每个请求都包含足够的信息来完成请求，服务器不需要保存任何上下文信息。
  4. 统一接口：使用统一的接口来简化客户端与服务器之间的交互，包括资源标识符、资源操作和响应消息的格式。
  5. 可缓存性：客户端可以缓存响应，以提高性能和减少网络流量。
  6. 分层系统：将系统分为多个层次，每个层次处理特定的功能。

RESTful风格的API设计具有良好的可读性、易用性和可扩展性，广泛应用于Web应用程序和移动应用程序的API设计中。

二、使用到的注解

（1）@RequestMapping

  • 类型 方法注解

  • 位置 SpringMVC控制器方法定义上方

  • 作用 设置当前控制器方法请求访问路径

  • 范例

        @RequestMapping(value = "/users", method = RequestMethod.GET)@ResponseBodypublic String save(){System.out.println("save user");return " '{'module': 'user save' }' ";}

  • 属性

    1. value 请求访问路径
    2. method http请求动作，标准动作（GET、POST、PUT、DELETE）

（2）@PathVariable

  • 类型 形参注解

  • 位置 SpringMVC控制器方法形参定义前面

  • 作用 绑定路径参数与处理器方法形参间的关系，要求路径参数名与形参名一一对应

  • 范例

        @RequestMapping(value = "users/{id}", method = RequestMethod.DELETE)@ResponseBodypublic String delete(@PathVariable Integer id) // PathVariable 路径参数 id对应路径中的id{System.out.println("delete user");return "'{'module': 'user delete'}'";}

（3）@RestControll

  • 类型 类注解

  • 位置 基于SpringMVC的RESTful开发控制器类定义上方

  • 作用 设置当前控制器类为RESTful风格，等同于 @Controller 与 @ResponseBody两个注解的组合功能

  • 范例

    @RestController
public class UserController
{@RequestMapping(value = "/users",method = RequestMethod.GET)public String save(){System.out.println("save user");return " '{'module': 'user save' }' ";}

（4）@GetMapping @PostMapping @PutMapping @DeleteMapping

  • 类型 方法注解

  • 位置 基于SpringMVC的RESTful开发控制器方法定义上方

  • 作用 设置当前控制器方法请求访问路径与请求动作，每种对应一个请求动作

  • 范例

    @RestController
@RequestMapping("/users") // 下面的每个控制器方法的请求路径都有前缀 /users
public class UserController
{@GetMapping("/{id}")public String getById(@PathVariable Integer id){return "getById";}
}

（5）@RequestBody @RequestParam @PathVariable

  1. 区别
    • RequestParam 用于接收URL地址传参或表单传参
    • RequestBody 用于接收JSON数据
    • PathVariable 用于接收路径参数，使用 {参数名} 描述路径参数
  2. 应用
    • 后期开发中，发送请求参数超过1个时，以JSON格式为主，所以@RequestBody应用较广泛
    • 如果发送非JSON格式数据，选用 @RequestParam 接收请求参数
    • 当参数数量只有一个时，或为数字时，可以采用 @PathVariable接收请求路径变量，通常传递id值

三、综合案例

这里提供一个简单的Java示例，用于实现一个基本的RESTful API。假设我们正在开发一个学生管理系统，需要使用RESTful API来实现对学生资源的增删改查操作。

首先，我们需要定义一个表示学生信息的Java类：

public class Student {private int id;private String name;private int age;public Student() { }public Student(int id, String name, int age) {this.id = id;this.name = name;this.age = age;}// Getters and setters
}

然后，我们需要创建一个控制器类来处理客户端请求：

@RestController
@RequestMapping("/students")
public class StudentController {// Mock data - replace with database queries laterprivate static List<Student> students = new ArrayList<>(Arrays.asList(new Student(1, "Alice", 20),new Student(2, "Bob", 21),new Student(3, "Charlie", 22)));// GET /students - get all students@GetMapping("")public List<Student> getAllStudents() {return students;}// GET /students/{id} - get a student by id@GetMapping("/{id}")public Student getStudentById(@PathVariable int id) {for (Student s : students) {if (s.getId() == id) {return s;}}return null;  // Return null if student not found}// POST /students - create a new student@PostMapping("")public ResponseEntity<String> createStudent(@RequestBody Student student) {students.add(student);return ResponseEntity.status(HttpStatus.CREATED).build();}// PUT /students/{id} - update an existing student@PutMapping("/{id}")public ResponseEntity<String> updateStudent(@PathVariable int id, @RequestBody Student updatedStudent) {for (int i = 0; i < students.size(); i++) {if (students.get(i).getId() == id) {students.set(i, updatedStudent);return ResponseEntity.status(HttpStatus.OK).build();}}return ResponseEntity.status(HttpStatus.NOT_FOUND).build();  // Return 404 if student not found}// DELETE /students/{id} - delete a student by id@DeleteMapping("/{id}")public ResponseEntity<String> deleteStudentById(@PathVariable int id) {for (int i = 0; i < students.size(); i++) {if (students.get(i).getId() == id) {students.remove(i);return ResponseEntity.status(HttpStatus.OK).build();}}return ResponseEntity.status(HttpStatus.NOT_FOUND).build();  // Return 404 if student not found}
}

这个控制器类中定义了四个HTTP方法，分别处理对学生资源的不同操作。我们使用Spring Boot框架和Spring MVC模块来实现RESTful API，并使用注解来定义路由和请求处理逻辑。

最后，我们需要在应用程序的入口点（如Spring Boot的main方法）中启动应用程序：

@SpringBootApplication
public class StudentManagementSystemApplication {public static void main(String[] args) {SpringApplication.run(StudentManagementSystemApplication.class, args);}
}

这样，我们就创建了一个简单的RESTful API，可以通过发送HTTP请求来执行学生管理系统的基本操作。

生活知识

网络标签：

相关问题