En un artículo anterior vimos una introducción a GraphQL, ahora vamos a ver como montar un servidor de GraphQL simple. En este ejemplo vamos a usar JavaScript (con Node.js) por simplicidad, pero es importante entender que podemos usar cualquiertecnologíadebackend para crear servidores de GraphQL.
Como en todo proyecto de JavaScript vamos a iniciarlo e instalar dependencias.
npm init --yes
# o con yarn
yarn init --yes
Luego de iniciar el proyecto instalamos las dependencias.
npm i body-parser compression cors express graphql graphql-server-express graphql-subscriptions graphql-tools morgan pg sequelize subscriptions-transport-ws uuid
npm i -D nodemon
# o con yarn
yarn add body-parser compression cors express graphql graphql-server-express graphql-subscriptions graphql-tools morgan pg sequelize subscriptions-transport-ws uuid
yarn add -D nodemon
Vamos a listar todas las dependencias y para explicar que hace cada una:
body-parser => middleware de Express para leer fácilmente el body de peticiones POSTcompression => middleware de Express para comprimir con GZIP nuestras respuestascors => middleware de Express para manejar CORSexpress => librería para crear un servidor HTTP y manejar rutasgraphql => implementación de GraphQL en JavaScriptgraphql-server-express => librería para conectar Express con GraphQLgraphql-subscriptions => librería para activar suscripciones en GraphQL para cosas en tiempo realgraphql-tools => herramientas que nos ayudan a crear servidores de GraphQL más fácilmorgan => middleware de Express para tener logs en consola de nuestras peticionespg => driver de PostgreSQL para usarlo como base de datossequelize => ORM de bases de datos SQL como PostgreSQLsubscriptions-transport-ws => librería para que nuestras suscripciones funcionen mediante WebSocketsuuid => librería para generar ID únicosnodemon => nos va a servir para correr nuestra aplicación en desarrolloComo vemos nuestra aplicación va a usar Express para el servidor HTTP y vamos a usar PG como base de datos.
Vamos a crear la conexión a la base de datos y nuestros modelos, nuestra aplicación va a ser de TODO, entonces vamos a tener un solo modelo, por esa razón vamos a tener todo en un único archivo que vamos a llamar db.js.
// importamos sequelizeconst Sequelize = require('sequelize');
// definimos en constantes nuestras variables de entorno con los datos de conexión de la base de datosconst DB_USER = process.env.DB_USER;
const DB_PASS = process.env.DB_PASS;
const DB_HOST = process.env.DB_HOST;
const DB_NAME = process.env.DB_NAME;
const DB_PORT = process.env.DB_PORT || 5432;
// creamos una nueva conexión de Sequelizeconst sequelize = new Sequelize(DB_NAME, DB_USER, DB_PASS, {
host: DB_HOST,
dialect: 'postgres',
pool: {
max: 5,
min: 0,
idle: 10000,
},
});
// definimos nuestro modelo Todo que va a tener 3 campos// un campo ID que va a ser un UUID// un campo content que va a ser un string// un campo status que puede ser `active`, `completed` y `deleted`const Todo = sequelize.define(
'todo',
{
id: {
type: Sequelize.UUID,
primaryKey: true,
unique: true,
},
content: {
type: Sequelize.STRING,
},
status: {
type: Sequelize.ENUM,
values: ['active', 'completed', 'deleted'],
},
},
{
indexes: [
{
unique: true,
fields: ['id'],
},
],
}
);
// exportamos nuestra conexión a la base de datos y nuestro modelomodule.exports = {
db: sequelize,
Todo,
};
Con eso ya tenemos nuestra conexión a la BD y nuestro modelo. Deben además tener una base de datos PG a la que pueda conectarse, para eso pueden instalar PG en local (o usando Docker) o pueden usar un servicio externo como ElephanSQL que nos provee de una base de datos PostgreSQL as a Service.
Luego de tener nuestra BD, vamos a definir nuestros esquemas de GQL. La forma en la que el cliente va a poder interactuar con nuestra API. Para eso creamos un archivo schema.js con este contenido:
// exportamos un template literal con nuestro esquema, esto podría estar dividido en varias partes// y podríamos luego combinarlos, por simplicidad vamos a usar solo un archivo con todo el esquemamodule.exports = `
# Una tarea pendiente
type Todo {
# El ID único de nuestro TODO
id: String!
# El contenido de nuestro TODO
content: String!
# El estado actual de nuestro TODO
status: String!
}
# Nuestra query principal que define la forma de consumir datos
type Query {
# Obtener un único TODO mediante el ID
todo(id: String!): Todo
# Obtener una lista de todos los TODO
allTodos: [Todo]
# Obtener una lista de los TODO activos
activeTodos: [Todo]
# Obtener una lista de los TODO completados
completedTodos: [Todo]
}
# Nuestras mutaciones que definen como interactuar con los datos
type Mutation {
# Crear un nuevo TODO pasando el contenido
createTodo(
content: String!
): Todo
# Borrar un TODO existente mediante el ID
deleteTodo(
id: String!
): Todo
# Marcar como completo un TODO existente mediante el ID
completeTodo(
id: String!
): Todo
}
# Nuestras suscripciones que definen a que datos suscribirse
type Subscription {
# Suscribirse a los nuevos TODOs creados
todoCreated(
status: String!
): Todo
# Suscribirse a las actualizaciones de un TODO mediante el ID
todoUpdated(
id: String!
): Todo
}
# Nuestro esquema principal que define la query, mutation y subscription
type Schema {
query: Query
mutation: Mutation
subscription: Subscription
}
`;
Ese es nuestro esquema de GQL. Como vemos vamos a utilizar queries, mutaciones y suscripciones en nuestro API, para refrescar que es cada una:
Ahora vamos a definir nuestros resolvers. Básicamente son funciones que se encargan de que cuando un cliente ejecuta una query, se pedan los datos necesarios para esa query. Igualmente con la mutaciones deben encargarse de crear o modificar nuestros datos y responder con lo esperado.
// importamos uuid para crear nuestros ID únicosconst uuid = require('uuid/v4');
// nos traemos nuestro modelo Todoconst { Todo } = require('./db');
// imporatmos el módulo pubsub usado para suscripciones (luego lo creamos)const pubsub = require('./pubsub');
// este objeto contiene todos nuestros resolversconst resolvers = {
// acá definimos como resolver cada query de nuestro esquema
Query: {
// nuestra query de obtener todos los TODOs
allTodos() {
// devolvemos todos los TODOs usando nuestro modeloreturn Todo.findAll();
},
// nuestra query de obtener solo los TODOs activos
activeTodos() {
// buscamos los TODO donde el estado es `active`return Todo.findAll({ where: { status: 'active' } });
},
// nuestra query para obtener solo los TODOs completados
completedTodos() {
// buscamos los TODO donde el estado es `completed`return Todo.findAll({ where: { status: 'completed' }});
},
// nuestra query para obtener un único ID
todo(_, { id }) {
// el segundo parámetro que recibimos es un objeto con los parámetros// que pasamos a nuestra query, en este caso `id`// luego obtenemos un único TODO usando el ID que recibimosreturn Todo.findById(id);
},
},
// acá definimos como resolver cada mutación de nuestro esquema
Mutation: {
// la mutación para crear un nuevo todoasync createTodo(_, { content }) {
// creamos un nuevo TODO usando `uudi` para generar el ID y definiendo status como `active`const todo = await Todo.create({ id: uuid(), content, status: 'active' });
// enviamos el TODO a nuestro PubSub en el canal `todoCreated`
pubsub.publish('todoCreated', todo);
// devolvemos el TODO que creamosreturn todo;
},
// la mutación para borrar un TODOasync deleteTodo(_, { id }) {
// actualizamos el estado a `deleted` en el TODO con el ID que recibimosawait Todo.update({ status: 'deleted' }, { where: { id }});
// obtenemos el TODO que creamos (el ORM no nos devuelve el TODO al hacer update)const todo = await Todo.findById(id);
// enviamos ese TODO a nuestro PubSub en el canal `todoUpdated`
pubsub.publish('todoUpdated', todo);
// devolvemos el TODO que actualizamosreturn todo;
},
// la mutación para completar un TODOasync completeTodo(_, { id }) {
// actualizamos el estado a `completed` en el TODO con el ID que recibimosawait Todo.update({ status: 'completed' }, { where: { id }});
// obtenemos el TODO que creamos (el ORM no nos devuelve el TODO al hacer update)const todo = await Todo.findById(id);
// enviamos ese TODO a nuestro PubSub en el canal `todoUpdated`
pubsub.publish('todoUpdated', todo);
// devolvemos el TODO que actualizamosreturn todo;
},
},
// acá definimos como resolver cada suscripción de nuestro esquema
Subscription: {
// cuando se crea un TODO recibimos ese TODO y lo enviamos a los clientes
todoCreated(todo) { return todo },
// cuando se actualiza un TODO recibimos ese TODO y lo enviamos a los clientes
todoUpdated(todo) { return todo },
},
};
module.exports = resolvers;
Y esos son los resolvers de nuestro API GQL. Como vemos son funciones bastante simples individualmente, hay una parte que todavía no implementamos que es el módulo ./pubsub.js, este módulo nos sirve para nuestra suscripciones y es lo siguiente que vamos a crear.
Este módulo es parte fundamental de las suscripciones. Nos permite tener canales por los cuales podemos enviar mensajes, esos canales llevan como nombre las suscripciones que definimos en nuestro esquema de GQL.
En proyectos del mundo real deberíamos usar algo como Redis o RabbitMQ para que podamos escalar nuestra aplicación horizontalmente (agregar más instancias del servidor) sin preocuparnos de que si un cliente está conectado a la instancia 1 no se entere de mutaciones que ocurran en la instancia 2.
Para nuestro ejemplo vamos a usar graphql-subscriptions que nos da un sistema de PubSub en memoria (solo sirve para una instancia).
const { PubSub } = require('graphql-subscriptions');
module.exports = new PubSub();
Extremadamente simple, importamos PubSub de nuestro módulo, lo instanciamos y exportamos. Luego como vimos en los resolvers usamos pubsub.publish para enviar mensajes desde las mutaciones.
Ahora es momento de combinar todo lo anterior para crear un servidor HTTP para nuestro API GQL.
// importamos la función de crear un servidor del módulo nativo HTTPconst { createServer } = require('http');
// importamos expressconst express = require('express');
// imporatmos los middlewares body-parser, cors, compression y morganconst bodyParser = require('body-parser');
const cors = require('cors');
const compression = require('compression');
const morgan = require('morgan');
// imporatmos nuestro middleware para combinar express con GraphQL y GraphiQL para tener el IDEconst { graphqlExpress, graphiqlExpress } = require('graphql-server-express');
// importamos una de las herramientas que nos provee `graphql-tools`, ya vamos a ver que haceconst { makeExecutableSchema } = require('graphql-tools');
// importamos el manejador de suscripciones de `graphql-subscriptions`const { SubscriptionManager } = require('graphql-subscriptions');
// importamos el servidor de suscripciones que funciona mediante WS// también hay opciones con socket.io por ejemploconst { SubscriptionServer } = require('subscriptions-transport-ws');
// imporatmos nuestro modeloconst { Todo } = require('./db');
// nuestro cliente de Pubsubconst pubsub = require('./pubsub');
// nuestro esquemaconst typeDefs = require('./schema');
// nuestros resolversconst resolvers = require('./resolvers');
// definimos en constantes nuestras variables de entornoconst PORT = process.env.PORT || 3000;
const HOST = process.env.HOST || 'localhost';
const NODE_ENV = process.env.NODE_ENV || 'development';
// creamos una función asíncrona autoejecutable para poder usar Async/Await
(async () => {
try {
// intentamos sincronizar nuestro modelo con la BD// si estamos en desarollo forzamos el sincronizado// borrando los datos viejosawait Todo.sync({ force: NODE_ENV !== 'production' });
} catch (error) {
// si ocurre un error mostramos el error y matamos el procesoconsole.log(error);
process.exit(0);
}
// creamos una aplicación de express y un servidor HTTP apartir de estaconst app = express();
const server = createServer(app);
// usamos 3 los middlewares que importamos
app.use(cors());
app.use(compression());
app.use(morgan('common'));
// combinamos nuestro esquema (`typeDefs`) y nuestros resolvers para crear un schema ejecutableconst schema = makeExecutableSchema({ typeDefs, resolvers });
// creamos nuestro administrador de suscripciones usando nuestro esquema ejecutable// y nuestro módulo de PubSub y definimos como manejar cada suscripciónconst subscriptionManager = new SubscriptionManager({
schema,
pubsub,
setupFunctions: {
// cuando alguien se suscribe a `todoUpdated` solo mandamos las del ID al que se suscribe
todoUpdated(options, args) {
return {
todoUpdated: {
filter: todo => todo.id === args.id,
},
};
},
// cuando alguien se suscribe a `todoCreated` solo enviamos las del status// al que el cliente se suscribe
todoCreated(options, args) {
return {
todoCreated: {
filter: todo => todo.status === args.status,
},
};
},
},
});
// definimos la URL `/graphql` que usa los middlewares `body-parser` y el `graphqlExpress`// usando el esquema ejecutable que creamos
app.use('/graphql', bodyParser.json(), graphqlExpress({ schema }));
// si no estamos en producciónif (NODE_ENV !== 'production') {
// usamos el middleware `graphiqlExpress` para crear la URL `/ide` donde cargamos GraphiQL// este IDE va a consumir datos de la URL `/graphql` que creamos antes y `/subscriptions`
app.use('/ide', graphiqlExpress({
endpointURL: '/graphql',
subscriptionsEndpoint: `ws://${HOST}:${PORT}/subscriptions`,
}));
}
// iniciamos el servidor en el puerto y host que obtuvimos por variables de entorno
server.listen(PORT, HOST, error => {
// creamos el servidor de suscripciones usando el administrador de suscripciones// combinando el servidor HTTTP y definiendo la ruta `/subscriptions`new SubscriptionServer({ subscriptionManager }, { server, path: '/subscriptions' });
// luego mostramos un simple log indicando la URL donde corre el servidorconsole.log('> Server running on http://%s:%d', HOST, PORT)
});
})();
Y ese es nuestro servidor, como vemos es mucha configuración e inicializar todo. Lo bueno es que una vez tenemos esto montado agregar más funcionalidades a nuestro API es solo definir más esquemas y resolvers y listo, este archivo no hay que tocarlo casi nunca.
Ahora vamos a configurar nuestros script del package.json para correr nuestra aplicación en desarrollo y producción.
{
...
"scripts": {
"dev": "NODE_ENV=development nodemon server.js",
"start": "node server.js"
}
...
}
Luego vamos a iniciar el proyecto con el siguiente comando en desarrollo:
npm run dev
# o con yarn
yarn dev
Y en producción con:
npm start
# o con yarn
yarn start
Cuando tratemos de correr el servidor nos va a dar un error ya que no definimos las variables de entorno. Para eso tenemos muchas formas, podríamos definir nuestras variables en el script dev antes de correr nodemon, podemos crear un archivo .env con las variables de entorno y usar el módulo dotenv o usar un archivo now.json con la propiedad env y usar now-env para correrlos en local.
Ya que luego vamos a hacer deploy a Now vamos a usar now-env, para eso lo instalamos con:
npm i now-env
# o con yarn
yarn add now-env
Luego creamos nuestro now.json:
{
"env": {
"NODE_ENV": "production",
"HOST": "localhost",
"PORT": 3000,
"DB_USER": "@db_user",
"DB_PASS": "@db_pass",
"DB_HOST": "@db_host",
"DB_NAME": "@db_name",
"DB_PORT": "@db_port"
}
}
Luego creamos un archivo now-secrets.json que vamos a ignorar en nuestros repositorios en los que vamos a colocar los valores de los secrets de la base de datos, algo similar a esto:
{
"@db_user": "user",
"@db_pass": "pass",
"@db_host": "host",
"@db_name": "name",
"@db_port": "port"
}
Estos deben ser los correctos para su base de datos, ya sea que la hayan instalado en local, usando ElephantSQL o algún otro servicio. Por último, vamos a nuestro código de server.js y agregamos esta línea:
require('now-env').config()
Al principio del código, con eso ya tenemos las variables de entorno configuradas 😃
Ahora sí, si corremos nuestra aplicación con el script que definimos antes va a funcionar todo sin problema.
Al entrar a localhost:3000/ide vamos a ver un GraphiQL conectado a nuestro API, ahí podemos probar nuestro API GQL haciendo queries, mutations o subscriptions, también podemos ver la documentación de nuestra API que se genera automáticamente gracias a los comentarios de nuestro esquema.
Por último para hacer deploy a producción debemos usar now secrets para definir nuestros secrets de producción para la base de datos y luego hacer deploy. Para definir estos secrets es un simple comando.
now secret add db_user my-db-user
now secret add db_pass my-db-pass
now secret add db_host my-db-host
now secret add db_name my-db-name
now secret add db_port my-db-port
Donde deben colocar los datos de acceso a su base de datos de producción. Luego vamos a hacer deploy. Vamos a primero modificar nuestro now.json para agregar el nombre de nuestra aplicación y el alias que vamos a usar.
{
"name": "platzi-now-api",
"alias": "platzi-now-api.now.sh",
"env": {
"NODE_ENV": "production",
"HOST": "localhost",
"PORT": 3000,
"DB_USER": "@db_user",
"DB_PASS": "@db_pass",
"DB_HOST": "@db_host",
"DB_NAME": "@db_name",
"DB_PORT": "@db_port"
}
}
Por último vamos a correr el comando para hacer deploy.
now
Con ese simple comando ya tenemos nuestra aplicación en producción con una URL única, le asignamos un alias para poder compartirlo con el mundo.
now aliasY ahora ya vamos a tener platzi-now-api.now.sh donde nuestra aplicación va a estar funcionando y puede ser consumida por un cliente de GrahpQL como Apollo simplemente haciendo queries, mutaciones o suscribiéndonos.
Parecen muchos pasos los que hay que hacer, pero si revisan es bastante fácil y una vez montado el servidor agregar funcionalidad solo requiere agregar más esquemas y sus respectivos resolvers, eso es todo.
Lo genial entonces es que usando GraphQL los frontend pueden crear nuevas funcionalidades muy fácil, simplemente haciendo queries diferentes y los backend pueden extender el API agregando más esquemas y pensando como escalar y optimizar nuestra aplicación para que no se caiga y funcione rápido.
Una guia pero utilizando netcore?