Production Ready GraphQL

GraphQL Schema Design

Design First

早い段階からDesign Firstのアプローチを取る
- 実装を急いだり、どういったライブラリを使うかといったことを優先して設計を怠らない
- スキーマがあってのAPIとなるので否が応でも設計をせざるを得ないと思っている

Client First

バックエンドの観点ではなく、クライアントのユースケースをベースに設計する
- Usecase-based APIということでいいのだろうか？
- graphql-rubyだとActiveRecordありきで使っているのでResource-based APIになりやすいと感じている
- Resource-basedで設計する方が良いという考えの人もいる
  - TypeをResource、QueryをUsecaseとして捉える
  - Query 1フィールドを見たとき、Resource-basedなことが多い気がしている
    - 複数フィールドを組み合わせた結果がUsecaseというのはその通りだと思う
  - GitHub APIのスキーマにおいて、Queryのフィールド定義は割とResource-basedな気がしている
    - Public APIという都合上、仕方ないのかもしれない
- https://scrapbox.io/koushisa/Resource-based_APIとUsecase-based_APIの勘所
より良い設計にするためにAPIを利用するクライアントへ共有して実際に使ってもらう
- GraphQLでモックサーバは作成しやすいのか気になった
- ハードコーディングでデータを返すというアプローチもできなくはない
API設計にもYAGNIは役に立つ
- 必要なデータだけを返すことでパフォーマンスの低下やセキュリティリスクを抑えることができるはず

Naming

The names are the API talking back to you, so listen to them

命名に一貫性を持たせる
クライアントはAPIを理解するために時間を要する
一貫性のないスキーマ例
- Query: find がついているフィールドとついていないフィールドが混在している
- Mutation: 新規作成を表現する命名に add と create が使用されている

type Query {
  products(ids: [ID!]): [Product!]!
  findPosts(ids: [ID!]): [Post!]!
}

type Mutation {
  addProduct(input: AddProductInput): AddProductPayload
  createPost(input: CreatePostInput): CreatePostPayload
}

APIに対称性を持たせる
- Mutation.publishPost を定義しているのであれば Mutation.unpublishPost も定義されるべき
- 驚き最小の原則
汎用的な命名を避ける
- ありがちな User や Event
- 抽象的な命名がtypeを表現している場合、interfaceとして定義できないか検討するといいかもしれないと思った

Expressive Schemas

複数のフィールドでprefixが付与されている場合は新しいtypeを定義する機会かもしれない

# creditCardというprefixが複数のフィールドで定義されている
type Payment {
  creditCardNumber: CreditCardNumber
  creditCardExpiration: CreditCardExpiration
  giftCardCode: String
}

# creditCardXxxを別のtypeに切り出した場合 (p.39)
type Payment {
  creditCard: CreditCard
  giftCardCode: String
}

type CreditCard {
  number: CreditCardNumber!
  expiration: CreditCardExpiration!
}

p.39の Payment はフィールドが全てnullableだが、これについては実装でチェックしようということなのだろうか
- unionを使った表現もできなくはないと思うが過剰な設計になりそう？

union Payment = CreditCard | GiftCardCode

type CreditCard {
  number: CreditCardNumber!
  expiration: CreditCardExpiration!
}

type GiftCardCode {
  code: String!
}