AZUPCKTS - Framework

A framework foi feita para facilitar o desenvolvimento de api e app console encapsulando implementações genéricas entre projetos para facilitar e agilizar o desenvolvimento, dentre várias está o processo de criação de rotas e injeções de conexão microserviços e outros. Há necessidade de iniciar o projeto seguindo os padrões de estrutura a partir do banco de dados.

Instalação

Instale azu-pck-ts e azu-pck-ts-cli com npm.

  npm install azu-pck-ts
  npm install azu-pck-ts-cli -g

Iniciando uma Aplicação

Use o comando abaixo para inicializar uma aplicação API/APP usando a cli.

Importante: A pasta do projeto deve estar vazia!

  azupckts tsi -api ou -app

Estrutura e Gerenciamento

A framework usa um conceito de gerenciamento usando o seguinte caminho operacional Service/Controller, ou seja, o acesso a aplicação se da pelo Service onde os dados podem sofrer mudanças ou validações (vide documentação posterior) e em seguinda vai para o Controller onde há o processamento dos dados.

Os dados sao gerenciados usando uma estrutura de entidade onde delas o dado é encaminhado para o banco de dados. Todas as tabelas do banco de dados devem ser mapeadas para entidades (vide documentação posterior) e estas entidades são responsáveis pelo gerenciamento do dado e envio para o banco.

Estrutura de Pastas

• src;

  • class;

    Pasta que armazena a estrutura das entidades do projeto.

  • controller;

    Pasta que armazena a estrutura dos controladores das rotas de processamento.

  • service;

    Pasta que armazena a estrutura dos serviços das rotas de processamento.

  • shared;

    Pasta contendo as estruturas para definição de eventos, biblioteca genérica do aplicativo e definção do arquivo de configuração.

  • sql;

    Pasta que armazena a estrutura de sql usado no projeto, desta forma o sql de banco de dados não fica misturado com código fonte.

Arquivo de configuração.

O arquivo de configuração do projeto são app.json e app.prod.json, o app.json deve conter apenas implementações que são para o uso em ambiente de desenvolvimento e o app.prod.json deve-se conter dados para o ambiente de produção;

Identificação do projeto.

Contem os dados da identifiação do projeto.

• name: Nome do projeto (Não conter espaços).
• description: Uma breve descrição do objetivo do projeto.
• version: Número da versão do projeto (Usar o padrão .<Subversão>.).

  "project": {
    "name": "projeto_teste",
    "description": "Projeto de Teste",
    "version": "1.0.0"
  }

Debugar SQL.

Contem a definição se visualiza os sql que estão sendo executados.

• viewsql: Exibe ou não os sql que estão executados, valores: (true/false).

  "debug": {
    "viewsql": false
  }

Gerar log no console.

Contem a definição se visualiza (true) ou não (false) os logs de execuções para o log do console.

• log: Exibe ou não os logs das execuções, valores: (true/false).

  "applicationlog": {
    "log": false
  }

Definição de acesso a banco de dados mongoDB.

Contem a definição dos acessos a banco de dados MongoDB.

• active: Ativar ou desativar a conexão, valores: (true/false).
• name: Nome da conexão (Não usar espaço), este nome é usado no método getMongodbConnection para obter a conexão.
• main: Ativar a injeção da conexão no canal principal de conexão, ou seja, não há necessidade de informar o nome da conexão no método getMongodbConnection, valores: (true/false).
• user: Usuário de acesso do banco de dados MongoDB.
• password: Senha de acesso do banco de dados MongoDB.
• host: Servidor do banco de dados MongoDB.
• port: Porta do banco de dados MongoDB.
• database: Nome do banco de dados MongoDB.
• autoinject: Ativa a alto injeção da conexão na rota, valores: (true/false).
• fieldscontrol: Ativa o gerenciamento dos campos de controle, valores: (true/false).

  "mongodatabase": [
    {
      "active": false,
      "name": "<name>",
      "main": true,
      "user": "<user>",
      "password": "<password>",
      "host": "<ip>",
      "port": 27017,
      "database": "<database>",
      "autoinject": true,
      "fieldscontrol": true
    }
  ]

Definição de acesso a banco de dados.

_Contem a definição dos acessos aos bancos de dados MySQL, Oracle, MSSQL, Firebird, PostgresSQL.

• driver: Driver de conexão do banco de dados, valores: (mysql/oracle/mssql/postgres/firebird).
• main: Ativar a injeção da conexão no canal principal de conexão, ou seja, não há necessidade de informar o nome da conexão no método getConnection, valores: (true/false).
• keydefinition: _Definição da chave primária das tabelas, padrão: {table}id;
• keygenerate: Ativa a gerção de um novo id usando a própria framework, por padrão usar a geração usando o próprio banco de dados, nos bancos que suportam autoincrement ou usando triggers nos que não suportam, valores: (true/false).
• keygeneratecommand: Comando para geração de id usado somente quando o parâmetro keygenerate = true.
• active: Ativa a conexão, valores: (true/false).
• autoinject: Ativa a alto injeção da conexão na rota, valores: (true/false).
• fieldscontrol: Ativa o gerenciamento dos campos de controle, valores: (true/false).
• initscript: Array de comandos (String) para execução ao iniciar a conexão.
• name: Nome da conexão (Não usar espaço), este nome é usado no método getConnection para obter a conexão.
• user: Usuário de acesso do banco de dados informado.
• password: Senha de acesso do banco de dados informado.
• host: Servidor do banco de dados informado.
• port: Porta do banco de dados informado.
• database: Nome do banco de dados informado.
• preservefieldsnames: Caso seja true ele irá preservar os nomes dos campos como são exibidos no sql respeitando maiusculo ou minusculo, caso contrario ele irá colocar todas as colunas para minusculo (default=false).
• config: Objeto contendo informações específicos de cada driver de conexão.
  • mysql: mysql2

    "config": {
      "whatForConnections": true,
      "connectionLimit": 10,
      "queueLimit": 10
    }

  • oracle: oracledb

    "config": {
      "pooMax": 10,
      "poolMin": 2,
      "pooIncrement": 2,
      "poolPingInterval": 1
    }

  • mssql: mssql

    "config": {
      "max": 10,
      "min": 0,
      "idleTimeoutMillis": 30000
    }

  • firebird: firebird

    "config": {
      "max": 10
    }

  • postgres: pg

    "config": {
      "max": 10,
      "idleTimeoutMillis": 30000,
      "connectionTimeoutMillis": 2000
    }

  "database": [
    {
      "driver": "mysql",
      "main": true,
      "keydefinition": "{table}id",
      "keygenerate": false,
      "keygeneratecommand": "",
      "active": true,
      "autoinject": true,
      "fieldscontrol": true,
      "initscript": [],
      "name": "<name>",
      "host": "<ip>",
      "user": "<user>",
      "port": 3306,
      "password": "<password>",
      "database": "<database>",
      "config": {
        "waitForConnections": true,
        "connectionLimit": 10,
        "queueLimit": 10
      }
    }
  ]

Configuração do gerador de relatório.

Contem a definição se inicializa (true) ou não (false) as libs para geração de relatório, caso queira usar o gerador de relatório é necessário que esta opção estja com (true) poise assim a framework efetuará o download da lib necessária para gerar relatório usando jasper.

• init: Inicializa a configuração das libs pra geração de relatório, valores: (true/false).

  "reportLib": {
    "init": false
  }

Configuração de repositório local.

Contem a lista de definições de repositórios locais do sistema.

• name: Nome do repositório.
• path: Caminho local do repositório.
• emptyFileName: Nome do arquivo que será retornado em caso de não existir o arquivo informado.
• charFolderSeparator: Caracter usado para separar pastas dentro da url do repositório.

  "repository": [
    {"name": "PADRAO", "path": "<path>", "emptyFileName": "<empty filename>", "charFolderSeparator": "*"}
  ],

Configuração link externo para o repositório local.

Contem a definição do link que será usado para o repositório local externamente.

• host: Url base para o repositorio.

  "repositoryUrl": {
    "host": "http://localhost:9090"
  }

Configuração de repositório de armazenamento.

Contem a definição se inicializa (true) ou não (false) as libs para geração de relatório, caso queira usar o gerador de relatório é necessário que esta opção estja com (true) poise assim a framework efetuará o download da lib necessária para gerar relatório usando jasper.

• init: Inicializa a configuração das libs pra geração de relatório, valores: (true/false).

  "reportLib": {
    "init": false
  }

Parâmetros específicos do usuário.

Contem a definição que são específicas do usuário, o objeto usersettings deve conter as mesmas propriedades da classe shared/user_settings.ts (UserSettings). Para acessar os valores desta definição espcífica deve-se usar como descrito no exemplo abaixo:

  "usersettings":{
      "teste": 10;
  }

shared/user_settings.ts (UserSettings)

  export class UserSettings {
    teste!: number;
  }

   import { ConfigApi } from 'azu-pck-ts';
   import { UserSettings } from '../../shared/user_settings';
   ...
   let valor = ConfigApi.getConfig<UserSettings>().usersettings.teste;

   // O valor=10

Configuração API

Definições basicas da API.

Contem as definições basicas para inicialização da API.

• environment: Ambiente da configuração da API, valores: (development/production).
• port: Porta que o processo redirecionará as rotas.
• limit_request: Tamanho em mb do buffer de entrada da API.
• clearEmptyFieldBody: Ativa ou não a remoção de fields vazios do objeto body, valores: (true/false).
• clearEmptyFieldHeader: Ativa ou não a remoção de fields vazios do objeto header, valores: (true/false).
• returnJustApiData: Ativa ou não o retorno direto dos daso na api, ou seja não inclui objetos ou valores a mais no retorno da api, caso esteja false o processo respeita o retorno padrão ou as anotações de retorno, valores: (true/false).

  "api": {
    "environment": "development",
    "port": 9696,
    "limit_request": "50mb",
    "clearEmptyFieldBody": false,
    "clearEmptyFieldHeader": false,
    "returnJustApiData": false
  }

Definições do serviço de https.

Contem as definições de certificado de acesso ao serviço de https.

• pathKey: Caminho do Key do certificado.
• pathCrt: Caminho do Crt do certificado.

  "https": {
    "pathKey": "",
    "pathCrt": ""
  }

Definições do serviço de swagger.

Contem as definições para gerar os serviços de Swagger da API.

• active: Ativa ou não o serviço de Swagger na API, valores: (true/false).
• definition: Configurações específicas do serviço de Swagger (vide lib express-swagger-generator).

  "swagger": {
    "active": false,
    "definition": {
      "info": {
        "description": "This is a sample server",
        "title": "Swagger",
        "version": "1.0.0"
      },
      "host": "localhost:3000",
      "basePath": "/v1",
      "produces": [
        "application/json",
        "application/xml"
      ],
      "schemes": [
        "http",
        "https"
      ]
    }
  }

Definições do serviço de limite requisições.

Contem as definições de número limite de requisições subsequentes em um determinado tempo.

• active: Ativa ou não o serviço de limite de requisição na API, valores: (true/false).
• definition: Configurações específicas do serviço de Swagger (vide lib express-rate-limit).

  "limit_rate": {
    "active": false,
    "definition": {
      "windowMs": 2000,
      "max": 1,
      "message": "Muitas conexões criadas a partir deste ip, tente novamente após 15 minutos!"
    }
  }

Definições de autenticação da API.

Contem as definições de autenticação da API.

• generatenewtokenallendpoint: Gera ou não um novo token em cada requisição, valores: (true/false).
• expiresIn: Tempo de expiração do token (vide site vercel/ms).
• loginpath: Preencher somente se a rota do arquivo de login for alterada.
• algorithm: Algoritimo de geração do token (vide lib jsonwebtoken).
• authorization: Chave secreta para geração do token de acesso da API.

  "tokenaccess": {
    "generatenewtokenallendpoint": true,
    "expiresIn": "1d",
    "loginpath": "",
    "algorithm": "HS256",
    "authorization": "<token authorization>"
  }

Definições de microserviços.

Contem as definições dos microserviços.

• name: Nome do repositório do microserviço, (não pode conter espaços).
• url: Este parâmetro pode ser uma string ou um array de strings, nele contem a url do microserviço, a url deve conter apenas o host e a porta, não colocar path interno do microserviço. Outro detalhe é que se houver mais de um endereço neste campo, o projeto do microserviço deve ser o mesmo em todos os endereços o que muda é onde e como está instalado, iste recurso serve para quando um microserviço demandar muito processamento pode-se subi-lo em mais de um processo no com portas diferentes ou em servicores diferentes, o processo de chamada do microserviço no main irá balanciar as requisições entre os endereços.

  "microservice_repository": [
    {
        "name": "<Nome do Microserviço>",
        "url": "<Url única>" ou ["Array de Urls"]
    }
  ],

Service

Os services são a porta de entrada das rotas (API, APP), as funções do services vão conter o código de validação dos dados recebidos e as configurações de injeções de configuração da rota, nos tópicos posteriors serão explicados com detalhes cada uma destas funções;

Validação

A validação conciste em verficar se os dados estão de acordo com as necessidados do controller, uma vez não estando de acordo, o service pode rejeitar a requisição com uma mensagem de erro que será retornada na requisição solicitante. Para efetuar estas validações de dados utiliza-se a biblioteca zod que já vem instalado junto com o pacote principal, vide site https://zod.dev, segue um exemplo de validação;

• @field: Variável para exibir o nome do campo na mensagem;

import { BodyService, RequestApi, StandardLoginService, Validation } from "azu-pck-ts";
import { z } from 'zod'

export class LoginService extends StandardLoginService {
  login(req: RequestApi, bodyService: BodyService): Promise<any> {
    return new Promise(async (resolve, reject) => {
      try {
        const LoginSchema = z.object({
          user: z.string({
            required_error: 'O campo @field deve ser preenchido!',
            invalid_type_error: 'O campo @field deve ser do tipo string!'
          }).email({message: 'O campo @field deve ser um email!'}),
          password: z.string({
            required_error: 'O campo @field deve ser preenchido!',
            invalid_type_error: 'O campo @field deve ser do tipo string!'
          })
        })
        await Validation.isValidObject(LoginSchema, bodyService.header)
        resolve(bodyService)
      } catch (error) {
        reject(error)
      }
    })
  }
}

Modificadores (Annotations);

Os modificadores tem como função alterar o processo para efetuar determinadas operações diferenciadas do processo normal, este modificadores podem ser usados tanto na class (Ativo em todos os métodos da class) como no método (Ativo somente no método);

• queryValuesIntoBody: Caso não haja conteudo no body da requisição mas possua no query este anotação pega o conteudo do query e coloca no body;
• requestProtocol:
  • type: Especifica o tipo de protocolo que a rota permite, TypeProtocol.GET, TypeProtocol.POST e TypeProtocol.All

        @requestProtocol({
            type: TypeProtocol.POST
        })

• errorServiceEvent:
  • event: Especifica o evento que será executado quando houver alguma rejeição na rota.

        @errorServiceEvent({
            event: (io: RequestApi, errorServiceEventDef: ErrorServiceEventDef): Promise<ErrorServiceEventDef> => {
                return new Promise(async (resolve, reject)=>{
                    // Implementações
                    resolve(errorServiceEventDef)
                })
            }
        })

• endServiceEvent:
  • event: Especifica o evento que será executado quando finalizar a rota.

        @endServiceEvent({
            event: (io: RequestApi, responseBody: any) => Promise<any> => {
                return new Promise(async (resolve, reject)=>{
                    // Implementações
                    resolve(responseBody)
                })
            }
        })

• startServiceEvent:
  • event: Especifica o evento que será executado quando inicializa a rota.

        @startServiceEvent({
            event: (io: RequestApi, bodyService: BodyService) => Promise<BodyService> => {
                return new Promise(async (resolve, reject)=>{
                    // Implementações
                    resolve(bodyService)
                })
            }
        })

        @startServiceEvent({
            event: (io: RequestApi, bodyService: BodyTypeService<MetodoHeader, MetodoBody, UserBody, MetodoQuery>) => Promise<BodyService> => {
                return new Promise(async (resolve, reject)=>{
                    // Implementações
                    resolve(bodyService)
                })
            }
        })

• repository:
  • name: Define o nome do repositório, o mesmo deve ser definido no arquivo de configuração parâmetro repository.
  • contentPath: Define o subdiretório dentro do diretório base do repositorio, caso não haja não passar o parâmetro. Importante: Quando se usa esta anotação não deve definir o método no controller.

        @repository({
            name: '<Nome do Repositório>',
            contentPath: '<Path Interno no Repositório>'
        })

• microservice:
  • link: Define o nome do link para o repositório que contem os endereços dos microserviços.
  • entity: Caso a entidade no projeto main for diferente da do projeto do microserviços deve-se informar aqui a entidade do microserviço.
  • method: Caso o método no projeto main for diferente da do projeto do microserviço deve-se informar aqui o método do microserviço; Importante: Quando se usa esta anotação não deve definir o método no controller.

        @microservice({
            link: '<Nome do Link>',
            entity: '<Nome da Entidade>',
            method: '<Nome do Método>'
        })

• blockExternalAccess: Caso o acesso ao endpoint venha de uma requisição api a mesma será bloqueada, caso a rota criada no service for para que um job execute o mesmo deve conter esta anotação para impedir o acesso externo ao service usado no job;
• ignoreToken: Ignora a validação de token na requisição;
• inTransacton: Criar uma requisição transacionada no banco de dados, ou seja, se tudo der ok o processo efetuará o commit no final da requisição, caso de erro, o processo irá efetuar um rollback.
• customResponseOk:
• customResponseError:
• injectMongoConnection:
• injectConnection:
• jasperReport: