web-dev-qa-db-fra.com

Quelles sont les meilleures pratiques de dénomination des schémas GraphQL?

Je commence le développement d'une application non triviale pour laquelle nous envisageons GraphQL. Lorsque je travaille sur la version initiale de notre schéma, je suis devenu un peu paralysé en essayant d'établir des conventions de dénomination qui évolueront à mesure que le produit mûrit. J'apprécierais vraiment les idées de quiconque a dû développer un schéma et se heurter à, ou a réussi à éviter les impasses ou les incohérences:

  1. Est-il généralement utile/idiomatique de conserver le nom "Interface" dans le nom d'une interface? Par exemple, Profile ou ProfileInterface serait-il préférable dans une grande application?

    interface ProfileInterface {
  # fields here...
}

type UserProfile implements ProfileInterface {
  # implemented fields here...
}

  2. Est-il courant de spécifier des valeurs à énumération unique en tant que "constantes"?

    enum GeoJSONFeatureTypeConstant {
  feature
}

interface GeoJSONFeatureInterface {
  id: ID
  type: GeoJSONFeatureTypeConstant!
  geometry: GeoJSONGeometryInterface!
  properties: GeoJSONProperties
}

  3. Est-il recommandé de déclarer tout ou rien objects comme scalar ou type, et où est la ligne tracée entre les deux? Imaginez un type Point qui serait généralement représenté sous la forme d'un tableau [x,y]; qui serait plus idiomadique?

    scalar Point

type Point {
  x: Float
  y: Float
}
  4. Toute autre meilleure pratique spécifiquement liée aux conventions de dénomination ou aux déclarations de type dans GraphQL qui serait difficile à connaître sans expérience.

Merci d'avance!

Cette question n'a pas pris l'élan que j'aurais souhaité, donc je vais commencer à publier des extraits utiles au fur et à mesure que je les trouve, qui peuvent évoluer en une sorte de réponse.

Nommer les types d'entrée avec Input à la fin est une convention utile, car vous souhaiterez souvent à la fois un type d'entrée et un type de sortie légèrement différents pour un seul objet conceptuel.

http://graphql.org/graphql-js/mutations-and-input-types/

reactjsschemagraphqlidioms
29
Mike Marcacci

J'ai réfléchi à ces mêmes questions et j'espère que cela vous sera utile.

1. Je ne pense pas que l'ajout d'une interface à la fin de chaque interface soit idiomatique. Il vaut mieux avoir un nom descriptif à la place. Prenons l'exemple fourni dans la spécification GraphQL relative aux interfaces. Ils n'ajoutent Interface à aucun de leurs types.

2. Les énumérations ne sont avantageuses que lorsqu'il existe plusieurs valeurs liées. Je ne vois pas en quoi l'inclusion de type est utile lorsqu'il n'y a qu'une seule valeur possible. Les valeurs d'énumération sont également nommées avec toutes les majuscules et les traits de soulignement selon la spécification GraphQL relative aux énumérations.

3. Si vous avez décidé d'implémenter un type scalaire, c'est à vous de valider le champ. Dans ce cas spécifique, fournir Point en tant que type a plus de sens, car un Point pourrait être 2D ou 3D. Le définir comme type est plus déclaratif.

Des valeurs telles que la date, l'e-mail et l'URL sont des exemples courants de types scalaires. Ils apportent une valeur sémantique et les clients sauront à quoi s'attendre de ces domaines.

Voici la section appropriée pour les scalaires personnalisés. Voici un exemple .

4. Vous trouverez utile l'article this de Lee Byron.

11
user3902496