| description |
|---|
Para manter o time de front alinhado quanto as melhores práticas para se lidar com suas tarefas mais habituais e garantir uma das formas de melhorar a estabilidade, qualidade e velocidade de suas entregas. |
Melhores práticas para manipular e tratar dados vindos do back-end com javascript
Essa RFC visa expor as etapas/camadas de tratamento pelas quais um dados vindo de um back-end passam até estarem disponíveis na tela para interação com o usuário.
- 0) Módulo Ajax: único trecho do código front end que conhece as configurações de métodos HTTP
- 1) Front APIs: Único ponto do código front end que conhece as urls de endpoints do back-end
- 2) Adapter: Único ponto do código front end que conhece os nomes das chaves vindas do backend
- 3) Repository: Armazena, adapta, filtra e cacheia os dados assim que eles retornam do backend
- 4) Constants: Nem sempre o back-end precisa trazer todos os dados que o front end vai usar
- 5) Model: Um intermediário capaz de guardar resultados das interações do usuário com a tela
- 6) ViewModel: É vínculo entre o template e o estado da tela
- 7) Tratamento e log de erros
Dados vindos do back end são trafegados e manipulados durante todo o ciclo de vida do front end. Possuir um contrato que especifique as melhores práticas para lidar com esses dados nas diversas fases de seu ciclo de vida torna o desenvolvimento mais ágil e o código mais fácil de manter e estender. Esse RFC define as melhores práticas para tratamento de dados vindos do back end com javascript.
Requisito: o projeto contém uma forma personalizada de fazer suas chamadas HTTP.
Solução: criar uma única classe javascript capaz de restringir essa personalização.
Exemplo de implementação: atualmente na plataforma o AaxModel é a implementação dessa solução. O AaxModel é uma factory angularJS com as configurações utilizadas pelas chamadas do $http.
É -1 em CR se:
- O código javascript faz uma chamada Ajax sem passar pelo Módulo Ajax.
Requisito: o front end precisa conhecer a url dos endpoints que ele acessa.
Solução: criar classes javascript contendo os endereços e as configurações básicas das requisições feitas a essas apis.
É -1 em CR se:
- As api no javascript caracterizam-se por arquivos terminados em
.api.js. - Cada um desses arquivos deve estar associado a módulo angularJS com sufixo
.api.
Para Exemplos de implementação de Front APIs acesse o RFC 004a .
Requisitos:
- O front end não deve depender da gramática utilizada no backend para construir seus objetos
- O front end não deve transformar um dado vindo do back-end duas vezes
Solução: para cada objeto trafegado no front end deve existir apenas um ponto responsável pela adaptação dos dados de back-end para front end.
Dica:
- Normalmente os adapters tem um arquivo isolado mas comumente são mais usados dentro de Repositories.
- Verifique se o objeto que você está tratando tem um Repository antes de criar seu Adapter, se tiver verifique se não faz mais sentido usar seu Adapter dentro desse Repository.
É -1 em CR se:
- A gramática do back-end está trafegando entre Model e ViewModel sem ser adaptada;
- O adapter guarda um dado em uma clojure
- Um novo adapter foi criado quando um adapter antigo já existia
Para Exemplos de implementação de Adapter acesse o RFC 004b .
Requisitos:
- As informações sobre um objeto devem ser consistentes
- Somente um trecho do javascript é responsável por pegar os dados que foram pegos via Front Api (item 1 dessa lista), adaptá-los (item 2), aplicar constants (item 4), cachear as informações.
Solução: para cada objeto trafegado no front end deve existir apenas um ponto responsável por armazenar e cachear os dados vindos do back-end.
É -1 em CR se:
- Um trecho de código usa dados que estão disponíveis no Repository sem passar por esse Repository
- O Repository possui utiliza uma função fora do init para cachear ou manipular os dados do init
- Um trecho do código fora do Repository altera os dados retornados pelo Repository, por exemplo, aplicando um filter sobre esses dados
Para Exemplos de implementação de Repository acesse o RFC 004c .
Requisitos: Eventualmente parte das propriedades de um objeto retornado por um Repository não vem do back-end pois só faz sentido no contexto da aplicação web.
Solução: Criar arquivos de constantes capazes de associar informações adicionais a dados vindos da Front Api e tratados pelo Repository
É -1 em CR se:
- Sua constant não é um objeto cujas propriedades são chaves únicas que se relacionam ao objeto que será associado
- Sua constant não é uma receita do tipo constant
Para Exemplos de implementação de Constants acesse o RFC 004d .
Requisitos: a interação entre os dados que vieram do Repository
Solução: criar models, trechos de código capazes de reagir a (1) interação do usuário com a tela e (2) tratamento de promessas
Curiosidade: A camada do Model é a primeira relacionado ao padrão MVVM, e refere-se diretamente a esse padrão.
É -1 em CR se:
- O model expõe desnecessariamente um dado. Exemplo: um dado que não é acessado pela tela, por exemplo.
Para Exemplos de implementação de Model acesse o RFC 004e .
Requisitos: O HTML de uma rota ou componente deve preferir receber seus dados de um Model
Solução: Criar um ViewModel magro, que preferencialmente só associa um model a uma variável disponível no HTML
Curiosidade: A camada ViewModel como utilizamos é inspirado pelo padrão MVVM.
É -1 em CR se:
- O ViewModel armazena dados não relacionado a tela que espera-se que sejam persistidos durante a navegação
- O escopo do ViewModel é maior do que o escopo do seu Model
- O ViewModel acessa diretamente constants, Repository, Adapter ou Front Api
Para Exemplos de implementação de ViewModel acesse o RFC 004f .
Requisitos: Toda resposta vinda de endpoint do back end pode apresentar um erro. Esse erro pode ser do tipo genérico, como um erro HTTP 500 ou um erro de aplicação com um código interno como USER_WITHOUT_CREDENTIALS código 4011. O front end deve esperar que toda resposta possa trazer um desses erros e reagir a eles de forma a preservar a integridade do fluxo do usuário dentro da aplicação.
Solução: Garantir que toda tarefa front end que consuma um endpoint de back end entenda, log os erros de back e ofereça ao usuário uma saída para continuar seu fluxo na aplicação.
É -1 em CR se:
- Em caso de erro o front não oferece um fluxo alternativo ao usuário que o permita continuar no site nem loga o errro
- Em caso de erro o front não oferece ao usuário um aviso de que o erro ocorreu nem loga o erro
- O front end não trata um erro na resposta de uma promessa que depende de back end
- O front end ignora que o endpoint traz um erro de aplicação e não trata esse erro
- O front end não loga um erro de aplicação vindo do back end
Para Exemplos de implementação de Tratamento e log de erros acesse o RFC 004g .