什么是 @gar/hapi-json-api
@gar/hapi-json-api 是一个基于 Hapi.js 平台的 JSON API 插件，它实现了简单方便的 API 格式化和路由控制。使用该插件可以轻松构建出符合 JSON API 规范的 Web API 接口。
安装
使用该插件需要先安装 Hapi.js，如果您还没有安装Hapi.js,请执行：
npm install hapi --save
接下来安装 @gar/hapi-json-api:
npm install @gar/hapi-json-api --save
使用教程
初始化
要使用 @gar/hapi-json-api,首先需要在 Hapi.js 的插件配置中添加该插件:
const Hapi = require('hapi');
const server = new Hapi.Server();
const pluginOptions = {};
await server.register({
plugin: require('@gar/hapi-json-api'),
options: pluginOptions
});定义路由
@gar/hapi-json-api 使用路由标记来继承、实现 JSON API 的路由格式化。它支持普通的 Hapi.js 路由参数，而且额外提供了一些特殊的路由参数：
| 参数 | 描述 |
|---|---|
| handler | |
| query.handler | |
| validation | 支持 Joi 验证 |
| auth | 支持 Hapi.js 的 auth 验证 |
| jsonApi | 设置 JSON API 的返回数据 |
以下是一个基本路由的示例代码：
-- -------------------- ---- -------
--------------
------- ------
----- ---------
-------- -
------------ ---- --- -------
----- ------- ---------
-------- ----- -------- --------- -- -
------ ----- ----------------------
--
-------- -
----------- ------ ------- -------- ------------ -------------
----- -
------ --
-
-
-
---定义 JSON API 消息
@gar/hapi-json-api 为 JSON API 定义了一个 API 响应的数据消息格式。当您使用 JSON API 请求时，它将自动使用此消息格式返回数据。
下面是 JSON API 消息的数据格式：
-- -------------------- ---- -------
-
------- -
----- -------
------- --------
------------- -
------- -----
-------- ----------------------
--
---------------- -
---
--
------- -
---
-
--
-------- -
------- -------------------------------
--
----------- -
---
--
------- -
---
-
-- data: 返回的实际数据，类型可以是对象、数组、null。
- links: 返回的 JSON API 链接。
- included: 以包含的方式返回非主要资源的额外数据。
- meta: 返回的元数据信息。
查询参数
@gar/hapi-json-api 支持一些通用的查询参数，可以让前端更方便的筛选、排序、分页以及限制结果条数。下面列出了支持的查询参数，以及应用方式。
| 查询参数 | 描述 | 应用 | 示例 |
|---|---|---|---|
| fields | 设置要返回的字段。字段名使用 ',' 分隔。 | 限制返回条目 | fields=name,email |
| sort | 根据某个字段进行排序。字段名前面添加 '-' 表示降序。 | 多个字段用 ',' 分隔。 | sort=-createdAt,name |
| page[offset]、page[limit] | 分页查询。必须同时设置。 | limit - 限制返回条目数量。offset - 返回的数据位移。 | page[offset]=5&page[limit]=10 |
| Include | 返回指定关联的包含资源。 | 应用到GET、POST | include=comments |
| filter | 根据字段筛选返回结果。支持匹配、范围查询、通配符等。 | 允许多种操作符号。 | filter[name]=John&filter[age][gte]=20 |
案例
下面是一个典型的 Web API 的示例，它使用 @gar/hapi-json-api 实现了 JSON API 标准的 API 接口。
- usersRoute.js —— 用户关联资源
- commentsRoute.js —— 评论资源
usersRoute.js
-- -------------------- ---- -------
----- --- - ---------------
----- ---- - ----------------
----- ----------- - ----------------------------
----- - -------- ------- - - ---------------------------------
---------------- - ----- ------ -- -
--------------
------- ------
----- ---------
-------- -
------------ ---- --- -------
----- ------- ---------
----- -
----------- --------
----- ----------
--
-------- ----- -------- --------- -- -
------ ----- --------------------------------------------
--
-------- -
----------- ------ ------- -------- ------------ -------------
----- -
------ --
-
--
--------- -
------ ------------
----- ------------
------- -------------------------------
------ -----------------------------------------
------------
--
-
-
---
--------------
------- ------
----- --------------
-------- -
------------ ---- ---- -- ----
----- ------- ---------
-------- ----- -------- --------- -- -
----- -- - ---------------------------
----- ---- - ----- -------------------------
-- ------- -
----- ------------------- --- --------
-
------ -----
--
-------- -
----------- ------ ------- -------- ------------ ------------
--
--------- -
------- ------------
--- -------------------
--
-
-
---
--
------------ - -------------commentsRoute.js
-- -------------------- ---- -------
----- --- - ---------------
----- -------------- - -------------------------------
----- - ------- - - ---------------------------------
---------------- - ----- ------ -- -
--------------
------- ------
----- ------------
-------- -
------------ ---- --- ----------
----- ------- ------------
-------- ----- -------- --------- -- -
------ ----- -----------------------------------------------
--
-------- -
----------- ------ ---------- --------- --------- ------------ ------------
--
--------- -
------ ------------
----- ------------
------- -------------------------------
------ -----------------------------------------
-------------
-------- ------------------------
--
-
-
---
--------------
------- ------
----- -----------------
-------- -
------------ ---- -------- -- ----
----- ------- ------------
-------- ----- -------- --------- -- -
----- -- - ---------------------------
----- ------- - ----- ----------------------------
-- ---------- -
----- ---------------------- --- --------
-
------ --------
--
-------- -
----------- ------ ---------- --------- --------- ------------ ------------
--
--------- -
------- ------------
--- ------------
--
-
-
---
--
------------ - ----------------示例代码
以下是示例代码，我们将创建一个 Web API 来显示用户和评论：
-- -------------------- ---- -------
----- ---- - ----------------
----- ----------- - ------------------------------
----- --- - --------------------------
----- ---------- - -------------------------------
----- ------------- - ----------------------------------
----- - -------- ------- - - --------------------------------
------ -- -- -
----- ------ - --- -------------
----- -----
----- ------------
------- -
----- -
------- ------
-------- ----------------- --------------- ----------------
-
-
---
----- -----------------------------
----- ---------------------
--------------------------- ------ -
---- --------------
--------- ----- -------------- -------- -- -- -
----- ---- - ----- ------------------------------------------
-- ------- -
------ - -------- ----- --
-
------ - -------- ---- --
--
-------------- -
----------------- -----
----------- ---------
-
---
---------------------------
--------------
------- -------
----- ---------
-------- -
------------ --------
----- --------
----- ------
-------- ----- -------- --------- -- -
----- - ------ -------- - - -------------------------
----- ------ - ----- ------------------ ------ -------- ---
------ - ---- ------ --
--
--------- -
-------- ------------
------ --------------------------------
--------- -----------------------
--
-
-
---
--------------
-----------
-------------
---
----- ---------------
------------------- ------- --- ---------------------
-----总结
@gar/hapi-json-api 提供了基于 Hapi.js 平台的 JSONAPI 插件，它可以轻松的构建符合 JSONAPI 规范的 Web API 接口，还支持通用查询参数，页面分页等功能。相信有了本篇文章的介绍和实例，您一定可以轻松上手使用并开发出满足业务需求的应用程序。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5f1bf6eb403f2923b035c513