1.0.0

Serverless Backend

Precisa de backend e não quer perder tempo e dinheiro com infra-estrutura?

Agora seu Mini App já pode contar com nossa solução de Backend Serverless.

Na raiz do seu projeto de Mini App execute:

mkdir src/server

Pronto! Seu Mini App agora tem um backend.

Quer mais? Sigamos!

Pré-requisitos

Para ter acesso aos recursos de serverless, você precisará da versão 1.10.0 (ou superior) do ame-app-tools.

Overview

Nossa solução de Backend Serverless permitirá que você integre seu Backend Serverless diretamente ao seu Mini App da forma mais rápida e simples possivel.

Seu Mini App pode ser composto de várias funções serverless implementadas por meio de classes. Por exemplo, para executar a funcao checkout da classe CheckoutBackend, precisamos:

  • Criar o módulo na pasta src/server
// src/server/CheckoutBackend.js
export default class CheckoutBackend {
    async checkout(req) {
        const { param1, param2 } = req.body
        // regra de negocio
    }
}
  • Chamar a função no codigo fonte do Mini App:
const result = Ame.server.exec('CheckoutBackend.checkout', {
  param1: valueForParam1,
  param2: valueForParam2
})

Essa funcionalidade agrega várias vantagens ao desenvolvimento de Mini Apps, dentre as quais destacamos:

  • Economia com contratação de infraestrutura
  • Fácil implementação
  • Fácil integração com frontend
  • Seu código-fonte de backend não é exibido como o código-fonte do frontend
  • Utilização de variaveis de ambiente no backend para ocultar dados que estejam hardcoded no frontend
  • Usuário autenticado no objeto req.user

Configuração

Como mencionado anteriormente, para habilitar o Backend Serverless para seu Mini App, basta criar o diretorio src/server em seu projeto de Mini App.

Nele você poderá adicionar quantos modulos preferir. Cada modulo deve conter uma classe com tantas funções quanto forem necessárias.

Uma vez definido seu modulo serverless, o ame-app-tools se encarregará de criar em nuvem todas as funções nele definidas durante a compilação.

Comandos

env

Adiciona uma ou mais variaveis de ambiente ao seu backend.

Parâmetros disponíveis

  • --prod Cria/atualiza variaveis de ambiente no ambiente de produção.

    Exemplo:

    ame-app-tools env EXTERNAL_PI_URL=https://external.api/base/path --prod

    Variaveis criadas com --prod são acessíveis apenas pelo Mini App publicado.

  • --verbose, -v Exibe logs detalhados do comando env.

    Exemplo:

    ame-app-tools env EXTERNAL_API_URL=https://external.api/base/path --verbose

  • --help, -hExibe ajuda sobre o comando env

    Exemplo:

    ame-app-tools env -h

Para acessar essas variáveis no código-fonte de seu Backend Serverless, basta:

const externalApiUrl = process.env.EXTERNAL_API_URL;

Estrutura de Arquivos

Sua estrutura de arquivos deve ficar semelhante a essa:

.
├── ame.conf.js
└── src
    ├── components
    ├── server
    │   ├── CheckoutService.js
    └── views

Notificação de Confirmação de Pagamento

Após o seu cliente final realizar o pagamento, você pode precisar realizar alguma operação de backoffice. Seu Backend Serverless é capaz de processar a notificação de confirmação desse pagamento bastando implementar um simples módulo: Notification.js.

Não é necessário fornecer url de callback nem qualquer outra configuração adicional, apenas implementar o Notificaton.js e sua função handler.

Esse módulo também deve pertencer ao diretório src/server, conforme ilustrado a seguir:

.
├── ame.conf.js
└── src
    ├── components
    ├── server
    │   ├── CheckoutService.js
    │   ├── Notification.js
    └── views
Exemplos:

  • Implementação de notificação para tratar dados do pagamento devolvidos no customPayload

    const TAG = __filename.split('/').pop();

export default class Notification {
    async handler(req) {
        console.debug(TAG, 'Recebendo notificação');

        const amePaymentObject = req.body;

        const customPayload = payment.attributes.customPayload;
        
        // Objeto fornecido na execução do Ame.startPayment().
        const myData = customPayload.myData;
        
        console.debug("Meus dados devolvidos: ", JSON.stringify(myData));
        
        // Return é opcional. O serverless loga o retorno para fins de debugging.
    }
}

  • Implementação de notificação para repassar a notificação à outras APIs

    import Axios from 'axios';

const TAG = __filename.split('/').pop();

export default class Notification {
    async handler(req) {
        console.debug(TAG, 'Recebendo notificação');

        // Adicionamos EXTERNAL_API_URL através do comando: ame-app-tools env
        const externalApiUrl = process.env.EXTERNAL_API_URL;
    
        const response = await Axios.post(externalApiUrl, req.body);

        console.debug("Notificação enviada à API externa: ", response.status);
        
        // Return é opcional. O serverless loga o retorno para fins de debugging.
    }
}

Mãos à obra...

Exemplo de implementação de um Hello World com backend sem notificação

Através do terminal de seu sistema operacional execute:

$ cd ~/
$ ame-app-tools create hello-world-serverless && cd hello-world-serverless
? Qual o nome do seu mini app? hello-world-serverless
? Qual o título do seu mini app? Hello World Serverless
? Qual o slug do seu mini app? hello.world.serverless
? Qual o nome da sua empresa? Ame

Seu projeto deve ter agora a seguinte estrutura:

.
├── ame.conf.js
└── src
    ├── assets
    │   └── images
    │       └── icon_ame.svg
    └── views
        ├── About.js
        ├── About.jsx
        ├── Home.js
        ├── Home.jsx
        ├── More.js
        └── More.jsx

Inicie o ame-app-tools

ame-app-tools start

Se o ame-app-tools alertar que as bibliotecas ame-miniapp-components e ame-super-app-client estão desatualizadas, atualize suas respectivas versões no arquivo ./ame.conf.js e reexecute o comando anterior.

Abra seu Super App Ame e escaneie o Qr Code que lhe foi exibido no navegador.

Abra um novo terminal e execute:

cd ~/hello-world-serverless

Crie o diretório para os módulos serverless:

mkdir src/server

Crie seu módulo serverless no diretório recém criado

touch src/server/HelloWorldBackend.js

Neste ponto, recomendamos importar o projeto hello-world-serverless na IDE de sua preferencia.

Inclua o código-fonte a seguir em HelloWorldBackend.js:

const TAG = __filename.split('/').pop();

export default class HelloWorldBackend {
    async sayHello(req) {
        console.debug(TAG, `About to say "Hello, ${req.body.message}!"`);
        return { hello: `Hello, ${req.body.message}!` };
    }
}

Neste momento, o terminal a rodar o comando start deverá ter logado o seguinte:

Arquivo ~/hello-world-serverless/src/server/HelloWorldBackend.js alterado.
Salvo 7943ms

A partir deste momento, sua função serverless encontra-se pronta para execução.

Agora, vamos alterar alguns dos arquivos que foram auto-gerados.

Primeiro, abrimos o arquivo src/views/Home.js e vamos substituir todo seu código-fonte por este aqui

import Ame from "ame-super-app-client";
const TAG = __filename.split('/').pop();

export default class Home {
  state = { helloMessage: '' };

  async componentDidMount() {
    try {
      const body = {
        message: 'World'
      }
      const result = await Ame.server.exec('HelloWorldBackend.sayHello', body);
      this.setState({helloMessage: result.hello});
    } catch (e) {
      console.error(TAG, e);
      this.setState({helloMessage: `Ops! Algo saiu errado: ${e.message}`});
    }
  }
}

Por último, abrimos o arquivo src/views/Home.jsx e vamos substituir todo seu código-fonte por este aqui

<Window>
  <View>
    <Illustration height={200} image={require('../assets/images/icon_ame.svg')}/>
    <Header textAlign="center" >{this.state.helloMessage}</Header>
  </View>
</Window>

Pronto, na tela de seu telefone você deverá estar vendo o seguinte:

Hello_Result

Pode ficar melhor. Incluamos variáveis de ambiente no exemplo anterior

Inclua as seguintes variáveis de ambiente. Abra outro terminal para executar os comandos abaixo caso ame-app-tools start ja esteja em execução.

$ ame-app-tools env ENV1='Variavel de ambiente 1'
As variaveis de ambiente foram criadas com sucesso.

$ ame-app-tools env ENV2='Variavel de ambiente 2'
As variaveis de ambiente foram criadas com sucesso.

Altere seu Home.jsx, incluindo o componente Paragraph

<Window>
  <View>
    <Illustration height={200} image={require('../assets/images/icon_ame.svg')}/>
    <Header textAlign="center" >{this.state.helloMessage}</Header>
    <Paragraph textAlign="center" >Env 1: {this.state.envValue1}</Paragraph>
    <Paragraph textAlign="center" >Env 2: {this.state.envValue2}</Paragraph>
  </View>
</Window>

Altere seu HelloWorldBackend.js

const TAG = __filename.split('/').pop();

export default class HelloWorldBackend {
    async sayHello(req) {
        console.debug(TAG, `About to say "Hello, ${req.body.message}!"`);
        return {
            hello: `Hello, ${req.body.message}!`,
            envValue1: process.env.ENV1,
            envValue2: process.env.ENV2,
        };
    }
}

Altere seu Hello.js

import Ame from "ame-super-app-client";
const TAG = __filename.split('/').pop();

export default class Home {
  state = {
    helloMessage: '',
    envValue1: '',
    envValue2: ''
  };

  async componentDidMount() {
    try {
      const body = {
        message: 'World'
      }
      const result = await Ame.server.exec('HelloWorldBackend.sayHello', body);
      const { hello, envValue1, envValue2 } = result;
      this.setState({helloMessage: hello, envValue1, envValue2 });
    } catch (e) {
      console.error(TAG, e);
      this.setState({helloMessage: `Ops! Algo saiu errado: ${e.message}`});
    }
  }
}

Pronto, na tela de seu telefone você deverá estar vendo o seguinte:

Hello_Result