RESTful设计规范

2023-12-13 12:30:59


前言

RESTful风格是由Roy Fielding在2000年提出。它主要用于构建基于Web的应用程序,强调使用HTTP协议的基本方法(如GET,POST,PUT,DELETE)进行交互,并将每个资源表示为唯一的URI(Uniform Resource Identifiers)。它还支持使用标准数据格式,如JSON和XML,以及状态代码和标头来传达客户端和服务器之间的状态信息。使用RESTful架构风格,可以实现可扩展性、可维护性和可靠性更高的Web服务。


一、RESTful API 设计规范

下面是一些常用的 RESTful 设计规范:

  1. 使用 HTTP 方法
    使用 HTTP 方法来表示对资源的操作。常见的 HTTP 方法包括:

    • GET:获取资源
    • POST:创建资源
    • PUT:更新资源
    • DELETE:删除资源
  2. 使用 URI 表示资源
    使用 URI(Uniform Resource Identifier)来表示资源。URI 应该具有唯一性,且易于理解和使用。URI 的格式应该遵循以下规则:

    • 使用小写字母
    • 使用短横线来分隔单词
    • 不使用文件扩展名
  3. 数据传输格式
    使用 JSON 或 XML 这样的标准数据格式来传输数据。JSON 是更加常用的格式,因为它更加轻量级和易于处理。

  4. 版本控制
    在 URI 中包含版本号,以便客户端能够确定它们正在使用的 API 版本。这可以避免版本不兼容的情况发生。

  5. 错误处理
    定义标准的错误信息格式,以便客户端能够正确处理错误响应。错误信息应该包含错误代码、错误消息和可选的错误详细信息。

  6. 安全性
    使用 HTTPS 协议来保证 API 的安全性。使用身份验证和授权机制来限制对 API 的访问。

  7. 缓存
    启用客户端缓存以提高 API 的性能和响应速度。使用 ETag 和 Last-Modified 头来支持缓存机制。

  8. 频率限制
    为了防止 API 被滥用,应该启用频率限制机制。可以限制每个用户的 API 调用次数和并发连接数等。

  9. API 文档
    提供清晰、详细、易于理解的 API 文档,包括 API 的使用方法、参数和返回值等信息,以便客户端开发人员正确调用 API。

以上是一些通用的 RESTful API 设计规范,不同的应用场景和需求可能会有所不同,需要根据实际情况进行调整。


二、基本设计方法

1、资源的命名

RESTful API 应该使用名词来表示资源,而不是动词。

例:表示用户资源
正确:/users
错误:/getUsers

注意:资源表示应该是自描述的。同时资源一般为复数形式,而不是单数。

2、资源的版本

如果需要升级版本,需要在资源前增加版本信息。

例:获取v2版本的用户资源
正确:/v2/users 或 /users/v2
错误:/userV2

注意:版本应该在URI中指定,而不是在HTTP头中指定。

3、确定的URL

根据RESTful的规范,URL应该反应出资源的层次结构,因此需要为每个资源分配一个唯一的URL。

4、选择HTTP方法

对于每个URL,需要确定支持哪些HTTP方法。常见的HTTP方法如下:

方法场景例如
GET获取数据GET /api/users/1 或 GET /api/users
POST创建数据POST /api/users
PATCH差量修改数据PATCH /api/users/1
PUT全量修改数据PUT /api/users/1
DELETE删除数据DELETE /api/users/1

5、选择合适的状态码

常见的状态码如下:

状态码场景
200请求成功,通常用在同步操作时
202请求成功,通常用在异步操作时,表示请求已接受,但是还没有处理完成
400服务器无法或不会处理请求。通常用在表单参数错误
401授权错误,通常用在 Token 缺失或失效,注意 401 会触发前端跳转到登录页
403操作被拒绝,通常发生在权限不足时,注意此时务必带上详细错误信息
404没有找到对象,通常发生在使用错误的 id 查询详情
500服务器错误

其他状态码可参考 MDN Web Docs

以下是一个合乎规范的接口设计:

URL描述
/v1/api/companies公司集合
/v1/api/companies/{cid}/departments指定某个部门的集合

代码实现,可以参考如下的例子:

@RestController
@RequestMapping("/companies")
public class StudentController {

    // 获取全部部门信息
    @GetMapping("")
    public List<Company> getAllCompanies() {
    	//do something
        return companyList;
    }
?
	//获取某个部门的信息
    @GetMapping("/{cid}")
    public Company getCompanyById(@PathVariable int cid) {
		//do something
        return company;  
    }
}

三、RESTful 和 SOAP的区别

RESTful 和 SOAP 都是Web服务架构风格,但它们之间有一些显著的区别:

  1. URL和数据传输格式:RESTful使用URL来定位特定的资源,而SOAP使用XML消息格式进行数据传输。

  2. 性能:RESTful在服务器端处理请求时,负载比较小,性能更好。而SOAP使用XML消息格式,传输数据量过大,性能相对较差。

  3. 安全性:SOAP有内置安全机制,支持多种安全协议,例如WS-Security。而RESTful并没有内置安全机制,需要使用其他的安全机制(如OAuth)来提高安全性。

  4. 编程风格:RESTful具有更加简单和自然的编程风格,而SOAP具有更加复杂和强制性的编程风格。

  5. 兼容性:RESTful比SOAP更加容易进行跨平台和跨语言的开发和集成。

因此RESTful更加轻量级和灵活,适用于简单的Web服务,也更适用于微服务架构,而SOAP更加适用于复杂的Web服务。


总结

总之,RESTful的设计规范具有易于理解、可读性高、可维护性好、可扩展性强、可移植性好、性能高和可伸缩性好等优点,因此在构建Web应用和API时被广泛采用。

文章来源:https://blog.csdn.net/moon_ly/article/details/134835143
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。