Editer le schéma GQL

18 min

Côté serveur, Apollo Server v4 est utilisé pour gérer la couche GraphQL, tandis qu’Apollo Client v3 est utilisé côté client. La documentation officielle d’Apollo est disponible ici

L'interface Apollo Sandbox, qui permet de visualiser le schéma complet GraphQL et de tester les queries et mutations, est accessible par défaut via l'URL : http://localhost:5500/graphql

Ajouter des types GraphQL

Pour tout ajout au schema GraphQL géré par le serveur, ajoutez vos types, queries ou mutations dans le dossier server/graphql

Dossier de travail :

server/graphql
├─ resolvers/
│   ├─ mutations/
│   ├─ queries/
│   └─ index.mjs
├─ types/
│   ├─ index.mjs
│   ├─ mutation-type.mjs
│   └─ query-type.mjs
└─ index.mjs

Ajouter un type

Ajoutez le fichier de votre type gql dans server/graphql/types

Exemple du type Business fichier business-type.mjs

import { gql } from 'graphql-tag';

export const BusinessType = gql`
  type Business {
    message: String
    isSomething: Boolean
  }
`;

Ajoutez ensuite l'export du fichier depuis server/graphql/types/index.mjs

...
export * from './business-type.mjs';

Enfin ajoutez le type aux typeDefs depuis le fichier server/graphql/index.mjs

export * from './resolvers/index.mjs';
import {
  ...
  BusinessType
} from './types/index.mjs';

export const BusinessTypeDefs = [
  ...
  BusinessType
];

Ajouter un input type

Répétez les mêmes étapes que pour l'ajout d'un type.

Ajoutez le fichier de votre input type gql dans server/graphql/types

Attention de définir votre input type avec input et non type

import { gql } from 'graphql-tag';

export const BusinessInputType = gql`
  input BusinessInputType {
    message: String
    isSomething: Boolean
  }
`;

Ajoutez ensuite l'export du fichier depuis server/graphql/types/index.mjs

...
export * from './business-type.mjs';
export * from './business-input-type.mjs';

Enfin ajoutez l'input type aux typeDefs depuis le fichier server/graphql/index.mjs

export * from './resolvers/index.mjs';
import {
  ...
  BusinessType,
  BusinessInputType,
} from './types/index.mjs';

export const BusinessTypeDefs = [
  ...
  BusinessType,
  BusinessInputType,
];

Ajouter un response type

Répétez les mêmes étapes que pour l'ajout d'un type.

Exemple :

import { gql } from 'graphql-tag';

// an example of response type, implements QueryResponse type defined from `@fasstech/oip-starter-utils`
export const BusinessResponseType = gql`
  type BusinessResponse implements QueryResponse {
    ok: Boolean!
    error: String
    business: Business
  }
`;

Dans cet exemple, le type BusinessResponse implémente le type QueryResponse défini dans le fichier query-type.mjs contenu dans le dossier server de la dépendance @fasstech/oip-starter-utils

Path : @fasstech/oip-starter-utils/server/graphql/types/query-type.mjs

Ajouter une query

Ajoutez le type de la query dans le fichier server/graphql/types/query-type.mjs

Exemple :

import { gql } from 'graphql-tag';

// the query type
export const QueryType = gql `
  extend type Query {
    # add your queries here
    business: BusinessResponse
  }
`;

Ajoutez le fichier du resolver de la query dans le dossier server/graphql/resolvers/queries

Exemple du fichier business-resolver.mjs

import { logger } from '@fasstech/logger';
import { OK } from '@fasstech/oip-starter-utils/server';

// an example of query resolver
export const businessResolver = ({ process, sessionId }) => {
  const { projectId } = process;
  logger.info(`[Resolver][business-exemple] sessionId=${sessionId} projectId=${projectId}`);
  return OK({
    business: {
      message: 'hello world!',
      isSomething: true
    }
  });
};

Exportez le fichier depuis server/graphql/resolvers/queries/index.mjs

...
export * from './business-resolver.mjs';

Enfin, ajoutez le resolver au resolver du type query depuis le fichier server/graphql/resolvers/index.mjs

import { businessResolver } from './queries/index.mjs';

export const businessResolvers = {
  Query: {
    business: (parent, args, context) => businessResolver(context)
  },
  Mutation: {
    ...
  }
};

Ajouter une mutation

Ajoutez le type de la mutation dans le fichier server/graphql/types/mutation-type.mjs

Exemple :

import { gql } from 'graphql-tag';

// the mutation type
export const MutationType = gql`
  extend type Mutation {
    # add your mutations here
    createBusiness(input: BusinessInputType!): BusinessResponse
  }
`;

Ajoutez le fichier du resolver de la query dans le dossier server/graphql/resolvers/mutations

Exemple du fichier create-business-resolver.mjs

import { logger } from '@fasstech/logger';
import { OK } from '@fasstech/oip-starter-utils/server';

// an example of mutation resolver
export const createBusinessResolver = (context, { input }) => {
  const { message, isSomething } = input;
  logger.info(`[Resolver][create-business-exemple] message=${message} isSomething=${isSomething}`);
  return OK({
    business: {
      message,
      isSomething
    }
  });
};

Exportez le fichier depuis server/graphql/resolvers/mutations/index.mjs

...
export * from './create-business-resolver.mjs';

Enfin, ajoutez le resolver au resolver du type mutation depuis le fichier server/graphql/resolvers/index.mjs

import { businessResolver } from './queries/index.mjs';
import { createBusinessResolver } from './mutations/index.mjs';

export const businessResolvers = {
  Query: {
    business: (parent, args, context) => businessResolver(context)
  },
  Mutation: {
    createBusiness: (parent, args, context) => createBusinessResolver(context, args)
  }
};

Côté client

Dossier de travail :

app/
├─ graphql/
│   ├─ fragments/
│   ├─ mutations/
│   ├─ queries/
│   └─ index.js
└─ hooks/
    └─ index.js

Ajouter une query ou une mutation

Les types gql associés doivent être préalablement définis côté server ainsi que la nouvelle query ou mutation

Ajoutez les queries ou mutations dans le dossier app/graphql dans les sous-dossiers queries ou mutations, respectivement.

Exemple d'une query, fichier, fichier business.js

import { gql } from '@apollo/client';

export const BusinessQuery = gql`
  query BusinessQuery {
    business {
      business {
        message
        isSomething
      }
      ok
      error
    }
  }
`;

Exemple d'une mutation, fichier create-business.js

import { gql } from '@apollo/client';

export const CreateBusiness = gql`
  mutation CreateBusiness($input: BusinessInputType!) {
    createBusiness(input: $input) {
      business {
        message
        isSomething
      }
      ok
      error
    }
  }
`;

Ajouter le hook associé

Si la nouvelle query ou mutation doit être utilisée dans les vues, déclarez le hook associé dans le dossier app/hooks

Exemple d'un hook pour une query, fichier use-query-example.hook.js

import { useQuery } from '@apollo/client';
import { BusinessQuery } from '../graphql/index.js';

export const useBusinessQuery = (args) => {
  const { data, error, loading, refetch } = useQuery(BusinessQuery, args);

  return {
    error,
    loading,
    refetch,
    business: data?.business?.business || {}
  };
};

Exemple d'un hook pour une mutation, fichier use-mutation-example.hook.js

import { useCommitMutation } from '@@views/_common/hooks/useCommitMutation';
import { CreateBusiness } from '../graphql/index.js';

export const useCreateCustomerMutation = () => {
  return useCommitMutation(CreateBusiness, { dataProp: 'createBusiness'});
};

Depuis une vue

Importer le hook respectif pour consommer la nouvelle query ou mutation depuis une vue ou un composant d'une vue.

Exemple :

import { 
  useBusinessQuery,
  useCreateCustomerMutation 
} from '@@appHooks';

const MyView = () => {
  // query
  const { business, loading, error } = useBusinessQuery();

  // mutation
  const { 
    onFormSubmit: mutate,
    loading,
    error 
  } = useCreateCustomerMutation();

  // on mutate
  const onMutate = () => {
    mutate({
      message: 'is magic',
      isSomething: true
    }, (ok, error, data) => {
      if (!ok) {
        console.error(error);
        return;
      }
      console.log(data);
    });
  };
  
  return (
    <div>
      ...
    
      <div>
        <p>Business:</p>
        <pre>{JSON.stringify(business, null, 2)}</pre>
      </div>
      
      <button onClick={onMutate}>MUTATE</button>
    </div>
  );
};

export default MyView;

Depuis un handler personnalisé

Veuillez vous référer à la documentation sur les handlers personnalisés pour exécuter une nouvelle query ou une mutation depuis un handler personnalisé.