简介
express-restify-mongoose-patch 是一个 Node.js 的 npm 包，用于快速构建 RESTful API。它是 express-restify-mongoose 的增强版，提供了更多功能和更简洁的 API。本文将介绍如何使用 express-restify-mongoose-patch 构建 RESTful API，以及如何使用其提供的各种功能。
安装
在使用 express-restify-mongoose-patch 之前，需要确保已经安装了 Node.js 环境，并在项目中安装 express 和 mongoose。安装命令如下：
npm install express mongoose express-restify-mongoose-patch
基础使用
express-restify-mongoose-patch 提供了一个 restify 方法，用于快速构建 RESTful API。通过在 mongoose schema 中定义资源的字段，即可轻松生成 RESTful API。下面是一个简单的例子：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- -------- - -------------------- ----- ------- - ------------------------------------------ --------------------------------------------- ----- --- - ---------- ----- ------------ - --- ----------------- ----- - ----- ------- --------- ---- -- ---- - ----- ------- --------- ---- - --- ------------------ ------------------------ --------------- -----------------展开代码
以上代码定义了一个名为 Person 的 mongoose model，包含 name 和 age 两个字段。通过调用 restify.serve 方法，将 Person model 以 RESTful API 的形式暴露出来，供客户端访问。
其中，restify.serve 方法有三个参数：
- app：express 实例。
- model：mongoose model。
- options：可选参数，用于配置 API 的行为。
我们在这里省略 options 参数，使用默认配置。options 参数的详细介绍将在后面的章节中提供。
现在，我们已经完成了一个非常简单的 RESTful API。以下是对该 API 的说明：
- GET /people：获取所有 person 的列表。
- GET /people/:id：根据 id 获取指定的 person。
- POST /people：新增 person，请求体中应包含 name 和 age 字段。
- PUT /people/:id：根据 id 更新指定的 person，请求体中应包含要更新的字段。
- DELETE /people/:id：根据 id 删除指定的 person。
配置选项
restify.serve 的第三个参数，即 options，默认配置如下：
-- -------------------- ---- ------- - ------- --- -------- --- ----------- ------ --------- --- ------------ ---- ------------------ ------ ----- ----- ----------------- ------ ----------------- ------ -------------- --- --------------- --- ------- ----- --------- ----- ----------------- ---------------- ----------- ------ ---------- ------ ------------ ------ ---------- ------ ----------- ----- ---------- ----- ------------ --- ------------ --- ------------------ ----- ------------------ ----- ------- ----- --------- ----- --------------- ----- ------- ----- ------- ----- -------------- ----- --------------- ----- ------------ --- ------------ ----- ------------- ------ ---------------------- ------ --------------------- ------ -------------------- ------ ------------ ----- -展开代码
下面对其中一些常用的选项进行介绍。
prefix
指定 API 的前缀。默认为空。
restify.serve(app, mongoose.model('Person', personSchema), { prefix: '/api/v1' });
pageSize
每页的数据条数。默认为 10。
restify.serve(app, mongoose.model('Person', personSchema), { pageSize: 20 });
maxPageSize
每页最大的数据条数。默认为 100。
restify.serve(app, mongoose.model('Person', personSchema), { maxPageSize: 50 });
lean
返回的对象是否是普通的 JavaScript 对象。默认为 true，表示返回普通的 JavaScript 对象。如果为 false，表示返回 mongoose document 对象。
restify.serve(app, mongoose.model('Person', personSchema), { lean: false });
access
控制 API 的访问权限。access 可以是一个布尔值或一个函数。如果 access 是一个函数，则函数返回值表示是否有权限访问 API。函数有两个参数：req 和 doc。req 表示当前的请求，doc 表示要访问的资源。如果 access 是一个布尔值，则表示所有用户可以访问 API。
function access(req, doc) { return req.user && req.user.role === 'admin'; } restify.serve(app, mongoose.model('Person', personSchema), { access: access });
outputFn
自定义输出函数。outputFn 可以是一个函数或一个对象。如果 outputFn 是一个函数，则函数返回值表示要输出的数据。函数有一个参数：doc，表示要输出的资源。如果 outputFn 是一个对象，则对象的 format 属性表示自定义输出函数，filter 属性表示要过滤的属性。
-- -------------------- ---- ------- -------- ------------- - ----- ---- - - ----- --------- ---- ------- -- ------ ----- - ------------------ ------------------------ -------------- - --------- -------- ---展开代码
excludeProjection
从返回结果中排除的字段名数组。默认为空数组。
restify.serve(app, mongoose.model('Person', personSchema), { excludeProjection: ['_id', 'password'] });
高级用法
除了基础使用之外，express-restify-mongoose-patch 还提供了很多高级用法。下面将逐一进行介绍。
聚合查询
如果需要在 API 中支持聚合查询，可以使用 restify.query() 方法。restify.query() 提供类似 MongoDB 的聚合查询语法，支持 match、group、sort、project 等操作。
-- -------------------- ---- ------- ----- ------- - ------------------- ----- -------- - -------------------- ----- ------- - ------------------------------------------ --------------------------------------------- ----- --- - ---------- ----- ------------ - --- ----------------- ----- - ----- ------- --------- ---- -- ---- - ----- ------- --------- ---- -- ------- - ----- ------- --------- ---- -- ----- - ----- ------- --------- ---- -- ------- - ----- ------- --------- ---- - --- ------------------ ------------------------ -------------- - ------- ----- -------------- ----------------- --- -----------------展开代码
以上代码定义了一个包含 name、age、gender、city 和 salary 五个字段的 Person model。通过在配置中指定 preMiddleware: [restify.query()]，即可开启聚合查询功能。下面是一些聚合查询的例子：
- GET /people?match={"gender":"male"}&group={"_id":null,"count":{"$sum":1}}：获取所有男性的人数。
- GET /people?match={"gender":"female","age":{"$gt":30},"salary":{"$gt":5000}}&sort={"age":1}&project={"name":1,"gender":1,"age":1}：获取所有女性中年龄大于 30，薪资大于 5000 的人，按照年龄升序排列，只返回 name、gender 和 age 三个字段。
自定义路由
如果需要在 API 中添加自定义路由，可以使用 restify.defaults() 方法。restify.defaults() 用于配置 API 路由的前缀、版本号等信息。可以设置多次，每次设置都会增加前缀、版本号等信息。下面是一个例子：
-- -------------------- ---- ------- ------------------ ------- ------- -------- ---- --- ------------------ ------- ----- --- ------------------ ------------------------ ---------------展开代码
以上代码设置了两次 restify.defaults()，第一次设置 API 前缀为 /api，版本号为 v1；第二次设置 API 前缀为 /v1，版本号不变。最终的 API 路由为 /api/v1/v1/people。
除了使用 restify.defaults()，还可以使用 restify.router() 方法，自定义 API 路由。restify.router() 接收一个函数作为参数，该函数返回一个 express router 实例，可以在里面定义自己的路由。
restify.router(app => { app.get('/custom-route', (req, res, next) => { res.send('Hello, world!'); }); }); restify.serve(app, mongoose.model('Person', personSchema));
以上代码使用 restify.router() 定义了一个名为 /custom-route 的路由，返回一个字符串 Hello, world!。由于 restify.router() 返回的是一个 express router 实例，因此需要把实例传递给 restify.serve() 才能生效。
自定义操作
如果需要在 API 中添加自定义操作，可以使用 restify.methods() 方法。restify.methods() 支持自定义 GET、POST、PUT 和 DELETE 四种操作，并且支持中间件。下面是一个例子：
-- -------------------- ---- ------- ----------------------- ------ ---------- - -------------------- ---- ----- -- - -- ----------------- --- ------ - ------ -------- ------------- ---------- - ------- --- ----------------- ---- ----- -- - -- --- --- ----------------- ---- ----- -- - -- --- --- -------------------- ---- ----- -- - -- --- -- --- ------------------ ------------------------ ---------------展开代码
以上代码定义了一个包含 GET、PUT 和 DELETE 三个操作的自定义操作。在操作之前，先添加一个中间件，用于校验请求参数中的 secret 值。如果 secret 不是 abc，则返回一个错误。使用 restify.methods() 添加 GET、PUT 和 DELETE 三个操作，每个操作都对应一个处理函数。在运行时，可以使用类似 /people/123?secret=abc 的 URL 访问这个自定义操作。
自定义响应
如果需要在 API 中自定义响应，可以使用 restify.outputFn() 方法。restify.outputFn() 接收一个函数作为参数，该函数返回要输出的数据。可以在函数中自定义数据的格式、过滤等操作。
-- -------------------- ---- ------- ---------------------- ---- ----- -- - ----- ------ - --- ----------------- - ---------------- ------------- - ---------------------- -- -- ----- ------------ ---- ---------- ---- ------ ------- --- ------------------ ------------------------ ---------------展开代码
以上代码使用 restify.outputFn() 定义了一个自定义输出函数，只返回 name 和 age 两个字段。在函数中，先定义了一个对象 output，包含了 totalCount 和 people 两个字段。在处理数据时，只选择了 name 和 age 两个字段，输出的数据格式经过了自定义。
插件扩展
如果需要在 API 中添加插件扩展，可以使用 restify.use() 方法，类似于 express 的中间件。restify.use() 支持多种插件扩展，包括分页、排序、筛选等。下面是一个例子：
-- -------------------- ---- ------- ----- ----------- - ------------------------ ----------------- ---- ----- -- - ----- ----- - ---------------------------------------- -------------- - ------------------ -- -- --------------- - ------------------- -- --- ------- --- ------------------ ------------------------ ---------------展开代码
以上代码使用 restify.use() 添加了一个插件扩展，用于解析查询参数中的 page 和 limit，设置默认值。通过 req.query.page 和 req.query.limit 可以得到解析后的值。
总结
express-restify-mongoose-patch 提供了一种快速构建 RESTful API 的方式，避免了繁琐的 CRUD 操作。本文介绍了 express-restify-mongoose-patch 的基础用法和高级用法，包括聚合查询、自定义路由、自定义操作、自定义响应和插件扩展等。希望能够帮助读者更好地使用 express-restify-mongoose-patch。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005524081e8991b448cfc97
