apollographql/graphql-schema

Que fait graphql-schema ?

Guide pour la conception de schémas GraphQL suivant les meilleures pratiques de l'industrie. Utilisez cette compétence lorsque : (1) vous concevez un nouveau schéma ou une API GraphQL, (2) vous examinez un schéma existant pour des améliorations, (3) vous décidez des structures de types ou de la nullabilité, (4) vous implémentez des motifs de pagination ou de gestion d'erreurs, (5) vous assurez la sécurité dans la conception du schéma.

Principes de base

• Utilisez des noms de types en PascalCase et des noms de champs en camelCase.
• Privilégiez les types scalaires personnalisés (DateTime, JSON, URL) pour la clarté.
• Évitez les types String génériques ; utilisez des énumérations ou des scalaires spécifiques lorsque c'est possible.

Nullabilité

• Par défaut, les champs doivent être non-nullables (!) dans le retour de requête pour éviter des surprises.
• Utilisez la nullabilité (String, Int) uniquement lorsque l'absence de donnée a une signification métier.
• Pour les listes, préférez [Type]! (liste non-nullable, éléments nullables) à [Type!]! (liste et éléments non-nullables) si les éléments peuvent manquer.

Pagination

• Implémentez la pagination basée sur des curseurs selon la spécification Relay Connection.
• Utilisez les types Connection et Edge pour chaque association paginée.
• Exemple :

type Query {
  users(first: Int, after: String): UserConnection
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  cursor: String!
  node: User!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Gestion d'erreurs

• Utilisez un type Error unifié avec un champ message et code, et intégrez-le dans vos résultats via des unions.
• Exemple :

union UserResult = User | UserNotFoundError | UnauthorizedError

type UserNotFoundError {
  message: String!
  code: String!
}

type UnauthorizedError {
  message: String!
  code: String!
}

Sécurité

• Appliquez des validations d'entrée et d'autorisation au niveau des résolveurs.
• Limitez la profondeur des requêtes et la taille des réponses.
• Utilisez des directives personnalisées pour la gestion des permissions (ex. @auth, @rateLimit).

Types et interfaces

• Préférez les interfaces pour les objets partageant des champs communs, et les unions pour des types complètement différents.
• Exemple d'interface :

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
  email: String!
}

Directives recommandées

• @deprecated(reason: String!) pour marquer des champs obsolètes.
• @specifiedBy(url: String!) pour les scalaires personnalisés.
• Évitez les directives propriétaires non documentées.

Ressources supplémentaires

• Documentation Apollo sur la conception de schémas
• Spécification GraphQL
• Relay Connection Specification