Каковы некоторые рекомендации по именованию схем GraphQL?

Question

Я начинаю разработку нетривиального приложения, для которого мы рассматриваем GraphQL. Работая над первоначальным проектом нашей схемы, я немного парализовался, пытаясь установить соглашения об именах, которые будут масштабироваться по мере взросления продукта. Я был бы очень признателен за понимание того, кто должен был разработать схему и столкнуться с ней или успешно избежать тупиков или несоответствий:

1. Является ли вообще полезным / идиоматическим сохранение имени "Интерфейс" в названии интерфейса? Например, будет Profile или же ProfileInterface предпочтительнее в большом приложении?

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

2. Распространено ли указывать значения с одним перечислением как "константы"?

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

3. Лучше всего объявлять все или ничего objectкак scalar или же typeи где проходит линия между ними? Представь себе Point тип, который, как правило, будет представлен в виде массива [x,y]; что было бы более идиомадным?

   scalar Point
   
   type Point {
     x: Float
     y: Float
   }
   

4. Любые другие передовые практики, конкретно связанные с соглашениями об именах или объявлениями типов в GraphQL, которые было бы трудно узнать без опыта.

Заранее спасибо!

---

Этот вопрос не набрал обороты, которые мне бы понравились, поэтому я начну публиковать полезные фрагменты по мере их нахождения, которые могут развиться в своего рода ответ.

Называть типы ввода с помощью Input на конце - это полезное соглашение, потому что вам часто нужно, чтобы и тип ввода, и тип вывода немного отличались для одного концептуального объекта.

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

Answer 1

Я размышлял над этими же вопросами и надеюсь, что это поможет вам.

1. Я не верю, что добавление интерфейса в конце каждого интерфейса является идиоматическим. Гораздо лучше иметь описательное имя. Рассмотрим пример, приведенный в спецификации GraphQL, касающейся интерфейсов. Они не добавляют интерфейс ни к одному из своих типов.

2. Перечисления выгодны только тогда, когда есть несколько связанных значений. Я не вижу, как включение типа полезно, когда есть только одно возможное значение. Значения перечисления также именуются всеми прописными и подчеркивающими знаками в спецификации GraphQL, относящейся к перечислениям.

3. Если вы решили реализовать скалярный тип, то вам нужно проверить поле. В данном конкретном случае предоставление точки в качестве типа наиболее целесообразно, поскольку точка может быть двухмерной или трехмерной. Определение его как типа является более декларативным.

Такие значения, как Date, Email и Url, являются типичными примерами скалярных типов. Они обеспечивают семантическую ценность, и клиенты будут знать, чего ожидать от этих полей.

Вот соответствующий раздел для пользовательских скаляров. Вот пример.

4. Эта статья Ли Байрона будет вам полезна.

Answer 2

Некоторое время назад я нашел это руководство по дизайну API-интерфейса graphql от Shopify. Я думаю, что нет явной главы, но лучшие практики в отношении соглашения об именах распространяются по всему учебнику.