Rails GraphQL Best Practices

Tests gate implementation — write specs before resolver code (see rspec-best-practices).
DO NOT add a new resolver or mutation without completing the N+1 analysis step below.
DO NOT rely solely on type-level authorization — see Authorization section.

1. SPEC:      Write failing spec (happy path + auth cases + validation error case)
2. TYPE:      Define argument and return types
3. IMPLEMENT: Write resolver or mutation class — delegate logic to a service object
4. N+1 CHECK: Verify every association load goes through a dataloader source
5. AUTH CHECK: Confirm field-level guards on all sensitive fields
6. RUN:       All new specs pass; run full suite before opening PR

# BAD — raw array, no cursor-based pagination
field :orders, [Types::OrderType], null: false

# GOOD — connection type enables cursor pagination
field :orders, Types::OrderType.connection_type, null: false

# BAD — business logic inline in the type
field :summary, String, null: false do
  def resolve
    object.line_items.sum(&:total)  # N+1 risk, logic buried in type
  end
end

# GOOD — resolver object handles logic and receives preloaded data
field :summary, resolver: Resolvers::Orders::SummaryResolver

# BAD — N+1: one query per order
def resolve
  object.user  # called for every order in the list
end

# GOOD — batch loads all users in one query
def resolve
  dataloader.with(Sources::RecordById, User).load(object.user_id)
end

# Type-level only — insufficient when the type is reused elsewhere
class Types::UserType < Types::BaseObject
  guard -> (obj, args, ctx) { ctx[:current_user].admin? }
  field :email, String, null: false
  field :internal_notes, String, null: true  # sensitive — needs its own guard
end

# GOOD — field-level guard on sensitive fields
field :internal_notes, String, null: true do
  guard -> (obj, args, ctx) { ctx[:current_user].admin? }
end

def resolve
  authorize! object, to: :read?, with: OrderPolicy
  # ... resolver logic
end

class AppSchema < GraphQL::Schema
  disable_introspection_entry_points if Rails.env.production?
end

class AppSchema < GraphQL::Schema
  max_depth 10
  max_complexity 300
end

class Types::Mutations::CreateOrderPayload < Types::BaseObject
  field :order, Types::OrderType, null: true
  field :errors, [String], null: false
end

class Mutations::CreateOrder < Mutations::BaseMutation
  argument :product_id, ID, required: true
  argument :quantity, Integer, required: true

  type Types::Mutations::CreateOrderPayload

  def resolve(product_id:, quantity:)
    result = Orders::CreateOrder.call(
      user: context[:current_user],
      product_id: product_id,
      quantity: quantity
    )

    if result.success?
      { order: result.order, errors: [] }
    else
      { order: nil, errors: result.errors }
    end
  rescue ActiveRecord::RecordInvalid => e
    { order: nil, errors: e.record.errors.full_messages }
  end
end

# spec/graphql/mutations/create_order_spec.rb
RSpec.describe "Mutations::CreateOrder", type: :request do
  let(:user)    { create(:user) }
  let(:product) { create(:product, stock: 5) }
  let(:query) do
    <<~GQL
      mutation CreateOrder($productId: ID!, $quantity: Int!) {
        createOrder(input: { productId: $productId, quantity: $quantity }) {
          order { id }
          errors
        }
      }
    GQL
  end

  subject(:result) do
    AppSchema.execute(query, variables: { productId: product.id, quantity: 1 },
                              context: { current_user: user })
  end

  it "creates an order" do
    expect(result.dig("data", "createOrder", "errors")).to be_empty
    expect(result.dig("data", "createOrder", "order", "id")).to be_present
  end
end

class Types::OrderType < Types::BaseObject
  description "A customer order containing one or more line items."

  field :id, ID, null: false, description: "Unique identifier."
  field :status, String, null: false, description: "Current order status: pending, confirmed, shipped, delivered."
  field :total_cents, Integer, null: false, description: "Total order amount in cents."
end