使用 HATEOAS 设计更好的 RESTful API
RESTful API 是当前互联网应用中最流行的一种 API 设计风格，特点是支持 HTTP 协议，使得服务端无状态、聚合 API，能分离前后端开发和升级。但是 RESTful API 的设计并不是一件简单的事情，设计不当会导致 API 的难以扩展和维护。
在 RESTful API 中，HATEOAS（Hypertext As The Engine Of Application State，即超媒体作为应用状态的引擎）是一个极具扩展性的概念。其核心是在每个返回实体的响应中嵌入其他相关资源的链接，这些链接能够告诉客户端可以执行的下一步行动，从而使客户端与服务端之间的通信变得更加灵活和可扩展。
本文将详细介绍 HATEOAS 的概念、原理和如何将其应用于设计 RESTful API。我们还将提供示例代码，帮助读者更好地理解如何实践 HATEOAS。
什么是 HATEOAS？
HATEOAS 是 RESTful API 中的一种实现方式。它基于超媒体，描述了资源的链接并提供了一组定义良好的操作，这使得客户端能够理解 API 的结构和如何操作它。
在没有 HATEOAS 的情况下，客户端必须知道每个可能的操作，例如要调用哪个 URL，要使用哪个方法等。而在有了 HATEOAS 的情况下，客户端可以根据服务器提供的操作来自动化调用。
例如，当客户端成功地使用用户名和密码进行身份认证后，HATEOAS 可以返回一个表示用户信息的 JSON 响应。在该响应中，服务器不仅可以返回用户信息本身，还可以提供“更新用户信息”、“删除用户”等操作的链接。然后，客户端可以根据链接中提供的操作来执行相应的操作，使得 RESTful API 变得灵活和可扩展。
如何设计 HATEOAS RESTful API
在设计 HATEOAS RESTful API 时，重要的是要考虑到资源和它们之间的关系，以及在响应中包含有关查询和关系的信息。
以下是一些实践 HATEOAS RESTful API 的最佳实践：
- 创建资源集合
资源集合是 RESTful API 的核心。它们是客户端发出查询的地方，同时也是客户端批量创建、更新和删除资源的地方。为每个资源建立一个 URL，并为资源集合建立一个 URL。
- 在响应中包含链接
包含链接是 HATEOAS 的核心，使客户端能够直接跳转到相关资源。在响应中包含的链接应该指向所有可用的操作，例如更新、删除和添加资源。
- 在响应中包含关系
包含关系使客户端能够了解资源间的复杂关系。例如，客户端可以发现用户、博客和评论之间的关系，而不必在客户端中访问每个资源。
- 支持请求头中的 Accept 标头
接受标头指示客户端接受哪种媒体类型的响应。通过支持这个标头，RESTful API 将成为一种真正的超媒体 API。
示例代码
假设我们正在创建一个 HATEOAS RESTful API 来处理博客的创建、查看和修改。我们首先为该 API 建立一个 URL：
https://example.com/api/blogs
然后定义一个模板来表示博客：
// javascriptcn.com 代码示例
{
"id" : "1",
"title" : "How to Design HATEOAS RESTful API",
"content" : "HATEOAS is a powerful concept for building scalable APIs. Here's how to do it!",
"_links" : {
"self" : { "href" : "https://example.com/api/blogs/1" },
"author" : { "href" : "https://example.com/api/users/1" },
"comments" : { "href" : "https://example.com/api/blogs/1/comments" }
}
}在该模板中，我们为每篇博客指定了一个 ID，标题和内容。最后，我们还在每个响应中包含了该博客资源的链接。
在 ResourcefulController 中，我们可以定义请求方法来支持客户端调用该 API：
// javascriptcn.com 代码示例
/**
* Retrieve a specific blog
*
* @return Response
*/
public function view($id)
{
$blog = Blog::find($id);
return response()->json([
'id' => $blog->id,
'title' => $blog->title,
'content' => $blog->content,
'_links' => [
'self' => [
'href' => route('blogs.view', $blog->id),
],
'author' => [
'href' => route('users.view', $blog->user->id),
],
'comments' => [
'href' => route('blogs.comments.index', $blog->id)
]
]
]);
}
/**
* Create a new blog
*
* @return Response
*/
public function create(Request $request)
{
$blog = Blog::create($request->all());
return response()->json([
'id' => $blog->id,
'title' => $blog->title,
'content' => $blog->content,
'_links' => [
'self' => [
'href' => route('blogs.view', $blog->id),
],
'author' => [
'href' => route('users.view', $blog->user->id),
],
'comments' => [
'href' => route('blogs.comments.index', $blog->id)
]
]
]);
}
/**
* Update a blog
*
* @return Response
*/
public function update(Request $request, $id)
{
$blog = Blog::find($id);
$blog->fill($request->all());
$blog->save();
return response()->json([
'id' => $blog->id,
'title' => $blog->title,
'content' => $blog->content,
'_links' => [
'self' => [
'href' => route('blogs.view', $blog->id),
],
'author' => [
'href' => route('users.view', $blog->user->id),
],
'comments' => [
'href' => route('blogs.comments.index', $blog->id)
]
]
]);
}
/**
* Delete a blog
*
* @return Response
*/
public function delete($id)
{
$blog = Blog::find($id);
$blog->delete();
return response()->json([
'message' => 'Blog deleted successfully'
]);
}在每种操作中，我们都返回该博客资源的标准 JSON 模板，其中包含了 self、author 和 comments 链接。这使得客户端能够了解资源及其关系，并自动执行操作。我们甚至可以在链接中指定其他属性，例如请求类型和媒体类型。
总结
在设计 RESTful API 时，HATEOAS 是一个重要的概念，使得客户端与服务端之间的通信变得更加灵活和可扩展。HATEOAS 使得客户端可以通过链接来理解和执行每个可用的操作，同时也使得客户端能够了解资源之间的关系。通过本文的介绍，您将学习如何设计一个 HATEOAS RESTful API，并理解如何将其实践于实际开发中。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/653b1b5e7d4982a6eb56cec0