sails

Guía de aprendizaje

v.0.11 (2ª Edición)

(Sails.js) Guía Aprendizaje

Por:  Josué J. Rodríguez

___________________________________________________________

1ª Edición Publicado el 12 de Noviembre 2014 (v.0.10)

2ª Edición Publicado el 3 de Febrero 2015 (v.0.11)

Tabla de Contenidos 

1. Sails.js

1. Visión
2. Instalación node
3. Instalación sails.js

2. Assets

1. Visión del conjunto
2. Tareas por defecto
3. Desactivando tareas  automatizadas
4. Tareas automatizadas

3. Configuración

1. Usando el archivo .sailsrc

4. Globales
5. Rutas

1. Rutas personalizadas
2. URL’s

6. Controladores
7. Respuestas Personalizadas
8. Modelos y ORM (Object-Relational mapping)

1. Asociaciones
2. Dominio
3. Many to Many (muchos a muchos)
4. One to Many (uno a muchos)
5. One to One (uno a uno)
6. Asociación única
7. Accediendo a tablas relacionadas
8. Atributos
9. Ciclo de vida Callbacks
10. Modelos
11. Lenguaje de consulta
12. Validaciones
13. Configuración de modelos

9. Vistas

1. Plantillas
2. Locales
3. Parciales
4. Manejadores de vistas

10. Servicios
11. Seguridad

1. Cross-Origin Resource Sharing (CORS) 
2. Cross-Site Request Forgery (CSRF)
3. Cickjacking
4. Política de seguridad
5. DDos
6. P3P
7. Robo de sockets
8. Seguridad de transporte HTTP stricta (HSTS)
9. XSS

12. Internacionalización
13. Políticas
14. Middleware
15. Cargar / Subir archivos al servidor
16. Logs

1. sails.log()

17. Testeo
18. Desplegando la aplicación                

Características Principales

Sails es un framework ligero. El conjunto de pequeños módulos trabajan juntos para proporcionar simplicidad, facilidad de mantenimiento y robustez en nuestras aplicaciones web.

1. sails.js

Visión

Sails es un framework web. La mayoría de las veces, cuando hacemos referencia a la “web”, nos viene a la mente conceptos como HTML5 o CSS3. Cuando oímos o leemos la palabra framework, lo primero en que pensamos es en Backbone, Angular o jQuery.

Sails no es de ese tipo de frameworks. sails trabaja juntamente con Angular o Backbone, pero nunca debes usar sails como sustitución de estas librerías.

Por otro lado, cuando hablamos de “frameworks web”, también nos referimos a la parte del back-end, pensamos en conceptos como REST, HTTP o WebSockets y tecnologías como Java, Ruby o Node.js.

Un framework para el back-end (como Sails) nos ayuda a construir APIs, servir archivos HTML y a manejar cientos de miles de usuarios conectados simultáneamente. Para llevar a cabo todo esto, sails, sí es el rey!  

Convención antes que configuración

Sails cumple con los muchos de los objetivos que otros entornos de desarrollo de aplicaciones web, usando las mismas metodologías MVC (Modelo, Vista, Controlador).  

Cualquiera que haya  trabajado antes con Zend, Laravel, CodeIgniter, Cake, Django, ASP .NET o Rails, se encontrará con un entorno bastante familiar. También le resultará fácil de entender la anatomía y la distribución del código de un proyecto en sails.

Instalación de node.js 

Aunque quizás sea obvio, hay que decir que sails es un framework de Node.js. Así que para empezar a utilizar sails, primero debemos tener instalado Node.js. A continuación, mostramos cómo efectuar la instalación en Windows, OSX y Linux.

[ OSX ]

Puedes optar por descargar el paquete desde la página oficial: http://www.nodejs.orj/download/ 

También a través de homebrew:  brew install node

O quizás quieras hacerlo por medio de macports: port install nodejs

Instalación node.js en Linux

[ Ubuntu, Mint ]

Los usuarios que tengan la versión Quantal (12.10), necesitarán instalar software-properties-common

[ Fedora ]

Node.js y npm están disponibles en el repositorio desde la versión 18 y posteriores

[ RHEL / CentOS / Scientific Linux 6 ]

[ Arch Linux ]

[ Gentoo ]

[ OpenSUSE & SLE ]

[ Windows ]

Puedes optar por descargar el paquete desde la página oficial: http://www.nodejs.orj/download/

O bien con chocolatey

Instalación de Sails

Bien, ahora que tenemos Node.js instalado, seguiremos con la instalación de sails, la instalación es mucho más sencilla, y la realizaremos de forma global con el parámetro -g, de esta forma podemos crear proyectos con sails sin tener que descargar el código fuente cada vez que iniciemos un nuevo proyecto.

Así de sencillo, ya tenemos sails instalado en nuestro sistema.

Otro requisito para utilizar sails aunque opcional, es tener instalado en nuestro sistema el gestor de tareas Grunt.

La instalación de Grunt es como la de sails, utilizaremos el parámetro -g para que la instalación se efectúe de forma global.

Para identificar los archivos y carpetas que mencionaremos a lo largo de esta guía, es necesario o más bien recomendable, crear un proyecto nuevo con sails. Así que vamos a ello.

Creando un nuevo proyecto Sails

Para crear un nuevo proyecto Sails, desde la consola nos dirigimos hasta el directorio donde queramos  guardar nuestro proyecto. Una vez dentro del directorio introducimos lo siguiente:

Automáticamente se creará una carpeta con el nombre que le hayamos dado al proyecto, accedemos a dicha carpeta mediante el comando:

$ cd el_nombre_que_le_queramos_dar

Y a continuación iniciamos el servidor web con el siguiente comando:

$ sails lift

Por consola nos saldrá algo como esto:

Nos muestra como el servidor es levantado en un entorno de desarrollo y es escuchado por el puerto 1337. Pues bien comprobemos los resultados, en nuestro navegador web preferido, introducimos lo siguiente en la barra de navegación, http://localhost:1337/, y esto es lo que veremos:

Comprobado que nuestro servidor funciona, vamos a pasar a materia y explicar como trabajar con sails

2. Assets

Visión de conjunto

“Assets” ¿Que son? nos referimos a los archivos estáticos ( js, css, imágenes, etc ) que son accesibles para cualquiera. En sails, estos archivos están ubicados en el directorio assets/ de nuestro proyecto, donde estos son procesados en un directorio temporal ( ./temp/public ) en el momento que el servidor es iniciado. El contenido de ./temp/public es el equivalente a la carpeta “public” que usamos en  express, o la carpeta “www” que tienen otros servidores web como Apache. Este paso permite a Sails preparar o pre-compilar estos archivos  para su uso en el frontend (lado del cliente).

Middleware Estáticos 

Sails usa el middleware estático express para servir los assets. Podemos configurar este middleware (más adelante veremos cómo configurar middlewares de terceros o personalizados por nosotros) en /config/http.js.

index.html

Como la mayoría de los servidores web, Sails hace honor a index.html. Por ejemplo si creas assets/foo.html en un nuevo proyecto, este será accesible desde http://localhost:1337/foo.html, pero si creaste  assets/foo/index.html, entonces estará disponible desde http://localhost:1337/foo/index.html y también desde http://localhost:1337/foo.

Prioridades

Esto es importante a tener en cuenta, ya que los middleware estáticos corren después del enrutador de sails

(más adelante explicamos qué es esto de del enrutador). Ahora por el momento Imagina que tenemos definida una ruta personalizada, y en nuestro directorio “assets”  tenemos un archivo con la misma ruta, en el momento que hay una petición a esta ruta, es la ruta personalizada la que intercepta la petición  antes que el middleware estático. Por ejemplo, creamos assets/index.html, sin definir ninguna ruta en el archivo config/routes.js, esta será servida en tu página de inicio, pero si definimos una ruta personalizada en el archivo config/routes.js  como podria ser “ / ” : “FooController.bar”, entonces a esta se le dará prioridad ya que las dos rutas apuntan al mismo sitio.

Tareas Predeterminadas

Visión de conjunto

El paquete Assets incluido en sails establece un conjunto de tareas configuradas con Grunt, diseñadas por defecto para crear un proyecto coherente y productivo. Todo el flujo de trabajo en la parte del frontend es completamente personalizable, aunque sails proporciona por defecto un conjunto de tareas predefinidas.

Con sails le resultará fácil configurar nuevas tareas que no vienen por defecto y que quizás necesite.

Aquí algunas de las tareas que tenemos por defecto al crear un proyecto en Sails que nos pueden ayudar:

• Compilación Automática LESS
• Compilación Automática JST
• Compilación Automática CoffeScript
• Inyección, Minificación y Concatenación de los assets
• Creación de un directorio público
• Sincronización de archivos
• Optimización de los assets en producción

Tareas de Comportamiento por Defecto en Grunt

A continuación se presentan las tareas de Grunt que están incluidas en un proyecto en sails, así como una pequeña descripción del trabajo que llevan a cabo..

clean

coffee

concat

copy

cssmin

less

sails-linker

sync

uglify

watch

Desactivando Grunt

Tanto si el proyecto a realizar es una API Rest, o una aplicación donde el servidor de nuestro proyecto no ha de incluir ficheros estáticos, es recomendable que desactive la integración de Grunt en nuestro proyecto sails, simplemente borraremos el archivo Gruntfile.js y la carpeta tasks/. También puede desactivarlo mediante la propiedad grunt, estableciendo dicha propiedad a false en el archivo .sailsrc :

También es posible añadir tareas para personalizar SASS, AngularJS, templates, etc. Basta con sustituir la tarea relevante de Grunt o añadir una nueva tarea.

3. Configuración

Visión del conjunto

Como hemos mencionado anteriormente sails mantiene su filosofía de “convención antes que configuración”, esto es importante a la hora de cómo personalizamos los valores predeterminados. Cada convención en sails, está acompañada de un set de opciones de configuración que podemos ajustar o sobre escribir según nuestras necesidades. Esta documentación incluye una completa referencia de las opciones configurables que están disponibles en Sails.

Disponemos de dos formas de configuración, a través de las variables de entorno o mediante argumentos desde la línea de comandos, usando los archivos de configuración que se encuentran en el directorio config/ de nuestro proyecto. 

Configuración Estándar (config/*)

Un número de archivos de configuración están incluidos por defecto en un proyecto sails cuando lo instalamos. Estos archivos de configuración poseen comentarios los cuales están diseñados para proporcionarnos ayuda.

En la mayoría de los casos, las claves de nivel superior en el objeto sails.config corresponden a un archivo de configuración en particular de nuestra aplicación (por ejemplo: sails.config.views). Sin embargo los valores de configuración se pueden organizar como queramos a través de los archivos en tu directorio config/. Lo importante es el nombre de la key (clave o llave) no confundir con el nombre del archivo.

Por ejemplo, digamos que agrega un archivo nuevo en el directorio config/ con el nombre config/foo.js :

Veremos más acerca de esto en la “Guía de Desarrollo con Sails”, donde se hará referencia a las configuraciones individuales, y como residen estos archivos de forma predeterminada.

Archivos Específicos de Entorno (config/env*)

Los ajustes específicos en los archivos de configuraciön generalmente están disponibles en cualquier entorno de trabajo (Desarrollo, Producción, Test, etc.). Si lo que quiere es tener su configuración solamente en ciertos entornos, entonces debe utilizar los archivos de las carpetas especificadas para ello, config/env/developent.js o config/env/production.js

• Cualquier archivo guardado en la carpeta /config/env/<nombre de entorno> será cargado solo cuando Sails se inicie con  <nombre de entorno>. Por ejemplo, los archivos guardados en config/env/production, solamente se cargarán cuando se ejecute Sails en modo producción.

Accediendo a los valores de configuración de nuestro proyecto

El objeto config está disponible en una instancia de aplicación de sails. Por defecto, este objeto está expuesto en un entorno de ámbito global, mientras sails esté corriendo, esto quiere decir que podemos acceder a él desde cualquier parte de nuestra aplicación. Veamos un ejemplo.

Configuración Personalizada

Sails reconoce varios entornos, nombres de espacio en diferentes claves de nivel superior (ej. sails.config.sockets y sails.config.blueprints). Sin embargo también puede utilizar sails.config para su propia configuración personalizada (ej. sails.config.cualquierProveedorApi.secret).

Ejemplo

Configuración desde línea de comandos

Cuando se trata la configuración, la mayor parte del tiempo estará centrado en la configuración de su aplicación (el puerto, las conexiones a la base de datos, etc.). Sin embargo puede ser útil personalizar Sails CLI, de esta manera simplificamos el flujo de trabajo, reducimos esas tediosas tareas repetitivas, la construcción personalizada de automatización, etc. Afortunadamente sails, desde su versión 0.10, añade una poderosa herramienta que nos ayudará precisamente a esto.

El archivo .sailsrc es diferente a cualquier otra fuente de configuración que encontremos en sails. Podemos usar este archivo para configurar todo el sistema, para un grupo de directorios o solo para un directorio determinado. La principal razón para hacer esto es personalizar los generadores que usa sails cuando se genera un nuevo proyecto o cuando levantamos nuestro servidor con $ sails lift. También es útil para personalizar o instalar nuestros propios generadores personalizados.

En el último capítulo (Extendiendo Sails) de este libro, veremos con más detalle cómo llevar a cabo todo esto.

Cuando generemos un nuevo proyecto, sails buscará el archivo .sailsrc más cercano en directorio actual o en su defecto en los directorios antecesores hasta llegar a la raíz.

Se puede utilizar con total seguridad este archivo para configurar nuestros ajustes, no es recomendable alojar este archivo en la nube.

El archivo config/local.js

El archivo config/local.js, nos resulta útil para la configurar una aplicación sails en un entorno local (Por ejemplo: PC, Portátil, etc). La configuración de este archivo tiene prioridad o preferencia sobre todos los demás archivos de configuración, excepto el archivo .sailsrc, que ya lo vimos anteriormente.

Dado que está destinado sólo para su uso local, no debería ser puesto bajo un control de versiones (GIT, Subversion, etc).

Cuando su aplicación esté lista para desplegarse en un entorno de producción, puede usar este archivo para configurar las opciones que mejor se ajusten en el servidor donde se desplegará la aplicación. Sin embargo, es preferible configurar los archivos de entorno para la implementación en un servidor de producción o un servidor de desarrollo

Usando el archivo .sailsrc

Como hemos visto anteriormente, además de los métodos que tenemos para configurar nuestra aplicación, disponemos del archivo .sailsrc donde podemos especificar la configuración para uno o más aplicaciones. A través de este archivo podemos aplicar todas las opciones de configuración  a todas las aplicaciones sails que tengamos en nuestro ordenador.

Cuando iniciamos o levantamos el servidor web, busca archivos .sailsrc en la carpeta actual y en la carpeta home (~/.sailsrc).

En realidad, sails busca el archivo .sailsrc en cualquier directorio, siguiendo la convención rc, aunque el mejor lugar para poner el archivo .sailsrc, como bien hemos comentado es en la carpeta actual o en el home.

4. Globales (Globals)

Visión de Conjunto

Para nuestra comodidad como desarrolladores sails pone a nuestra disposición una serie de variables globales. Por defecto, los modelos, servicios y el objeto sails están disponibles en todo el ámbito global de nuestra aplicación. Esto significa que podemos hacer referencia a ellos por su nombre en cualquier parte del código, siempre y cuando el servidor sails esté corriendo.

Nada que esté en el núcleo de sails se basa en estas variables globales. Las variables globales pueden estar desactivadas, las podemos modificar y configurar desde el archivo config.globals.js  

El objeto App (sails)

En la mayoría de los casos, usted querrá mantener el objeto global sails accesible, con el propósito de que el código de la aplicación sea mucho más limpio. Sin embargo, si deseas o necesitas desactivar todas las variables globales, incluyendo sails, puedes obtener acceso a través del objeto (req).

Modelos y Servicios

Los modelos y servicios de tu aplicación están expuestas como variables globales utilizando su globalId. Por ejemplo, el modelo definido en el archivo api/models/Foo.js está accesible globalmente como Foo y el servicio definido en el archivo api/services/Baz.js está accesible globalmente como Baz.

Async (async) y Lodash ( _ )

Sails dispone de una instancia de lodash como _ (guion bajo), y una instancia de async como async. Sails proporciona estas utilidades por defecto, lo que quiere decir que no es necesario instalarlas por medio de npm install. Al igual que cualquier otra variable global, se pueden desactivar.

Deshabilitando Globales

Sails determina qué globales están disponibles para su uso examinando sails.config.globals, que convencionalmente se configura en config/globals.js.

Para deshabilitar todas las variables globales, has de establecer el parámetro con valor false :

Si lo que desea es deshabilitar solo una o algunas de las variables globales, ha de establecer a false las que quiera deshabilitar :

5. Rutas (Routes)

Visión de Conjunto

La característica más básica de cualquier aplicación web, es la habilidad de interpretar una petición enviada a una URL, y emitir una respuesta. Para ello la aplicación tiene que ser capaz de distinguir una URL de otra.

Sails provee un mecanismo de ruteo que mapea URL’s a controladores y vistas. Las rutas son reglas o normas que le dicen a sails qué hacer cuando reciben una petición.

Existen dos tipos principales de rutas personalizadas o explícitas y las automáticas o implícitas.

Rutas personalizadas (explícitas)

Sails nos permite diseñar la URL’s de nuestra aplicación como queramos, sin restricciones a nivel de framework.

Cada proyecto en sails cuento con el archivo config/routes.js, un simple módulo de node.js que exporta las rutas personalizadas o explícitas. En el siguiente ejemplo se definen seis rutas, donde unas hacen referencia a una acción de un controlador, mientras que otras rutas hacen referencia directamente a una vista.

Cada ruta consiste en una dirección (‘get /me’) y un destino (‘UserController.profile’). A la dirección opcionalmente le podemos especificar el método HTTP. El destino lo podemos definir de varias maneras diferentes (como veremos a continuación), aunque las dos sintaxis que hemos visto en el ejemplo son las más comunes.

Cuando sails recibe una petición, este chekea las direcciones de las rutas personalizadas hasta encontrar una coincidencia. Si encuentra una coincidencia, entonces la petición pasa al destino.

Por ejemplo, si pudiésemos hablar directamente con sails, sería esto lo que le ordenaremos:

“Estate atento, cuando recibas una petición con el método HTTP GET que apunte a la dirección http://localhost/mi_dominio.com/me, ejecuta la acción profile del controlador UserController”.

Notas

El hecho de que una petición coincida con una dirección de ruta, no significa que se pasará directamente al controlador, algunas peticiones HTTP pasarán primero a través de middlewares. Y si la ruta apunta a una acción de controlador, la petición deberá pasar a través de alguna política configurada previamente.

Rutas Automáticas

Además de las rutas personalizadas, sails enlaza muchas rutas de forma automática. Si una ruta no coincide con la ruta personalizada, puede coincidir con una ruta automática y generar una respuesta.

Los principales tipos de rutas automáticas en sails son:

• Rutas Blueprint, que proveen los controladores y modelos en una API Rest Full.
• Assets, archivos javascript, stylsheets o imágenes.
• CSRF, si está activado, provee una ruta a nuestra aplicación que podemos usar para recuperar un token CSRF.

Protocolos soportados

El router de sails sabe como manejar las peticiones entrantes HTTP y mensajes enviados vía WebSockets. Esto se logra mediante la escucha de los mensajes enviados por Socket.io, estos mensajes son enviados a los controladores de eventos en un formato simple, llamado JWR (JSON-WebSocket Requies/Response).

Notas

Los usuarios avanzados pueden optar por eludir el router y enviar mensajes directamente al servidor mediante Socket.io. Puede enlazar los eventos socket directamente en la aplicación con la función onConnect (localizado en el archivo config/socket.js).

Rutas personalizadas

Como veremos a continuación, sails permite explícitamente definir rutas de varias formas diferentes en nuestro archivo config/routes.js. Cada configuración de ruta contiene una dirección URL y un destino a alcanzar. Por ejemplo:

Dirección de Ruta

La dirección de ruta indica a qué URL debe responder con el fin de aplicar un controlador y las opciones definidas en el destino. Una ruta puede contener opcionalmente un verbo HTTP (GET, POST, … )

Sí no se especifica un verbo, el destino se aplicará a cualquier petición que coincida con la ruta, independientemente del método HTTP utilizado. Ten en cuenta la barra  ” / ” que indicamos al principio de la dirección, todas las rutas han de comenzar con “ / ” para que trabajen correctamente.

Además de usar una ruta estática como /foo/bar, también podemos utilizar el asterisco (*) 

Esta dirección coincidirá con todas las rutas

Esta otra, coincidirá con todas las rutas que empiezan por  /user/foo

Se pueden capturar partes de la dirección que coinciden con parámetros sustituyendo  *  por los nombres de parámetros

Esta también coincidirá con las mismas URLs

Expresiones regulares en las direcciones

Además de utilizar el  *  como ya hemos visto, también podemos utilizar expresiones regulares para definir direcciones URL. La sintaxis para definir direcciones con expresiones regulares es:

r|<expresion regular>|<coma delimitadora listado de nombres de parámetros>

r|^/\\d+/(\\w+)/(\\w+)$|foo,bar": "MessageController.myaction

Una petición URL como esta /123/abc/def ejecutaría la acción “myaction” del controlador “MessageController” y tanto abc como def serían los valores de req.param(‘foo’) y req.param(‘bar’)

NOTA: “La doble barra invertida en  \\d  y  \\w son necesarias para que la expresión regular funcione correctamente.”

El orden de rutas importa

Tanto si usamos * , como si usamos expresiones regulares en nuestras rutas, debemos tener muy en cuenta en como las ordenamos, cuáles ponemos antes y cuáles después. Las URLs se comparan con las direcciones de ruta de arriba a abajo, en el momento que encuentra coincidencia, para y no sigue buscando otras coincidencias.

Destinos de ruta

Podríamos decir que las rutas se conforman de dos porciones, la primera es donde especificamos la dirección que debe coincidir con la URL solicitada. La segunda porción es el destino que especifica a sails que debe hacer, a donde ha de ir a parar en el momento que encuentre coincidencia la dirección URL con la petición. Disponemos de varias formas de definir el destino. En algún momento es posible que necesites que una ruta tenga varios destinos colocados en un array, pero en la mayoría de los casos cada ruta tendrá su dirección junto con un solo destino. A continuación vemos los diferentes tipos que hay para definir los destinos, seguido de como se pueden aplicar.

Destino … Controlador / acción

Cada una de las rutas GET /foo/go accede a la acción myGoAction del controlador api/controllers/FooController.js. Cada vez que se realice una petición a GET /foo/go se ejecutará el código de la acción. Si tu controlador o acción no existiera, se producirá un error y no haría caso de la ruta.

Tanto el nombre del controlador como el de la acción, son case-insesitive (es decir, distingue mayúsculas de  minúsculas).

Ten en cuenta de que blueprints añade las siguientes acciones por defecto  a los controladores ( find, create, update y delete), todos ellos están disponibles para el enrutado.

Se asume que se ha de tener un archivo controlador api/controllers/UserController.js y un archivo modelo en api/models/User.js.

Destino … una vista

Otro destino bastante común es asociarla a una vista. La forma de definirla es muy sencilla: Es la ruta relativa hacia el archivo que contiene la vista dentro de la carpeta views, pero sin la extensión.

Esta ruta GET /home apunta a la vista guardada en views/home/index.ejs (asumiendo que como motor de templates estés usando EJS).

Destino … Blueprint

En algunos casos es posible que quieras asignar una dirección a una acción blueprint de sails. Por ejemplo, si tienes un controlador llamado UserController y un modelo llamado User, sails asigna automáticamente una de las acciones blueprint  “find” a esta dirección (GET /user) retornando un listado de usuarios. Si deseas asignar una dirección diferente para tal acción de blueprint, la sintaxis a llevar a cabo sería algo parecido a esto:

En la primera ruta establecemos tanto el modelo (model) como la acción blueprint, mientras que en la segunda ruta solamente establecemos blueprint. Esto es porque sails examinará en la dirección asumiendo que el modelo es User. Aunque podemos sobreescribir esto explícitamente estableciendo un modelo.

Aunque rara vez o nunca vayas a realizar esto (ya que harías muy confusa tu aplicación), es bueno saber todas las características de que dispone sails a la hora de construir aplicaciones. Nunca se sabe, si en algún caso en concreto tendrás que recurrir a algo parecido.

Si especificamos un modelo que no existe, Sails emitirá un error y no hará caso de la ruta.

Destino … Redireccionando

Puedes tener una ruta que redirija a otra URL ya sea dentro de nuestra aplicación o en otro servidor, solamente hemos de especificar la URL a la que queremos que se dirija.

Ten cuidado de no crear un bucle infinito al redirigir dentro de la aplicación.

Has de saber que al redirigir, lo más probable es que tanto el método HTTP, parámetros y cabeceras se pierdan, y la petición se transforma en una simple petición GET. En el ejemplo una petición a  la ruta /alias daría como resultado una petición GET a /some/other/route.

Destino … Respuesta personalizada

También podemos asignar una dirección directamente a una respuesta personalizada:

Sólo tienes que especificar el nombre del archivo sin la extensión (.js) que contiene tu respuesta, deberá estar ubicado en api/responses. El nombre de la respuesta que especifiquemos hace diferencia entre mayúsculas y minúsculas. Si una ruta apunta hacia una respuesta inexistente, Sails emitirá un error y no hará caso de la ruta.

Destino … Política

En la mayoría de los casos para aplicar una política a una acción de un controlador, hacemos uso del archivo de configuración config/policies.js. Habrá ocasiones en la que quieras aplicar una política directamente a una ruta, sobre todo cuando estés usando en el destino de la ruta una vista o blueprint.  

Sin embargo, aparte de aplicar la política, también querrás que tenga otro tipo de destino. Esto lo conseguimos usando un array, quedaría de esta forma:

‘/foo’: [{ policy: ‘miPolicy’ }, { blueprint: ‘find’, model: ‘user’ }]

Esto aplicará la política a la ruta, si la política devuelve true o next(), entonces se ejecuta la acción find.

Opciones de los destinos

Aparte de todas la opciones que hemos visto hasta ahora, cualquier otra propiedad que  quieras introducir en el destino, será transferido al controlador como un objeto req.options. 

Hay varias propiedades reservadas  que se pueden utilizar para alterar el comportamiento de las rutas, estas se enumeran en la siguiente tabla.

URL’s amigables (slugs)

Las URL semánticas o URL amigables son aquellas URLs que son, dentro de lo que cabe, entendibles para el usuario. Lejos de las clásicas URLs de las páginas dinámicas llenas de variables GET y números difíciles de recordar, las URL semánticas están formadas con palabras relacionadas con el contenido de la página y fáciles de recordar. Estas se utilizan en los sitios web dinámicos (no estáticos). Por ello se están utilizando mucho más que las URL extensas.

Un caso de uso muy común para las rutas explícitas es diseñarlas para que sean amigables. Por ejemplo, considera una url de un repositorio de Github (http://www.github.com/balderdashy/sails.js). En sails, podríamos definir esta ruta en la parte inferior de nuestro archivo config/routes.js.

En la acción show de nuestro RepoController usamos req.para(‘account’) y req.param(‘repo’) para saber los datos del repositorio adecuado, para luego pasarlo tanto a la vista como a las locales (locals), esta parte la veremos más adelante en la sección de vistas.

La opción skipAssets nos asegura de que la ruta no coincide accidentalmente con cualquiera de nuestros assets o archivos estáticos (ej.: /images/logo.png).

6. Controladores

Visión del conjunto

Los controladores son los objetos principales en nuestra aplicación, estos son los responsables para responder a las peticiones que provienen normalmente de un navegador web, aplicaciones móviles u otro sistema capaz de comunicarse con el servidor.  La mayoría de las veces actúan como intermediarios entre nuestros modelos y vistas. Para cualquier aplicación, los controladores contienen la lógica de negocio de nuestro proyecto.

Acciones

Los controladores están compuestos de una colección de métodos llamados acciones (actions).  Los métodos o acciones se pueden unir a las rutas de nuestra aplicación, de tal modo que cuando el cliente solicite una ruta el método o acción se ejecute para realizar la lógica de negocio y en la mayoría de los casos genere una respuesta. Por ejemplo la ruta GET /hola podría estar ligada a un método o acción como se muestra a continuación:

Así que cada vez que nuestro navegador apunte a la ruta /hola, este imprimirá en pantalla Hola!.

¿Donde definimos los controladores?

Los controladores están o serán definidos en el directorio api/controllers/. Podemos crear tantos controladores como queramos, pero para que sean cargados como controladores deberán estar dentro de dicho directorio, el nombre del archivo deberá finalizar con Controller.js. Por convención, los controladores usa Pascal-cased, con lo que la primera letra de cada palabra (incluida la primera) la escribiremos en mayúscula, por ejemplo UserController.js, MiController.js o CualquierOtroNombreController.js .

Puedes organizar tus controladores dentro de grupos, guardando estos en sub-carpetas dentro de api/controllers , sin embargo nota que el nombre de la sub-carpeta pasará a formar parte de la identidad del controlador en el momento que se utilice el enrutamiento (aprenderemos más sobre esto en la sección de “Routing” ).

¿Como es un archivo Controlador?

Un archivo controlador se define como un objeto en JavaScript. La llave o clave (key) es el nombre de la acción, y los valores son los métodos de dicha acción. Observa este ejemplo sencillo de un controlador:

Este controlador define dos acciones: por un lado tenemos la acción “hola” que responde a la petición con un mensaje de tipo string (cadena de texto) y la segunda acción “adios” que responde redireccionado a otra página web.

Los objetos “req” y  “res” le resultará familiar si anteriormente ha usado Express.js. Esto es porque Sails usa Express para manejar o manipular el enrutado. Quizás te preguntes acerca del argumento “next” en las acciones, a diferencia de otros métodos en Express, los controladores en Sails siempre deben ser la última parada en la cadena de la petición, es decir, que siempre ha de devolver o una respuesta o un error. Aunque es posible utilizar el argumento “next” en las acciones, no es nada recomendable, en su lugar puedes hacer  uso de este parámetro en las políticas (policies) siempre que sea posible, algo que veremos en su momento.

Enrutado (Routing)

Por defecto, Sails crea rutas blueprint (las rutas blueprint enlazan rutas vinculadas automáticamente, sin tener que definirlas explícitamente en una ruta) para cada acción, de modo que si hacemos una petición GET a /:controlador/:accion se activará la acción. Si tomamos como ejemplo el controlador anterior, imagina que lo hubiésemos guardado como api/controllers/SayController.js, entonces las rutas hacia dichas acciones estarían disponibles como /say/hola  y  /say/adios. Si el controlador lo hubiésemos guardado en una sub-carpeta como por ejemplo api/controllers/we/SayControlller.js entonces las rutas serían /we/say/hola y  /we/say/adios.

Además de las rutas por defecto, Sails te permite enlazar manualmente las rutas a las acciones de los controladores utilizando el archivo config/routes.js. A las rutas definidas en este archivo se les denomina rutas explicitas ¿Cuando debemos utilizar rutas explícitas?

• Cuando tengamos que utilizar más de una acción para una ruta, por ejemplo una misma ruta nos puede servir para llamar a una acción que solo responda al método POST, pero también esta misma ruta podrá llamar a otra acción que responda al método GET, PUT, DELETE, etc.
• Cuando quieras que una acción esté disponible en una URL personalizada (ej.: PUT /login, POST /signup, o GET /:username)
• Cuando desees configurar opciones adicionales de cómo se debe manejar una ruta (ej.: Configuración CORS)

Para enlazar manualmente una ruta a una acción, lo haremos siempre desde el archivo config/routes.js, usamos el verbo HTTP y la dirección. La dirección de la ruta es la clave o llave (key) y el nombre_del_controlador.nombre_de_la_acción es el valor.

Por ejemplo, la siguiente ruta hará que la aplicación  active la acción preparar(), siempre que la petición reciba el método POST

        api/controllers/BocadilloController.js

Para hacerte una idea más completa, revisa la sección rutas, obtendrás una descripción más completa de las opciones disponibles.

Controladores ligeros

La mayoría de los frameworks MVC recomiendan escribir controladores ligeros, sails no iba a ser menos, ni hacer una excepción, ya que es una buena idea mantener los controladores tan simples como sea posible. Mostraremos el porqué es útil mantenerlos lo más simple posible.

El código del controlador depende esencialmente de un evento. En la parte del backend de sails, este evento es casi siempre una solicitud entrante. De modo que si escribimos un montón de código en las acciones del controlador, no es raro pensar que el código se vuelva dependiente del contexto de la petición, lo cual está bien…. hasta que quieras utilizar ese código en otra acción diferente o desde la línea de comandos.

Así que la filosofía de mantener el controlador lo más simple posible o ligero, es fomentar la disociación del código para poderlo hacer reutilizable, de esta forma cuando quieras realizar un cambio no tendrá que hacerlo en todos los controladores. Con sails podemos lograr esto de varias maneras diferentes, pero las más comunes para la extrapolación de código de los controladores son:

• Escribir un modelo personalizado para encapsular un código que realiza una tarea en particular con relación a un determinado modelo.
• Escribir un servicio como una función para encapsular un código que realiza una tarea específica en la aplicación.
• Si encuentras algo de código que es útil en varias de tus aplicaciones, es una buena práctica extraerlo a un módulo de NodeJS.  De esta manera podrás re-utilizarlo en cualquiera de tus proyectos futuros o mejor aún publicarlo en npm bajo la licencia Open-Source para que otros desarrolladores puedan beneficiarse y te ayuden a mantenerlo.

Generando Controladores

Puedes utilizar la herramienta que brinda Sails,  desde la línea de comandos puedes generar controladores automáticamente, junto con sus acciones, por ejemplo:

Por ejemplo, si ejecutamos el siguiente comando:

Sails generará un archivo en api/controllers/ComentarioController.js parecido a esto:

7. Respuestas Personalizadas

Visión del conjunto

Sails nos permite personalizar las respuestas que emite el servidor, por defecto, en la carpeta o directorio api/responses, encontramos las más comunes. Para personalizarlas solamente hemos de editar el archivo .js apropiado para ello.

Veamos un ejemplo, considerando la siguiente acción:

Este código maneja una petición, respondiendo con un error de tipo 400 y un mensaje corto que describe el problema. Sin embargo, este código tiene algunos inconvenientes, principalmente:

• No está normalizado. El código es específico en esta instancia, es decir en esta acción solamente, y tendríamos que escribir mucho código para mantener el mismo formato de error en toda nuestra aplicación.
• No es abstracto, con lo que sí queremos que los errores similares muestren el mismo mensaje, vamos a tener que copiar/pegar en muchas ocasiones.
• Si el cliente está esperando una respuesta JSON, no obtendrá lo que espera.

Ahora considera este cambio:

Ahora este enfoque, contiene las siguientes ventajas:

• El error está normalizado
• Se tiene en cuenta tanto si el servidor está en Producción como en Desarrollo
• El código de error ahora es consecuente y consistente
• El contenido contendrá JSON o HTML
• Los ajustes de la API se pueden editar para una respuesta adecuada

Métodos de respuesta y archivos

Todos los archivos .js guardados o almacenados en la carpeta /api/responses serán ejecutados por la llamada res.[nombreRespuesta] desde nuestro controlador. Por ejemplo, /api/responses/serverError.js puede ser llamado o ejecutado llamándolo a través de res.serverError(errores). Los objetos request y  response están disponibles dentro del archivo response (serverError.js) cómo this.req y this.res , esto permite que la función de respuesta tome los parámetros arbitrariamente.

Respuestas Por Defecto

Cada una de las respuestas envía un objeto JSON normalizado, si el cliente lo que espera es un JSON, contiene una clave/llave (key) con el código de estado HTTP y claves adicionales con información acerca del error.

res.serverError(errors)

Esta respuesta normaliza el error o errores en un array de objetos. Los errores pueden ser una o varias cadenas de texto o incluso objetos. Sails registra todos los errores normalmente en consola y responde con la vista /500.* si el cliente esta esperando HTML, o en su defecto el cliente obtiene un JSON si es lo que esperaba. En modo desarrollo, la lista de errores se incluye en la respuesta. En modo producción los errores reales se suprimen.

res.badRequest(validationErrors, redirectTo)

Esta respuesta incluye el código de estado 400 y todos los datos relevantes pasados a través de los parámetros validationErrors.

Para los formularios web tradicionales (sin AJAX) este middleware sigue las mejores prácticas para cuando el usuario envía datos del formulario que no son válidos.

res.notFound()

Si lo que el cliente espera es JSON, esta respuesta envía un objeto con código de estado 404.

De lo contrario Sails sirve la vista /views/404.* Si la vista no es encontrada, entonces el cliente recibirá la respuesta en formato JSON.

res.forbiden(message)

Si lo que el cliente espera es JSON, esta respuesta envía un objeto con código de estado 403 junto con el contenido del mensaje.

De lo contrario Sails sirve la vista /views/403.* Si la vista no es encontrada, entonces el cliente recibirá la respuesta en formato JSON.

Respuesta Personalizada

Para añadir tu propio método de respuesta personalizada, solamente has de añadir un archivo en la carpeta /api/responses con el mismo nombre del método que le gustaría crear. El archivo debe exportar la función, y puede obtener tantos parámetros como desees. Mira este ejemplo de una respuesta personalizada:

8. Modelos y ORM

Waterline: SQL/noSQL Tratamiento de Datos (ORM/ODM)

Sails lleva incorporado un magnífico ORM/ODM llamado Waterline. Una herramienta que simplifica la interacción de nuestra aplicación con una o más bases de datos. Proporciona una capa de abstracción en la parte superior de la base de datos, que permite consultar y manipular fácilmente los datos, sin necesidad de escribir una gran cantidad de código.

En las bases de datos como Postgres, Oracle y MySQL, los modelos están representados por tablas, en cambio en MongoDB se representa por colecciones. En Redis se representa por medio de pares clave/valor (key/value). Cada base de datos tiene su propio dialecto que hace que consultar sus datos sea totalmente distinta unas de otras, en algunos casos incluso requiere instalación y compilación de algún módulo nativo específico para la conexión al servidor.

La sintaxis de waterline se centra en la lógica de negocio, como la creación de nuevos registros o búsqueda de registro/s existentes, actualización o la destrucción de los mismos. Da lo mismo a la base de datos que estemos conectados, el uso de waterline será el mismo. Por otra parte waterline permite asociaciones entre modelos de una manera sencilla, incluso si los datos de cada modelo reside en una bases de datos diferente. Esto significa que podemos cambiar los modelos de nuestra aplicación de MongoDB a Postgress o MySQL o Redis, sin tener que cambiar ningún código de nuestra aplicación.

Para momentos en los que necesitamos la funcionalidad de una base de datos específica,  waterline proporciona una interfaz de consulta que nos permite interactuar directamente con el controlador de la base de datos.

Escenario

Imaginemos que estamos construyendo una aplicación web que contiene un comercio online (e-commerce), a esta aplicación le acompaña otra que permite acceder desde un dispositivo móvil. Los usuarios podrán navegar por los productos, filtrarlos por categoría o realizar una búsqueda de un artículo en concreto, finalmente el usuario realizará una compra. Algunas partes de la aplicación son bastante comunes. En nuestra API habrá partes que han de controlar la autenticación de usuarios, registro, órdenes de pago, reseteo de contraseñas, etc. Sin embargo, existen todavía algunas características en las que nos tenemos que involucrar aún más.

Flexibilidad

Quizá se pregunte, qué motor de base de datos es la mejor para llevar a cabo la aplicación web de comercio online.

Pues bien, no se apresure, seguro que no le gustará tomar una decisión equivocada.

En la mayoría de los casos elegiremos una sola base de datos para una aplicación API, cabe la posibilidad que se necesite mantener la compatibilidad con una o más bases de datos, ya sea porque así lo deseemos o bien por razones de rendimiento.

Sails  usa sails-disk por defecto, esto significa que puedes empezar a construir tu aplicación sin configurar nada, usando un archivo temporal como almacenamiento de datos.

Compatibilidad

El cliente me pide que integre los productos en la aplicación de comercio online, me dice que los tiene en una ERP con no sé qué de DB2. De todas formas seguro que no es difícil implementarlo.

Cuando desarrollamos aplicaciones empresariales, nos encontramos que a menudo debemos integrarlas con bases de datos que el propio cliente ya tiene. Si tienes suerte, una migración de datos de una sola vez, puede que sea todo lo que necesites, pero en algunas ocasiones es posible que la base de datos existente se vea modificada por otras aplicaciones en tiempo real. Con el fin de construir su aplicación es posible que tenga que convivir con otros sistemas de conjunto de datos  separados en otro lugar. Estos conjuntos de datos podrían incluso estar en cinco servidores diferentes repartidos por el mundo. Una base de datos podría albergar datos relacionales SQL, mientras que otro servidor podría contener colecciones de MongoDB.

Sails/Waterline te permite conectar modelos a diferentes bases de datos, ya sean locales o en cualquier otro sitio en internet. Puedes construir un modelo “Usuario” y que esté asignado a una tabla de MySQL personalizada que herede de otra base de datos. De igual manera para un modelo “Producto” que esté asignado a una tabla de DB2 o lo mismo para una colección de MongoDB. Lo mejor de todo es que podemos a través de .populate() conectarnos a diferentes almacenes de datos y adaptadores y configurar un modelo para que resida en una base de datos diferente. Tu modelo o controlador no sufrirán ningún cambio en el  código.

Adaptadores

Como la mayoría de los frameworks MVC y sails no iba a ser menos, soportan múltiples bases de datos. Esto significa que la sintaxis para manipular o hacer consultas a la base de datos es siempre el mismo, ya sea que esté trabajando con MySQL, MongoDB o cualquier otra base de datos compatible.

Waterline se basa en la flexibilidad de sus adaptadores. Un adaptador es un pedazo de código que asigna métodos como find() y create() para una sintaxis de bajo nivel como SELECT * FROM  y  INSERT INTO. El núcleo de sails contiene adaptadores de código abierto de las bases de datos más populares. También una gran cantidad de adaptadores  que están disponibles en la comunidad.

Conexiones

Una conexión representa la configuración de una base de datos en particular. Este objeto configura un adaptador: el host, puerto, nombre de usuario y contraseña. Las conexiones se definen en config/connections.js

Por defecto la conexión a la base de datos para una aplicación en sails se encuentra en config/models.js, pero podemos sobreescribir la conexión en un modelo especificando una conexión (connection).

Analogía

Imagine un archivador físico lleno de hojas de facturas. Todas las facturas tienen los mismos campos (ej.: número_de_factura, fecha, nombre_cliente,  … ), pero en cada factura, los valores de estos campos varían. Por ejemplo, una factura puede contener “100”, “2015-05-16T21:16:15.127Z”, “Pedro Manuel”, …

mientras que otra factura contiene “101”, “2015-06-16T21:16:15.127Z”, “Aitor Menta”, …

Ahora imagine que tiene un negocio de venta de perritos calientes, si es una persona organizada, es posible que establezca los archivos de su negocio de la siguiente manera:

• Empleados (contiene los registros de los empleados)

• nombreCompleto
• salario
• numeroTelefono

• Ubicaciones (contiene las ubicaciones en las que se trabaja)

• direccion
• ciudad
• codigoPostal
• compras

• listado de todas las compras hechas en esta ubicación

• empleado

• el empleado que gestiona esta ubicación

• Compras (contiene los registros de cada compra hecha por un cliente)

• ubicacionCompra
• productosComprados
• fechaCompra

• Productos (contiene los registros de cada producto)

• nombre
• precio
• numeroCalorias
• porcentajeCarne
• disponible

• listado de las ubicaciones donde este producto está disponible

En su aplicación, un modelo será como un archivador que uno o muchos archivos, ya sean de empleados, facturas de compras, etc. Los atributos son los campos que contiene cada archivo, todos los archivo de un archivador tienen los mismos campos pero con diferentes valores.

Nota: Esta documentación no será aplicable si reemplazas el ORM que trae consigo Sails, (Waterline).

Asociaciones / Relaciones

Con Sails y Waterline, puede asociar modelos a través de múltiples bases de datos. Esto significa que si los los datos de usuarios residen en una base de datos PostgreSQL y las fotografías de estos usuarios residen en una base de datos MongoDB, puede interactuar con los datos como si la ubicación de los usuarios y las fotos estuvieran en la misma base de datos.

También puede hacer que las asociaciones abarquen diferentes conexiones usando el mismo adaptador. Esto es muy útil, si su aplicación necesita acceso o actualizar los datos almacenados en una base de datos MySQL que tenga físicamente en su empresa o negocio, pero también guardar o recuperar datos desde otra base de datos MySQL pero esta vez ubicada en la nube.

Dominación

Veamos un ejemplo algo peculiar. Donde tenemos un modelo que reside en una base de datos

MySQL y otro modelo en una base de datos Redis. Entre ellos queremos crear una relación de

muchos-a-muchos.

Es fácil saber lo que está pasando en esta relación de muchos-a-muchos (many-to-many) donde

usuarios y productos están relacionados. De hecho, se ha puesto este ejemplo pero podría ser otro

cualquiera.

Ahora surge la pregunta … ¿Dónde reside el recurso de la relación Producto-Usuario? Sabemos

que en un lugar o en otro va a estar, pero qué pasa si queremos controlar la base de datos en la que

va a residir el recurso.

Para una posible solución podríamos especificar una tercera conexión o adaptador para la unión de los

dos modelos. Por ahora, nos centraremos cual de los dos lados sea el que predomine.

Para ello nos centramos en el concepto de “posición dominante”. En cualquier cruce  de modelos

relacionados, uno de los lados ha de dominar. Para entenderlo mejor, imagine un matrimonio donde

el hombre tiene la nacionalidad Española y la mujer la nacionalidad Francesa, al tener un hijo, este,

podrá escoger a qué nacionalidad quiere pertenecer.

Volviendo al ejemplo anterior, pero en esta ocasión estableceremos la base de datos MySQL como la

dominante. Esto significa que la relación Producto-Usuario se almacenará como una tabla MySQL.

        La elección de una tabla como “dominante”

        Existen varios factores que influyen a la hora de tomar la decisión de elegir como dominante una

        tabla:

• Si la base de datos es SQL, la relación nos permite que las consultas sean más eficientes, ya que las relaciones se pueden unir antes de que otro lado se comunique. Esto reduce el número de consultas requeridas de 3 a 2.

• Si una conexión a la base de datos es más rápida que otras, esas otras tendrán la misma igualdad de condiciones, por ello tiene sentido establecer la dominante a la conexión más rápida.

• Si una de las conexiones a la base de datos es de solo lectura, es una buena elección establecerla como dominante.

¿Que pasa si una colección no tiene la propiedad “via”?

Si una asociación de una colección no tiene la propiedad “via”, automáticamente se establece como dominante.

¿Que ocurre si ninguno de las colecciones tienen la propiedad “via”?

Entonces las colecciones no tienen relación, Ambas son dominante, ya que son tablas de relaciones separadas.

¿Que ocurre con las asociaciones de modelo?

En todos los otros tipos de asociaciones, la propiedad dominante no está permitida. La configuración de un lado como dominante solo es necesaria para asociaciones entre dos modelos que tengan una propiedad o atributo: { via: ‘...’, collection: ‘...’ } en ambos lados.

¿Pueden ser ambos modelos dominante?

No. Si ambos modelos en una conexión cruzada con relación de muchos-a-muchos se establecen como dominantes, se produce un error antes de que empiece a correr el servidor o nuestra aplicación.

¿Que ocurre si ambos modelos no son dominantes?

Si ninguno de los modelos en una conexión cruzada con relación de muchos-a-muchos no tiene establecida la propiedad dominante, se produce una advertencia al iniciar el servidor y automáticamente basándose en las características de la relación establece a un modelo la propiedad dominante, tomando esa decisión por orden alfabético.

Relaciones de Muchos-a-Muchos

Visión de conjunto

Una asociación de muchos-a-muchos establece que un modelo se puede asociar a muchos otros modelos y viceversa. Debido a que ambos modelos pueden tener muchos modelos relacionados, se deberá crear una nueva tabla que realice la unión entre ellos.

Waterline analizará los modelos en busca de asociaciones y automáticamente construirá esa tabla de unión por nosotros.

Veamos un ejemplo, donde construimos un esquema de usuarios y otro de mascotas, en donde un usuario podrá tener muchos registros de mascotas y una mascota varios usuarios.

Ejemplo de muchos-a-muchos

En este ejemplo, iniciamos con un array de usuarios y un array de mascotas. Creamos los registros para cada elemento de cada array, luego asociamos todas las mascotas con todos los usuarios.

Si todo funciona correctamente, nosotros podremos realizar una consulta a cualquier usuario y ver todas las mascotas que tiene. Por otra parte, también se podrá consultar una mascota y ver los usuarios que tienen asociada esta mascota.

        myApp/api/models/Mascota.js

myApp/api/models/Usuario.js

        myApp/config/bootstrap.js

A continuación ejecutamos nuestra aplicación con sails console

Asociando en una sola dirección

Visión de conjunto

Una asociación de sentido único, es un modelo donde se asocia con otro modelo. Puede realizar una consulta a ese modelo y obtener su modelo asociado. Sin embargo no se puede consultar el modelo asociado y obtener el modelo que lo asocia.

Ejemplo

Entenderemos mejor todo esto con un ejemplo. En este ejemplo, asociaremos un Usuario con una Mascota, pero no una Mascota con un Usuario.

myApp/api/models/Mascota.js

myApp/api/models/Usuario.js

Ejecutamos sails console

Hemos formado una asociación en uno de los modelos, con lo cual una mascota no tiene restricciones en el número de Usuarios al que puede pertenecer.

Uno-a-Muchos

Visión de conjunto

Las asociaciones de uno-a-muchos afirma que  un modelo se puede asociar a muchos otros modelos. Para construir esta asociación es necesario añadir un atributo a un modelo usando la propiedad collection.

En una asociación de uno-a-muchos uno de los lados ha de tener un atributo collection y el otro lado ha de contener un atributo con el nombre del modelo que lo asocia.

Ejemplo

myApp/api/models/Mascota.js

myApp/api/models/Usuario.js

Ejecutamos sails console

Uno-a-Uno

Visión de conjunto

Las asociaciones uno-a-uno asumen que un modelo solo se puede relacionar con otro modelo. Para que un modelo sepa que está asociado con otro modelo, se debe incluir en los registros un foreign key.

Ejemplo

En este ejemplo asociamos una mascota a un usuario. El usuario sólo puede tener una mascota asociada y una mascota sólo puede tener un usuario asociado. Sin embargo,  a la hora de realizar una consulta la podemos realizar de cualquiera de los dos lados, crear o actualizar ambos modelos.

myApp/api/models/Mascota.js

myApp/api/models/Usuario.js

Ejecutamos sails console

Atributos

Los atributos son piezas básicas de información acerca de un modelo. Un modelo, puede contener atributos como, nombre, apellidos, teléfono, edad, email, etc…

Opciones de los atributos

Las opciones que veremos a continuación se pueden utilizar para hacer cumplir limitaciones y añadir mejoras a los atributos del modelo..

type: Especifica el tipo de dato que podrá almacenar el atributo, de los cuales podemos optar por los siguientes

• string
• text
• integer
• float
• date
• datetime
• boolean
• binary
• array
• json
• email

defaultsTo: Cuando se crea un nuevo registro en la base de datos, es posible que algún campo no se le esté suministrando un valor externamente, pero es posible que queramos que cuando ocurra esto se le asigne un valor por defecto, para ello haremos uso de esta opción.

autoIncrement: Establece el atributo como una key auto-incremental. Cuando se añade un nuevo registro al modelo, si no se especifica un valor para este atributo, se incrementa en uno tomando como parámetro el último valor de los registros creados anteriormente, si no existe se establece en 1.

Importante! Al atributo que especifiquemos “autoIncrement”, deberá ser siempre de tipo integer. Ten en cuenta también, que si la base de datos con la que estás trabajando con este modelo es MySQL, has de saber que este no permite que dos columnas tengan la key “auto-incremental”

unique: Se asegura de que dos registros no contengan el mismo valor. Esta es una restricción a nivel de adaptador (MySql, MongoDB, ...) con lo que se  crea un índice único en la base de datos.

primaryKey: Usa este atributo como la clave principal. Sólo un atributo por modelo puede ser primaryKey. Cuidado! Nunca debes utilizar primaryKey si no tienes autoPK establecido a false

enum: Atribuye validación especial, solo guarda los datos, que coinciden con una serie de valores estipulados en un array.

size: Es soportado por el adaptador, puedes usarlo para definir el tamaño del atributo, por ejemplo en MySQL se especifica como número: varchar(n).

columnName: Dentro de una definición de atributo, puede especificar un nombre de columna, para forzar a Sails/Waterline a que almacene los datos de ese atributo en una columna específica. Esto no es solamente para MySQL, también funciona en campos de MongoDB y otros. Mientras que la propiedad columnName está diseñada para trabajar con bases de datos heredadas, también puede sernos útil en situaciones en las que la base de datos está siendo compartida por otras aplicaciones o en los casos que no tengas permisos para cambiar el esquema de  la tabla.

Esto es un ejemplo muy sencillo de cómo aplicar un nombre de columna a un atributo, pero veamos un caso más real.

Digamos que tienes un modelo “Usuario” en tu aplicación más o menos similar a este:

Todo funciona bien, pero en lugar de usar una base de datos MySQL existente, alberga los datos de usuario en algún lugar de Internet:

Imaginemos que en esta base de datos encontramos una tabla llamada “nuestros_usuarios” que tiene un aspecto como este:

Para utilizar esto desde Sails, cambiaríamos nuestro modelo a algo parecido a esto:

Habrás notado, que usamos la propiedad tableName en este ejemplo. Indicamos el nombre de la tabla donde se guardarán nuestros datos.

Ciclo de vida de los Callbacks

Sails pone a disposición algunas retrollamadas (callbacks) en los modelos que se ejecutan automáticamente antes o después de ciertas acciones. Por ejemplo, algunas veces utilizamos un callback para encriptar un password antes de crear o modificar un registro de nuestro modelo.

Callbacks (on create) Al Crear

• beforeValidate: fn(values, cb)
• afterValidate: fn(values, cb)
• beforeCreate: fn(values, cb)
• afterCreate: fn(newlyInsertedRecord, cb)

Callbacks on update (Al Modificar)

• beforeValidate: fn(valuesToUpdate, cb)
• afterValidate: fn(valuesToUpdate, cb)
• beforeUpdate: fn(valuesToUpdate, cb)
• afterUpdate: fn(updatedRecord, cb)

Callbacks on destroy (Al Eliminar)

• beforeDestroy: fn(criteria, cb)
• afterDestroy: fn(destroyedRecords, cb)

Ejemplo

Si queremos encriptar un password antes de que se guarde un registro en la base de datos, haremos uso del callback beforeCreate().

Modelos

Un modelo representa una estructura de datos, ya sea en una colección o tabla. usualmente corresponde a una única tabla o colección en la base de datos. Los modelos se definen creando un archivo en la carpeta o directorio api/models/

Utilizando los modelos

Accedemos a los modelos a través de los controladores, políticas, servicios, respuestas, tests y métodos personalizados. Existen varios métodos incorporados en sails que están disponibles en los modelos, los más importantes son los métodos denominados crud: find, create, update y destroy. Estos métodos son asíncronos, Waterline envía una petición y espera una respuesta.

Consecuentemente, los métodos de consulta devuelven un objeto deferred. Para ejecutar una consulta, llamamos al objeto .exec(cb), donde cb es la función callback que corre después de que la consulta se ha completado.

Waterline también incluye soporte para las promesas (promises). En lugar de llamar a la función .exec(), podemos ejecutar .then(), .spread() o .catch() esto nos devolverá una respuesta Bluebird promise

Métodos de modelo (estáticos o de  clase [statics or class])

Los métodos de clase son funciones integradas en el propio modelo, que realizan alguna tarea en particular en sus propios registros. Aquí es donde se encuentran los métodos CRUD que habitualmente utilizamos para atacar a la base de datos. .create(), .update(), .destroy(), .find(), etc.

Métodos de modelo personalizados

Waterline permite definir métodos personalizados en nuestros modelos. Esta característica se aprovecha de que los modelos en Waterline ignoran las keys que no reconoce, has de tener cuidado de no sobrescribir los métodos incorporados en sails (.create(), .find(), etc.) o buscadores dinámicos. Los métodos de modelo personalizados son útiles para extrapolar el código de un controlador que se relaciona con un modelo en particular, es decir permite sacar el codigo de los controladores en funciones reusables a los que podemos llamar desde cualquier sitio (con lo que no dependen de los objetos req o res).

Los métodos de modelo son generalmente funciones asíncronas. Por convección los métodos asíncronos deben ser funciones de tipo 2-ary, estos aceptan un objeto como primer argumento (usualmente llamados opts o options) y un callback como segundo argumento. También puedes optar por devolver una promesa. Ambas estrategias funcionan igual de bien, el utilizar una u otra es cuestión de preferencia, si no tienes preferencia sigue utilizando los callbacks.

Una buena práctica es escribir tu propio método de modelo estático, de modo que este pueda aceptar un registro o el valor de la clave principal (primaryKey). Para que los modelos operen en varios registros a la vez, debes pasarle una tabla de registros o un array de valores de clave principal.

Esto hace que nuestro método tenga más líneas de código de lo normal, pero a la vez, nos queda un método más robusto. Y ya que estas haciendo esto para extrapolar la lógica, vale la pena el esfuerzo.

Por ejemplo:

Ahora podemos...

Otro ejemplo:

Métodos de Atributo

Un método de atributo es una función que se encuentra disponible en los registros, podríamos decir que es una instancia del modelo. Por ejemplo, si tu quieres buscar o encontrar los diez estudiantes con mejor nota en el modelo Estudiante, cada uno de estos registros tendrá acceso a los métodos de atributos incorporados o que deseemos incorporar.

Construyendo métodos de atributos

Cada modelo incluye unos métodos por defecto, a saber:

• .toJSON()
• .save()
• .destroy()
• .validate()

Métodos de atributo personalizables

Los modelos de Waterlines, también permiten definir sus propios métodos de atributo personalizado, los definiremos como  cualquier otro atributo,  escribiendo una función al lado del nombre del atributo.

Ten presente que a excepción de .save() y .destroy(), los demás atributos/método serán siempre síncronos por convección.

Cuando debemos escribir un atributo / método personalizado?

Los atributos/métodos son útiles a la hora de extraer información de un registro. Por ejemplo mirando el código de ejemplo anterior podríamos pedir información al registro de la siguiente manera:

Cuando NO escribir un atributo / método personalizado ?

Evita escribir tus propios métodos de atributos asíncronos. A veces pueden tener consecuencias no deseadas y no es la forma más adecuada de construir tu aplicación.

Waterline Query Language (Lenguaje de consulta)

“Waterline Query Language”  es un lenguaje basado en objetos utilizados para recuperar los registros de cualquier adaptador (recuerda que los adaptadores son los encargados de mantener comunicación entre nuestra aplicación y las bases de datos MySQL, MongoDB, etc.).

Esto significa que la misma consulta que escribamos para MySQL nos va a servir tanto para MongoDB, como Redis, etc. Esto nos permitirá en un futuro cambiar de base de datos pero no el código de nuestra aplicación.

Lenguaje de consulta (Lo Básico)

El criterio de estos objetos se forma utilizando uno de los cuatro tipos clave del objeto. Estos son las claves de nivel superior utilizados en un objeto de consulta. Se basa libremente en los criterios que se utiliza en MongoDB, aunque con algunas variaciones.

Las consultas se pueden construir utilizando “WHERE”, también podremos usar las opciones “limit”, “skip” y “sort”. Si en la consulta omitimos el “WHERE”, el criterio que seguirá la consulta, será como si de un simple “WHERE” se tratase. Observa este ejemplo donde lo entenderás mejor.

Pares de claves : valor

El par clave/valor se usa para buscar registros con valores coincidentes exactamente con lo que se especifica. Este es el criterio que sigue el objeto “WHERE”, la clave representa el atributo del modelo y el valor es una estricta verificación de igualdad.

También podemos usar varios atributos para realizar una búsqueda

Las consultas IN tiene una forma muy similar a las consultas in de MySQL, cada elemento del array será tratado como ‘OR’

Las consultas NOT-IN  son similares a las “IN”, pero siguiendo otro criterio

Las consultas OR se usa mediante un array de pares clave/valor. Los resultados devueltos, serán según los criterios pasados en el array.

Los siguientes modificadores, están disponibles para su uso a la hora de construir consultas.

• ‘<’                Menor Que
• ‘<=’                Menor o Igual Que
• ‘>’                Mayor Que
• ‘>=’                Mayor o Igual Que
• ‘!’                Not
• ‘like’                
• ‘contains’        Contiene ...
• ‘startsWith’        Empieza con ...
• ‘endsWith’        Termina con ...

‘<’        Menor Que

Busca registros donde el valor es menor que el valor especificado. Por ejemplo

‘<=’        Menor o Igual Que

Busca registros donde el valor es menor o igual que el valor especificado. Por ejemplo

‘>’        Mayor Que

Busca registros donde el valor es mayor que el valor especificado. Por ejemplo

‘>=’        Menor o Igual Que

Busca registros donde el valor es mayor o igual que el valor especificado. Por ejemplo

‘!’        NOT

Busca registros donde los valores no son iguales al valor especificado. Por ejemplo

‘contains’

Retorna registros donde los valores coincidan con el patrón especificado en cualquier lado de la cadena, ya sea al principio o al final. Por ejemplo

‘startsWith’

En esta ocasión sólo retornará los registros que coincidan con el valor especificado solamente al inicio de la cadena

‘endsWith’

En esta ocasión sólo retornará los registros que coincidan con el valor especificado solamente al final de la cadena

‘Intervalo entre Fechas’

Puedes realizar busquedas entre fechas utilizando los operadores de comparación:

Opciones de Consulta

Las opciones de consulta permiten afinar los resultados que se devuelven. Las opciones que tenemos disponibles para llevar a cabo esto son:

• limit  (Limita el número de resultados que son retornados de una consulta)

• skip  (Retorna todos los resultados menos el numero de elementos que especifiquemos para skip)

• sort (Retorna todos lo resultado pero ordenadamente según lo especifiquemos)

Cuidado! A la hora de realizar consultas (querys), ya que Waterline es Case-Sensitivity, es decir, que hace diferencia entre mayúsculas y minúsculas.

Validaciones

Sails soporta las validaciones automáticas para los atributos de nuestros modelos. Cada vez que se crea o actualiza un nuevo registro, se cotejan los datos de los atributos con las reglas de validación predefinidas. Esto proporciona un mecanismo de seguridad para las entradas no válidas a la base de datos de nuestra aplicación.

Reglas de validación

Las validaciones en sails son gestionadas por Anchor y Validator (https://github.com/chriso/validator.js), actualmente son las librerías de validación más robustas para Node.js. Sails soporta la mayoría de las validaciones disponibles en Validator (https://github.com/chriso/validator.js).