前言
RESTful风格是由Roy Fielding在2000年提出。它主要用于构建基于Web的应用程序,强调使用HTTP协议的基本方法(如GET,POST,PUT,DELETE)进行交互,并将每个资源表示为唯一的URI(Uniform Resource Identifiers)。它还支持使用标准数据格式,如JSON和XML,以及状态代码和标头来传达客户端和服务器之间的状态信息。使用RESTful架构风格,可以实现可扩展性、可维护性和可靠性更高的Web服务。
一、RESTful API 设计规范
下面是一些常用的 RESTful 设计规范:
-
使用 HTTP 方法
使用 HTTP 方法来表示对资源的操作。常见的 HTTP 方法包括:- GET:获取资源
- POST:创建资源
- PUT:更新资源
- DELETE:删除资源
-
使用 URI 表示资源
使用 URI(Uniform Resource Identifier)来表示资源。URI 应该具有唯一性,且易于理解和使用。URI 的格式应该遵循以下规则:- 使用小写字母
- 使用短横线来分隔单词
- 不使用文件扩展名
-
数据传输格式
使用 JSON 或 XML 这样的标准数据格式来传输数据。JSON 是更加常用的格式,因为它更加轻量级和易于处理。 -
版本控制
在 URI 中包含版本号,以便客户端能够确定它们正在使用的 API 版本。这可以避免版本不兼容的情况发生。 -
错误处理
定义标准的错误信息格式,以便客户端能够正确处理错误响应。错误信息应该包含错误代码、错误消息和可选的错误详细信息。 -
安全性
使用 HTTPS 协议来保证 API 的安全性。使用身份验证和授权机制来限制对 API 的访问。 -
缓存
启用客户端缓存以提高 API 的性能和响应速度。使用 ETag 和 Last-Modified 头来支持缓存机制。 -
频率限制
为了防止 API 被滥用,应该启用频率限制机制。可以限制每个用户的 API 调用次数和并发连接数等。 -
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服务架构风格,但它们之间有一些显著的区别:
-
URL和数据传输格式:RESTful使用URL来定位特定的资源,而SOAP使用XML消息格式进行数据传输。
-
性能:RESTful在服务器端处理请求时,负载比较小,性能更好。而SOAP使用XML消息格式,传输数据量过大,性能相对较差。
-
安全性:SOAP有内置安全机制,支持多种安全协议,例如WS-Security。而RESTful并没有内置安全机制,需要使用其他的安全机制(如OAuth)来提高安全性。
-
编程风格:RESTful具有更加简单和自然的编程风格,而SOAP具有更加复杂和强制性的编程风格。
-
兼容性:RESTful比SOAP更加容易进行跨平台和跨语言的开发和集成。
因此RESTful更加轻量级和灵活,适用于简单的Web服务,也更适用于微服务架构,而SOAP更加适用于复杂的Web服务。
总结
总之,RESTful的设计规范具有易于理解、可读性高、可维护性好、可扩展性强、可移植性好、性能高和可伸缩性好等优点,因此在构建Web应用和API时被广泛采用。