Boas práticas de desenvolvimento - MarcosPiccoli/DotNetPractices GitHub Wiki

Práticas gerais

Aqui está documentado práticas gerais que melhoram principalmente a manutenção do sistema.

Utilizar o padrão RESTful

O padrão RESTful (Representational State Transfer) é um conjunto de diretrizes e princípios para o design de APIs (Interfaces de Programação de Aplicações) que utilizam os métodos HTTP de forma eficiente, escalável e padronizada. Embora o REST não seja uma tecnologia em si, ele define um conjunto de restrições que uma arquitetura de software deve seguir para ser considerada "RESTful". REST se baseia em princípios da web e visa criar sistemas distribuídos simples, escaláveis e de fácil manutenção.

Exemplo de uma API RESTful Simples: Imaginemos uma API para gerenciar usuários em um sistema:

  • GET /users: Retorna a lista de todos os usuários.
  • GET /users/{id}: Retorna um usuário específico pelo ID.
  • POST /users: Cria um novo usuário.
  • PUT /users/{id}: Atualiza um usuário existente (completo).
  • PATCH /users/{id}: Atualiza parcialmente um usuário.
  • DELETE /users/{id}: Exclui um usuário.

Implementação de logs

Adicionar logs na aplicação é uma prática fundamental principalmente por tornar possível o rastreamento dos erros. Seus níveis são:

  • DEBUG: Informações detalhadas para desenvolvimento e debugging.
  • INFO: Informações gerais sobre o funcionamento do sistema.
  • WARN: Avisos sobre situações que podem precisar de atenção, mas não são críticas.
  • ERROR: Erros que exigem correção, mas que não param o sistema.
  • FATAL: Erros críticos que causam falha no sistema ou que exigem intervenção imediata.

Http Codes

Tratar adequadamente os códigos HTTP em uma aplicação é uma boa prática por várias razões, e esse tratamento adequado impacta diretamente a confiabilidade, a segurança, a usabilidade e a manutenibilidade do sistema. Segue alguns exemplos:

Status de sucesso: (200 - 299)

  • 200: Sucesso
  • 201: Responsável por retornar que o recurso foi criado.
  • 204: Requisição foi realizada com sucesso mas não retorna nenhum body.

Status de erros no cliente: (400-499)

  • 401: Não está autenticado. (Precisa realizar o login)
  • 403: Não está autorizado a utilizar o sistema. (Seu acesso não tem permissão para acessar esse endpoint)
  • 424: Ocorreu uma falha de dependência. Exemplo: Minha API está fazendo uma requisição para uma API externa (como buscar CEP) e está indisponível

O ideal é utilizar o erro 500 ( erro interno do sistema ) somente para erros que não estão sendo tratados, como exemplo: erro de banco de dados indisponível

Para verificar demais códigos de resposta, acesse aqui.