DEV Community: Vitor Silva Delfino

Autenticação com JWT

Vitor Silva Delfino — Wed, 31 Mar 2021 20:33:50 +0000

Neste post, vamos escrever um middleware de autenticação e um módulo de login.

O serviço de login vai receber um payload com usuário e senha, após tudo ser validado na base, vamos gerar um token do tipo JWT e devolver pro client.

Para a geração do token, vamos utilizar a lib jsonwebtoken

Todas as outras requests, precisarão desse token no cabeçalho, assim garantimos que é uma request feita por um usuário previamente autenticado, e tudo que antes necessitava do ID do usuário, agora podemos pegar de dentro do token.

Instalações



yarn add jsonwebtoken && yarn add -D @types/jsonwebtoken

Configurações

Após a instalação da lib, vamos criar uma variável de ambiente que vai servir como uma chave secreta. Ela vai ser utilizada no momento da geração do token

.env.dev



PORT=3000
DATABASE_MONGO_CONN=mongodb://localhost:27017/example
SECRET=0917B13A9091915D54B6336F45909539CCE452B3661B21F386418A257883B30A

E agora vamos importar esse hash nas configs
src/config/index.ts



...
export const auth = {
  secret: String(process.env.SECRET),
  expires: '1h',
};

Código

Vamos começar criando uma pasta Auth dentro de apps

E vamos criar um service.

Responsabilidade da service:

1 - Vamos buscar o usuário na base
2 - Caso o usuário não exista devolvemos um erro
3 - Caso o usuário exista, geramos um token e devolvemos
4 - Se acontecer algum outro erro, devolvemos uma falha interna

src/apps/Auth/AuthService.ts



/* eslint-disable no-underscore-dangle */
import { CustomError } from 'express-handler-errors';
import { sign } from 'jsonwebtoken';
import { MongoRepository, getConnection } from 'typeorm';

import { dbConnections, auth } from '@config/index';

import { Users } from '@apps/Users/Users.entity';

import logger from '@middlewares/logger';

class AuthService {
  private readonly repository: MongoRepository<Users>;

  constructor() {
    this.repository = getConnection(
      dbConnections.mongo.name
    ).getMongoRepository(Users);
  }

  async auth(data: {
    document: string;
    password: string;
  }): Promise<{ token: string }> {
    const { document, password } = data;
    logger.info(`AuthService::auth::`, data);

    try {
      // Buscando usuário
      const user = await this.repository.findOne({ document, password });

      // Validando existência
      if (!user) {
        throw new CustomError({
          code: 'USER_NOT_FOUND',
          message: 'Usuário não encontrado',
          status: 404,
        });
      }

      // Gerando token
      const token = await sign(
        {
          _id: user._id,
          document: user.document,
          name: user.name,
        },
        auth.secret,
        {
          expiresIn: auth.expires,
        }
      );

      return {
        token,
      };
    } catch (e) {
      if (e instanceof CustomError) throw e;
      logger.error(`AuthService::auth::${e.message}`);

      throw new CustomError({
        code: 'ERROR_AUTHENTICATE',
        message: 'Erro ao autenticar',
        status: 500,
      });
    }
  }
}

export default new AuthService();

E então criamos o controller, um validator e a rota

src/apps/Auth/AuthController.ts



import { Request, Response } from 'express';

import AuthService from './AuthService';

export const auth = async (req: Request, res: Response): Promise<Response> => {
  const { document, password } = req.body;
  const response = await AuthService.auth({ document, password });
  return res.json(response);
};

src/apps/Auth/validator.ts



import { NextFunction, Request, Response } from 'express';

import yup from '@config/yup';

export const validateAuthPayload = async (
  req: Request,
  _: Response,
  next: NextFunction
): Promise<void> => {
  await yup
    .object()
    .shape({
      document: yup.string().length(11).required(),
      password: yup.string().min(6).max(10).required(),
    })
    .validateSync(req.body, { abortEarly: false });

  return next();
};

src/apps/Auth/routes.ts



import { Router } from 'express';

import * as controller from './AuthController';
import { validateAuthPayload } from './validator';

const routes = Router();

routes.post('/', validateAuthPayload, controller.auth);

export default routes;

E vamos adicionar o path '/auth' no arquivo de rotas raiz.

src/routes.ts



import { Router } from 'express';

import * as controller from './AuthController';
import { validateAuthPayload } from './validator';

import 'express-async-errors';

const routes = Router();

routes.post('/', validateAuthPayload, controller.auth);

export default routes;

Realizando Login

Criei um usuário com os requests que já existe

Agora vou atualizar o arquivo de requests com o endpoint de login

requests.http



...
POST http://localhost:3000/api/auth HTTP/1.1
Content-Type: application/json

{
  "document": "42780908890",
  "password": "123456"
}

Podemos ver o token, na resposta da autenticação

Se colarmos esse token no site https://jwt.io, podemos ver a informação armazenada dentro dele, mas só com a secret conseguimos fazer a validação.

Então, nunca devemos gravar informações sensíveis dentro do token

Middleware

Antes de escrever o middleware, vamos modificar a interface do express.

No primeiro tutorial, adicionamos o campo id dentro da request.
Agora vamos adicionar o campo user com os tipos do payload do nosso token.

src/@types/express/index.d.ts



declare namespace Express {
  interface Request {
    id: string;
    user: {
      _id: string;
      document: string;
      name: string;
    };
  }
}

Agora, vamos escrever um middleware que vai receber esse token e fazer a validação

src/middlewares/authorize



import { Request, Response, NextFunction } from 'express';
import { CustomError } from 'express-handler-errors';
import { verify } from 'jsonwebtoken';

import { auth } from '@config/index';

import logger from '@middlewares/logger';

export const authorize = (
  req: Request,
  _: Response,
  next: NextFunction
): void => {
  // coletamos o token do header da requisição
  const token = req.headers.authorization;
  logger.info(`Authorize::validate token::${token}`);

  // se não existir o token, devolvemos 401, que é o HTTP code para não autorizado
  if (!token)
    return next(
      new CustomError({
        code: 'UNAUTHORIZED',
        message: 'Token não enviado',
        status: 401,
      })
    );
  try {
    // Aqui fazemos a validação do token
    const decoded = verify(token, auth.secret) as any;
    req.user = decoded;
    logger.info(`Authorize::user authorized::`);
    // No sucesso da validação a request segue em frente ...
    return next();
  } catch (e) {
    // Se der erro na validação, devolvemos 401 novamente
    logger.error(`Authorize::error decode token::${e.message}`);
    return next(
      new CustomError({
        code: 'UNAUTHORIZED',
        message: 'Token inválido',
        status: 401,
      })
    );
  }
};

Para utilizar o middleware, vamos alterar o método findOne do módulo User

src/config/index.ts



...
export type IUserRequest = {
  _id: string;
  document: string;
  name: string;
};
...

src/apps/User/UserService.ts



...
async findOne(userAuthenticated: IUserRequest): Promise<Users> {
    const user = await this.repository.findOne(userAuthenticated._id);
    if (!user)
      throw new CustomError({
        code: 'USER_NOT_FOUND',
        message: 'Usuário não encontrado',
        status: 404,
      });

    return user;
  }
...

E passar o userAuthenticated no controller

src/apps/User/UserController.ts



...
export const findOne = async (
  req: Request,
  res: Response
): Promise<Response> => {
  const response = await UserService.findOne(req.user);
  return res.json(response);
};
...

Agora, passamos o middleware na rota e podemos realizar o teste

src/apps/User/routes.ts



import { Router } from 'express';

import * as controller from './UserController';
import { validateUserPayload } from './validator';

import 'express-async-errors';
import { authorize } from '@middlewares/authorize';

const route = Router();

route.post('/', validateUserPayload, controller.create);
route.get('/', authorize, controller.findOne);
route.put('/:id', controller.update);
route.delete('/:id', controller.deleteOne);

export default route;

Para realizar o teste, vamos alterar a request dentro de requests.http



...
GET http://localhost:3000/api/users HTTP/1.1
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MDY0YjU1NjBlMTJkZjBiOWVjY2JjZWUiLCJkb2N1bWVudCI6IjQyNzgwOTA4ODkwIiwibmFtZSI6IlZpdG9yIiwiaWF0IjoxNjE3MjE2NTE1LCJleHAiOjE2MTcyMjAxMTV9.oZSom3PhiuLp554A_R4VajBV67T1Sb3DbCEGkNwMCEE
...

Estamos utilizando a informação de dentro do token, para resgatar um usuário da nossa base.

Tests

E como ficam os testes unitários que escrevemos ????

Como alteramos o serviço, os testes agora estão quebrando.

Vamos refatorar o teste existente.

Nós vamos precisar escrever um novo escopo em nossa switch de testes.

Como o token, tem uma expiração de 1h, fica inviável ter que gerar sempre um novo token para rodar os testes.

Nesses casos, vamos usar a função afterEach, para limpar o mock feito para o middleware de autenticação.

tests/User/user.test.ts



import { MockProxy } from 'jest-mock-extended';
import jwt from 'jsonwebtoken';
import request from 'supertest';
import { MongoRepository } from 'typeorm';
...

describe('## GET ##', () => {
    // Aqui estamos restaurando o mock
    afterEach(() => {
      jest.resetAllMocks();
    });
    test('should return error when user does not exists', async () => {
      /**
       * Vamos espionar a função verify,
       * a mesma utilizada no middleware e modificar o seu comportamento
       * é um outro jeito de mocar funções com jest
       *
       */
      const spy = jest.spyOn(jwt, 'verify');
      spy.mockReturnValue({
        _id: '6064b5560e12df0b9eccbcee',
        document: '42780908890',
        name: 'Vitor',
      } as any);
      repository.findOne.mockResolvedValue(null);
      await request(app)
        .get('/api/users')
        .set('Authorization', 'token')
        .expect(404, {
          errors: [
            {
              code: 'USER_NOT_FOUND',
              message: 'Usuário não encontrado',
              status: 404,
            },
          ],
        });
    });

    test('should return an user', async () => {
      const spy = jest.spyOn(jwt, 'verify');
      spy.mockReturnValue({
        _id: '6064b5560e12df0b9eccbcee',
        document: '42780908890',
        name: 'Vitor',
      } as any);
      const user = {
        _id: '6064b5560e12df0b9eccbcee',
        name: 'Teste',
        password: '1234',
      };
      repository.findOne.mockResolvedValue(user);
      await request(app)
        .get('/api/users')
        .set('Authorization', 'token')
        .expect(200, user);
    });
  });
...

Vamos escrever os testes do login

tests/Auth/auth.test.ts



import { MockProxy } from 'jest-mock-extended';
import jwt from 'jsonwebtoken';
import request from 'supertest';
import { MongoRepository } from 'typeorm';

jest.mock('typeorm');
jest.mock('../../src/middlewares/logger');
describe('## Auth Module ##', () => {
  const { app } = require('../../src/app').default;

  const repository = require('typeorm').mongoRepositoryMock as MockProxy<
    MongoRepository<any>
  >;

  describe('## Login ##', () => {
    afterEach(() => {
      jest.resetAllMocks();
    });
    test('should return error when user does not exists', async () => {
      repository.findOne.mockResolvedValue(null);
      await request(app)
        .post('/api/auth')
        .send({ document: '42780908890', password: '123456' })
        .expect(404, {
          errors: [
            {
              code: 'USER_NOT_FOUND',
              message: 'Usuário não encontrado',
              status: 404,
            },
          ],
        });
    });

    test('should return an token', async () => {
      repository.findOne.mockResolvedValue({
        _id: '6064b5560e12df0b9eccbcee',
        document: '42780908890',
        name: 'Vitor',
      });

      const spy = jest.spyOn(jwt, 'sign');
      const token =
        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MDY0YjU1NjBlMTJkZjBiOWVjY2JjZWUiLCJkb2N1bWVudCI6IjQyNzgwOTA4ODkwIiwibmFtZSI6IlZpdG9yIiwiaWF0IjoxNjE3MjE2NTE1LCJleHAiOjE2MTcyMjAxMTV9.oZSom3PhiuLp554A_R4VajBV67T1Sb3DbCEGkNwMCEE';
      spy.mockReturnValue(token as any);

      await request(app)
        .post('/api/auth')
        .send({ document: '42780908890', password: '123456' })
        .expect(200, {
          token,
        });
    });

    test('should return error when generate token', async () => {
      repository.findOne.mockResolvedValue({
        _id: '6064b5560e12df0b9eccbcee',
        document: '42780908890',
        name: 'Vitor',
      });

      const spy = jest.spyOn(jwt, 'sign');

      spy.mockImplementation(() => {
        throw new Error('Error to generate token');
      });

      await request(app)
        .post('/api/auth')
        .send({ document: '42780908890', password: '123456' })
        .expect(500, {
          errors: [
            {
              code: 'ERROR_AUTHENTICATE',
              message: 'Erro ao autenticar',
              status: 500,
            },
          ],
        });
    });
  });
});

E o resultado do coverage fica assim

Considerações finais

Para finalizar, vamos atualizar o swagger

No get do usuário, vamos remover o parâmetro id

src/apps/User/swagger.ts



const paths = {
  '/users/{id}': {
    ...
  },
  '/users': {
    get: {
      tags: ['User'],
      summary: 'User',
      description: 'Get user by Id',
      security: [
        {
          Bearer: [],
        },
      ],
      parameters: [
        {
          in: 'path',
          name: 'id',
          required: true,
          schema: {
            type: 'string',
          },
          description: 'uuid',
        },
      ],
      responses: {
        200: {
          description: 'OK',
          schema: {
            $ref: '#/definitions/User',
          },
        },
        404: {
          description: 'Not Found',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
        500: {
          description: 'Internal Server Error',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
      },
    },
...
    },
  },
};

const definitions = {
  User: {
    type: 'object',
    properties: {
      _id: { type: 'string' },
      name: { type: 'string' },
      document: { type: 'string' },
      password: { type: 'string' },
      createdAt: { type: 'date' },
      updatedAt: { type: 'date' },
    },
  },
  UserPayload: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      document: { type: 'string' },
      password: { type: 'string' },
    },
  },
};

export default {
  paths,
  definitions,
};

E vamos escrever o swagger do módulo Auth

src/apps/Auth/swagger.ts



const paths = {
  '/auth': {
    post: {
      tags: ['Auth'],
      summary: 'Auth',
      description: 'Authenticate User',
      security: [
        {
          Bearer: [],
        },
      ],
      parameters: [
        {
          in: 'body',
          name: 'update',
          required: true,
          schema: {
            $ref: '#/definitions/AuthPayload',
          },
        },
      ],
      responses: {
        200: {
          description: 'OK',
          schema: {
            $ref: '#/definitions/AuthResponse',
          },
        },
        404: {
          description: 'Not Found',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
        500: {
          description: 'Internal Server Error',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
      },
    },
  },
};

const definitions = {
  AuthResponse: {
    type: 'object',
    properties: {
      token: { type: 'string' },
    },
  },
  AuthPayload: {
    type: 'object',
    properties: {
      document: { type: 'string' },
      password: { type: 'string' },
    },
  },
};

export default {
  paths,
  definitions,
};

Escrevendo testes com Jest + supertest

Vitor Silva Delfino — Wed, 24 Mar 2021 16:49:35 +0000

Neste post, vamos escrever o teste unitário do CRUD de usuários feito até aqui.

Como a nossa camada de serviço acessa a base de dados com o typeorm, vamos escrever algumas funções que vai mockar a instância do typeorm, facilitando reescrever o retorno do acesso ao banco.

Passo a passo

Instalar as dependências (babel-jest, jest, jest-mock-extended, supertest, ts-jest) e seus types
Configurar o Jest
Escrever mocks de alguns middlewares, por exemplo de logs
Escrever o mock do typeorm
Implementar os testes

Instalações

yarn add -D babel-jest jest jest-mock-extended supertest ts-jest @types/jest @types/supertest

Configurações

O próprio jest tem uma função para montar o arquivo de configurações, como eu já uso a lib em vários projetos, vou copiar um padrão que eu costumo utilizar. Por estarmos usando o babel e import nomeado (@middleware, etc...) a config já está certinha ;D

jest.config.js

const { pathsToModuleNameMapper } = require('ts-jest/utils');

const { compilerOptions } = require('./tsconfig.json');

module.exports = {
  clearMocks: true,
  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, {
    prefix: '<rootDir>',
  }),
  coverageDirectory: 'coverage',
  coverageReporters: ['lcov', 'html', 'text'],
  coveragePathIgnorePatterns: [
    '/node_modules/',
    'src/tools',
    'src/services',
    'src/middlewares',
  ],
  preset: 'ts-jest',
  testEnvironment: 'node',
  modulePathIgnorePatterns: ['dist', 'node_modules', 'coverage'],
  testMatch: ['**/?(*.)+(spec|test).(js|ts|tsx)'],
};

Mocks

Mocking user modules

Simulações manuais são definidas por escrever um módulo em um subdiretório mocks/ imediatamente adjacente ao módulo. Por exemplo, para simular (mock, em inglês) um módulo chamado user no diretório models, crie um arquivo chamado user.js e coloque ele no diretório models/mocks.

Levando em conta a explicação da documentação do Jest, vamos mockar o middleware de logs.

src/middlewares/__mocks__/logger.ts

const logger = {
  log: () => {},
  info: () => {},
  warn: () => {},
  error: () => {},
  debug: () => {},
  silly: () => {},
};

export default logger;

Agora, quando o nosso teste passar por um log dentro da classe de serviço, não vai ser executado nada, deixando o console do teste mais limpo.

Mock Typeorm

Quando queremos mockar um módulo que foi instalado como dependênciacia, nós criamos a pasta __mocks__ na raiz do projeto, e dentro dela os arquivos com o nome da lib.

__mocks__/typeorm.ts

import { mock } from 'jest-mock-extended';
import { Repository, MongoRepository } from 'typeorm';

export const repositoryMock = mock<Repository<any>>();

export const mongoRepositoryMock = mock<MongoRepository<any>>();

export const getConnection = jest.fn().mockReturnValue({
  getRepository: () => repositoryMock,
  getMongoRepository: () => mongoRepositoryMock,
});

export class BaseEntity {}
export const ObjectIdColumn = () => {};
export const Column = () => {};
export const Index = () => {};
export const CreateDateColumn = () => {};
export const UpdateDateColumn = () => {};
export const Entity = () => {};

Aqui estamos mockando todos os recursos do typeorm que a aplicação está utilizando, decorators, repositories, funções, etc...

Então lá na classe de serviço, onde importamos um repository no construtor, quando o teste for executado, é o objeto do arquivo acima que será utilizado. Dessa forma, no teste unitário eu consigo simular o retorno dos métodos de acesso ao banco, findOne, find, update, delete, etc...

Escrevendo o primeiro teste

Para os testes do crud, vou utilizar o supertest, ele simula a camada do express, e assim conseguimos fazer um request pra nossa api.

Vamos escrever nossos testes dentro uma pasta tests na raiz do projeto, e então o separamos por módulos.

GET

Os testes unitários são executados em blocos de código, assim conseguimos separar cada bloco em um assunto específico, revise a documentação caso necessário

E para facilitar a escrita do testes, fazendo passar por todas as regras de negócio, eu costumo deixar a classe serviço aberta lado a lado do teste.

A primeira regra é: Se o usuário não existir na base de dados, a api devolve um erro com status 404.

Então vamos escrever esse teste

tests/User/user.test.ts

import { MockProxy } from 'jest-mock-extended';
import request from 'supertest';
import { MongoRepository } from 'typeorm';

jest.mock('typeorm');
jest.mock('../../src/middlewares/logger');
describe('## User Module ##', () => {
  // Importamos a instância do express para usar com supertest
  const { app } = require('../../src/app').default;

  // Aqui é a instância do typeorm que vai na base de dados
  const repository = require('typeorm').mongoRepositoryMock as MockProxy<
    MongoRepository<any>
  >;

  // Vamos separar os endpoints do crud por blocos

  describe('## GET ##', () => {
    // Aqui vamos escrever os testes para o método findOne da classe de serviço
    test('should return error when user does not exists', async () => {
      // A condição para retornar esse erro é o retorno da base ser nulo
      // Então vamos mocar o retorno do typeorm

      // Assim quando o typeorm resolver a chamada findOne,
      // o retorno é o objetos que passarmos no mock
      repository.findOne.mockResolvedValue(null);

      // Aqui estou fazendo um request para a api
      await request(app)
        .get('/api/users/some-id')
        .expect(404, {
          errors: [
            {
              code: 'USER_NOT_FOUND',
              message: 'Usuário não encontrado',
              status: 404,
            },
          ],
        });
    });
  });
});

No Vscode, instale a extenções Jest e Jest Runner

Com elas, podemos executar um teste específico clicando no botão Run

Agora, vamos escrever todos os outros testes do bloco ## GET ##


  ...

  describe('## GET ##', () => {
    test('should return error when user does not exists', async () => {
      repository.findOne.mockResolvedValue(null);
      await request(app)
        .get('/api/users/some-id')
        .expect(404, {
          errors: [
            {
              code: 'USER_NOT_FOUND',
              message: 'Usuário não encontrado',
              status: 404,
            },
          ],
        });
    });

    test('should return an user', async () => {
      const user = {
        _id: '6001abf43d4675bc1aa693bc',
        name: 'Teste',
        password: '1234',
      };
      repository.findOne.mockResolvedValue(user);
      await request(app).get('/api/users/some-id').expect(200, user);
    });
  });

...

Nosso CRUD, não tem tantas regras de negócio, mas é importante passar por todas elas, para simular o comportamento da api.

POST

Agora vamos escrever os testes da criação do usuário

async create(user: Users): Promise<Users> {
    try {
      const response = await this.repository.save(user);
      return response;
    } catch (e) {
      if (e.code === 11000)
        throw new CustomError({
          code: 'USER_ALREADY_EXISTS',
          message: 'Usuário já existente',
          status: 409,
        });
      throw e;
    }
  }

Na classe de serviço, só temos uma regra, a de usuário ja existente. Mas temos um middleware para validar o payload recebido, os testes desse bloco deve cobrir todas essas regras.

O primeiro teste vai cair na validação de documento

...
describe('## POST ##', () => {
    test('should return error when document is invalid', async () => {
      await request(app)
        .post('/api/users')
        .send({ name: 'Teste', document: '1234', password: '0123456789' })
        .expect(400, {
          errors: [
            {
              code: 'ValidationError',
              message: 'document: deve conter exatamente 11 caracteres',
            },
          ],
        });
    });
  });
...

O segundo teste na validação do password

...
test('should return error when password is invalid', async () => {
      await request(app)
        .post('/api/users')
        .send({
          name: 'Teste',
          document: '12345678900',
          password: '1234',
        })
        .expect(400, {
          errors: [
            {
              code: 'ValidationError',
              message: 'password: valor muito curto (mínimo 6 caracteres)',
            },
          ],
        });
    });
...

E um teste para validar a obrigatoriedade dos campos

...
test('should return error when payload is invalid', async () => {
      await request(app)
        .post('/api/users')
        .send({})
        .expect(400, {
          errors: [
            { code: 'ValidationError', message: 'name é um campo obrigatório' },
            {
              code: 'ValidationError',
              message: 'document é um campo obrigatório',
            },
            {
              code: 'ValidationError',
              message: 'password é um campo obrigatório',
            },
          ],
        });
    });
...

Agora, o teste vai passar nas validações, mas cair na regra de usuário já existente

...
test('should return error when user already exists', async () => {
      // Aqui vamos simular o erro de criação do usuário
      repository.save.mockRejectedValue({
        code: 11000,
      });

      await request(app)
        .post('/api/users')
        .send({
          name: 'Teste',
          document: '12345678900',
          password: '1234567890',
        })
        .expect(409, {
          errors: [
            {
              code: 'USER_ALREADY_EXISTS',
              message: 'Usuário já existente',
              status: 409,
            },
          ],
        });
    });
...

Caindo na exception não tratada

...
test('should return error when create user', async () => {
      repository.save.mockRejectedValue(new Error('Some Exception'));

      await request(app)
        .post('/api/users')
        .send({
          name: 'Teste',
          document: '12345678900',
          password: '1234567890',
        })
        .expect(500, {
          errors: [{ code: 'E0001', message: 'Some Exception' }],
        });
    });
...

Agora o de sucesso

...
test('should create an user', async () => {
      const user = {
        name: 'Teste',
        document: '12345678900',
        password: '1234567890',
      };
      repository.save.mockResolvedValue({
        ...user,
        _id: 'some-id',
      });

      await request(app).post('/api/users').send(user).expect(200, {
        name: 'Teste',
        document: '12345678900',
        password: '1234567890',
        _id: 'some-id',
      });
    });
...

Coverage

Antes de escrever os testes de UPDATE e DELETE. Vamos ver como está ficando a cobertura dos testes

No arquivo package.json, vamos escrever um script que executa os testes e colhe a cobertura

package.json

{
 ...
"scripts": {
    ...
    "coverage": "rimraf coverage && NODE_ENV=test jest --coverage --silent --detectOpenHandles --forceExit",
    ...
  },
 ...
}

No terminal vamos executar

yarn coverage

Esse comando gerou uma pastinha chamada coverage na raiz do projeto.

abra o arquivo index.html dela no browser e vemos o resultado dos testes com a cobertura

Navegando até UserService, podemos ver que já estamos com 77% de cobertura nesse arquivo, e os métodos create e findOne está totalmente coberto.

Não esqueca de adicionar a pasta coverage no arquivo .gitignore, para não subi-la para o repositório

UPDATE e DELETE

...
describe('## PUT ##', () => {
    test('should return error when user does not exists', async () => {
      repository.updateOne.mockResolvedValue({} as any);
      repository.findOne.mockResolvedValue(null);
      await request(app)
        .put('/api/users/6001abf43d4675bc1aa693bd')
        .send({ name: 'Teste' })
        .expect(404, {
          errors: [
            {
              code: 'USER_NOT_FOUND',
              message: 'Usuário não encontrado',
              status: 404,
            },
          ],
        });
    });

    test('should return updated user', async () => {
      const user = {
        name: 'Teste',
        document: '12345678900',
        password: '1234567890',
      };
      repository.updateOne.mockResolvedValue({} as any);

      repository.findOne.mockResolvedValue({
        ...user,
        _id: '6001abf43d4675bc1aa693bd',
      });

      await request(app)
        .put('/api/users/6001abf43d4675bc1aa693bd')
        .send({ name: 'Teste' })
        .expect(200, {
          ...user,
          _id: '6001abf43d4675bc1aa693bd',
        });
    });
  });

  describe('## DELETE ##', () => {
    test('should return error when user does not exists', async () => {
      repository.findOne.mockResolvedValue(null);
      await request(app)
        .delete('/api/users/6001abf43d4675bc1aa693bd')
        .send({ name: 'Teste' })
        .expect(404, {
          errors: [
            {
              code: 'USER_NOT_FOUND',
              message: 'Usuário não encontrado',
              status: 404,
            },
          ],
        });
    });

    test('should return deleted user', async () => {
      const user = {
        name: 'Teste',
        document: '12345678900',
        password: '1234567890',
      };

      repository.findOne.mockResolvedValue({
        ...user,
        _id: '6001abf43d4675bc1aa693bd',
      });

      repository.deleteOne.mockResolvedValue({} as any);

      await request(app)
        .delete('/api/users/6001abf43d4675bc1aa693bd')
        .send({ name: 'Teste' })
        .expect(200, {
          ...user,
          _id: '6001abf43d4675bc1aa693bd',
        });
    });
  });
...

Agora com todos os testes executados, o coverage está em 100%

Considerações Finais

Pra finalizar, vamos escrever um script que executa todos os testes.

E ao realizar um commit, todos os testes serão executados e caso algum falhe, o commit será barrado.

Essa é uma boa prática, nos impede de subir alguma coisa que está falhando devido alguma alteração no código

package.json

{
 ...
"scripts": {
    ...
    "test": "rimraf coverage && NODE_ENV=test jest --coverage --silent --detectOpenHandles --forceExit",
    ...
  },
"husky": {
    "hooks": {
      "pre-commit": "npm test",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
 ...
}

Agora, em todo commit teremos os testes sendo executados

Forcei um erro para a imagem abaixo

E com todos os testes OK

O que está por vir

No próximo post, implementaremos uma camada de autenticação com JWT

Validações com Yup + Swagger

Vitor Silva Delfino — Tue, 23 Mar 2021 21:36:12 +0000

Dando continuidade na aplicação, vamos escrever um middleware para validação do payload recebido, e escrever a documentação da API utilizando Swagger.

Yup

Yup é um construtor de esquema JavaScript para análise e validação de valor

Instalações

Vamos instalar a lib e seus types.

yarn add yup@0.28.5 && yarn add -D @types/yup

Após a instalação, vamos configurar uma instância do Yup.

src/config/yup.ts

import * as yup from 'yup';

yup.setLocale({
  string: {
    email: 'Preencha um email válido',
    min: '${path}: valor muito curto (mínimo ${min} caracteres)',
    max: '${path}: valor muito longo (máximo ${max} caracteres)',
    matches: '${path}: valor inválido, verifique o formato esperado',
    length: '${path}: deve conter exatamente ${length} caracteres',
  },
  mixed: {
    required: '${path} é um campo obrigatório',
    oneOf: '${path} deve ser um dos seguintes valores [${values}]',
  },
});

export default yup;

Importamos o yup e configuramos algumas mensagens padrão para cada tipo de validação feito.

Com yup configurado, vamos escrever uma validação para o nosso cadastro de usuário.

src/apps/Users/validator.ts

import yup from '@config/yup';

export const validateUserPayload = async (
  req: Request,
  _: Response,
  next: NextFunction
): Promise<void> => {
  await yup
    .object()
    .shape({
      name: yup.string().required(),
      document: yup.string().length(11).required(),
      password: yup.string().min(6).max(10).required(),
    })
    .validate(req.body, { abortEarly: false });

  return next();
};

Definimos algumas regras para o payload da criação de usuário

name, document e password são obrigatórios
document deve ter 11 caracteres
password deve ter no mínimo 6 e no máximo 10 caracteres

E na rota, antes de passar a request para a controller, vamos adicionar o middleware de validação

src/apps/Users/routes.ts

import { Router } from 'express';

import * as controller from './UserController';
import { validateUserPayload } from './validator';

import 'express-async-errors';

const route = Router();

route.post('/', validateUserPayload, controller.create);
route.get('/:id', controller.findOne);
route.put('/:id', controller.update);
route.delete('/:id', controller.deleteOne);

export default route;

Vamos testar nossa validação.

No arquivo de requests, vamos adicionar um request com payload inválido e executa-lo.

...
POST http://localhost:3000/api/users HTTP/1.1
Content-Type: application/json

{
  "name": "Vitor",
  "document": "123",
  "password": "1234"
}
...

A lib express-handlers-errors sabe lidar com os erros devolvidos pelo Yup. E podemos ver as mensagens de erro no retorno.

{
  "errors": [
    {
      "code": "ValidationError",
      "message": "document: deve conter exatamente 11 caracteres"
    },
    {
      "code": "ValidationError",
      "message": "password: valor muito curto (mínimo 6 caracteres)"
    }
  ]
}

Swagger

Agora que já sabemos escrever validações com Yup, vamos documentar os endpoints da nossa aplicação.

Instalações

Começamos instalando a lib swagger-ui-express

yarn add swagger-ui-express && yarn add -D @types/swagger-ui-express

Após a instalação, vamos escrever um script.

Esse script vai ser executado sempre no start da aplicação, e vai varrer todas as pastas dentro de src/apps procurando um arquivo swagger.ts

Então como convenção, cada módulo da aplicação terá um arquivo de documentação, por exemplo:

src/apps/Users/swagger.ts aqui vai estar toda a documentação do módulo de usuário
src/apps/Products/swagger.ts aqui vai estar toda a documentação do módulo de produtos
...

Vamos ao middleware:
src/middlewares/swagger.ts

import fs from 'fs';
import { resolve } from 'path';

class SwaggerConfig {
  private readonly config: any;

  private paths = {};

  private definitions = {};

  constructor() {
    // Aqui fazemos uma configuração inicial, informando o nome da aplicação e definindo alguns tipos
    this.config = {
      swagger: '2.0',
      basePath: '/api',
      info: {
        title: 'Tutorial de Node.JS',
        version: '1.0.0',
      },
      schemes: ['http', 'https'],
      consumes: ['application/json'],
      produces: ['application/json'],
      securityDefinitions: {
        Bearer: {
          type: 'apiKey',
          in: 'header',
          name: 'Authorization',
        },
      },
    };

    this.definitions = {
      ErrorResponse: {
        type: 'object',
        properties: {
          errors: {
            type: 'array',
            items: {
              $ref: '#/definitions/ErrorData',
            },
          },
        },
      },
      ErrorData: {
        type: 'object',
        properties: {
          code: {
            type: 'integer',
            description: 'Error code',
          },
          message: {
            type: 'string',
            description: 'Error message',
          },
        },
      },
    };
  }

  /**
   * Função responsável por percorrer as pastas e adicionar a documentação de cada módulo
   * @returns 
   */
  public async load(): Promise<{}> {
    const dir = await fs.readdirSync(resolve(__dirname, '..', 'apps'));
    const swaggerDocument = dir.reduce(
      (total, path) => {
        try {
          const swagger = require(`../apps/${path}/swagger`);
          const aux = total;
          aux.paths = { ...total.paths, ...swagger.default.paths };
          if (swagger.default.definitions) {
            aux.definitions = {
              ...total.definitions,
              ...swagger.default.definitions,
            };
          }

          return total;
        } catch (e) {
          return total;
        }
      },
      {
        ...this.config,
        paths: { ...this.paths },
        definitions: { ...this.definitions },
      }
    );
    return swaggerDocument;
  }
}

export default new SwaggerConfig();

E então configuramos as rotas para apresentação da documentação:
src/swagger.routes.ts

import { Router, Request, Response } from 'express';
import { setup, serve } from 'swagger-ui-express';

import SwaggerDocument from '@middlewares/swagger';

class SwaggerRoutes {
  async load(): Promise<Router> {
    const swaggerRoute = Router();
    const document = await SwaggerDocument.load();
    swaggerRoute.use('/api/docs', serve);
    swaggerRoute.get('/api/docs', setup(document));
    swaggerRoute.get('/api/docs.json', (_: Request, res: Response) =>
      res.json(document)
    );

    return swaggerRoute;
  }
}

export default new SwaggerRoutes();

E nas configurações do express, usaremos essa rota
src/app.ts

...

import routes from './routes';
import swaggerRoutes from './swagger.routes';
import 'reflect-metadata';

class App {
  public readonly app: Application;

  private readonly session: Namespace;

  constructor() {
    this.app = express();
    this.session = createNamespace('request'); // é aqui que vamos armazenar o id da request
    this.middlewares();
    this.configSwagger(); // Aqui chamamos a função para configurar o swagger
    this.routes();
    this.errorHandle();
  }

 ...

  private async configSwagger(): Promise<void> {
    const swagger = await swaggerRoutes.load();
    this.app.use(swagger);
  }

  ...

export default new App();

Agora é só startar a aplicação e acessar a documentação

http://localhost:3000/api/docs

Configurando a documentação das rotas

Vamos escrever a documentação do nosso módulo de usuários

Em todo arquivo vamos exportar dois objetos, paths e definitions

em paths definimos as rotas
em definitions definimos os modelos

Em qualquer caso de dúvida, é só acessar a documentação

src/apps/Users/swagger.ts

const paths = {
  '/users/{id}': {
    get: {
      tags: ['User'],
      summary: 'User',
      description: 'Get user by Id',
      security: [
        {
          Bearer: [],
        },
      ],
      parameters: [
        {
          in: 'path',
          name: 'id',
          required: true,
          schema: {
            type: 'string',
          },
          description: 'uuid',
        },
      ],
      responses: {
        200: {
          description: 'OK',
          schema: {
            $ref: '#/definitions/User',
          },
        },
        404: {
          description: 'Not Found',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
        500: {
          description: 'Internal Server Error',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
      },
    },
    put: {
      tags: ['User'],
      summary: 'User',
      description: 'Update user',
      security: [
        {
          Bearer: [],
        },
      ],
      parameters: [
        {
          in: 'path',
          name: 'id',
          required: true,
          schema: {
            type: 'string',
          },
          description: 'uuid',
        },
        {
          in: 'body',
          name: 'update',
          required: true,
          schema: {
            $ref: '#/definitions/UserPayload',
          },
        },
      ],
      responses: {
        200: {
          description: 'OK',
          schema: {
            $ref: '#/definitions/User',
          },
        },
        404: {
          description: 'Not Found',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
        500: {
          description: 'Internal Server Error',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
      },
    },
    delete: {
      tags: ['User'],
      summary: 'User',
      description: 'Delete User',
      security: [
        {
          Bearer: [],
        },
      ],
      parameters: [
        {
          in: 'path',
          name: 'id',
          required: true,
          schema: {
            type: 'string',
          },
          description: 'uuid',
        },
      ],
      responses: {
        200: {
          description: 'OK',
        },
        404: {
          description: 'Not Found',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
        500: {
          description: 'Internal Server Error',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
      },
    },
  },
  '/users': {
    post: {
      tags: ['User'],
      summary: 'User',
      description: 'Create user',
      security: [
        {
          Bearer: [],
        },
      ],
      parameters: [
        {
          in: 'body',
          name: 'update',
          required: true,
          schema: {
            $ref: '#/definitions/UserPayload',
          },
        },
      ],
      responses: {
        200: {
          description: 'OK',
          schema: {
            $ref: '#/definitions/User',
          },
        },
        404: {
          description: 'Not Found',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
        500: {
          description: 'Internal Server Error',
          schema: {
            $ref: '#/definitions/ErrorResponse',
          },
        },
      },
    },
  },
};

const definitions = {
  User: {
    type: 'object',
    properties: {
      _id: { type: 'string' },
      name: { type: 'string' },
      document: { type: 'string' },
      password: { type: 'string' },
      createdAt: { type: 'date' },
      updatedAt: { type: 'date' },
    },
  },
  UserPayload: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      document: { type: 'string' },
      password: { type: 'string' },
    },
  },
};

export default {
  paths,
  definitions,
};

Agora se atualizarmos a página vemos os endpoints

E todos os requests podem ser feitos diretamente por ali

Considerações finais

Documentar a api com swagger é realmente muito verboso, e a cada mudança nas internfaces/contratos o swagger deve ser atualizado.

Mas mantendo a documentação em dia, você facilita o trabalho do QA, do front que vai realizar a integração e muito mais.

O que está por vir

No próximo post, vamos configurar o jest e implementar o primeiro teste unitário. E para simular um teste sem precisa acessar a base de dados, vamos mockar as funções do typeorm

Configurando Typeorm + Primeiro CRUD

Vitor Silva Delfino — Fri, 15 Jan 2021 20:41:25 +0000

Dando continuidade ao post anterior, hoje vamos configurar o Typeorm e escrever o primeiro crud.

OBS: Sugiro que para o bom entendimento do tutorial, o caro leitor já esteja familiarizado com uso do Docker

Typeorm

Como o próprio nome ja diz, o Typeorm é o cara que vai nos ajudar a conectar no banco e manipular seus dados.

Sem muita enrolação, bora pro código.

Instalações

Começamos instalando algumas dependências:



yarn add typeorm reflect-metadata mongodb && yarn add @types/mongodb -D

Após o fim da instalação, precisamos importar o reflect-metadata em um arquivo global da nossa aplicação.

Configurações

src/app.ts



.
.
.
import 'reflect-metadata';

class App {
 .
 .
 .
}

Vamos atualizar o nosso arquivo global de environments com alguns novos dados:

src/config/index.ts



import { config } from 'dotenv';

const envfile = `.env.${process.env.NODE_ENV}`;
const envdir = process.cwd();

config({ path: `${envdir}/${envfile}` });

export const server = {
  port: process.env.PORT,
  env: process.env.NODE_ENV,
};

// dados de conexão com o banco
export const dbConnections = {
  mongo: {
    name: 'mongo',
    conn: String(process.env.DATABASE_MONGO_CONN),
  },
};

Agora criamos as nossas configurações de conexão com o banco:

src/config/db/index.ts



import { createConnections } from 'typeorm';

import { dbConnections, server } from '../index';

const connection = createConnections([
  {
    name: dbConnections.mongo.name,
    type: 'mongodb',
    url: dbConnections.mongo.conn,
    entities: [],
    useNewUrlParser: true,
    useUnifiedTopology: true,
    synchronize: server.env === 'dev', // Se o ambiente for dev, o typeorm se incarrega de gerar e alterar as tabelas
  },
]);

export default connection;

Após todas as configurações feitas, precisamos alterar o start da nossa aplicação e também adicionar a url de conexão nas variaveis de ambiente.

.env.dev



PORT=3000
DATABASE_MONGO_CONN=mongodb://localhost:27017/example

Primeiro conectamos na base, e no sucesso da conexão startamos a API.

src/server.ts



import connection from '@config/db';
import { server } from '@config/index';

import logger from '@middlewares/logger';

connection.then(() => {
  logger.info(`Database connected`);
  // precisamos importar o express somente após a conexão com a base, ou então o typeorm vai reclamar que alguns repositories não existem
  require('./app').default.app.listen(server.port, () => {
    logger.info('Server running', { port: server.port, mode: server.env });
  });
});

E agora para testar nossa conexão, vamos utilizar do Docker/Docker Compose para subir uma imagem do MongoDB

docker-compose.yml



version: '3'

volumes:
  mongo_volume:
    driver: local

services:
  mongo:
    image: mongo
    container_name: mongo_example
    ports:
      - '27017:27017'

Vamos subir o banco e iniciar a api e ver o que aparece no console.



docker-compose up -d
yarn start:dev

Primeira Entidade

Já estamos conectando na base de dados, mas ainda não temos nenhuma entididade definida.

Vamos escrever nossa primeira entidade.

Com o typeorm, nós definimos uma classe com alguns @decorators e a mágica acontece:

Adicionamos uma nova pastinha na nossa estrutura: src/apps/Users

A única regra na nossa collection de usuários é que não pode existir dois com o mesmo documento

src/apps/Users/Users.entity.ts



import {
  BaseEntity,
  Column,
  CreateDateColumn,
  Entity,
  Index,
  ObjectIdColumn,
  UpdateDateColumn,
} from 'typeorm';

@Entity()
export class Users extends BaseEntity {
  @ObjectIdColumn({
    type: 'uuid',
  })
  _id!: string;

  @Column()
  name!: string;

  @Column()
  @Index({ unique: true })
  document!: string;

  @Column()
  password!: string;

  @CreateDateColumn({
    type: 'timestamp',
  })
  createdAt!: Date;

  @UpdateDateColumn({
    type: 'timestamp',
    nullable: true,
  })
  updatedAt?: Date;
}

E por final vamos passar nossas entidades nas configurações do typeorm:

src/config/db/index.ts



import { createConnections } from 'typeorm';

import { Users } from '@apps/Users/Users.entity';

import { dbConnections, server } from '../index';

const connection = createConnections([
  {
    name: dbConnections.mongo.name,
    type: 'mongodb',
    url: dbConnections.mongo.conn,
    entities: [Users],
    useNewUrlParser: true,
    useUnifiedTopology: true,
    synchronize: server.env === 'dev', // Se o ambiente for dev, o typeorm se incarrega de gerar e alterar as tabelas
  },
]);

export default connection;

Após o restart da aplicação, já conseguimos ver a collection de usuários criada, para isso faça o download da extension MongoDB for VS Code

Clique no ícone do mongodb e configure a url de conexão

Com a base conectada e a collection criada, vamos escrever nossa classe de serviço e as rotas.

CRUD

Vamos escrever o crud de usuários

src/apps/Users/UserService.ts



import { CustomError } from 'express-handler-errors';
import { ObjectID } from 'mongodb';
import { getConnection, MongoRepository } from 'typeorm';

import { dbConnections } from '@config/index';

import { Users } from './Users.entity';

class UserService {
  private readonly repository: MongoRepository<Users>;

  constructor() {
    this.repository = getConnection(
      dbConnections.mongo.name
    ).getMongoRepository(Users);
  }

  async create(user: Users): Promise<Users> {
    try {
      const response = await this.repository.save(user);
      return response;
    } catch (e) {
      if (e.code === 11000)
        throw new CustomError({
          code: 'USER_ALREADY_EXISTS',
          message: 'Usuário já existente',
          status: 409,
        });
      throw e;
    }
  }

  async findOne(_id: string): Promise<Users> {
    const user = await this.repository.findOne(_id);
    if (!user)
      throw new CustomError({
        code: 'USER_NOT_FOUND',
        message: 'Usuário não encontrado',
        status: 404,
      });

    return user;
  }

  async update(_id: string, name: string): Promise<Users> {
    await this.repository.updateOne(
      {
        _id: new ObjectID(_id),
      },
      {
        $set: {
          name,
        },
      }
    );
    return this.findOne(_id);
  }

  async delete(_id: string): Promise<Users> {
    const user = await this.findOne(_id);
    await this.repository.deleteOne({
      _id: new ObjectID(_id),
    });
    return user;
  }
}

export default new UserService();

src/apps/Users/UsersController.ts



import { Request, Response } from 'express';

import UserService from './UserService';

export const create = async (
  req: Request,
  res: Response
): Promise<Response> => {
  const response = await UserService.create(req.body);
  return res.json(response);
};

export const findOne = async (
  req: Request,
  res: Response
): Promise<Response> => {
  const response = await UserService.findOne(req.params.id);
  return res.json(response);
};

export const update = async (
  req: Request,
  res: Response
): Promise<Response> => {
  const response = await UserService.update(req.params.id, req.body.name);
  return res.json(response);
};

export const deleteOne = async (
  req: Request,
  res: Response
): Promise<Response> => {
  const response = await UserService.delete(req.params.id);
  return res.json(response);
};

src/apps/routes.ts



import { Router } from 'express';

import * as controller from './UserController';

const route = Router();

route.post('/', controller.create);
route.get('/:id', controller.findOne);
route.put('/:id', controller.update);
route.delete('/:id', controller.deleteOne);

export default route;

E por final configuramos a rota de usuários, no arquivo global das rotas;

src/routes.ts



import { Router } from 'express';

import UserRoutes from '@apps/Users/routes';

const route = Router();

route.use('/users', UserRoutes);

export default route;

Testando o CRUD

Instale a extension REST Client.

Na raiz do projeto crie um arquivo requests.http

Criando usuário

requests.http



POST http://localhost:3000/api/users HTTP/1.1
Content-Type: application/json

{
  "name": "Vitor",
  "document": "42780908890",
  "password": "1234"
}

Repare que vai ter uma label escrito Send Request, clique nela e o request será realizado.

Buscando o usuário pelo Id

requests.http



.
.
.
GET http://localhost:3000/api/users/6001abf43d4675bc1aa693bd HTTP/1.1

Se atualizarmos a aba do mongodb, também podemos buscar o usuário lá.

Atualizando o nome

requests.http



.
.
.
PUT http://localhost:3000/api/users/6001abf43d4675bc1aa693bd HTTP/1.1
Content-Type: application/json

{
  "name": "Vitor Delfino"
}

Excluindo o usuário

requests.http



.

.

.

DELETE http://localhost:3000/api/users/6001abf43d4675bc1aa693bd HTTP/1.1

Error Handler

E como ficaram os responses caso o usuário não exista ou o documento ja tenha sido cadastrado

Considerações finais

Hoje configuramos o primeiro serviço da nossa aplicação.

Na estrutura sugerida, os serviços ficam dentro de uma pasta apps e caso a aplicação aumente muito, e cada serviço precise se tornar uma aplicação a parte, está fácil fazer a quebra do nosso mini monolito.

Só precisamos fazer a configuração básica do ultimo post para cada serviço desaclopado.

O que está por vir

No próximo post, vamos fazer algumas validações com Yup antes de cadastrar usuários, e também escrever um swagger.

E pra facilitar o teste das nossas rotas, vamos configurar um Insomnia.

Setup inicial + Express

Vitor Silva Delfino — Sun, 10 Jan 2021 03:14:46 +0000

Olá, sou Vitor Delfino e como muitos de vocês que cairam aqui, sou um dev.

Faz um tempo que tenho a vontade de começar a escrever alguns posts, mas nunca tomava essa iniciativa. Que em 2021 seja um pouco diferente.

Bora lá !

Após diversos projetos criados, tanto profissionalmente quanto para aprendizado, cheguei a uma estrutura interessante de projetos com Node e decidi compartilha-lo em alguns posts.

O que eu costumo utilizar:

Node.js + Typescript
Typeorm
Jest

Com apenas isso, já é possível desenvolver muita coisa.
Maaaas, para deixar o projeto de exemplo um pouco mais profissional, algo parecido com o que encontrariamos em uma empresa, vou escrever um exemplo mais completo, com testes mocados, documentação com swagger, separação das variáveis por ambiente e utilizar recursos externos com Docker (mongoDb, Redis, Rabbit, etc...) que é algo que sempre senti falta nos tutorias.

Neste primeiro post, irei montar toda a estrutura das pastas e configurar o ESLint, Commitlint, tsconfig.json e algumas outras coisinhas.

Iniciando o projeto

Vamos lá, primeiramente criamos a pasta e inicializamos o projeto.

Eu costumo utilizar yarn.

mkdir example
cd example
yarn init -y
code .

E depois instalamos algumas dependências.

Plugins e mais plugins

Primeiramente instalo o eslint e o inicio com as seguintes opções.

yarn add eslint -D
yarn eslint --init

Como o eslint instala os pacotes utilizando npm, eu simplemente apago o arquivo package-lock.json e rodo o comando yarn.

E para incrementar as nossas regras, instalamos mais alguns plugins.

yarn add eslint-config-prettier eslint-import-resolver-typescript eslint-plugin-import-helpers eslint-plugin-prettier prettier typescript -D

E alteramos o eslint.json com as seguintes configurações.

{
    "env": {
        "es2021": true,
        "node": true
    },
    "extends": [
        "airbnb-base",
        "plugin:@typescript-eslint/recommended",
        "prettier",
        "prettier/@typescript-eslint"
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
        "ecmaVersion": 12,
        "sourceType": "module"
    },
    "plugins": [
        "@typescript-eslint",
        "prettier",
        "eslint-plugin-import-helpers"
    ],
    "rules": {},
    "settings": {
        "import/resolver": {
            "typescript": {
                "directory": "./tsconfig.json"
            },
            "node": {
                "paths": [
                    "src"
                ],
                "extensions": [
                    ".ts"
                ]
            }
        }
    }
}

Configurando alguns arquivos

Próximo passo, configuramos o tscofig.json, .prettierrc e .editorconfig

.preetierrc

{
  "singleQuote": true,
  "trailingComma": "es5",
  "prettier/prettier": [
    "error",
    {
      "endOfLine": "auto"
    }
  ]
}

tsconfig.json

{
  "compilerOptions": {
    "target": "es2017",
    "lib": [
      "es2019.array"
    ],
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "removeComments": true,
    "strict": true,
    "sourceMap": true,
    "allowJs": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "resolveJsonModule": true,
    "forceConsistentCasingInFileNames": true,
    "suppressImplicitAnyIndexErrors": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "@apps/*": [
        "./src/apps/*"
      ],
      "@config/*": [
        "./src/config/*"
      ],
      "@helper/*": [
        "./src/helper/*"
      ],
      "@middlewares/*": [
        "./src/middlewares/*"
      ],
      "@tools/*": [
        "./src/tools/*"
      ]
    },
    "typeRoots": [
      "./src/@types",
      "node_modules/@types"
    ]
  },
  "include": [
    "./src/**/*",
    ".vscode/@types"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "logs",
    "coverage"
  ]
}

Por enquanto, ignore o campo paths, irei explicar um pouco pra frente.

.editorconfig Veja mais detalhes sobre esse cara aqui

root = true

[*]
end_of_line = lf
indent_style = space
indent_size = 2
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

E até o momento temos a seguinte estrutura:

Geralmente o start de projetos é realmente chato, mas com o tempo isso vai ficando mais automático, e a gente acaba aproveitando muitas configurações de projetos anteriores.

Então vamos para um pouco de código.

Lets code!

Começamos instalando o necessário para a configuração do express e para o start da api.

Algumas libs que vamos utilizar.

express-async-errors
express-handler-errors Essa eu mesmo criei, para lidar de uma forma mais simplificada com os erros retornados pela API.
express-request-id para adicionar um uuid na request
continuation-local-storage para capturar o id da request nos serviços e nos logs
cors
dotenv para separação das environments
morgan-body para logar o conteúdo das requests
winston para logs

yarn add express cors dotenv continuation-local-storage express-async-errors express-handler-errors express-request-id morgan-body winston  && yarn add @types/express @types/cors @types/dotenv @types/node @types/winston @types/continuation-local-storage

O primeiro arquivo que eu começo escrevendo, é o arquivo que configura todas as variáveis de ambiente utilizada pela aplicação.

Fica na seguinte estrutura: /src/config/index.ts

E é aqui que utilizamos a lib dotenv

/src/config/index.ts

import { config } from 'dotenv';

/*
 * Aqui estamos dizendo para o dotenv
 * onde ele deve buscar as variáveis de ambiente
 * NODE_ENV será o stage da nossa aplicação [dev, qa, prod, local, etc...]
 */
const envfile = `.env.${process.env.NODE_ENV}`;
const envdir = process.cwd();

config({ path: `${envdir}/${envfile}` });

export const server = {
  port: process.env.PORT,
  env: process.env.NODE_ENV,
}

Até aqui, já podemos observar que o eslint está reclamando de algumas coisas, então vamos atualizar as configs.

adicione as regras no campo rules

eslintrc.json

"rules": {
    "prettier/prettier": "error",
    "global-require": "off",
    "no-new": "off",
    "no-console": "off",
    "import/prefer-default-export": "off",
    "import/extensions": [
      "error",
      "ignorePackages",
      {
        "js": "never",
        "ts": "never"
      }
    ],
    "import-helpers/order-imports": [
      "warn",
      {
        "newlinesBetween": "always", // new line between groups
        "groups": [
          "module",
          "/^@config/",
          "/^@apps/",
          "/^@services/",
          "/^@helper/",
          "/^@/",
          [
            "parent",
            "sibling",
            "index"
          ]
        ],
        "alphabetize": {
          "order": "asc",
          "ignoreCase": true
        }
      }
    ]
  },

Vamos escrever agora as configurações do winston

Esse vai ser nosso primeiro middleware.

src/middlwares/logger.ts

import { getNamespace } from 'continuation-local-storage';
import winston from 'winston';

const options = {
  console: {
    level: 'info',
    format: winston.format.combine(
      winston.format.colorize(),
      winston.format.simple()
    ),
    prettyPrint: true,
    colorize: process.stdout.isTTY,
  },
};

const logger = winston.createLogger({
  transports: [new winston.transports.Console(options.console)],
  exitOnError: false,
});

const formatMessage = (message: string) => {
  // É aqui que resgatamos o id da requisição que será armazenado em um storage
  const namespace = getNamespace('request');
  const id = namespace && namespace.get('id');
  return id ? `[${id}] ${message}` : message;
};

/**
 * aqui devolvemos os níveis do log
 * formatando a mensagem com o id da requisição caso exista
 */
export default {
  log: (message: string): winston.Logger => logger.info(message),
  info: (message: string, obj?: any): winston.Logger =>
    logger.info(formatMessage(message), obj),
  error: (message: string, obj?: any): winston.Logger =>
    logger.error(formatMessage(message), obj),
  warn: (message: string, obj?: any): winston.Logger =>
    logger.warn(formatMessage(message), obj),
  debug: (message: string, obj?: any): winston.Logger =>
    logger.debug(formatMessage(message), obj),
  silly: (message: string, obj?: any): winston.Logger =>
    logger.silly(formatMessage(message), obj),
};

E agora algumas configurações do express

src/app.ts

import { Namespace, createNamespace } from 'continuation-local-storage';
import cors from 'cors';
import express, {
  Application,
  NextFunction,
  Request,
  RequestHandler,
  Response,
} from 'express';
import { ErrorHandler } from 'express-handler-errors';
import morgan from 'morgan-body';

import logger from '@middlewares/logger';

class App {
  public readonly app: Application;

  private readonly session: Namespace;

  constructor() {
    this.app = express();
    this.session = createNamespace('request'); // é aqui que vamos armazenar o id da request
    this.middlewares();
    this.errorHandle();
  }

  /**
   * Aqui nos configuramos os middlewares
   */
  private middlewares(): void {
    this.app.use(express.json());
    this.app.use(cors());
    const reqId = require('express-request-id'); // essa lib não tem tipagem
    this.app.use(reqId());
    const attachContext: RequestHandler = (
      _: Request,
      __: Response,
      next: NextFunction
    ) => {
      this.session.run(() => next());
    };

    const setRequestId: RequestHandler = (
      req: Request,
      _: Response,
      next: NextFunction
    ) => {
      this.session.set('id', req.id);
      next();
    };
    // Toda vez que chegar um request, nós armazenamos o id dela em um storage
    this.app.use(attachContext, setRequestId);
    morgan(this.app, {
      noColors: true,
      prettify: false,
      logReqUserAgent: false,
      stream: {
        write: (msg: string) => logger.info(msg) as any,
      },
    });
  }

  /**
   * Aqui é a configuração da lib para tratar os error
   */
  private errorHandle(): void {
    this.app.use(
      (err: Error, _: Request, res: Response, next: NextFunction) => {
        new ErrorHandler().handle(err, res, next, logger as any);
      }
    );
  }
}

export default new App();

Por enquanto o arquivo fica assim, ainda adicionaremos algumas outras configurações.

E se repararmos no import de nossas dependências, conseguimos buscar as pastas utilizando @, é por conta da configuração dos paths no tsconfig.json

Mas ainda há um problema de tipagem nas configurações do express.

Por padrão, a interface Request do express não conhece o campo id que adicionamos nela. Então vamos sobrescrever essa interface.

/src/@types/express/index.d.ts

declare namespace Express {
  interface Request {
    id: string;
  }
}

No nosso tsconfig.json nós adicionamos o path /src/@types como um caminho para definição de tipos

tsconfig.json

...
"include": [
    "./src/**/*",
    ".vscode/@types"
  ],

Agora vamos configurar o arquivo que irá iniciar a nossa aplicação.

src/server.ts

import { server } from '@config/index';

import logger from '@middlewares/logger';

import express from './app';

express.app.listen(server.port, () => {
  logger.info('Server running', { port: server.port, mode: server.env });
});

Nossa aplicação está quase pronta para ser iniciada, mas como estamos utilizando typescript, precisamos transpilar todos os nossos arquivos, só assim o Node conseguirá entender o que queremos que ele execute.

E também tem um outro ponto, quando o transpilador encontrar um import nomeado com @middlewares/logger por exemplo, ele precisa entender exatamente onde buscar o arquivo.

Então utilizaremos mais duas bibliotecas para lidar com o build e transpile da aplicação.

Vamos aos downloads

yarn add @babel/cli @babel/core @babel/node @babel/plugin-proposal-class-properties @babel/plugin-proposal-decorators @babel/preset-env @babel/preset-typescript babel-eslint babel-plugin-module-resolver babel-plugin-transform-typescript-metadata ts-node-dev tsconfig-paths

E mais algumas configurações...

babel.config.js

module.exports = {
  presets: [
    ['@babel/preset-env', { targets: { node: 'current' } }],
    '@babel/preset-typescript',
  ],
  plugins: [
    'babel-plugin-transform-typescript-metadata',
    ['@babel/plugin-proposal-decorators', { legacy: true }],
    ['@babel/plugin-proposal-class-properties', { loose: true }],
    [
      'module-resolver',
      {
        // aqui que ensinamos ele onde buscar os imports
       // e também ja podemos ter uma ideia de como irá ficar nossa estrutura de pastas
        alias: {
          '@apps': './src/apps',
          '@config': './src/config',
          '@helper': './src/helper',
          '@middlewares': './src/middlewares',
          '@shared': './src/shared',
          '@tools': './src/tools',
          '@services': './src/services',
          '@utils': './src/utils',
        },
      },
    ],
  ],
  ignore: ['**/*.spec.ts'],
};

Vamos adicionar o script de start

package.json

...
"scripts": {
    "start:dev": "NODE_ENV=dev ts-node-dev -r tsconfig-paths/register --respawn --transpile-only --ignore-watch node_modules --no-notify src/server.ts"
}
...

Nesse momento, a aplicação já até pode ser iniciada utilizando o comando

yarn start:dev

Porém, nós não configuramos a porta que ficará escutando as requisições e também nenhuma rota.

Vamos lá!
Primeiro, nossa única variável de ambiente até o momento

.env.dev

PORT=3000

Agora, vamos configurar um arquivo de rotas e conecta-lo ao express

src/routes.ts

import { Request, Response, Router } from 'express';

import logger from '@middlewares/logger';

const route = Router();

route.get('/hello', (_: Request, res: Response) => {
  logger.info(`Request recebida`);
  res.json({ message: 'Hello World' });
});

export default route;

criaremos um método para plugar as rotas e chamaremos no construtor

src/app.ts

...

class App {
  public readonly app: Application;

  private readonly session: Namespace;

  constructor() {
    this.app = express();
    this.session = createNamespace('request'); // é aqui que vamos armazenar o id da request
    this.middlewares();
    // chamada do método
    // primeiro configuramos as rotas e depois o error handler
    this.routes();
    this.errorHandle();

  }

  ...

 /**
   * configuração de rota
   */
  private routes(): void {
    this.app.use('/api', routes);
  }
}

export default new App();

Agora se subirmos a api e chamarmos no navegador http://localhost:3000/api/hello, teremos o seguinte resultado

O que podemos notar no log do console:

o endoint que foi chamado Request: GET /api/hello at Sat Jan 09 2021 17:21:53 GMT-030
o log que adicionamos Request recebida
o que a nossa api devolveu Response Body:{"message":"Hello World"}
o id da requisição do inicio de toda linha logada fc410867-6fb3-4637-b771-7334c2f12781

O responsável por logar as informações do request é o Morgan que configuramos no arquivo src/app.ts

E como ficou a visão da request no navegador

Primeiro commit

Agora já estamos prontos para realizar o primeiro commit, mas antes disso, vamos escrever mais uma configuração.

Vamos usar o commitlint e o commitzen, para desde de o início todos os commits já seguir um padrão

Também vamos utilizar o husky para executar alguns scripts antes de cada commit. Por exemplo, no futuro antes de cada commit, vamos rodar a switch de testes para garantir que nada suba quebrado para o repositório.

Execute os camandos:

npx commitizen init cz-conventional-changelog --save-dev --save-exact

npm install --save-dev @commitlint/{cli,config-conventional} 

yarn add -D husky

rm -rf node_modules

yarn

Crie o arquivo commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
  'commit-msg': 'commitlint -E HUSKY_GIT_PARAMS',
};

Veremos que no arquivo package.json terá agora uma configuração nova.

"config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }

adicionamos também alguns scripts e a configuração do husky

{
  "name": "example",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "start:dev": "NODE_ENV=dev ts-node-dev -r tsconfig-paths/register --respawn --transpile-only --ignore-watch node_modules --no-notify src/server.ts",
    "commit": "git-cz" // um script para abrir uma interface de commit
  },
  "devDependencies": {
    ...
  },
  "dependencies": {
    ...
  },
  // configuração do husk
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }
}

E podemos fazer o primeiro commit.

Vamos inicializar o git e configurar .gitignore.

git init

.gitignore

node_modules

Note que se tentarmos escrever uma mensagem sem padrão no commit, receberemos um erro.

Leia mais sobre a convenção de mensagens aqui

Para facilitar escrever o commit, instalamos a lib commitzen

Vamos testa-la:

A lib nos oferece uma CLI no terminal, e fica bem mais fácil seguir o padrao de mensagens.

Considerações finais

Sei que esse primeiro post ficou realmente grande, mas espero ter conseguido detalhar bem o passo a passo da criação de uma api, um pouco mais robusta, com mais configurações, algo mais parecido com a vida real.

Até o momento, nossa estrutura de pastas está assim.

No próximo post, iremos configurar Typeorm para conectar com o banco de dados, e escrever o primeiro CRUD.

Meu github
Meu portfólio