自定义模型操作

目前为止，我们的进展非常顺利，我们使用了 Sails 的默认路由来访问或修改模型实例。这些默认设置（包含在 Sails Blueprint API 中）负责我们期望从 Web 或移动应用程序获得的基本的创建（create）、读取（read）、更新（update）和删除（delete）功能。但是所有开发生产 HTTP API 的开发人员都会告诉您，简单的 CRUD 只有这点能耐。即使您从这里着手，也需要能够定制基本路由与控制器的映射。

Blueprint API 对您很有帮助，但最终您需要某个更强大、灵活和可自定义（或同时具备这三种特性）的工具来构建您的客户和用户想要的应用程序。对于大部分开发周期，都可以使用蓝图路由来建立原型，然后将此框架替换为自定义的路由和关联的控制器。

除了 CRUD 路由，一个常规 Sails.js 安装中已经预先定义了其他一些控制器-路由组合。但是，从很大程度上讲，您往往想创建自己的映射来获得所需的行为。

映射复杂的查询

在上一篇教程中，您将我们最开始拥有的博客 API 扩展为了一个更庞大的内容管理系统（CMS）后端。尽管您目前构想的是让这个应用程序为一个网络博客提供支持，但它还可以用于其他用途。该 RESTful API 可供几乎任何想要获取并显式博客文章或 RSS 提要的前端应用程序访问，而且它允许搜索查询。扩展该 API 后得到了多种新模型类型，分别是 Author、Entry 和 Comment。每个 Entry 拥有一个 Author 和Comment，这些类型也链接回它们引用的 Entry。

切换成 CMS 后，越来越明确地表明您希望能够设置 Sails 的默认路由所不支持的操作。假设您想能够发出复杂的查询（比如针对一个由特定作者在特定日期后编写的，按给定条件进行组织的文章），或者获取与一个特定标签对应的所有文章。您可能需要提供的不是采用原生 JSON 的格式，而是采用兼容 RSS 或 Atom 的 XML 格式的文章。在输入端，您可能希望添加一个导入功能，使 CMS 能够通过 RSS 或 Atom 提要获取并存储完整的现有博客。

实际上，您可以做很多事情，而且许多事情都是 Sails 默认不支持的。

控制器的作用

在传统 MVC 模式中，控制器（controller）定义模型（model）与其视图（view）之间的交互。当某个模型的数据发生更改时，控制器会确保附加到该模型的每个视图都会相应地更新。用户在视图内执行某项操作时，控制器也会获得通知。如果该操作必须更改某个模型，控制器会向所有受影响的视图发出通知。从架构角度讲，模型、控制器和视图都是在服务器上定义的。视图通常是某种形式的 HTML 模板（理想情况下包含极少的代码）；模型是域类或对象；控制器是路由背后的代码块。

在 HTTP API 中，三个应用程序组件之间的关系类似但不等同于 MVC。不同于 MVC 架构，HTTP API 的模型、视图和控制器通常并不都包含在同一个服务器上。具体地讲，视图通常位于服务器外，会是一个单页 Web 应用程序或移动应用程序的形式。

在架构上，HTTP API 或多或少与 MVC 应用程序有些类似：

· 模型 是通过线路交换的工件。（HTTP API 使用了一种专为简化传输而设计的模型，该模型有时称为 ViewModel。）

· 控制器 是 API 的动词形式；它们的存在是为“执行”某个操作而不是“成为”某个东西。

在 HTTP API 中，当一个视图将 HTTP 请求传到控制器端点时，该请求直接依靠控制器来执行。控制器获取通过 URL 或请求正文传入的数据，对一个或多个现有模型执行某个操作（或创建新模型），并生成响应返回给视图来进行更新。控制器的响应通常是 API 开发人员定义的 HTTP 状态代码和 JSON 主体的组合。

理论介绍得已经足够多了，现在让我们开始实现控制吧。

文档：目前，对于错误场景的含义，HTTP API 设计中还没有标准。错误编码 500 究竟是表明请求未被处理，还是表明它已被处理，但由于执行请求的逻辑中的内部错误而失败了？所以应该始终显式地文档化您的 HTTP API 中的错误编码的含义。

· 视图 显示了通过 HTTP API 收到的数据。

创建一个控制器

开始使用 Sails 控制器的最简单方法是，创建一个返回静态数据的控制器。在本例中，您将创建一个简单的控制器，它返回 CMS API 的一个用户友好的版本。这将是一个运行迅速且容易使用的 API，业务客户可使用它测试服务器是否在正常运行。客户还能够大体了解任何最近的更改，比如对 API 的升级，并相应地调整其 Web 或移动前端。

可通过两种方式在 Sails 中创建新控制器：可以使用 sails 命令生成框架，或者可以让这些文件为您生成控制器。在后一种情况下，生成器使用 Sails 约定规则所定义的命名系统来识别和放置文件，这些文件通常是空的。对于第一个控制器，我们将会使用生成器：

~$ sails generate controller System

info: Created a new controller ("System") at api/controllers/SystemController.js!

控制器位于您的 Sails 项目的 api/controllers 目录中。根据约定，它们拥有 controller 后缀。如果您在控制器名称后附加额外的描述符，Sails 会假设这些是要在控制器上执行的操作（方法）。通过提前指定操作，您可以节省一些步骤；否则默认生成器会生成一个空的控制器，如这里所示：

/**

* SystemController

*

* @description :: Server-side logic for managing the System

* @help        :: See http://sailsjs.org/#!/documentation/concepts/Controllers

*/

module.exports = {

};

运行一个稍微不同的命令——sails generate controller System version——会留下更多工作让您处理：控制器位于您的 Sails 项目的 api/controllers 目录中。根据约定，它们拥有 controller 后缀。如果您在控制器名称后附加额外的描述符，Sails 会假设这些是要在控制器上执行的操作（方法）。通过提前指定操作，您可以节省一些步骤；否则默认生成器会生成一个空的控制器，如这里所示：

/**

* SystemController

*

* @description :: Server-side logic for managing Systems

* @help        :: See http://sailsjs.org/#!/documentation/concepts/Controllers

*/

module.exports = {

/**

* `SystemController.version()`

*/

version: function (req, res) {

return res.json({

todo: 'version() is not implemented yet!'

});

}

};

添加命令会对搭建的方法端点进行布局，但您可以看到，这些命令目前未执行太多工作，仅返回有帮助的错误消息。使用该生成器创建已建立框架的控制器，最初可能很有帮助。随着时间的推移，许多开发人员最终仅在自己最喜欢用的文本编辑器中执行 File|New。如果您决定这么做，则需要正确地命名该文件和端点（例如 foocontroller.js 中的 FooController），并手动编写导出的函数。这些方式都没有对错，所以请使用最适合您的方式。

实现第一个简单的控制器非常容易：

module.exports = {

/**

* `SystemController.version()`

*/

version: function (req, res) {

return res.json({

version: '0.1'

});

}

}"，

绑定和调用控制器

接下来，您希望绑定您的控制器，然后调用它。绑定（Binding）将控制器映射到一个路由；调用（invoking）向该路由发出合适的 HTTP 请求。基于此控制器的文件名和所调用方法的名称，此控制器的默认路由将是 /System/version。

就个人而言，我不喜欢将“system”放在 URL 中，而是更喜欢使用“/version”。Sails 允许将控制器的调用绑定到选择的任何路由，所以我们将它设置为绑定到 /version。

您可以在 Sails 路由表中创建一个条目来设置控制器路由，该路由表存储在 config/routes.js 中。只要您创建一个 Sails 应用程序，就会生成这个默认文件。除去所有注释后，此文件几乎是空的：

odule.exports.routes = {

/***************************************************************************

*                                                                          *

* Make the view located at `views/homepage.ejs` (or `views/homepage.jade`, *

* etc. depending on your default view engine) your home page.              *

*                                                                          *

* (Alternatively, remove this and add an `index.html` file in your         *

* `assets` directory)                                                      *

*                                                                          *

***************************************************************************/

'/': {

view: 'homepage'

}

};

大体上讲，config/routes.js 包含一组路由（routes）和目标（targets）。路由是相对 URL，目标是您希望 Sails 调用的对象。默认路由是 / URL 模式，它调出 Sails 的默认主页。如果您愿意的话，还可以将此默认路由替换为一个常规 HTML 页面。这样，该 HTML 将位于您的 assets 目录中，就在我们将一直使用的 api 目录旁边。

升级 CMS 的 HTML 对于像 React.js 这样的单页应用程序框架可能是一种有趣的练习，但这里的目的是添加一个 /version 路由，并让它指向 SystemController.version 方法。为此，您需要向 config.js 所导入的 JSON 对象添加额外的一行代码：

module.exports.routes = {

'get /version': 'SystemController.version'

};

Blueprint API 中的控制器

将此路由保存到 config.js 文件中后，向 /version 发出 HTTP GET 请求会发回您之前设置的相同 JSON 结果。

创建模型时，Sails 的工具会自动为该模型创建一个控制器。所以，即使您没有打算创建它们，您的每个方法也已经有一个控制器：AuthorController、EntryController 等。

为了进一步熟悉 Sails 控制器和路由，我们假设您希望 AuthorController 持有一个方法，该方法返回您 CMS 中所有作者的简历的聚合列表。该实现非常简单——只需要获取所有 Authors，提取它们的简历，并传回该列表：

module.exports = {

bios: function(req, res) {

Author.find({})

.then(function (authors) {

console.log("authors = ",authors);

var bs = [];

authors.forEach(function (author) {

bs.push({

name: author.fullName,

bio: author.bio

});

});

res.json(bs);

})

.catch(function (err) {

console.log(err);

res.status(500)

.json({ error: err });

});

}

};

测试状态如果您使用了默认的 /author/bios 路由，您的 routes.js 中甚至不需要特殊条目。在这种情况下，默认条目就够用了（如果您不这么认为，您知道如何更改它），所以我们暂时保留默认路由。

测试状态

您可能发现种子控制器（seed controller）对一些测试很有用。这种控制器将数据库初始化为一种已知状态，就象这样：

module.exports = {

run: function(req, res) {

Author.create({

fullName: "Fred Flintstone",

bio: "Lives in Bedrock, blogs in cyberspace",

username: "fredf",

email: "fred@flintstone.com"

}).exec(function (err, author) {

Entry.create({

title: "Hello",

body: "Yabba dabba doo!",

author: author

}).exec(function (err, created) {

Entry.create({

title: "Quit",

body: "Mr Slate is a jerk",

author: author.id

}).exec(function (err, created) {

return res.send("Database seeded");

});

});

});

}

};

在这种情况下，该已知状态被绑定到控制器的默认路由 /seed/run。您还可以为不同的测试和/或开发场景设置不同的种子方法（seed method）。对于所关注的路由，可使用 curl 命令将数据库设置为特定状态。但需要确保您在生产代码中禁用或删除了这些路由。

管理控制器输入：

现在，您已拥有一个没有输入的非常简单的控制器。但是，控制器通常需要从调用方获取输入。有三种类型的控制器输入：

1. 请求正文中发送的表单参数。这是通过 Web 接受输入的传统机制。

2. 通过请求正文中的 JSON 对象发送的输入数据。此概念与表单参数相同，但发送的内容类型为application/json，而不是 form/multipart-form-data。客户端通常更容易生成输入数据，而且服务器也更容易使用。

3. 通过参数指定并通过 URL 路由中的占位符发送的输入。请求某个特定作者的文章时，您通常希望在 URL 自身中传递作者标识符。一个示例是 /author/1/entries，其中的“1”是作者的唯一标识符。这样，您就保留了博客文章包含在作者资源中的外观，即使这些文章在物理上未与该作者存储在一起。（示例应用程序就是如此，Entry 对象存储在一个与 Author 对象不同的集合或表中。）

表单参数属于传统的 Express 样式 request.getParam() 调用的领域，已在其他地方具有明确规定。而且 HTTP API 也不经常使用表单参数，所以我们暂时放弃该方法。第二种方法非常适合 CMS 应用程序。

获取输入

捕获通过 JSON 对象发送的值通常很简单，只需使用一个 request.body.field。如果输入是一个位于 JSON 最高层级的数组，您则可以使用 request.body[idx].field。

首先，您将创建一个端点，它将返回 CMS 数据库中所有 Entry 对象的 RSS XML 提要。（在实际的系统中，需要限制此数字来支持分页模式，比如返回最近的 20 篇文章，但我们暂时保持简单即可。）命名您的控制器（我在下面选择了 FeedController），并在它之上放置一个 RSS 方法，使默认路由（/feed/rss）变得有意义：

var generateRSS = function(entries) {

var rss =

'<rss version="2.0">' +

'<channel>' +

'<title>SailsBlog</title>';

// Items

entries.forEach(function (entry) {

rss += '<item>' +

'<title>' + entry.title + '</title>' +

'<description>' + entry.body + '</description>' +

'</item>';

});

// Closing  rss += '</channel>' +

'</rss>';

return rss;

}

module.exports = {

rss: function (req, res) {

Entry.find({})

.then(function (entries) {

var rss = generateRSS(entries);

res.type("rss");

res.status(200);

res.send(rss);

})

.catch(function (err) {

console.log(err);

res.status(500)

.json({ error: err });

});

return res;

}

};

现在，这是一个很小的提要，但是，如果您想将提要限制到一个或多个特定作者，该怎么办？在这种情况下，您需要设置一个新路由（/author/{id}/rss）。新路由将获取 URL 中传递的标识符，然后使用它限制查询，仅查找给定作者编写的文章。该 RSS 方法的剩余部分基本相同。

看看该方法在代码中的效果。首先，FeedController 获取一个针对每个作者的 RSS 方法，就像之前一样：

module.exports = {

rss: // as before

authorRss: function(req, res) {

Entry.find({ 'author' : req.param("authorID") })

.then(function (entries) {

var rss = generateRSS(entries);

res.type("rss");

res.status(200);

res.send(rss);

})

.catch(function (err) {

console.log(err);

res.status(500)

.json({ error: err });

});

return res;

}

};

不同的是上面是一个查询，它现在被限制为仅查找所有具有某个作者 ID 的 Entry 对象。请注意 HTTP 请求中包含的参数 authorID 的指令。authorID（在本例中为传入的 URL 模式的第三部分）的映射在routes.js 文件中指定，如下所示：

var generateRss = // as before

module.exports = {

rss: // as before

authorRss: function(req, res) {

Entry.find({ 'author' : req.param("authorID") })

.then(function (entries) {

var rss = generateRSS(entries);

res.type("rss");

res.status(200);

res.send(rss);

})

.catch(function (err) {

console.log(err);

res.status(500)

.json({ error: err });

});

return res;

}

};

routes 文件中指定的参数是区分大小写的，所以请确保您保持了一致的命名约定。大小写差异是应用程序代码中一种常见但不易察觉的错误来源。