DEV Community: Tayllan

Gerenciando Múltiplos Schemas de GraphQL com Ruby on Rails

Tayllan — Sun, 22 May 2022 12:12:50 +0000

Nesse post quero mostrar uma forma de gerenciar schemas de GraphQL no Ruby on Rails, entretanto, boa parte também poderá ser aplicada a qualquer outra aplicação que use a gem graphql.

Um dos motivos para se separar Schemas GraphQL é quando há recursos que necessitam ser acessados com autenticação e outro sem autenticação. Você também pode ter a necessidade de separar os schemas por aplicação que será fornecida, como a que é entregue a um aplicativo e a entregue a um sistema interno administrativo da aplicação. Assim, seus schemas entregam apenas o que é necessário para a aplicação que irá consumir e também restringe o acesso de recursos internos.

Hands On!

Todo o código fonte pode ser encontrado aqui

Neste exemplo, vamos fazer uma API de um blog, mas para manter a simplicidade, vamos ignorar a parte de autenticação.

Teremos dois schemas.

Schema público que trará a lista de posts e seus respectivos autores.
Schema privado que permitirá cadastrar novos posts.

Após criar a aplicação, instalar a gem graphql e executar o comando rails generate graphql:install, teremos a seguinte estrutura de arquivos.

app
├── controllers
│   ├── application_controller.rb
│   └── graphql_controller.rb
└── graphql
    ├── app_name_schema.rb
    ├── mutations
    │   └── base_mutation.rb
    └── types
        ├── base_argument.rb
        ├── base_connection.rb
        ├── base_edge.rb
        ├── base_enum.rb
        ├── base_field.rb
        ├── base_input_object.rb
        ├── base_interface.rb
        ├── base_object.rb
        ├── base_scalar.rb
        ├── base_union.rb
        ├── mutation_type.rb
        ├── node_type.rb
        └── query_type.rb

O que precisamos é a pasta graphql em namespaces, cada um com suas Queries, Mutations e Types.

Veja como é o schema inicial gerado pelo instalador.

# app/graphql/app_name_schema.rb
class AppNameSchema < GraphQL::Schema
  mutation(Types::MutationType)
  query(Types::QueryType)
end

Um schema é composto basicamente por uma classe que diz quais são as mutations e uma class que define quais são as queries.

Veja como é o controller inicial gerado pelo instalador.

class GraphqlController < ApplicationController
  protect_from_forgery with: :null_session

  def execute
    variables = prepare_variables(params[:variables])
    query = params[:query]
    operation_name = params[:operationName]
    context = {
      # Query context goes here, for example:
      # current_user: current_user,
    }
    result = AppNameSchema.execute(query, variables: variables, context: context, operation_name: operation_name)
    render json: result
  rescue StandardError => e
    raise e unless Rails.env.development?
    handle_error_in_development(e)
  end

private

  # Handle variables in form data, JSON body, or a blank value
  def prepare_variables(variables_param)
    case variables_param
    when String
      if variables_param.present?
        JSON.parse(variables_param) || {}
      else
        {}
      end
    when Hash
      variables_param
    when ActionController::Parameters
      variables_param.to_unsafe_hash # GraphQL-Ruby will validate name and type of incoming variables.
    when nil
      {}
    else
      raise ArgumentError, "Unexpected parameter: #{variables_param}"
    end
  end

  def handle_error_in_development(e)
    logger.error e.message
    logger.error e.backtrace.join("\n")

    render json: { errors: [{ message: e.message, backtrace: e.backtrace }], data: {} }, status: 500
  end
end

Precisaremos definir dois endpoints graphql, um para o schema público e outro para o schema privado.

Mas primeiro, vamos gerar os models que usaremos na aplicação.

rails g model author name
rails g model post title content:text author:references
rails g model email email

O model de email será usado para o público assinar o recebimento de posts por email.

Vamos começar pelo graphql público. Vamos ter 1 query que lista os posts, 1 query que retorna um post pelo ID e uma mutation que cadastra o email na lista de emails.

A pasta do graphql público fica assim.

# app/graphql/public_graphql.rb
class PublicGraphql < GraphQL::Schema
  mutation(Mutations)
  query(Queries)
end

# app/graphql/public_graphql/mutations.rb
class PublicGraphql
  class Mutations < Types::BaseObject
    field :add_email_to_list, mutation: AddEmailToList
  end
end

# app/graphql/public_graphql/queries.rb
class PublicGraphql
  class Queries < Types::BaseObject
    include Posts
    include PostById
  end
end

Acima já descrevi as queries e mutations que teremos, elas ficarão dentro dos namespaces Queries e Mutations.

A seguir, as Queries.

# app/graphql/public_graphql/queries/posts.rb
class PublicGraphql
  class Queries
    module Posts
      extend ActiveSupport::Concern

      included do
        field :posts, [Types::Post], null: false
      end

      def posts
        Post.all
      end
    end
  end
end

# app/graphql/public_graphql/queries/post_by_id.rb
class PublicGraphql
  class Queries
    module PostById
      extend ActiveSupport::Concern

      included do
        field :post_by_id, Types::Post, null: true do
          argument :id, GraphQL::Types::ID, required: true
        end
      end

      def post_by_id(id:)
        Post.find_by(id:)
      end
    end
  end
end

Para que as queries funcionem, precisamos dos types que utilizamos nelas, que é apenas o Post.

# app/graphql/types/post.rb
module Types
  class Post < Types::BaseObject
    field :id, ID, null: false
    field :title, String, null: false
    field :content, String, null: false
    field :author, Types::Author, null: false
  end
end

# app/graphql/types/author.rb
module Types
  class Author < Types::BaseObject
    field :id, ID, null: false
    field :name, String, null: false
  end
end

Note que colocamos os types na pasta raiz Types mesmo. Fiz isso pois precisamos desses tipos no graphql privado também, então aqui fica compartilhado. Caso o tipo seja de uso somente para aquele schema em especifico, você pode criar o tipo dentro do namespace PublicGraphql mesmo.

Já as mutations, movi a classe Mutations::BaseMutation (essa é a que foi gerada automaticamente pela gem) para Types::BaseMutation. Assim a pasta de mutations pode ser excluída.

A mutation AddEmailToList fica assim:

# app/graphql/public_graphql/mutations/add_email_to_list.rb
class PublicGraphql
  class Mutations
    class AddEmailToList < Types::BaseMutation
      argument :email, String, required: true

      field :success, Boolean, null: false

      def resolve(email:)
        { success: !!Email.create(email:) }
      end
    end
  end
end

Para finalizar o Graphql público, falta seu controller. Assim, criamos o PublicGraphqlController

# app/controllers/public_graphql_controller
class PublicGraphqlController < ApplicationController
  def execute
    variables = prepare_variables(params[:variables])
    query = params[:query]
    operation_name = params[:operationName]
    result = PublicGraphql.execute(query, variables:, operation_name:) # here we call the PublicGraphql class
    render json: result
  rescue StandardError => e
    raise e unless Rails.env.development?
    handle_error_in_development(e)
  end

  private

  # same private methods from the generated class
end

Não esqueça de atualizar as rotas

Rails.application.routes.draw do
  post "/graphql", to: "public_graphql#execute"
  # ...
end

O PrivateGraphql podemos seguir o mesmo estilo. Aqui vamos ter a listagem de posts de um autor e o cadastro de posts.

# app/graphql/private_graphql.rb
class PrivateGraphql < GraphQL::Schema
  mutation(Mutations)
  query(Queries)
end

# app/graphql/private_graphql/queries.rb
class PrivateGraphql
  class Queries < Types::BaseObject
    include MyPosts
  end
end

# app/graphql/private_graphql/mutations.rb
class PrivateGraphql
  class Mutations < Types::BaseObject
    field :create_post, mutation: CreatePost
  end
end

# app/graphql/private_graphql/queries/my_posts.rb
class PrivateGraphql
  class Queries
    module MyPosts
      extend ActiveSupport::Concern

      included do
        field :my_posts, [Types::Post], null: false
      end

      def my_posts
        context[:current_author].posts
      end
    end
  end
end

# app/graphql/private_graphql/mutations/create_post.rb
class PrivateGraphql
  class Mutations
    class CreatePost < Types::BaseMutation
      argument :title, String, required: true
      argument :content, String, required: true

      field :post, Types::Post, null: false

      def resolve(title:, content:)
        post = Post.new(title:, content:, author: context[:current_author])
        if post.save
          {post:}
        else
          {}
        end
      end
    end
  end
end

# app/controllers/private_graphql_controller.rb
class PrivateGraphqlController < ApplicationController
  # here you can put an authentication method to protect your private graphql schema
  # before_action :authenticate! 

  def execute
    variables = prepare_variables(params[:variables])
    query = params[:query]
    operation_name = params[:operationName]
    context = { current_author: Author.first } # hardcoding an author just for example
    result = PrivateGraphql.execute(query, variables:, context:, operation_name:)
    render json: result
  rescue StandardError => e
    raise e unless Rails.env.development?
    handle_error_in_development(e)
  end

  private

  # same private methods from the generated class
end

# config/routes.rb
Rails.application.routes.draw do
  # ...
  post "/private_graphql", to: "private_graphql#execute" # added
end

E pronto! Temos os dois schemas bem separados e organizados.
Nossa nova estrutura ficou da seguinte forma.

├── private_graphql
│   ├── mutations
│   │   └── create_post.rb
│   ├── mutations.rb
│   ├── queries
│   │   └── my_posts.rb
│   └── queries.rb
├── private_graphql.rb
├── public_graphql
│   ├── mutations
│   │   └── add_email_to_list.rb
│   ├── mutations.rb
│   ├── queries
│   │   ├── post_by_id.rb
│   │   └── posts.rb
│   └── queries.rb
├── public_graphql.rb
└── types
    ├── author.rb
    ├── base_argument.rb
    ├── base_connection.rb
    ├── base_edge.rb
    ├── base_enum.rb
    ├── base_field.rb
    ├── base_input_object.rb
    ├── base_interface.rb
    ├── base_mutation.rb
    ├── base_object.rb
    ├── base_scalar.rb
    ├── base_union.rb
    ├── mutation_type.rb
    ├── node_type.rb
    ├── post.rb
    └── query_type.rb

Nessa organização fica simples encontrar onde cada operação está e só de bater o olho na pasta você consegue ver tudo o que aquela API expõe.

Vale notar também que separar cada query e cada mutation em um único arquivo também ajuda na hora dos testes, pois eles ficam mais concisos!

O que acha dessa organização? Como você organiza múltiplos schemas graphql? Deixa teu comentário abaixo :) !

Uma API ruby com AWS Lambda e Serverless Framework

Tayllan — Sun, 19 Apr 2020 22:26:35 +0000

O AWS Lambda nos permite que com alguns poucos passos possamos ter uma aplicação no ar, sem ter que configurar ou gerenciar servidores. Além disso, você só paga por tempo de computação, então podemos entregar pequenos serviços com velocidade e baixo custo.

Os principais casos de uso do AWS Lambda são: Processamento de arquivos e streams em tempo real e backend de aplicações web, iot ou mobile.

Quero mostrar como podemos criar uma pequena API em ruby e disponibilizá-la para consumo em poucos minutos e com todo um ambiente robusto e autoescalável para realização de suas tarefas.

O que é o Serverless Framework?

É uma ferramenta Open Source que te ajuda a fazer deploy e configuração de aplicações serverless em várias plataformar diferentes (AWS, GCloud, Azure, etc). Com um simples arquivo de configuração .yml podemos descrever tudo que nossa aplicação precisa.

Vamos ao código!

Iremos desenvolver uma aplicação que você passa como entrada um CEP qualquer e a API retornará o endereço completo.

Aqui utilizarei Ruby 2.7.0 e minha conta da AWS. Dado o nosso uso, nada será cobrado, pois o Lambda tem um nível de uso gratuito.

O nível de uso gratuito do AWS Lambda inclui 1 milhão de solicitações gratuitas por mês e 400.000 GB/segundos de tempo de computação por mês.

Instalando o Serverless Framework

Recomendo que você tenha Node 6 ou maior instalado e o npm, pois facilita a instalação de alguns plugins que o serverless nos fornece.

Feito isso, basta executar o comando npm install -g serverless e estamos prontos.

Criando o projeto

Crie um repositório lambda-ruby-api e então execute bundle init.

Para o nosso projeto, vamos precisar da gem correios-cep, então adicione ela ao Gemfile e execute bundle install

# frozen_string_literal: true

source 'https://rubygems.org'

gem 'correios-cep'

Agora vamos criar nossa função em um arquivo chamado handler.rb

# frozen_string_literal: true

require 'correios-cep'

def handler(event:, context:)
  cep = event['pathParameters']['cep']

  address = Correios::CEP::AddressFinder.get(cep)

  { statusCode: 200, body: JSON.generate(address) }
end

Nossa função recebe o event, que é um JSON que conterá os dados de entrada para o processamento de nossa função. O context contem informações sobre o nome da função, versão, arn, limite de memória, etc. Não utilizaremos o context nessa aplicação.

No corpo do event, iremos receber o cep e então chamaremos o AddressFinder da gem para buscar o endereço que precisamos.

Por fim, retornamos um statusCode 200 para indicar que tudo deu certo e o endereço que foi processado pela gem, em JSON.

Observações!!
Nosso endpoint da api será da forma https://.../cep_aqui
Para acessar isso via lambda, usamos o pathParameters. A nossa key será cep.
Isso será definido nos próximos passos.

Configurando Serverless Framework

Agora precisamos fazer algumas configurações para fazer o deploy da nossa aplicação.

Para que o Serverless possa fazer uso da AWS precisamos criar algumas credenciais para ele usar.

Acesse sua conta da AWS e então acesse Serviços > IAM > Usuários > Adicionar Usuário.
Dê um nome. Eu coloquei serverless-test.
Habilite acesso programático e vá para a aba anexar políticas existentes de forma direta.
Selecione AdministratorAccess e finalize a criação do usuário.
Acesse a página do usuário que você criou, vá em credenciais de segurança.
Clique em criar chave de acesso e guarde essas chaves.

Voltando agora para nosso terminal, basta digitar o seguinte comando para dar permissão de acesso a AWS ao serverless.

serverless config credentials --provider aws --key=key_id --secret=key_secret

Substitua o key_id pela sua chave e key_secret por sua chave secreta.

⚠️ Atenção!
Aqui estamos habilitando acesso máximo a AWS, já que estamos apenas testando isso agiliza nosso processo de entendimento. Entretanto, recomendo que depois você configure um acesso mais específico para o serverless. Veja mais aqui.

serverless.yml

Para que o deploy seja feito, devemos criar um arquivo .yml que define os requisitos da nossa aplicação. O nosso arquivo será o seguinte:

service: ruby-cep # nome da nossa função lambda

provider:
  name: aws # onde vamos fazer o deploy
  runtime: ruby2.7 # linguagem que vamos utilizar

plugins:
  - serverless-ruby-package # plugin para empacotamento de dependencias

package: # o que queremos que seja enviado para o AWS Lambda
  include: # tudo que precisamos para que função funcione
    - handler.rb
    - vendor/**

functions: # podemos definir várias funções em uma configuração só
  api: # vamos definir apenas nosso endpoint api para ceps
    handler: handler.handler # onde está nossa função
    events: # eventos no qual ela será disparada
      - http: # chamando via http
          path: /{cep} # caminho e o parâmetro cep
          method: get
          cors: true # habilita chamada de todas as origens

Sobre o serverless-ruby-package
Precisamos que nossas dependencias sejam enviadas para o Lmabda também, a fim de que possam ser utilizadas. Esse plugin nos ajuda com esse processo removendo todos os arquivos e nos forçando a definir quais queremos que sejam enviados (em package).

Para instalar o plugin basta executar npm i serverless-ruby-package --save

Fazendo o deploy

Temos que fazer uma pequena alteração para que possamos carregar as dependencias da nossa função.

Execute bundle install --standalone --path vendor/bundle
Modifique handler.rb

# frozen_string_literal: true

load 'vendor/bundle/bundler/setup.rb' # adicionado

require 'correios-cep'

def handler(event:)
  cep = event['pathParameters']['cep']

  address = Correios::CEP::AddressFinder.get(cep)

  { statusCode: 200, body: JSON.generate(address) }
end

Agora é só ir no terminal e executar serverless deploy, aguarde alguns minutos e pronto! Você terá um output similar a este.

Serverless: Stack update finished...
Service Information
service: ruby-cep
stage: dev
region: us-east-1
stack: ruby-cep-dev
resources: 11
api keys:
  None
endpoints:
  GET - https://some-id.execute-api.us-east-1.amazonaws.com/dev/
functions:
  api: ruby-cep-dev-api
layers:
  None
Serverless: Run the "serverless" command to setup monitoring, troubleshooting and testing.

Veja que ele já nos deu o endpoint que configuramos! Vamos lá testar se funciona 😄

Copie e cole no seu navegador o caminho com seu CEP para testar.
Exemplo: https://some-id.execute-api.us-east-1.amazonaws.com/dev/00000-000

E aí? Deu certo ⁉️

Atualizando a função

Agora queremos adicionar mais funcionalidades, como retornar diferentes respostas quando recebermos um CEP inválido.

O CEP pode ser inválido tanto por estar escrito em um formato inválido (Ex: 00-0) ou por não existir. Fazemos algumas modificações:

# frozen_string_literal: true

load 'vendor/bundle/bundler/setup.rb'

require 'correios-cep'

def handler(event:, context:)
  cep = event['pathParameters']['cep']

  address = Correios::CEP::AddressFinder.get(cep)

  if address.empty?
    { statusCode: 404 }
  else
    { statusCode: 200, body: JSON.generate(address) }
  end
rescue ArgumentError
  { statusCode: 422 }
end

A gem dos correios faz uma validação no formato do cep, se for inválido ele dispara uma exceção do tipo ArgumentError e nós a capturamos. 😄

404 significa não encontrado
422 significa entidade não processável

Para fazer o deploy rápido dessas modificações basta rodar o comando:

serverless deploy function -f api
Nesse caso api é o nome da função que declaramos dentro da chave functions do nosso serverless.yml

# ...
functions: 
  api: # aqui
    handler: handler.handler 
    events:
      - http: 
          path: /{cep} 
          method: get
          cors: true

Rapidamente a função será atualizada e agora podemos verificar se está tudo ok. Teste um cep inválido e veja as mensagens retornadas.

Exemplos inválidos:
404: https://some-id.execute-api.us-east-1.amazonaws.com/dev/00000-000
422: https://some-id.execute-api.us-east-1.amazonaws.com/dev/0

Conclusão

Com AWS Lambda e Serverless Framework podemos construir e entregar pequenas e úteis aplicações rapidamente. O que mostrei aqui foi só um pequeno exemplo, mas podemos criar aplicações bem grandes para executar nessa infraestrutura e economizar alguns gastos.

Código fonte: https://github.com/mtayllan/lambda-ruby-api