DEV Community: Guilherme Camargo

Construindo uma API com Deno: Da instalação ao Deploy

Guilherme Camargo — Thu, 18 Jun 2020 21:47:06 +0000

Criei minha primeira API com Deno recentemente e decidi compartilhar tudo que aprendi sobre ele neste artigo.

Esta API é parte de um projeto open-source que estou desenvolvendo. Meu objetivo com ele é implementar um "e-commerce" seguindo a arquitetura de microservices, com a stack JS, e aprender outras tecnologias no processo. Todo o código que usei está no meu GitHub.

O que é o Deno

Deno ~~como todos já estão cansados de ouvir~~ é o novo runtime JS/TS, feito pelo mesmo criador do Node, Ryan Dahl. Ele possui fortes restrições de segurança, é construído com a linguagem Rust, em cima da V8 do Google e tem ~~uma meia~~ um dinossauro de mascote.

Instalação

Vou sair um pouco do convencional e mostrar uma alternativa pra instalar o Deno - ou qualquer outro runtime que queira.

asdf é um gerenciador de versão universal. Após instalá-lo com o guia oficial rode os seguintes comandos:

$ asdf plugin-add deno https://github.com/asdf-community/asdf-deno.git
$ asdf install deno 1.0.5
$ asdf global deno 1.0.5

Como estou usando a versão 1.0.5 nos exemplos, deixei fixo aqui, mas você pode repetir os últimos dois comandos com "latest" e usar a versão mais atual depois.

Para conferir se deu tudo certo é só rodar $ deno --version.

Setup Environment

VS Code extension

VS Code se tornou o ambiente padrão para muitas linguagens, acredito que JS/TS seja a maior delas. Já temos uma extensão criada pela equipe do Deno que nos dará um suporte melhor durante o desenvolvimento.

VS Code settings

Após instalar a extensão do Deno precisamos setar a versão do Typescript que o VS Code usa para a última versão. Se ainda não instalou - e considerando que você já tenha Node instalado na sua máquina - rode $ npm i -g typescript. Agora precisamos obter o caminho para os executáveis. No terminal rode $ npm list -g typescript, ele irá nos dizer o caminho até a pasta raiz onde o TS foi instalado, navegue até lá e vá para a pasta "lib", rode $ pwd, copie todo o caminho e cole na propriedade "typescript.tsdk" no settings.json global do VS Code ou do workspace.

No meu caso estou usando o settings do workspace com algumas outras configurações, recomendo usar as mesmas.

{
  "typescript.tsdk": "~/.asdf/installs/nodejs/12.18.0/.npm/lib/node_modules/typescript/lib",
  "[typescript]": {
    "editor.defaultFormatter": "vscode.typescript-language-features",
  },
  "deno.enable": true,
  "deno.unstable": true,
}

Variáveis de ambiente

O Deno usa uma pasta global na sua máquina para salvar algumas coisas. Caso não tenha sido criada ainda rode $ mkdir -p ~/.deno/bin. Este será o caminho onde ficará alguns executáveis que instalaremos com o Deno. Agora precisamos que nosso terminal olhe para esta pasta quando for procurar pelos binários. Abra o arquivo de configuração do seu terminal (.bashrc, .zshrc, ...) e cole isso no início do arquivo.

export DENO_DIR=$HOME/.deno
export PATH=$PATH:$DENO_DIR/bin

Recomendo que feche e abra uma nova instância do terminal para que reflita as alterações.

Typescript

O projeto será full typescript. Você pode usar JS puro se preferir, mas prefiro TS, gosto muito do tooling que ele me dá e ele me ajuda a evitar erros bobos. Além disso, TS é a linguagem recomendada para desenvolver com Deno.

Apesar de não ser necessário geralmente, neste projeto iremos utilizar decorators e para isso precisamos dizer ao TS para aceitar essa sintaxe. Para isso temos que criar o arquivo tsconfig.json dentro da pasta src.

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Estrutura do projeto

Esta API será responsável por cadastrar as avaliações dos usuários para os produtos que eles comprarem.

Só teremos duas rotas:

POST /ratings
GET /ratings

A estrutura final do projeto será esta:

.
├── .env
├── .env.example
├── .vscode
│   ├── launch.json
│   └── settings.json
├── Dockerfile
├── denon.json
├── docker-compose.yml
└── src
    ├── controllers
    │   └── rating.controller.ts
    ├── database
    │   ├── connection.ts
    │   ├── entities
    │   │   ├── buyer.entity.ts
    │   │   ├── product.entity.ts
    │   │   └── rating.entity.ts
    │   └── repositories
    │       ├── buyer.repository.ts
    │       ├── product.repository.ts
    │       └── rating.repository.ts
    ├── deps.ts
    ├── env.ts
    ├── routes.ts
    ├── server.ts
    └── tsconfig.json

Framework Web

O Deno tem uma ótima standard library, porém não queremos trabalhar com a classe de http diretamente, pois teríamos que fazer muita coisa na mão, é por isso que usamos frameworks. No Node o comum é o express, no Deno o framework mais estável e com mais uso até o momento é o oak - ele é baseado no koa ~~pessoal do Deno adoram fazer anagramas~~.

A primeira coisa que precisamos criar é o arquivo server.ts, que será o arquivo de entrada para a aplicação.

import { Application } from 'https://deno.land/x/oak/mod.ts'

const app = new Application();
const port = 8001

console.log(`Running on port ${port}`);
await app.listen({ port: port});

Agora podemos rodar usando $ deno run --allow-net server.ts.

Imports

A primeira coisa que vemos de diferente em comparação com o Node é que no Deno usamos ES Modules ao invés do CommonJS e estamos dando import de uma URL direto no nosso código. Isso pode parecer meio estranho - Deno se inspirou na linguagem Go neste aspecto - porém no browser isso sempre foi comum. É como a tag script do HTML funciona: <script src="URL">

node_modules / package.json

Então se estamos importando as dependências via URL, toda vez que quisermos rodar a aplicação teremos de ter acesso à internet?
Não!

Assim que usamos uma nova dependência o Deno baixa o código desta URL para um cache em uma pasta global na sua máquina - o caminho padrão é ~/.deno/deps/https. Na próxima vez que rodarmos esta aplicação, ou outra que tenha a mesma dependência, o Deno irá obter a dependência desta pasta.

Dito isso, não precisamos mais de uma pasta na raiz do nosso projeto como o node_modules. Se, por exemplo, temos duas APIs com Deno que usam a mesma versão do oak, não teremos ele duplicado duas vezes na nossa máquina.

Como não instalamos as dependências, só fazemos referência, também não precisamos mais do arquivo package.json. A única coisa que precisamos é do próprio arquivo JS/TS.

deps.ts

O ponto ruim de fazer referência via URL é que, dependendo do tamanho do projeto, você ficará com URLs espalhadas por toda a aplicação. E caso queira atualizar uma dependência para outra versão, remover ou até mesmo saber quais libs estão sendo usadas, você não terá isso em um ponto centralizado.

Pensando nisso podemos centralizar essas referências em um arquivo e importar o que precisamos deste arquivo.

Dentro de src crie o arquivo deps.ts

export { 
  Application,
  Router,
  Context
} from "https://deno.land/x/oak/mod.ts"

Top level await

Outra coisa interessante que estamos usando é await sem uma função async. Deno tem esta feature graças ao V8, onde podemos usar await direto na raiz do arquivo.

Denon

Assim como no Node usamos o Nodemon para que a aplicação reinicie toda vez que um arquivo é alterado, no Deno usamos o denon. Após instalá-lo seguindo o readme, vamos criar um arquivo chamado denon.json na raiz do projeto. Ele é muito útil, podemos fazer varias configurações de como nossa aplicação deve rodar.

{
  "$schema": "https://deno.land/x/denon/schema.json",
  "allow": [
    "env",
    "net"
  ],
  "tsconfig": "src/tsconfig.json",
  "unstable": true,
  "scripts": {
    "start": {
      "cmd": "src/server.ts"
      "env": {
        "APP_PORT": "8001",
      }
    }
  },
  "logger": {
    "debug": true
  }
}

allow é onde damos as permissões do que o Deno pode executar na nossa máquina.
tsconfig é pra dizermos pro Deno considerar nossas configurações extras do TS;
unstable pois nem todas as funcionalidades do deno e de algumas libs estão prontas;
scripts é onde criamos configurações específicas. Podemos dar qualquer nome, coloquei start por convenção mesmo;
cmd temos só nome do arquivo de entry-point para aplicação, mas ele irá executar $ deno run... antes;
env para exportar variáveis de ambientes que só esta aplicação irá usar;
logger para termos um log mais detalhado no terminal;

Assim que rodarmos $ denon start você notará que o que ele realmente executa é $ deno run --allow-env --allow-net --config src/tsconfig.json --unstable src/server.ts. Imagina ter que lembrar e digitar tudo isso toda vez? Denon é opcional, mas extremamente útil.

Debuging

Pra melhorar ainda mais nossa experiência com Deno podemos debugar a aplicação pelo VS Code.

Basta criar o arquivo .vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Deno",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "deno",
      "runtimeArgs": [
        "run",
        "--unstable",
        "--config",
        "src/tsconfig.json",
        "--inspect-brk",
        "-A",
        "src/server.ts"
      ],
      "port": 9229
    }
  ]
}

Camada de dados

TypeORM

Acho ORM uma ferramenta indispensável. Trabalhar direto com SQL no código - além de deixar tudo mais sujo, extenso e complexo - abre brechas de segurança e possibilidade de vários bugs. ORMs encapsulam toda essa complexidade e nos oferecem uma interface simples, testada e a possibilidade de usar a mesma estrutura da linguagem com o restante da aplicação.

Não foi fácil encontrar um ORM que funcionasse direito no Deno, testei alguns e o que acabei mais gostando foi um fork do TypeORM que já existia no Node.

Dentro do arquivo deps.ts vamos adicionar esta nova dependência

export { 
  createConnection, 
  Connection, 
  Entity, 
  PrimaryGeneratedColumn, 
  Column, 
  OneToMany,
  ManyToOne,
  Repository
} from "https://denolib.com/denolib/typeorm@v0.2.23-rc4/mod.ts";

Até o momento da publicação deste artigo este fork está em release candidate ainda, muitas coisas podem não funcionar corretamente. Paciência você deve ter.

Entities

A primeira coisa que devemos fazer é criar as entidades. Dentro da pasta src/database/entities crie os seguintes arquivos

buyer.entity.ts

import { Entity, PrimaryGeneratedColumn, Column, OneToMany } from "../../deps.ts";
import Rating from "./rating.entity.ts";

@Entity("buyers")
export default class Buyer {

  @PrimaryGeneratedColumn()
  id!: number;

  @Column({ type: "varchar", length: 256 })
  fullName!: string;

  @OneToMany(type => Rating, _ => _.buyer)
  ratings!: Rating[];
}

product.entity.ts

import { Entity, PrimaryGeneratedColumn, Column, OneToMany } from "../../deps.ts";
import Rating from "./rating.entity.ts";

@Entity("products")
export default class Product {

  @PrimaryGeneratedColumn()
  id!: number;

  @Column({ type: "varchar", length: 256 })
  name!: string;

  @OneToMany(type => Rating, x => x.product)
  ratings!: Rating[];
}

rating.entity.ts

import { Entity, PrimaryGeneratedColumn, Column, ManyToOne } from "../../deps.ts";
import Product from "./product.entity.ts";
import Buyer from "./buyer.entity.ts";

@Entity("ratings")
export default class Rating {

  @PrimaryGeneratedColumn()
  id!: number;

  @Column({ type: "int" })
  rate!: number;

  @Column({ type: "text" })
  comment!: string;

  @ManyToOne(type => Product, _ => _.ratings)
  product!: Product;

  @ManyToOne(type => Buyer, _ => _.ratings)
  buyer!: Buyer;
}

Como pode ver, toda configuração referente ao banco de dados é feita com decorators dentro do TypeORM. Isso é muito legal pois podemos utilizar a mesma classe em outro cenários sem sujá-la com propriedades referente a como os dados estão armazenados.

O decorator @Entity() torna nossa classe uma tabela dentro do banco, caso queira você pode dizer o nome que esta tabela terá;
@PrimaryGeneratedColumn diz que o campo id é a chave-primária e será auto-incrementável;
Com @Column() fazemos as configurações que a coluna terá no banco;
Para fazer relacionamento no TypeORM mantemos um campo com o tipo da classe relacionada como referência e usamos o decorator OneToOne(), OneToMany(), ManyToOne() ou ManyToMany() neste campo. Sempre lembrando de fazer tanto a ida quanto a volta para ambas as entidades. Repare que na entidade Rating não criamos a foreign key para Product nem Buyer, o TypeORM faz isso pra gente e nos deixa trabalhar direto com a classe. Muito massa isso 😃

Há diversos outros decorators e opções para os mais diversos cenários dentro do TypeORM. Recomendo olhar a documentação para casos mais complexos.

Connection

Entidades criadas, agora vamos criar a conexão com o banco.

Dentro da pasta src/database crie o arquivo connection.ts com essas configurações:

import { createConnection, Connection } from "../deps.ts";

import Buyer from "./entities/buyer.entity.ts";
import Product from "./entities/product.entity.ts";
import Rating from "./entities/rating.entity.ts";
import env from "../env.ts";

class RatingConnection {

  connection!: Connection;

  async connect() {
    try {
      this.connection = await createConnection({
        type: "postgres",
        host: env.DB_HOST,
        port: env.DB_PORT,
        username: env.DB_USERNAME,
        password: env.DB_PASSWORD,
        database: env.DB_DATABASE,
        entities: [
          Rating,
          Product,
          Buyer,
        ],
        synchronize: true,
        logging: true,
      });

      return this.connection;

    } catch (err) {
      console.error(err);
    }
  }
}

export default new RatingConnection();

syncroniz irá deixar o banco igual nossas entidades, criando as tabelas e removendo as que não existem;
logger para vermos as queries que a aplicação fará no terminal;

Irei falar sobre postgres e o env.ts logo abaixo.

Repositories

Com TypeORM conseguimos usar um query-builder muito poderoso, podemos fazer queries complexas com código JS/TS. Fazemos essas queries a partir da connection, porém o TypeORM oferece a opção de criar um repository padrão com muitos métodos comuns. A partir da connection chamamos o método getRepository passando o tipo da Entity no parâmetro. Isso irá retornar um novo objeto do tipo Repository<TEntity> que possui métodos como: getId, create, update, delete, find, findOne, entre outros.

Dentro da pasta src/database/repositories vamos criar os seguintes arquivos:

buyer.repository.ts

import { Repository } from '../../deps.ts';
import RatingConnection from '../connection.ts';
import Buyer from '../entities/buyer.entity.ts';

class BuyerRepository {

  private _instance: Repository<Buyer> | undefined;

  get instance() {
    if (!this._instance) {
      this._instance = RatingConnection.connection?.getRepository(Buyer);
    }

    return this._instance;
  }
}

export default new BuyerRepository();

product.repository.ts

import { Repository } from '../../deps.ts';
import Product from '../entities/product.entity.ts';
import RatingConnection from '../connection.ts';

class ProductRepository {

  private _instance: Repository<Product> | undefined;

  get instance() {
    if (!this._instance) {
      this._instance = RatingConnection.connection?.getRepository(Product);
    }

    return this._instance;
  }
}

export default new ProductRepository();

rating.repository.ts

import { Repository } from '../../deps.ts';
import Rating from '../entities/rating.entity.ts';
import RatingConnection from '../connection.ts';

class RatingRepository {

  private _instance: Repository<Rating> | undefined;

  get instance() {
    if (!this._instance) {
      this._instance = RatingConnection.connection?.getRepository(Rating);
    }

    return this._instance;
  }
}

export default new RatingRepository();

Basicamente estamos criando uma classe com um método singleton que irá retornar uma instância do repository.

No TypeORM podemos usar o decorator @EntityRepository(TEntity) para criar esses repositories de maneira automática, porém essa versão apresentou alguns problemas. Uma alternativa seria usar uma lib de dependency injection, mas não vi a necessidade disso pra este projeto.

Controllers

Camada de dados pronta, agora vamos criar os endpoints.

Dentro da pasta src/controllers crie o arquivo rating.controller.ts.

import { Context } from "../deps.ts";
import RatingRepository from '../database/repositories/rating.repository.ts';
import BuyerRepository from '../database/repositories/buyer.repository.ts';
import ProductRepository from '../database/repositories/product.repository.ts';
import Rating from '../database/entities/rating.entity.ts';

class RatingController {

  async index({ response }: Context) {

    const ratings = await RatingRepository.instance
      .createQueryBuilder('ratings')
      .select(['ratings', 'product.name', 'buyer.fullName'])
      .leftJoin('ratings.product', 'product')
      .leftJoin('ratings.buyer', 'buyer')
      .getMany();

    response.body = {
      success: true,
      data: ratings.map((rating: Rating) => {
        return {
          id: rating.id,
          comment: rating.comment,
          rate: rating.rate,
          buyer: rating.buyer.fullName,
          product: rating.product.name
        }
      })
    };
  }

  async create({ response, request }: Context) {
    const body = await request.body();
    const { comment, rate, buyerId, productId } = body.value;

    if (rate < 0 || rate > 5) {
      response.status = 400;
      response.body = {
        success: false,
        message: 'invalid rate'
      }

      return;
    }

    const product = await ProductRepository.instance.findOne(productId)
    const buyer = await BuyerRepository.instance.findOne(buyerId);

    if (!product || !buyer) {
      response.status = 404;
      response.body = {
        success: false,
      }

      return;
    }

    const rating = new Rating();
    rating.buyer = buyer;
    rating.product = product;
    rating.comment = comment;
    rating.rate = rate;
    await RatingRepository.instance.save(rating);

    response.status = 201;
    response.body = {
      success: true,
      data: rating
    }
  }
}

export default new RatingController();

Primeiro importamos os repositories. O método index irá retornar um array de Rating, a partir do RatingRepository fazemos a query dando join nas tabelas relacionadas e select nos campos que iremos usar. O método create irá cadastrar um novo Rating, após pegar os dados do body fazemos uma validação, depois pegamos as entidades relacionadas e, caso não forem nulas, salvamos um novo Rating. Bem simples.

Rotas

Agora dentro de src crie router.ts

import { Router } from './deps.ts'

import RatingController from './controllers/rating.controller.ts';

const router = new Router();

router
  .get('/ratings', RatingController.index)
  .post('/ratings', RatingController.create);

export default router;

Server.ts

Fizemos várias alterações. Agora precisamos voltar ao server.ts e atualizá-lo com as novas classes.

import { Application } from './deps.ts'
import env from './env.ts';
import router from './routes.ts'
import RatingConnection from './database/connection.ts';

await RatingConnection.connect();

const app = new Application();

app.use(router.routes());
app.use(router.allowedMethods());

console.log(`Running on port ${env.APP_PORT}`);
await app.listen({ port: env.APP_PORT_INTERNAL || env.APP_PORT });

Deploy

.env

Toda aplicação tem dados sensíveis que mudam de ambiente para ambiente. É prática comum exportar esses valores quando rodamos a aplicação e obtê-los durante o runtime. Para sabermos quais dados devemos passar criamos um arquivo chamado .env.example.

# Application
APP_PORT=
APP_PORT_INTERNAL=
APP_ENVIRONMENT=

# Database
DB_HOST=
DB_PORT=
DB_USERNAME=
DB_PASSWORD=
DB_DATABASE=

Com esse template copiamos todos as variáveis e criamos outro arquivo chamado .env com os devidos valores. Não devemos versionar este último, ele deve existir somente no ambiente na qual a aplicação irá rodar.

Podemos também passar esses valores dentro da chave env do denon.json ou usar alguma lib que lê este tipo de arquivo e o carrega no environment do runtime.

Dockerfile

Docker é uma das ferramentas mais usadas no desenvolvimento de software atualmente. Me atrevo a dizer que saber Docker hoje em dia é quase tão importante quanto saber Git. Ele é muito prático e nos ajuda em várias coisas.

Não existe uma imagem oficial do Deno até o momento, o mais próximo disso é esta imagem que está sendo cogitada nas issues do GitHub.

FROM hayd/deno:alpine-1.0.5

EXPOSE 3333

WORKDIR /app

USER deno

COPY src/deps.ts /app
RUN deno cache --unstable deps.ts

ADD /src /app
RUN deno cache -c tsconfig.json --unstable server.ts

CMD ["run", "--allow-env", "--allow-net", "--config", "tsconfig.json", "--unstable", "server.ts" ]

Cada comando no Docker é como uma camada, onde a anterior se torna a base para as próximas. Com isso em mente:

Primeiro obtemos a imagem base com FROM. Estamos usando a versão alpine, que é uma versão mais leve do linux. Estamos usando a versão 1.0.5 do Deno também. É boa prática sempre dizer a versão que sua aplicação usa para não atualizar de uma hora pra outra e, possivelmente, quebrar o sistema;
Em seguida expomos a porta 3333 onde podemos receber requisições;
WORKDIR é basicamente um $ cd dentro do container. Ele cria a pasta, caso ainda não exista;
Mudamos de usuário root com USER;
Aqui um ponto importante. Copiamos o arquivo deps.ts e fazemos o cache dele. Este comando só será executado novamente caso as dependências mudem;
Depois copiamos o restante da pasta src para dentro do container e cacheamos o server.ts para que não seja compilado toda vez que rodarmos uma nova instância do container.
E por último, CMD irá executar os argumentos dentro do array toda vez que o container for iniciado.

Fazendo uma analogia com OOP: O Dockerfile é como uma classe - onde definimos o shape que nosso container terá - e o container é o objeto instanciado.

docker-compose

Para instanciar um container precisamos passar diversos argumentos pelo terminal. Lembrando também que um sistema geralmente não funciona sozinho - no BackEnd, por exemplo, temos a aplicação e o banco de dados. Pra conectar ambos pelo docker precisamos criar uma network. No caso do banco de dados, precisamos passar o volume para manter os dados persistidos. Além disso podemos passar as variáveis de ambiente, expor portas, entre outras coisas.

Para gerenciar tudo isso temos o docker-compose. Sua função é configurar todos os containers que precisamos, com todos os argumentos, e conectá-los.

Iremos criar dois containers

app que fará o build da aplicação e configurar seus parâmetros de entrada;
database onde iremos configurar um banco de dados da nossa escolha. No meu caso escolhi o postgres, mas pode ser qualquer outro de sua preferência. Só lembre de alterar o type no arquivo connection.ts caso mude de banco;

version: "3.1"

services:
  app:
    build: .
    env_file:
      - .env
    restart: always
    environment: 
      APP_PORT: ${APP_PORT}
      APP_PORT_INTERNAL: 3333
      DB_HOST: ${DB_HOST}
      DB_PORT: 5432
      DB_USERNAME: ${DB_USERNAME}
      DB_PASSWORD: ${DB_PASSWORD}
      DB_DATABASE: ${DB_DATABASE}
    ports:
      - ${APP_PORT}:3333
    depends_on: 
      - database
  database:
    image: postgres
    env_file:
      - .env
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_DATABASE} 
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - ${DB_PORT}:5432
    volumes:
      - "ec.rating.data:/var/lib/postgresql/data"

volumes:
  ec.rating.data:

Em app:

Primeiro dizemos em qual diretório o Dockerfile se encontra. Como está no mesmo do docker-compose.yml, utilizamos .;
env_file irá ler o .env e carregar os valores pra dentro do container. Usamos a sintaxe ${...} para obter esses valores;
restart caso o container pare queremos que ele reinicie sem precisar de intervenção humana;
environment passamos para a aplicação todas as variáveis de ambiente que ela precisará;
ports mapeamos a porta do nosso host para dentro do container;
depends_on para que o app suba após o database. Isso irá evitar o erro do app subir primeiro e tentar conectar com o database que ainda não existe;

Em database:

image base do postgres disponível no DockerHub
(...) mesma coisa do app
Como um container não mantêm estado precisamos mapear um diretório do host para dentro do container. Fazemos isso através dos volumes. Assim, independente de qual container esteja rodando, isso manterá os arquivos salvos já que ele sempre olhará para a mesma pasta.

Quando criamos containers pelo docker-compose eles fazem parte automaticamente da mesma network. Dentro do app, por exemplo, podemos fazer referência ao database pelo seu alias.

A imagem do app não irá compilar a menos que você diga. Antes de mais nada rode $ docker-compose build app para que a imagem seja criada. Feito isso é só rodar $ docker-compose up e deve estar tudo funcionando :).

Testando os endpoints

Eu costumo utilizar o Insomnia para fazer requisições http, mas qualquer um serve.

GET

Utilizando a porta dentro do .env, fazemos uma requisição GET para http://localhost:$PORT/ratings e ele deve retornar um json com esta mesma estrutura:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "comment": "best console",
      "rate": 4,
      "buyer": "Bruce Wayne",
      "product": "PS4"
    },
    {
      "id": 2,
      "comment": "xbox one is better",
      "rate": 2,
      "buyer": "Bruce Wayne",
      "product": "PS4"
    }
  ]
}

POST

Agora para criar um novo registro envie uma requisição POST para a mesma URL. Com um body nessa estrutura:

{
    "comment": "new rate",
    "rate": 4,
    "productId": 1,
    "buyerId": 1
}

A resposta deve ser algo parecido com isso:

{
  "success": true,
  "data": {
    "buyer": {
      "id": 1,
      "fullName": "Bruce Wayne"
    },
    "product": {
      "id": 1,
      "name": "PS4"
    },
    "comment": "new rate",
    "rate": 4,
    "id": 3
  }
}

AWS

Irei publicar este projeto na AWS, porém como estamos usando Docker, qualquer provedor irá servir e a mudança na publicação é mínima.

Instale o AWS CLI na sua máquina, configure seu acesso pelo terminal e instale o docker-machine. Agora, se foi tudo configurado certo, rodamos $ docker-machine create --driver amazonec2 aws01 e isso irá criar e configurar uma máquina com tudo que precisamos para rodar os containers na AWS. Se rodarmos $ docker-machine env aws01 iremos ver alguns valores referentes a máquina criada. Na última linha terá um comando como este: $ eval $(docker-machine env aws01). Assim que rodá-lo o CLI do Docker irá referenciar esta máquina remota como o Host, desta forma podemos rodar $ docker-compose up -d e isso criará toda a aplicação e o banco de dados neste servidor. Feito isso é só liberar as portas no Dashboard da AWS e pronto.

Para voltar a referenciar sua máquina como host no Docker rode $ eval $(docker-machine -u).

Com Docker conseguimos criar todo um ambiente de maneira automatizada e fazer o Deploy de maneira muito simples. O próximo passo seria criar um processo de CI/CD e fazer este deploy de maneira automática também.

Considerações finais

Vimos neste artigo a criação de uma API com Deno de ponta-a-ponta utilizando práticas de uma aplicação real.

Dado esta experiência posso concluir que Deno é uma promessa para um futuro próximo ainda. Definitivamente não recomendo criar nenhuma aplicação para produção com ele! Mas como bons programadores que somos, é muito legal aprender sobre algo novo, testar e ver tudo funcionando no final. Quem sabe daqui 1 ou 2 anos estaremos com um ambiente estável e discutindo sobre novas features dele. Quem quiser contribuir com a comunidade, este é o melhor momento.

Aprenda, teste e ensine.
DEVELOPERS TOGETHER STRONG

Implementando Domain-Driven Design

Guilherme Camargo — Wed, 22 Apr 2020 12:53:44 +0000

Após vermos os conceitos do DDD com os Strategic Patterns, está na hora de ver algum código. Neste artigo abordarei os Tactical Patterns.

Tactical Patterns

O objetivo dos Tactical Patterns é gerenciar a complexidade e garantir a expressividade do Domain Model.

Eric Evans agrupou alguns Design Patterns (Building Blocks) em seu livro, que são um conjunto de boas práticas em torno dos princípios de OOP. Todos esses patterns já existiam antes de Evans os agrupar e não são exclusivos do DDD, porém Evans conseguiu consolidá-los de tal maneira que se tornaram uma ferramenta poderosa quando queremos criar um design rico e expressivo em domínios complexos.

Entity

Uma Entity é um objeto que mantém um ciclo de vida independente do seu estado atual. Seus atributos podem mudar, porém podemos sempre identificá-las por algum campo específico, como um número inteiro ou um GUID, por exemplo.

Vamos pegar de exemplo uma cesta de compras de um e-commerce. Após criarmos uma Entity Basket ela naturalmente passará por mutação, o valor total, quantidade de itens e outros campos podem receber outros valores, porém sempre saberemos diferenciá-la pelo seu Id.

Em uma modelagem Table Oriented, onde cria-se classes com objetivo de representar tabelas em um banco relacional, deixa-se de considerar sua representatividade para o domínio, onde essas classes anêmicas são simplesmente sacolas de dados.

Você deve ser capaz de criar todo o seu domínio e testá-lo sem sequer saber qual banco de dados irá usar, seja relacional ou NoSQL.

A Entity é uma das peças fundamentais no nosso Domain Model e devemos criá-la exclusivamente para satisfazê-lo. Ela é composta não apenas por atributos primitivos (int, float, string...), mas também por outras Entities e objetos complexos - Value Objects.

É importante mantermos sua consistência. Em linguagens orientadas a objeto devemos tornar seus atributos privados de modo a blindá-los de modificações externas. Isso vai garantir que toda a mudança de estado passe por um método que aplicará possíveis regras.

A própria Entity deve saber se construir. É uma má-pratica não ter um construtor neste caso, pois se deixamos classes externas criar objetos sem considerar suas regras, eventualmente iremos ter objetos inconsistentes.

Quando temos comportamento correspondente a uma Entity, quem melhor para tratá-los do que ela mesma? É comum em modelagens anêmicas deixar todo o comportamento para classes externas, porém acabamos somente quebrando a classe em N pedaços e dividindo sua responsabilidade. Se algo do mundo real tem estado e comportamento, uma Entity deve representá-lo fielmente.

Value Object

Diferentemente da Entity, um Value Object é definido por seus atributos.

Tome o clássico exemplo da classe Money. O que difere duas instâncias com o mesmo valor? Nada! Eles não mantêm um ciclo de vida, sendo criados, utilizados e descartados! Também são plenamente substituíveis por outro objeto do mesmo tipo e valor.

Value objects são imutáveis por definição. Assim como no mundo real você não consegue transformar R$ 5,00 em R$ 50,00, Value Objects também não permitem esta mudança. Para conseguir um novo valor devemos criar uma nova instância de seu tipo, nunca alterar seus atributos internos.

Uma Entity pode ser composta por N Value Objects. Como Value Objects não mantêm estado, não temos como identificá-los no banco de dados, portanto devemos persisti-lo junto a Entity, nunca separado.

Em bancos de dados orientado a documentos podemos salvá-lo dentro do mesmo objeto. Em bancos de dados relacionais podemos usar um ORM para mapear esses objetos para colunas específicas.

Domain-Service

Quando temos um comportamento não atrelado a uma Entity ou Value Object, podemos representá-lo como um Domain Service.

Domain Service tem as seguintes características:

Não mantêm estado
Não tem rastreabilidade
Podem receber Entities e Value Objects como parâmetro
Podem ter dependências de interfaces para serviços externos
Executam alguma regra de negócio.

Tome como exemplo o cálculo de taxa de envio de um pedido. Ele deve considerar os itens do carrinho, o peso de cada item e a distância do endereço de entrega. Logo, percebemos que toda essa lógica não se encaixa em nenhuma Entity ou Value Object. Um Domain Service é perfeito neste caso.

É importante mantermos a Ubiquitous Language sempre em mente e aplicá-la aqui também, tanto no nome da classe e funções, quanto internamente - em nome de variáveis, por exemplo. Você pode pedir para uma pessoa de negócio explicar toda a regra e traduzir esse entendimento para o código. Assim se algo estiver faltando você facilmente conseguirá descrever o algoritmo para o domain expert e receber um feedback de possíveis inconsistências.

Aggregate

Para expressar uma ideia no código é comum ter uma árvore de classes que se relacionem e possuem dependências uma da outra. Porém, conforme o Domain Model se expande esta árvore acaba se tornando muito extensa e com várias ramificações. Isso dificultará seu carregamento do banco de dados, suas invariâncias ao fazer alterações e problemas de concorrência.

Com Aggregates conseguimos diminuir a complexidade de objetos grandes para pequenos grupos de classes que devem ter operações atômicas.

Uma operação atômica é uma ação que ocorre completamente independente de outro processo. Uma transaction num banco de dados relacional segue esse princípio. Assim que você inicia uma transaction, nenhum outro processo poderá ler ou gravar um novo valor até que o processo anterior seja finalizado, desta forma se garante a consistência da operação e dos dados.

Um Aggregate se comporta como uma única unidade em memória, tendo sempre uma Entity principal que será o Aggregate Root e a partir dela teremos acesso a outras Entities e Value Objects. Aggregates podem se relacionar mantendo o Id de outro Aggregate em seus atributos, mas nunca uma referência para outro objeto Aggregate.

Essa divisão deve seguir os conceitos do domínio e não apenas agrupar dados. Pense em suas invariâncias. Um Address só pode ser alterado se soubermos a quem ele pertence, então não faz sentido Address ser um objeto isolado já que ele está fortemente acoplado com Customer. Por sua vez, Customer é uma Entity forte, dado que conseguimos outras informações através dela. Neste cenário faz sentido termos um Aggregate chamado Customers, sendo a Entity Customer seu Aggregate Root.

Em bancos orientado a documentos temos a facilidade de poder persistir um Aggregate por documento e obtê-lo de uma única vez.



FakeCommerce.Store.Shopping.Domain
├── Baskets
│   ├── Basket.cs
│   ├── BasketItem.cs
│   └── Coupon.cs
├── Customers
│   ├── Address.cs
│   ├── CreditCart.cs
│   └── Customer.cs
└── Products
    ├── Price.cs
    ├── Product.cs
    └── Size.cs

Factory

Se um Aggregate é suficientemente complexo para ser construído podemos usar o pattern Factory. Ele é um dos patterns originais do GOF. Seu objetivo é criar objetos respeitando suas invariâncias, ou seja, ele só criará objetos que respeitem certas regras e estejam em estado válido.

Por padrão, devemos usar o método construtor presente em muitas linguagens. Uma Factory é útil somente em ocasiões em que o construtor fica sobrecarregado com regras, ou quando temos mais de uma maneira de construir o objeto.

Repository

Agora que temos os objetos organizados por Aggregates precisamos de um meio para persistí-los e hidratá-los. O pattern Repository é um dos mais conhecidos e seu objetivo é abstrair o acesso a dados da camada de domínio. Ele se comporta como uma coleção de dados em memória. Para quem está consumindo é transparente, além de não criar acoplamento com o meio de persistência.

Devemos ter um Repository por Aggregate. Como o Aggregate se comporta como uma unidade, não faz sentido ter um Repository para cada classe dele, faz mais sentido persistir e hidratar esses objetos juntos.

O uso de Repositories acaba sendo extrapolado em alguns casos. Ele é bastante útil quando precisamos hidratar os dados na camada de domínio e para reaproveitar operações comuns, porém seu uso não é obrigatório. Se você precisa extrair um relatório do sistema ou obter dados, formatar e enviar através de uma API, por exemplo, um Repository acaba não ajudando muito, pois não se torna tão flexível. É importante mantermos o senso crítico e somente usá-lo quando trazer algum benefício.

Para usá-lo adequadamente basta criar uma interface na pasta do Aggregate e definir os métodos. Lembre-se de usar a Ubiquitous Language e evitar o nome do pattern na camada de domínio. Eu geralmente crio as interfaces com o nome do Aggregate no plural, ICustomers, por exemplo, assim indico o seu comportamento (uma coleção em memória) sem sujar a linguagem.

Agora, com Dependency Inversion, podemos receber esta interface pelo construtor sem conhecer sua implementação que está na camada de infraestrutura.

Domain-Event

Domain Events são muito úteis quando queremos propagar ações ocorridas dentro do Domain Model.

Esse pattern se dá na criação de uma classe POCO com os dados que queremos propagar. Todo o Domain Event lançado já aconteceu, refletindo o passado. Events são imutáveis, já que uma vez que este evento ocorreu não tem como voltar e alterá-lo. Eles seguem o princípio Fire and Forget, já que uma vez lançado não temos mais controle de quem irá receber, podendo ser uma ou mais classes, devido a isso também eles não possuem nenhum retorno.

Temos algumas maneiras de implementá-lo:

Se o Domain Event será somente de uso interno - dentro do mesmo Bounded Context, podemos usar uma biblioteca como MediatR. Ela já possui uma interface chamada INotification que será aplicada no Domain Event e outra INoficationHandler que será aplicada em quem esta ouvindo este evento. Assim toda vez que você disparar um novo Domain Event todos os Handlers irão ser chamados imediatamente, pois tudo isso acontece em memória dentro do mesmo processo.
Se o Domain Event se propaga para outros Bounded Contexts podemos usar uma solução mais robusta, como o RabbitMQ, por exemplo. Com ele não precisamos criamos acoplamento entre os Bounded Contexts, e seus Handlers podem ficar em processos separados, aumentando a escalabilidade da aplicação.

Modules

E por último, mas não menos importante, vamos falar de Modules.

Para criar Modules em C# temos os namespace, que nada mais são do que um caminho virtual para as classes. Temos também os arquivos de extensão .csproj, esses servem para separar os arquivos fisicamente e gerenciar suas dependências. Outras linguagens tem conceitos parecidos - como packages em Java - mas só o caminho real já pode ser o suficiente na maioria dos casos.

Com o uso de Modules conseguimos manter a organização do projeto de maneira consistente e respeitar a estrutura da Ubiquitous Language. Esta estrutura deve nos dizer sua intenção e falar a linguagem do negócio ao mesmo tempo. Essa organização, entre outras coisas, ajuda:

A entender assuntos relacionados e manter assuntos distintos fisicamente separados.
Na manutenção, pois quando você precisar mexer em uma área saberá exatamente onde procurar.
A novos desenvolvedores entender o projeto e saber onde devem ou não mexer.
A evitar conflitos de classes com o mesmo nome.

Modules são usados para decompor o Domain Model. Um domínio grande terá múltiplos Bounded Contexts e esses terão múltiplos conceitos. Podemos considerar esses conceitos como os Modules. Por exemplo, quando o domain expert da Store fala sobre Shopping, espera-se que todo o código relacionado a este assunto esteja em um namespace como {CompanyName}.Store.Shopping. Modules se mantém entre o Bounded Context e os Aggregates.

Não há uma regra dizendo como você deve arquitetar seu projeto, isso é muito subjetivo e tem N fatores que influenciam, mas de modo a ilustrar um exemplo seguindo a divisão em camadas proposta por alguns autores, podemos ter algo parecido com isso:



└── FakeCommerce.Store
    └── FakeCommerce.Store.Shopping
        ├── FakeCommerce.Store.Shopping.Application
        ├── FakeCommerce.Store.Shopping.Domain
        ├── FakeCommerce.Store.Shopping.Integration
        └── FakeCommerce.Store.Shopping.Persistence

Application onde ficará os casos de uso e regras da aplicação.
Domain terá os Aggregates e as regras de negócio.
Integration será responsável pela comunicação com outros Bounded Contexts (Anti-Corruption Layer) e serviços externos.
Persistence cuidará da infraestrutura do banco de dados e terá a implementação dos Repositories.

Desta forma, garantimos que o domínio fique isolado do restante da aplicação e que só tenha classes com regras de negócio, sem se preocupar com detalhes de implementação que irão ficar em outras camadas.

Considerações Finais

Os Building Blocks são patterns poderosos para nos auxiliar a construir um Domain Model que satisfaça as necessidades do Domain.

Seja pragmático no seu uso, saber não é dever. Cada pattern tem sua utilidade na construção do Domain Model e eles devem ser usados à medida que as necessidades surgem, não antes. Deixe o domínio emergir naturalmente, já que a tendência é começar simples e ir ficando complexo com o tempo. Essas ocasiões são perfeitas para rever o que foi implementado e refatorar o que for necessário.

Pratique! Criei um projeto para exercitar esses patterns e aproveite para se aprofundar mais em cada um conforme as dúvidas surgirem. É nessas horas que você realmente entende o problema que cada um resolve e o seu valor como pattern.

Referências

Entendendo Domain-Driven Design

Guilherme Camargo — Fri, 13 Mar 2020 01:24:22 +0000

Um dos principais conceitos que aprendi e mudou a forma como escrevo software foi Domain-Driven Design. Ele me trouxe outra visão de como abordar problemas, como criar soluções mais alinhadas com a área de negócio e com um melhor design. Neste artigo irei revisá-lo e compartilhar o meu conhecimento sobre os seus conceitos.

Overview

O que é, onde aplicar e benefícios

Domain-Driven Design (DDD) é uma metodologia de desenvolvimento de software. Originou-se em 2003 por Eric Evans em seu conhecido livro Domain-Driven Design: Tackling Complexity in the Heart of Software.

Ele é, acima de tudo, uma metodologia que habilita o desenvolvimento de software de alta complexidade de negócio de maneira efetiva. Através da sua filosofia, práticas e patterns, DDD nos permite gerar valor, reduzir custos e facilitar a evolução de aplicações que poderiam facilmente terminar de maneira trágica. Ele nos apresenta maneiras de modelar essas aplicações de tal forma que fique muito próxima à área de problema que estamos resolvendo, isso habilita a equipe técnica a desenvolver tais sistemas de maneira consistente e saudável.

O que não é, onde evitar e malefícios

Devemos ter ciência que quando falamos exclusivamente de arquitetura de software ou design patterns (Repositories, Entities, Services, Factories, etc) não estamos falando sobre DDD necessariamente. A parte prática com Building Blocks e Design de Arquitetura são importantes também, sem dúvida, porém elas não se sustentam sozinhas e não são o ponto central do DDD, estão lá simplesmente para nos auxiliar. Podemos ter um sistema que implementa todos os design patterns sugeridos, mas não atende o negócio. Por outro lado podemos ter um design mais simplista, mas que esteja totalmente alinhado ao domínio. DDD não exige que nenhum design pattern seja implementado, a única coisa exigida é que nosso domínio esteja isolado do restante da aplicação para que possamos focar nas regras de negócio e não misturar esses conceitos com problemas técnicos, além disso, DDD não está restrito somente ao paradigma de programação orientada a objetos. Concluímos então que não existe receita de bolo ou template padrão para implementá-lo.

Não devemos considerar DDD em aplicações onde não há complexidade de negócio. Tais aplicações não iriam se beneficiar do que nos é apresentado. DDD somente traria complexidade desnecessária e dificuldade em sua execução. Também devemos evitar seu uso onde não temos pessoas qualificadas para aplicar o conhecimento e as práticas requeridas, nem onde não temos contato direto com pessoas de negócio.

Problem Space

Quando falamos de Problem Space estamos nos referindo a área de negócio na qual o cliente está inserido e o que nosso software pretende resolver. Aqui aprendemos a gerenciar o problema e a destila-lo a fim de reduzir a sua complexidade.

Domain

O domínio é realidade do negócio, se refere a área de conhecimento e atividade na qual a organização e as pessoas estão inseridas. Envolve todas as regras, comportamentos, processos e entendimentos que lá habitam. Domínio é onde as pessoas de negócio vivem e na qual nós, desenvolvedores, não temos interferência.

Subdomains

Subdomain se dá no processo de decompor o nosso domínio em três categorias:

Core

É o que gera maior valor, o motivo da organização existir, o diferencial entre os seus concorrentes, é onde os 20% geram 80% dos resultados. O Core Domain é onde se deve gastar maior parte do tempo e recursos. Onde os desenvolvedores mais experientes devem trabalhar e onde devemos criar o design mais robusto.

Em um projeto de e-commerce, por exemplo, o Core Domain pode ser Sales. Isso não quer dizer que todos os e-commerces possuem o mesmo Core. Se um e-commerce se propõe a fazer entregas em até 24 horas, o Core Domain será Shipping, se outro e-commerce se destaca por ser o mais barato entre a concorrência, seu Core Domain será Pricing, então tenha em mente que os subdomains serão diferentes de empresa para empresa. Nosso papel aqui é mapear a realidade do negócio existente, não tentar encaixar modelos preconcebidos nele.

Supporting

Ele é o que habilita o Core Domain exercer seu papel, sem ele a organização não iria funcionar e ele precisa de um certo nível de customização, porém não possui vantagem competitiva. Ele é importante, mas não devemos gastar mais esforços do que o necessário. Aqui feito é bem feito!

Olhando nosso exemplo, os items em amarelo são áreas que sem elas o sistema não iria funcionar. Não conseguimos vender um produto sem um meio de pagamento, sem estoque no armazém, sem uma boa logística, etc. Todas essas áreas servem de auxílio para que o Core funcione adequadamente.

Generic

Não são de maior preocupação e não possui relação exclusiva com nosso Core Domain. Caso seja criada uma solução interna devemos fazer com que ela simplesmente funcione, nada mais, provavelmente delegar para desenvolvedores menos experientes. Outra alternativa seria contratar uma solução de terceiros.

As nossas caixinhas em vermelho representam o que é genérico para nós. Como o nosso foco é a venda temos que deixar algumas coisas de lado. Aceitamos que existem soluções de recomendações muito melhores do que podemos criar, podemos contratar uma dessas soluções através de SaaS. Também não é nosso foco customizar a experiência de cada cliente, só precisamos de alguns dados básicos - uma API com alguns métodos CRUD resolverá o nosso problema.

Solution Space

Solution Space se refere ao como iremos resolver o Problem Space. Envolve práticas e patterns a fim de criar uma solução efetiva.

Domain Models

O que é exatamente um "Modelo"? Segundo o Dicionário Criativo temos a seguinte definição:

Representação abstrata de um fenômeno, capaz de captar as características formais ou funcionais do objeto de estudo.

Podemos entender então que um modelo nada mais é do que uma visão/imagem que temos de um conceito. Trazendo para nosso cenário seria criar abstrações que representam nosso domínio em um determinado contexto. Ao fazer isso poderemos discutir com mais propriedade os termos e obter das pessoas de negócio conceitos subentendidos. Ele é fruto da colaboração. Sua maior utilidade se dá no entendimento compartilhado das regras e processos. Em resumo, Domain Model é a implementação de uma solução para o Domain.

Analysis Model

Durante as reuniões irão surgir ideias que podemos traduzir para diagramas (UML), onde desenvolvedores e pessoas de negócio possam entender e colaborar sobre os processos discutidos, estes são conhecidos como analysis model. Eles não são focados no aspecto técnico e não devem ter detalhes de implementação.

Code Model

Code Model é a implementação dos Analysis Model. Eles são criados utilizando os conceitos aprendidos no modelo anterior. Todo o Code Model deve servir apenas e exclusivamente ao nosso domínio, não devemos utilizar aqui nomes de patterns como Repository, Factory, Service, Manager, etc - isso somente iria gerar ruído na comunicação. Ao invés disso devemos utilizar a Ubiquitous Language na implementação.

Model-Driven Design

É o processo de sincronização entre o analysis model com code model. Em um cenário ideal ambos são traduzíveis de 1:1, para isso precisamos de uma implementação livre de detalhes técnicos e um analysis model que não seja tão abstrato. Durante esse processo precisamos analisar se os jargões foram modelados de forma explícita para garantir que os mesmo termos usados nas discussões estejam na implementação. Durante a implementação do code model a equipe técnica poderá identificar falhas de conceitos e regras, isso permite trazer novas reflexões durante reuniões e refinar o processo de maneira iterativa, o que levará na atualização do analysis model inicial. Desta forma isso gera um processo de melhoria contínua na qual analysis model e code model se retroalimentam.

Strategic Patterns

Os Strategic Patterns nos ajudam a destilar o Problem Space e arquitetar a aplicação guiada pelo domínio.

Ubiquitous Language

Entende-se como onipresente aquilo que está em todos os lugares. Para conseguirmos ter uma comunicação efetiva com pessoas de domínio é essencial falarmos a mesma língua. Ubiquitous Language é criada entre a colaboração da equipe técnica e pessoas de negócio, ela deve ser falada e escrita durante conversas, desenhos e implementações. Ela é dividida entre os Bounded Context. Esta linguagem é um artefato vivo, terá evoluções e refinamentos. É importante deixá-la de forma explícita para que todos entendam os seus termos, talvez manter um glossário ou outra documentação em que todos tenham acesso.

Inglês ou Português?

É prática comum, até recomendável, que nosso código seja escrito em inglês, porém isso entra em conflito com a Ubiquitous Language. Quando estamos trabalhando com domínio complexo devemos deixar nosso código com o idioma falado para não perder a relação com as pessoas de negócio.

Bounded Context

Após identificar nossos subdomains e ter uma linguagem compartilhada com pessoas de negócio iremos perceber que os termos utilizados tendem a ter mais de um significado para pessoas/processos/áreas diferentes. Um Product para o contexto Sales significa uma coisa e para o contexto Shipping outra. Ao invés de tentar criar um modelo único, aka God Object, a ideia do Bounded Context é criar divisões entre essa linguagem, onde cada um tem o seu modelo que representa uma abstração do problema, isso impede que os conceitos se misturem e que nosso software acabe se tornando um BBoM.

Um Subdomain é algo abstrato/conceitual no qual podemos apenas discutir. Um Bounded Context, por outro lado, é um artefato que traduz esses conceitos para o software. Em um mundo perfeito todos nossos Subdomains seriam traduzíveis para um Bounded Context correspondente, infelizmente a realidade pode não ser tão generosa em alguns casos. Podemos ter N Bounded Contexts para satisfazer um Subdomain, o que ira guiar a divisão neste caso é a Ubiqutious Language. Devemos ficar atentos somente quando um Bounded Context tende a atender mais de um Subdomain, isso fere o Single Responsibility Principle, pois um B.C. terá mais de um motivo para ser alterado.

Seguindo os Subdomains propostos, vamos pensar na organização do projeto. Dentro de Customer podemos ter um Bounded Context chamado User que irá tratar do Nome, Endereços, Formas de Pagamento, Avatar, etc; e outro Bounded Context de Account contendo E-mail, Password, Roles, Claims, etc. E em Sales temos Orders, Pricing e ShoppingCart, para os demais acredito que um Bounded Context para cada irá servir.

App
  ├── Billing
  ├── Catalog
  ├── Customers
  │ ├── Account
  │ └── User
  ├── Sales
  │ ├── Orders
  │ ├── Pricing
  │ └── ShoppingCart
  ├── Shipping
  └── Warehouse

Tome cuidado para não dividir os Bounded Contexts pelos dados e reuso, infelizmente nos como desenvolvedores temos esse hábito. É um erro pensar em Bounded Context desta forma, isso levará a inconsistências no modelo e ao longo prazo pode acabar comprometendo a evolução do sistema. Bounded Context é meio difícil de entender no começo, estude bem antes de implementar!

Bounded Context geralmente é recomendado como a primeira linha de divisão em aplicações microservices.

Context Maps

Dado o cenário onde você já identificou e separou os contextos da sua aplicação, agora é hora de entender como eles se comunicam. Context Maps nos ajudam a entender melhor a barreira entre os Bounded Context e visualizar como eles interagem entre si. Há alguns patterns para a comunicação entre os contextos de maneira eficiente, porém irie comentar apenas dos dois principais:

SharedKernel

Haverá cenários em que teremos, dentro de um Subdomain, modelos e regras que se aplicam em mais de um Bounded Context, a fim de evitar duplicidade e não criamos acoplamento podemos ter uma camada que contém o que é comum entre os Bounded Contexts envolvidos.

Podemos exemplificar criando uma camada Core em Sales, ela pode ter o modelo base de Product.

App/Sales
├── Core
├── Orders
├── Pricing
└── ShoppingCart

Anticorruption Layer

Quando estamos criando um Bounded Context seguindo a Ubiquios Language não queremos contaminá-lo com models externas, ou ainda pior, criar acoplamento com partes legadas do sistema. Neste cenário podemos criar uma camada intermediária entre o Bounded Context e suas dependências. Através de uma interface definida nele, podemos implementar nesta nova camada e traduzir o retorno de chamadas de outros Bounded Contexts para o nosso. Desta forma conseguimos utilizar recursos externos de forma transparente e sem acoplamento.

Em Billing temos uma camada chamada Integration que será responsável por obter dados de Customer, que está dentro do Bounded Context User. Ela também será responsável pela comunicação com a API de pagamentos externa.

App/Billing
├── src
│ ├── Domain
│ └── Integration
└── tests

Highlights

Colaboração

É fundamental para o entendimento do domínio que desenvolvedores e pessoas de negócio trabalhem juntas. Somente com a colaboração e entrevistas constantes podemos extrair os conceitos mais complexos e entender fluxos de negócio de maneira esmiuçada.

Foque no Core-Business

Nem toda parte da nossa aplicação tem a mesma relevância. DDD nos permite enxergar com mais clareza o problema que estamos resolvendo e entendendo melhor o que gera valor, devemos então direcionar nossos esforços para os processos que realmente impactam o negócio, aumentando assim a chance de sucesso do nosso software.

Evolução constante

Não importa o quão experiente você seja, não há como mapear e ter um design perfeito de início. O processo para destilar o domínio e criar modelos que o representam é iterativo. Além do que conceitos podem e vão mudar, novas necessidades irão surgir e precisamos ficar atentos para alinhar nosso design com o negócio. Podemos ter um sistema 1:1 no começo, porém se não darmos continuidade nas práticas e processos do DDD em alguns meses estaremos defasados. DDD necessita de manutenção constante!

Conclusão

Neste artigo tentei ilustrar com exemplos didáticos o que seria a abordagem do DDD em um software que pretende resolver um domínio complexo. Tenha em mente que devido a sua natureza, nenhum artigo, livro ou curso irá te passar a experiência real do DDD, pois isso envolve trabalhar com pessoas de negócio, distilar e refinar o domínio, colaboração, entre outros. Aprender sobre DDD não é como aprender uma linguagem ou framework novo, envolve muita soft-skill e recursos do dia-a-dia. Os problemas de negócio aqui apresentados são pensados para ilustrar possíveis situações que podem acontecer, porém, somente em um domínio real você irá notar as nuances do DDD e o absorver com mais clareza. Recomendo continuar estudando e, caso tenha a oportunidade, começar a pratica-lo com outros desenvolvedores mais experientes.

Irei falar mais sobre DDD nos próximos artigos onde abordarei os Tactical Patterns e Architecture Patterns.

Referências

Desacoplando chamadas com Mediator

Guilherme Camargo — Tue, 11 Feb 2020 01:15:20 +0000

Quando precisamos fazer chamadas em pontos da aplicação e não temos uma boa definição para isso, podemos acabar criando dependências que não façam sentido e deixar nosso código acoplado. Neste artigo iremos ver como trabalhar com o pattern Mediator e Command a fim de minimizar este problema e ter um design mais limpo.

Se você estiver pensando algo do tipo: "Ei, mas eu já consigo desacoplar meu código com interfaces". Sim, é comum (e recomendável) utilizar IoC através de interfaces a fim de ter mais flexibilidade.
Mas te pergunto: Suas interfaces mudam? Com que frequência?

Intefaces são muito importantes em linguagens fortemente tipadas, mas não devemos usá-las como a única solução para todos nossos problemas. Elas não foram feitas para serem alteradas com frequência, seu objetivo é definir um contrato para que qualquer classe que queira implementá-la tenha a mesma assinatura, nos permitindo assim substituir seu comportamento de maneira fácil onde ela é requisitada.

Qualquer alteração em uma interface levará a um refactor considerável em N partes do código.

Porém em certos pontos da nossa aplicação devemos ter mais flexibilidade. Tome como exemplo a camada mais externa de um sistema, seu objetivo é expor os dados para o client. Inevitavelmente vamos ter que mudar parâmetros, adicionar novos campos e fazer alterações baseadas em novas necessidades. Interfaces acabam sendo um inconveniente neste cenário.

O pattern Mediator pode ser uma boa alternativa neste caso. Ele foi catalogado no conhecido livro "Design Patterns: Elements of Reusable Object-Oriented Software, GOF". Ele é, literalmente, um mediador entre duas classes que não se conhecem, nos permitindo realizar chamadas entre dois pontos sem criar acoplamento. Essas chamadas podem ser feitas através de um Command - outro pattern que teve a mesma origem. O Command trata de encapsular uma chamada através de uma classe que será enviada para execução.

Um pacote bem conhecido que implementa este pattern é o MediatR. Iremos utilizá-lo neste exemplo.

SHOW ME THE CODE!

Nosso projeto irá conter quatro csprojs, um web chamado API e três classlib chamados Application, Domain e Persistence. Todo o código exemplificado aqui está no meu GitHub.

guisfits / decoupling-calls-with-mediatr

How to make calls in a simple way and make your code more organized.

Tendo o dotnet cli instalado em sua máquina, vamos adicionar o MediatR ao nosso projeto e logo em seguida o pacote para configurá-lo.

dotnet add API package MediatR
dotnet add API package MediatR.Extensions.Microsoft.DependencyInjection

Vamos habilitar o MediatR através da classe startup na nossa API. Iremos primeiro carregar o assemply onde os handlers estaram implementados e passa-lo para o método AddMediatR.

Repare que boa parte do código original foi omitido a fim de simplificar este exemplo. Também irei omitir processos não relacionados a este artigo, para mais detalhes consulte o repositório.

using MediatR;

namespace API
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            var applicationAssembly = AppDomain.CurrentDomain.Load("Application");
            services.AddMediatR(applicationAssembly);
        }
    }
}

Na camada Application também temos que adicionar o pacote MediatR a fim de utilizarmos as interfaces IRequest e IRequestHandler.

Um esclarecimento. O MediatR chama de Request o ato de disparar uma classe para processamento. Não o confunda com HttpRequest.

dotnet add Application package MediatR

A interface IRequest tem como objetivo marcar nosso Command para ser processado por um Handler. Também podemos utilizar o overload com generics de IRequest<>, onde passamos T como tipo de retorno que o Handler nos dará deste Command.

Dentro de Application iremos criar um comando para adicionar um novo usuário.

using MediatR;

namespace Application.Commands
{
    public class CreateUserCommand : IRequest
    {
        public string Name { get; set; }
    }
}

Na camada Domain iremos adicionar nossa entidade User e seu repository, IUsers.

public class User
{
    public User(string name)
    {
        Name = name;
    }

    public int Id { get; private set; }
    public string Name { get; private set; }
}

public interface IUsers
{
    Task Add(User newUser);
}

Feito isso iremos para a parte mais importante, o Handler!
Vamos voltar para Application e criar uma classe chamada UserCommandHandler

class UserCommandHandler : IRequestHandler<CreateUserCommand>
{
    private readonly IUsers _users;

    public UserCommandHandler(IUsers users)
    {
        _users = users;
    }

    public async Task<Unit> Handle(CreateUserCommand request, CancellationToken cancellationToken)
    {
        Validate(request);

        var user = new User(request.Name);
        await _users.Add(user);

        return Unit.Value;
    }

    private void Validate(CreateUserCommand command)
    {
        if (string.IsNullOrEmpty(command.Name))
            throw new ArgumentException(nameof(command.Name));
    }
}

Vamos testar

Em API vamos criar UserController, obter a interface IMediator e enviar o command para execução.

[ApiController]
[Route("api/users")]
public class UserController : ControllerBase
{
    private readonly IMediator _mediator;

    public UserController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpPost]
    public async Task<IActionResult> Create(CreateUserCommand body)
    {
        await _mediator.Send(body);
        return Created("", body);
    }
}

Agora vamos fazer uma requisição para a rota criada

Como podemos ver no print, nosso request chegou até o handler.

Agora confirmamos o retorno com sucesso.

Pontos de Atenção

Repare que nosso Handler é uma classe privada, não dando a chance de classes externas o chamarem;
Como o Handler é uma classe comum do C#, podemos receber as dependências através de IoC;
Seguindo o Single Responsibility Principle, seria uma boa prática ter somente um Command por Handler. Assim segmentamos melhor nossas dependências e podemos evoluir a aplicação de maneira isolada;
Não precisamos dizer explicitamente qual Handler implementa qual Command. O MediatR é esperto o suficiente pra fazer isso automaticamente pra gente;

Recomendações

CQRS: MediatR acaba nos ajudando na separação entre Commands e Queries;
Event Driven: MediatR tem outra interface chamada INotification para lançar eventos, pode ser uma boa alternativa em casos simples;
IPipelineBehavior: Farei outro artigo em breve sobre essa funcionalidade;

Conclusão

Vimos neste artigo um simples exemplo de como utilizar o pattern Mediator e Command através do MediatR a fim de um design mais elegante entre as chamadas da nossa aplicação.

Não se esqueça de procurar a documentação oficial para mais detalhes e fique atento à mudanças em futuras versões.

Caso tenha gostado não deixe de curtir, comentar e divulgar este post se possível. Também fique a vontade para me seguir por aqui, no GitHub e me adicionar no Linkedin. Este é o meu primeiro artigo técnico, pretendo escrever muitos outros daqui pra frente.

Espero que esta leitura tenha sido de alguma ajuda pra você.

Um grande e abraço e até a próxima.