43、RESTful API 保姆教程

RESTful API

目录

1. RESTful API简介
2. RESTful设计原则
3. RESTful设计规范
4. RESTful统一返回体
5. JAX-RS
6. JAX-RS与SpringBoot集成
7. 构建Restful服务实践
8. 总结

一、RESTful API 简介

REST（Representational State Transfer）是一种基于HTTP的web服务架构风格，RESTful API则是遵循REST原则的网络接口。RESTful API通过标准的HTTP方法（如GET、POST、PUT、DELETE）来操作服务器端资源，并以JSON或XML等格式传输数据。REST的特点包括无状态、缓存性和统一接口等。

1.Web开发的两种模式：

前后端不分离：

以前没有移动互联网时，我们做的大部分应用都是前后端不分的，比如jsp，或者thymeleaf等后端分离模板，在这种架构的应用中，数据基本上都是在后端渲染好返回给前端展示的，也就是后端需要控制前端的展示，前端与后端的耦合度很高。
这种应用模式比较适合纯网页应用，但是当后端对接App时，App可能并不需要后端返回一个HTML网页，而仅仅是数据本身，所以后端原本返回网页的接口不再适用于前端App应用，为了对接App后端还需再开发一套接口。这样前后端不分离就有局限性了。

前后端分离：

在前后端分离的应用模式中，后端仅返回前端所需的数据，不再渲染HTML页面，不再控制前端的效果。至于前端用户看到什么效果，从后端请求的数据如何加载到前端中，都由前端自己决定，网页有网页的处理方式，App有App的处理方式，但无论哪种前端，所需的数据基本相同，后端仅需开发一套逻辑对外提供数据即可。
在前后端分离的应用模式中 ，前端与后端的耦合度相对较低。
我们通常将后端开发的每个视图都称为一个接口，或者API，前端通过访问接口来对数据进行增删改查。

前面我们讲解了前后端不分离不分离模式，现在来讲解一下前后端分离模式怎么实现.

2.什么是API？

API：全称是 Application Programming Interface，应用程序编程接口。API是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。简单的说API 是一套协议，规定了我们与外界的沟通方式：如何发送请求和接收响应。
比如我们平时在QQ上可以看到天气信息，而这些天气信息不是腾讯公司用卫星监测到的，而是去调用气象局的天气信息的。但腾讯公司不需要也不能访问气象局的数据库和源码，而是通过调用气象局提供的一个公共函数来实现，我们只需要知道这个函数需要传递什么参数，以及返回什么样的数据就行，函数的内部结构我们并不需要知道。这个函数就是API。

3.什么是RESTful

为了在团队内部形成共识、防止个人习惯差异引起的混乱，我们需要找到一种大家都觉得很好的接口实现规范，
而且这种规范能够让后端写的接口，用途一目了然，减少双方之间的合作成本。所以出现了接口服务架构，目前市面上大部分公司开发人员使用的接口服务架构主要有：restful、rpc。

REST：那Rest是什么呢，它是一种架构风格，就像气象局建立API时要遵守的一种规则，可以是Rest也可以是其它规则。这种规则是为web应用服务的，也就是用URL定位资源，用HTTP动词（GET,POST,DELETE,PUT）描述操作，用HTTP Status Code返回结果状态的这种client和server的交互方式。实现看Url就知道要什么，看http 方法就知道干什么，看http status code就知道结果如何。

RESTFul：RESTful是一种定义Web API接口的设计风格，尤其适用于前后端分离的应用模式中。RESTFul就是为了实现REST这种交互方式而制定的一套约束条件和规则，符合这些约束条件和原则的应用程序或设计就是RESTful。也就是REST本身不实用，实用的是如何设计 RESTful API（REST风格的网络接口）。这种风格的理念认为后端开发任务就是提供数据的，对外提供的是数据资源的访问接口，所以在定义接口时，客户端访问的URL路径就表示这种要操作的数据资源。

二、RESTful 设计原则与设计规范

1、REST的核心原则

1. 资源导向（Resource-Oriented）
   • 将一切服务和数据视为资源（Resources）。
   • 资源通过URI（Uniform Resource Identifier）唯一标识。
   • 客户端通过URI访问资源。
2. 客户端-服务器分离（Client-Server Separation）
   • 客户端和服务器分离，客户端负责用户界面和应用逻辑，服务器负责数据存储和计算。
   • 这种分离使得客户端和服务器可以独立演进。
3. 无状态（Stateless）
   • 服务器不需要保存客户端的会话状态。
   • 每次请求必须包含所有必要的信息，服务器可以独立处理每个请求。
4. 层次化接口（Layered System）
   • 系统可以分层，比如代理服务器、缓存服务器等。
   • 这种分层结构可以提高安全性和性能。
5. 统一接口（Uniform Interface）
   • 使用统一的接口和协议（如HTTP）进行通信。
     -统一接口包括资源的表示（Representation）、资源的操作（HTTP方法）、资源的地址（URI）等。

2、RESTful设计原则

1. 资源命名规则
   • URI命名使用单数或复数名词，例如：
     • 获取所有用户：GET /users
     • 获取特定用户：GET /users/123
   • 避免使用动词，动词由HTTP方法表示。
2. 版本控制
   • 在URI中明确标明API版本，例如：
     • GET /v1/users
     • GET /api/v2/users
   • 避免在URL中使用查询参数（如?version=1）或自定义头部（如Accept: application/vnd.myapp.v1+json）。
3. 使用标准HTTP方法
   • GET：获取资源（读操作）。
   • POST：创建资源（写操作）。
   • PUT：更新资源（替换操作）。
   • PATCH：部分更新资源。
   • DELETE：删除资源。
   • HEAD：获取资源的元信息（类似于GET，但不返回响应体）。
   • OPTIONS：获取支持的HTTP方法。
4. 状态码（Status Code）
   • 使用标准的HTTP状态码，例如：
     • 200 OK：请求成功。
     • 201 Created：资源创建成功。
     • 400 Bad Request：请求格式错误。
     • 401 Unauthorized：未认证或权限不足。
     • 404 Not Found：资源不存在。
     • 500 Internal Server Error：服务器内部错误。
5. 支持内容协商（Content Negotiation）
   • 通过Accept头部指定响应格式，例如：