Diseñando APIs GraphQL Robustas con Directivas Personalizadas: Más Allá de lo Básico

Las APIs GraphQL nos ofrecen una flexibilidad increíble para consultar datos, pero a veces necesitamos ir más allá de los tipos y campos estándar. Aquí es donde entran en juego las directivas personalizadas, una herramienta poderosa para extender la funcionalidad de tu esquema GraphQL y añadir lógica de negocio directamente en la definición de tu API.

En este tutorial, aprenderás qué son las directivas, por qué son útiles y cómo puedes crearlas e implementarlas para resolver problemas comunes como la validación de entrada, la autorización y la transformación de datos.

📌 ¿Qué Son las Directivas GraphQL?

En GraphQL, una directiva es un modificador que puede adjuntarse a campos, fragmentos, tipos o incluso argumentos para alterar su comportamiento o añadir metadatos. El estándar GraphQL define algunas directivas incorporadas (@skip, @include, @deprecated), pero lo realmente potente es la capacidad de definir tus propias directivas personalizadas.

Piensa en ellas como atributos o decoradores que añades a tu esquema para indicar que ciertas partes deben comportarse de una manera específica en tiempo de ejecución. Esto permite desacoplar la lógica de presentación del esquema, haciendo tu API más declarativa y fácil de entender.

¿Por qué Usar Directivas Personalizadas? 🤔

Las directivas personalizadas te abren un mundo de posibilidades. Aquí te dejo algunas razones clave para utilizarlas:

• Validación de Entrada: Define reglas de validación directamente en tu esquema (ej. @validate(min: 0, max: 100)).
• Autorización: Controla quién puede acceder a qué campos o tipos (ej. @auth(roles: [ADMIN, EDITOR])).
• Transformación de Datos: Modifica los datos antes de que sean devueltos al cliente (ej. @uppercase, @formatDate).
• Formato y Localización: Adapta la salida según las preferencias del cliente.
• Caching: Indica qué campos o tipos pueden ser cacheados y por cuánto tiempo.
• Auditoría y Logging: Marca campos para registrar su acceso.
• Manejo de Errores: Define cómo deben manejarse ciertos errores.

🛠️ Anatomía de una Directiva GraphQL

Una directiva se define en el lenguaje de definición de esquemas (SDL) de GraphQL y luego se implementa en el código de tu servidor.

1. Definición SDL

La definición SDL de una directiva se parece a un tipo, pero comienza con directive @:

directive @myDirective(arg1: String, arg2: Int!) on FIELD_DEFINITION | ARGUMENT_DEFINITION

Analicemos sus partes:

• directive @myDirective: Define una nueva directiva llamada myDirective.
• (arg1: String, arg2: Int!): La directiva puede aceptar argumentos, igual que los campos. Esto permite configurarla dinámicamente.
• on FIELD_DEFINITION | ARGUMENT_DEFINITION: Esto es crucial. Indica las ubicaciones donde la directiva puede ser aplicada. Algunas ubicaciones comunes son:
  • SCHEMA: Para el esquema completo.
  • SCALAR, OBJECT, FIELD_DEFINITION, ARGUMENT_DEFINITION, INTERFACE, UNION, ENUM, ENUM_VALUE, INPUT_OBJECT, INPUT_FIELD_DEFINITION: Para diferentes partes del esquema.
  • FRAGMENT_DEFINITION, FRAGMENT_SPREAD, INLINE_FRAGMENT: Para el lado de la consulta.

2. Implementación en el Servidor

La definición SDL solo indica la existencia de la directiva. La lógica de lo que hace la directiva debe ser implementada en el servidor GraphQL. La forma de hacerlo varía ligeramente según el framework que uses (Apollo Server, GraphQL.js directamente, etc.).

Generalmente, implica:

1. Parsear el esquema: El servidor carga el esquema que incluye tus directivas.
2. Transformar el esquema: Un SchemaTransformer o SchemaVisitor (en librerías como @graphql-tools/schema) recorre el esquema buscando las directivas aplicadas.
3. Aplicar lógica: Cuando encuentra una directiva, envuelve el resolver del campo afectado (o realiza otra acción) con la lógica definida por la directiva.

🚀 Ejemplos Prácticos de Directivas Personalizadas

Veamos cómo implementar algunas directivas comunes.

Ejemplo 1: Directiva de Autorización @auth

Esta directiva es fundamental para controlar el acceso a los datos. Permitirá especificar qué roles son necesarios para acceder a un campo o tipo.

1. Definición SDL

enum Role {
  ADMIN
  EDITOR
  VIEWER
}

directive @auth(roles: [Role!] = []) on FIELD_DEFINITION | OBJECT

• Definimos un enum Role para nuestros posibles roles.
• La directiva @auth acepta una lista de roles.
• Puede aplicarse a FIELD_DEFINITION (un campo específico) o a OBJECT (todos los campos de un tipo).

2. Implementación (con @graphql-tools/schema)

Vamos a usar la librería @graphql-tools/schema, que es muy común para manipular esquemas GraphQL.

// server.js
const { makeExecutableSchema, mapSchema, get</code></pre><code>Directive, MapperKind } = require('@graphql-tools/schema');
const { ApolloServer } = require('apollo-server');

// Suponemos que tenemos un contexto que contiene el usuario actual y sus roles
const getUser = (token) => { /* ... lógica para obtener usuario y roles ... */ return { id: '1', name: 'John Doe', roles: ['EDITOR'] }; };

function authDirectiveTransformer(schema, directiveName) {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
      const authDirective = getDirective(schema, fieldConfig, directiveName)?.[0];

      if (authDirective) {
        const { roles } = authDirective;
        const { resolve = defaultFieldResolver } = fieldConfig;

        fieldConfig.resolve = async (source, args, context, info) => {
          const user = context.user; // Obtenido del contexto de Apollo Server

          if (!user || !user.roles) {
            throw new Error('No autenticado.');
          }

          const hasPermission = roles.some(role => user.roles.includes(role));

          if (!hasPermission) {
            throw new Error(`Acceso denegado. Se requiere uno de los roles: ${roles.join(', ')}.`);
          }

          return resolve(source, args, context, info);
        };
      }
      return fieldConfig;
    },
  });
}

const typeDefs = `
  enum Role {
    ADMIN
    EDITOR
    VIEWER
  }

  directive @auth(roles: [Role!] = []) on FIELD_DEFINITION | OBJECT

  type User {
    id: ID!
    name: String!
    email: String! @auth(roles: [ADMIN, EDITOR]) # Solo admins y editores pueden ver el email
    role: Role!
  }

  type Query {
    me: User @auth(roles: [VIEWER, EDITOR, ADMIN])
    allUsers: [User] @auth(roles: [ADMIN]) # Solo admins pueden ver todos los usuarios
  }
`;

const resolvers = {
  Query: {
    me: (parent, args, context) => {
      // Aquí devolverías el usuario actual del contexto
      return context.user;
    },
    allUsers: () => [
      { id: '1', name: 'John Doe', email: 'john@example.com', role: 'EDITOR' },
      { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'ADMIN' },
    ],
  },
  User: {
    // Los resolvers para campos individuales aquí si son complejos
    // Por ejemplo, si email fuera un campo computado o tuviera lógica especial
  }
};

let schema = makeExecutableSchema({ typeDefs, resolvers });
schema = authDirectiveTransformer(schema, 'auth');

const server = new ApolloServer({
  schema,
  context: ({ req }) => {
    // Aquí obtendrías el token del encabezado Authorization y lo verificarías
    const token = req.headers.authorization || '';
    const user = getUser(token); // Simulación de obtención de usuario
    return { user };
  },
});

server.listen().then(({ url }) => {
  console.log(`🚀 Servidor listo en ${url}`);
});

Explicación del código:

1. authDirectiveTransformer: Esta función toma el esquema y el nombre de la directiva.
2. mapSchema: Es una utilidad de @graphql-tools/schema que permite recorrer cada parte del esquema y aplicar transformaciones. Usamos MapperKind.OBJECT_FIELD para actuar sobre cada campo de objeto.
3. getDirective: Nos ayuda a extraer los argumentos de la directiva @auth que se aplicó a un campo.
4. fieldConfig.resolve: Si el campo tiene la directiva @auth, envolvemos su resolver original con nuestra lógica de autenticación. Antes de llamar al resolver original, verificamos los roles del usuario en el context. Si no tiene los roles requeridos, lanzamos un error.
5. context de Apollo Server: El contexto es donde pasamos información de la solicitud (como el usuario autenticado) a los resolvers.

Ejemplo 2: Directiva de Formato @formatDate

Esta directiva transformará un campo Date en una cadena formateada.

1. Definición SDL

directive @formatDate(format: String = "YYYY-MM-DD") on FIELD_DEFINITION

scalar Date

type Post {
  id: ID!
  title: String!
  createdAt: Date! @formatDate(format: "DD/MM/YYYY HH:mm")
  updatedAt: Date! @formatDate
}

type Query {
  post(id: ID!): Post
}

• La directiva @formatDate acepta un argumento format (con un valor predeterminado).
• Puede aplicarse a FIELD_DEFINITION.
• Hemos definido un scalar Date (que necesitará su propio parser y serializer).

2. Implementación

Para esta implementación, necesitamos un scalar Date personalizado y un transformer de directivas. Usaremos moment.js para el formateo.

// server.js (continuación o un nuevo archivo)
const { GraphQLScalarType, Kind, defaultFieldResolver } = require('graphql');
const moment = require('moment');
// ... imports de @graphql-tools/schema y ApolloServer

const dateScalar = new GraphQLScalarType({
  name: 'Date',
  description: 'Date custom scalar type',
  serialize(value) {
    return value.toISOString(); // Valor de salida al cliente (ISO string)
  },
  parseValue(value) {
    return new Date(value); // Valor de entrada de variables
  },
  parseLiteral(ast) {
    if (ast.kind === Kind.STRING) {
      return new Date(ast.value); // Valor de entrada en la consulta (literal)
    }
    return null;
  },
});

function formatDateDirectiveTransformer(schema, directiveName) {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
      const formatDateDirective = getDirective(schema, fieldConfig, directiveName)?.[0];

      if (formatDateDirective) {
        const { format } = formatDateDirective;
        const { resolve = defaultFieldResolver } = fieldConfig;

        fieldConfig.resolve = async (source, args, context, info) => {
          const result = await resolve(source, args, context, info);
          if (result instanceof Date) {
            return moment(result).format(format);
          }
          return result;
        };
      }
      return fieldConfig;
    },
  });
}

const typeDefs2 = `
  directive @formatDate(format: String = "YYYY-MM-DD") on FIELD_DEFINITION

  scalar Date

  type Post {
    id: ID!
    title: String!
    createdAt: Date! @formatDate(format: "DD/MM/YYYY HH:mm")
    updatedAt: Date! @formatDate
  }

  type Query {
    post(id: ID!): Post
  }
`;

const resolvers2 = {
  Date: dateScalar,
  Query: {
    post: (parent, { id }) => {
      // Suponemos que obtenemos esto de una DB o servicio
      return {
        id: id,
        title: `Post ${id}`,
        createdAt: new Date(),
        updatedAt: new Date(Date.now() - 3600 * 1000) // Hace una hora
      };
    },
  },
};

let schema2 = makeExecutableSchema({ typeDefs: typeDefs2, resolvers: resolvers2 });
schema2 = formatDateDirectiveTransformer(schema2, 'formatDate');

// Para ejecutar este, necesitarías un nuevo ApolloServer o integrarlo con el anterior
// const server2 = new ApolloServer({ schema: schema2 });
// server2.listen().then(({ url }) => { console.log(`🚀 Servidor de posts listo en ${url}`); });

Explicación del código:

1. dateScalar: Implementamos un scalar Date que serializa y deserializa las fechas correctamente.
2. formatDateDirectiveTransformer: Similar al anterior, pero esta vez, después de que el resolver original obtiene el valor (que esperamos sea un objeto Date), lo transformamos usando moment().format(format).

💡 Consideraciones al Usar Directivas

Aunque las directivas son potentes, su uso debe ser considerado cuidadosamente para no complicar en exceso tu esquema.

Pros y Contras

Cuándo Usar y Cuándo No Usar

Pruebas de Directivas

Probar tus directivas es crucial. Puedes hacerlo de varias maneras:

1. Pruebas unitarias para la lógica de la directiva por separado.
2. Pruebas de integración simulando un servidor GraphQL completo y ejecutando consultas que deberían activar la directiva (ej. una consulta autorizada vs. una no autorizada).

🌐 Alternativas y Enfoques Complementarios

Las directivas no son la única forma de añadir lógica a tu API GraphQL. A menudo se complementan o se comparan con:

• Middlewares de Resolvers: Funciones que envuelven tus resolvers para añadir lógica antes o después. En muchos sentidos, las directivas son una forma más declarativa de implementar middlewares específicos.
• Validación en la Capa de Servicio: La lógica de validación compleja y específica del dominio a menudo reside mejor en la capa de servicio detrás de tus resolvers, en lugar de en directivas.
• Esquemas Separados (Schema Stitching/Federation): Para arquitecturas más grandes, dividir tu esquema en microservicios y usar federación puede ser una alternativa a directivas muy complejas que intentan manejar lógica global.

Conclusión ✨

Las directivas personalizadas son una característica muy potente de GraphQL que te permite extender la expresividad y funcionalidad de tu esquema de una manera declarativa y reutilizable. Hemos explorado cómo definirlas en SDL e implementarlas en el servidor usando @graphql-tools/schema para casos de uso como la autorización y el formateo de datos.

Dominar las directivas te permitirá construir APIs GraphQL más robustas, seguras y fáciles de mantener, moviendo la lógica transversal del código imperativo a la definición declarativa de tu esquema. ¡Experimenta con ellas y descubre cómo pueden transformar tu forma de construir APIs GraphQL!