Spring Boot Restful API

从零开始丶从新开始

已于 2023-08-10 18:45:29 修改

阅读量112

点赞数

于 2023-08-10 18:43:03 首次发布

本文链接：https://blog.csdn.net/u011257649/article/details/132216064

版权

Spring Boot 专栏收录该内容

9 篇文章 0 订阅

订阅专栏

什么是Restful API

在网络应用程序的开发中，Restful API成为了一个广受欢迎的架构模型。简单地说，Restful API是一种API设计模式，其通过HTTP协议提供Web服务接口，通过定义URI、资源状态、资源间关系及HTTP方法等方式实现对资源的增删改查操作，来满足客户端的需求。

Restful API是基于HTTP协议的，REST是Representational State Transfer的缩写，这里的‘Representational’表示资源的表现形式，‘State Transfer’表示操作的状态转移。REST的核心思想是将应用程序功能抽象成为资源，并且使用HTTP协议定义了一套对资源的操作，这些操作对应着HTTP请求的方法，包括GET、POST、PUT、DELETE等等。

Restful API的优点在于其简单性、灵活性和扩展性。与SOAP等Web服务相比，Restful API的开发、测试、使用和部署都比较简单和方便，同时Restful API的传输数据格式通常是JSON或XML，而不是SOAP中的XML，具有更高的可读性和可扩展性。

Restful API的核心原则：

资源的标识：每一个资源都有一个唯一的标示URI
资源的状态：对资源的状态的表现按照某一标准表达，如JSON、HTML等
资源的方法：使用HTTP协议定义对资源的操作方式，如GET、POST、PUT、DELETE等
无状态：客户端的请求不保存在服务端，各请求之间没有关联
可缓存：通过协商缓存等机制来缓解服务器端资源的负载压力

创建Restful API建议遵循以下规范：

URI规范：使用名词作为URI的一部分，如 /orders、/users等
HTTP方法规范：对资源的增删改查操作对应HTTP请求中的方法GET、POST、PUT、DELETE等
数据格式：返回数据是采用JSON格式更加简洁和清晰
统一的API标准：通过Swagger等工具生成API文档，方便维护和使用

如何使用Spring Boot创建Restful API

Spring Boot是一个快速开发、轻量级、微服务框架，它结合了Spring框架和Spring的各种扩展库，使开发人员能够更加方便快捷地构建可扩展的、健壮的Web应用。其中，Spring Boot对于支持Restful API也提供了非常便捷的方式。

1. 引入依赖

在使用Spring Boot开发Restful API时，我们需要在Maven或Gradle的构建文件中引入Spring Boot的Web依赖，Web依赖包含了一些必要的类和API，支持Restful API的开发。

对于使用Maven构建的项目，需要在pom.xml文件中添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

对于使用Gradle构建的项目，需要在build.gradle文件中添加以下依赖：

compile('org.springframework.boot:spring-boot-starter-web')

2. 定义控制器

在Spring Boot中，我们需要使用@Controller或@RestController注解定义Restful API的控制器。其中，@RestController是一种特殊的@Controller注解，它默认返回JSON格式的响应，而@Controller返回的是HTML格式的响应。

例如，我们定义一个简单的UserController来支持Restful API：

@RestController
@RequestMapping("/users")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }

    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        return userService.updateUser(id, user);
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
    }
}

上面代码中，我们使用@RestController注解定义了一个UserController，并通过@RequestMapping指定了API的URI。其中，@GetMapping、@PostMapping、@PutMapping和@DeleteMapping注解分别对应HTTP协议中的GET、POST、PUT和DELETE请求方法。@PathVariable注解表示该参数是Restful API中的路径参数，@RequestBody注解表示该参数是请求体中的JSON格式数据。

3. 定义实体类

在Spring Boot中，我们需要定义Restful API所需操作的实体类，通常是针对一个数据表或者一种业务对象。实体类需要使用JPA或者MyBatis等数据访问框架进行持久化操作。

例如，我们定义了一个简单的User实体类：

@Entity
@Table(name = "users")
public class User implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    @NotBlank
    @Column(nullable = false, unique = true)
    private String username;

    @NotBlank
    @Column(nullable = false)
    private String password;

    // 省略getter和setter方法
}

上面代码中，我们使用@Entity注解定义了一个User实体类，并使用@Id和@GeneratedValue注解定义了该实体类的主键策略。@Table注解指定了对应的数据表名，@Column注解指定了数据表中字段的属性。

4. 定义服务层

在Spring Boot中，我们需要定义服务层，该层包含了业务逻辑和数据持久化操作。通常，我们使用@Service注解来定义服务层。

例如，我们定义了一个简单的UserService。

@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    public User getUserById(Long id) {
        return userRepository.findById(id).orElse(null);
    }

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }

    public User createUser(User user) {
        return userRepository.save(user);
    }

    public User updateUser(Long id, User user) {
        User oldUser = userRepository.findById(id).orElse(null);
        if (oldUser != null) {
            oldUser.setUsername(user.getUsername());
            oldUser.setPassword(user.getPassword());
            return userRepository.save(oldUser);
        }
        return null;
    }

    public void deleteUser(Long id) {
        userRepository.deleteById(id);
    }
}

上面代码中，我们使用@Service注解定义了一个UserService，并通过@Autowired注解注入了一个UserRepository。UserService通过调用UserRepository来实现对User实体类的数据持久化。

如何保证Restful API的质量

1. 注重URI的设计，符合REST架构风格

在设计Restful API时，需要考虑URI的合理性和易读性。URI是API的唯一标识符，应该具有明确的语义。合理的URI设计应该提供资源的层次结构，使用名词表示资源，使用动词表示资源的操作。

为了保证URI的可读性和易用性，应该遵循以下设计原则：

使用名词形式表示资源，如/articles、/users等。
使用HTTP动词表示操作，如GET表示获取资源，POST表示创建资源，PUT表示修改资源，DELETE表示删除资源。
使用斜杠分隔URI中的不同部分，如/articles/123表示获取id为123的文章。
避免使用API版本号，如/v1/articles，通过升级API来实现版本管理。
简化URI中的嵌套结构，如使用/articles/123/comments替代/articles/123#comments。

例如：
获取商品列表的URI可以设计为：/api/products
获取特定商品的URI可以设计为：/api/products/{id}
更新商品的URI可以设计为：/api/products/{id}/update

2. 使用HTTP方法

Restful API使用HTTP方法来实现对资源的操作，提供了一种统一的方式来处理不同的操作类型。常见的HTTP方法有GET、POST、PUT、DELETE等。

GET用于获取资源，不会对服务器状态进行修改，是幂等的。
POST用于创建资源，通过请求主体提交数据。
PUT用于更新资源，请求主体包含要更新的数据，是幂等的。
DELETE用于删除资源，是幂等的。
HEAD用于获取资源的元数据，如响应头信息，不返回响应体。
OPTIONS用于获取资源支持的HTTP方法和其他信息。

3. 遵循HTTP状态码的规范

HTTP状态码是Restful API与客户端交互的重要信息，它表示服务器对请求的响应状态，应该返回正确的状态码，便于客户端处理异常情况，遵循以下设计原则：

2xx表示成功，如200表示请求成功，201表示资源创建成功。
3xx表示重定向，如301表示资源永久移动，302表示资源暂时移动。
4xx表示客户端错误，如400表示请求参数错误，401表示未授权，404表示未找到资源。
5xx表示服务器错误，如500表示服务器内部错误，503表示服务不可用。

通过使用合适的状态码可以提供更好的错误处理和调试能力。

4. 使用JSON格式返回数据

Restful API通常使用JSON格式来传输数据。相比于XML格式，JSON更加简洁轻量且易于解析。JSON提供了一种结构化的数据表示方式，适合于多种编程语言进行解析和处理，具有较好的可读性和可扩展性，应该作为默认的数据格式，遵循以下设计原则：
1.使用标准的JSON格式，如使用双引号表示字符串，使用方括号表示数组，使用大括号表示对象。
2.指定数据编码格式为UTF-8，保证跨语言兼容性。
3.提供可选的数据字段，如通过参数控制返回字段，通过过滤器筛选、排序数据等。