Unlimited WordPress themes, graphics, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Node.js
Code

使用 NodeJS 和 Restify 进行 RESTful API 设计

by
Difficulty:IntermediateLength:LongLanguages:

Chinese (Simplified) (中文(简体)) translation by Fuhuan (you can also view the original English article)

Final product image
What You'll Be Creating

RESTful API 包含两个主要概念:Resource 和 Representation。 资源可以是与数据关联的任何对象,也可以用 URI 标识(多个 URI 可以引用相同的资源),并且可以使用 HTTP 方法进行操作。 表示是显示资源的方式。 在本教程中,我们将介绍有关 RESTful API 设计的一些理论信息,并使用 NodeJS 实现示例博客应用程序 API。

资源

为 RESTful API 选择正确的资源是很重要的。 首先,你需要分析你的业务领域,然后确定将使用与你的业务需求相关的资源数量和类型。  如果你正在设计博客 API,则可能会使用文章,用户和评论。 这些是资源名称,与之关联的数据是资源本身:

资源动词

确定所需资源后,可以继续执行资源操作。 这里的操作是指 HTTP 方法。 例如,要创建文章,你可以发出以下请求:

确定所需资源后,可以继续执行资源操作。 这里的操作是指 HTTP 方法。 例如,要创建文章,你可以发出以下请求:

确定所需资源后,可以继续执行资源操作。 这里的操作是指 HTTP 方法。 例如,要创建文章,你可以发出以下请求:

我可以使用有效负载向 / articles / update / 123456789012 发出另一个 POST 请求。

也许更好一些,但 URI 变得越来越复杂。 如前所述,操作可以引用 HTTP 方法。 这意味着,在 HTTP 方法中声明更新操作,而不是将其放在 URI 中。 例如:

也许更好一些,但 URI 变得越来越复杂。 如前所述,操作可以引用 HTTP 方法。 这意味着,在 HTTP 方法中声明更新操作,而不是将其放在 URI 中。 例如:

有时,你需要在文章过期时删除它。 在这种情况下,你可以对 / articles / 123456789012 使用 DELETE HTTP 请求。

HTTP 方法是标准概念。 如果你将它们用作操作,你将拥有简单的 URI,这种简单的 API 接口将帮助你获得客户。

如果想在文章中插入评论怎么办? 可以选择文章并为所选文章添加新评论。 通过使用此语句,可以使用以下请求:

上述形式的资源称为子资源。 评论是文章的子资源。 上面的 Comment 有效负载将作为 Article 的子项插入数据库中。  有时,不同的 URI 引用相同的资源。 例如,要查看特定注释,可以使用以下任一方法:

或者:

版本

通常,API 功能会经常更改,以便为消费者提供新功能。 在这种情况下,同一 API 的两个版本可以同时存在。  为了分离这两个功能,你可以使用版本控制。 版本控制有两种形式

  1. URI 中的版本:你可以在 URI 中提供版本号。 例如,/ v1.1 / articles123456789012。
  2. 标题中的版本:在标题中提供版本号,并且永远不会更改 URI。 例如:

实际上,版本仅更改资源的表示,而不更改资源的概念。 因此,你无需更改 URI 结构。 在 v1.1 中,可能会在 Article 中添加一个新字段。  但是,它仍然会返回一篇文章。 在第二个选项中,URI 仍然很简单,消费者不需要在客户端实现中更改其 URI。

在消费者不提供版本号的情况下设计策略非常重要。 未提供版本时可能会引发错误,或者你可以使用第一个版本返回响应。  如果你使用最新的稳定版本作为默认版本,则消费者可以为其客户端实现获取许多错误。

表示

表示是 API 显示资源的方式。 当你调用 API 端点时,你将返回一个资源。 此资源可以是 XML,JSON 等任何格式。  但是,如果要更新用于返回 XML 响应的现有 API,则可以为 JSON 响应提供另一个版本。

这是关于 RESTful API 设计的足够的理论信息。 让我们通过使用 Restify 设计和实现 Blogging API 来了解实际使用情况。

博客 REST API

设计

为了设计 RESTful API,我们需要分析业务领域。 然后我们可以定义我们的资源。 在 Blogging API 中,我们需要:

  • 创建,更新,删除,查看文章
  • 创建,更新,删除,查看文章
  • 创建,更新,删除,查看文章

在此 API 中,我将不介绍如何对用户进行身份验证以创建文章或评论。 对于身份验证部分,你可以参考使用 AngularJS 和 NodeJS 的基于令牌的身份验证教程。

我们的资源名称已准备就绪 资源操作只是 CRUD。 你可以参考下表了解 API 的一般展示。

资源名称 资源名称 资源名称
文章 创造文章
更新文章
GET / article / 123
GET / article / 123
有效负载的 POST / 文章
带有效负载的 PUT / articles / 123
DELETE / articles / 123
GET / article / 123
评论 创建评论
更新评论
删除评论
查看评论
有效负载的 POST / articles / 123 / 评论
有效负载的 POST / articles / 123 / 评论
DELETE / comments / 123
得到 / comments / 123
用户 创建用户
更新用户
删除用户
查看用户
有效负载的 POST / 用户
带有效负载的 PUT / users / 123
DELETE / users / 123
DELETE / users / 123

项目设置

在这个项目中,我们将使用的 NodeJS 用的 RESTify。 资源将保存在 MongoDB 数据库中。 首先,我们可以将资源定义为 Restify 中的模型。

文章

评论

用户

用户资源不会有任何操作。 我们假设我们已经知道能够操作文章或评论的当前用户。

你可能会问这个模块来自哪里。 它是作为 NodeJS 模块编写的 MongoDB 最流行的 ORM 框架。 该模块包含在另一个配置文件中的项目中。

现在我们可以为上述资源定义 HTTP 动词。 你可以看到以下内容:

在此代码段中,首先迭代包含控制器方法的所有控制器文件,并初始化所有控制器以执行对 URI 的特定请求。  之后,为基本 CRUD 操作定义特定操作的 URI。 还有一篇关于文章操作的版本控制。

例如,如果在 Accept-Version 标头中将版本声明为 2,则将执行 viewArticle_v2。 viewArticle 和 viewArticle_v2 都执行相同的工作,显示资源,但它们以不同的格式显示文章资源,你可以在下面的标题字段中看到。  最后,服务器在特定端口上启动,并应用一些错误报告检查。 我们可以继续使用控制器方法对资源进行 HTTP 操作。

article.js

你可以在下面的 Mongoose 侧找到有关基本 CRUD 操作的说明:

  • createArticle:这是对请求正文发送的 articleModel 的简单保存操作。 可以通过将请求主体作为构造函数传递给 var articleModel = new Article(req.body)之类的模型来创建新模型。
  • viewArticle:为了查看文章详细信息,URL 参数中需要一个文章 ID。 带有 ID 参数的 findOne 足以返回文章详细信息。
  • updateArticle:文章更新是一个简单的查找查询和对返回文章的一些数据操作。 最后,需要通过发出 save 命令将更新的模型保存到数据库中。
  • deleteArticle:findByIdAndRemove 是通过提供文章 ID 删除文章的最适合方法了。

上面提到的 Mongoose 命令只是静态的,就像通过 Article 对象的方法一样,它也是 Mongoose 模式的引用。

comment.js

当你向其中一个资源 URI 发出请求时,将执行控制器中声明的相关功能。 控制器文件中的每个函数都可以使用 req 和 res 对象。 这里的评论资源是文章的子资源。  所有查询操作都是通过 Article 模型进行的,以便查找子文档并进行必要的更新。 但是,每当你尝试查看 Comment 资源时,即使 MongoDB 中没有集合,你也会看到一个。

其他设计建议

  • 选择易于理解的资源,以便于消费者使用。
  • 让业务逻辑由消费者实现。 例如,Article 资源有一个名为 slug 的字段。 消费者无需将此详细信息发送到 REST API。  这个 slug 策略应该在 REST API 端进行管理,以减少 API 和消费者之间的耦合。 消费者只需要发送标题详细信息,你可以根据 REST API 端的业务需求生成 slug。
  • 为 API 端点实施授权层。 未经授权的消费者可以访问属于另一个用户的受限数据。 在本教程中,我们没有介绍用户资源,但你可以参考使用 AngularJS 和 NodeJS 的基于令牌的身份验证,以获取有关 API 身份验证的更多信息。
  • 用户 URI 而不是查询字符串。/ articles / 123(好),/ articles?id = 123(差)。
  • 不要保持国家; 始终使用即时输入 / 输出。
  • 使用名词作为资源。 你可以使用 HTTP 方法来操作资源。

最后,如果你按照这些基本规则设计 RESTful API,你将始终拥有灵活,可维护,易于理解的系统。

关注我们的公众号
Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.