As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Estruture um projeto Python em arquitetura hexagonal usando o AWS Lambda *Furkan Oruc, Dominik Goby, Darius Kunce e Michal Ploski, Amazon Web Services* ## Resumo Esse padrão mostra como estruturar um projeto Python em arquitetura hexagonal usando o AWS Lambda. O padrão usa o AWS Cloud Development Kit (AWS CDK) como ferramenta de infraestrutura como código (IaC), o Amazon API Gateway como API REST e o Amazon DynamoDB como camada de persistência. A arquitetura hexagonal segue os princípios de design orientados por domínio. Na arquitetura hexagonal, o software consiste em três componentes: domínio, portas e adaptadores. Para obter informações detalhadas sobre arquiteturas hexagonais e seus benefícios, consulte o guia [Criação de arquiteturas hexagonais na AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/hexagonal-architectures/)*.* ## Pré-requisitos e limitações **Pré-requisitos ** + Uma conta AWS ativa + Experiência em Python + Familiaridade com AWS Lambda, AWS CDK, Amazon API Gateway e DynamoDB + Uma GitHub conta (veja [as instruções para se inscrever](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account)) + Git (consulte as [instruções de instalação](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)) + Um editor de código para fazer alterações e enviar seu código para GitHub (por exemplo, [Visual Studio Code ou [JetBrains PyCharm](https://www.jetbrains.com/pycharm/))](https://code.visualstudio.com/) + Docker instalado e o daemon do Docker instalado e funcionando **Versões do produto** + Git versão 2.24.3 ou superior + Python versão 3.7 ou superior + AWS CDK v2 + Poetry versão 1.1.13 ou superior + AWS Lambda Powertools para Python versão 1.25.6 ou superior + pytest versão 7.1.1 ou superior + Moto versão 3.1.9 ou superior + pydantic versão 1.9.0 ou superior + Boto3 versão 1.22.4 ou superior + mypy-boto3-dynamodb versão 1.24.0 ou superior ## Arquitetura **Pilha de tecnologias de destino** A pilha de tecnologia de destino consiste em um serviço em Python que usa o API Gateway, Lambda e DynamoDB. O serviço usa um adaptador do DynamoDB para manter os dados. Ele fornece uma função que usa o Lambda como ponto de entrada. O serviço usa o Amazon API Gateway para expor uma API REST. A API usa o AWS Identity and Access Management (IAM) para a [autenticação de clientes](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html). **Arquitetura de destino** Para ilustrar a implementação, esse padrão implanta uma arquitetura de destino com tecnologia sem servidor. Os clientes podem enviar solicitações para um endpoint do API Gateway. O API Gateway encaminha a solicitação para a função do Lambda de destino que implementa o padrão de arquitetura hexagonal. A função do Lambda executa operações de criação, leitura, atualização e exclusão (CRUD) em uma tabela do DynamoDB. | | | Este padrão passou por testes em um ambiente de PoC. Você deve realizar uma análise de segurança para identificar o modelo de ameaça e criar uma base de código segura antes de implantar qualquer arquitetura em um ambiente de produção. | | --- | ![\[Arquitetura de destino para estruturar um projeto Python em arquitetura hexagonal\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/images/pattern-img/25bd7169-ea5e-4a21-a865-c91c30a3c0da/images/de0d4f0d-ad19-43ec-bd10-676b25477b64.png) A API oferece suporte a cinco operações em uma entidade de produto: + `GET /products` devolve todos os produtos. + `POST /products` cria um novo produto. + `GET /products/{id}` retorna um produto específico. + `PUT /products/{id}` atualiza um produto específico. + `DELETE /products/{id}` exclui um produto específico. Você pode usar a seguinte estrutura de pastas para organizar seu projeto de acordo com o padrão de arquitetura hexagonal:   ``` app/ # application code |--- adapters/ # implementation of the ports defined in the domain |--- tests/ # adapter unit tests |--- entrypoints/ # primary adapters, entry points |--- api/ # api entry point |--- model/ # api model |--- tests/ # end to end api tests |--- domain/ # domain to implement business logic using hexagonal architecture |--- command_handlers/ # handlers used to execute commands on the domain |--- commands/ # commands on the domain |--- events/ # events triggered via the domain |--- exceptions/ # exceptions defined on the domain |--- model/ # domain model |--- ports/ # abstractions used for external communication |--- tests/ # domain tests |--- libraries/ # List of 3rd party libraries used by the Lambda function infra/ # infrastructure code simple-crud-app.py # AWS CDK v2 app ``` ## Ferramentas **Serviços da AWS** + [O Amazon API Gateway](https://aws.amazon.com/api-gateway/) é um serviço totalmente gerenciado que facilita aos desenvolvedores criar, publicar, manter, monitorar e proteger APIs em qualquer escala. + O [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) é um banco de dados NoSQL totalmente gerenciado, de valor-chave e com tecnologia sem servidor, projetado para executar aplicativos de alto desempenho em qualquer escala. + O [AWS Lambda](https://aws.amazon.com/lambda/) é um serviço computacional com tecnologia sem servidor e orientado a eventos que permite executar o código em virtualmente qualquer tipo de aplicação ou serviço de backend sem o provisionamento ou gerenciamento de servidores. Você pode iniciar funções do Lambda a partir de mais de 200 serviços da AWS e aplicativos de software como serviço (SaaS) e pagar somente pelo que usar. **Ferramentas** + O [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)  é usado como sistema de controle de versão para desenvolvimento de código nesse padrão. + O [Python](https://www.python.org/) é usado como linguagem de programação para esse padrão. O Python fornece estruturas de dados de alto nível e uma abordagem à programação orientada a objetos. O AWS Lambda fornece um runtime integrado do Python que simplifica a operação dos serviços do Python. + O [Visual Studio Code](https://code.visualstudio.com/) é usado como IDE para desenvolvimento e teste desse padrão. Você pode usar qualquer IDE que ofereça suporte ao desenvolvimento em Python (por exemplo, [PyCharm](https://www.jetbrains.com/pycharm/)). + O [AWS Cloud Development Kit (AWS CDK](https://aws.amazon.com/cdk/)) é uma estrutura de desenvolvimento de software de código aberto que permite definir recursos de aplicações em nuvem usando linguagens de programação conhecidas. Esse padrão usa o CDK para escrever e implantar a infraestrutura de nuvem como código. + O [Poetry](https://python-poetry.org/) é usado para gerenciar dependências no padrão. + O [Docker](https://www.docker.com/) é usado pelo AWS CDK para criar o pacote e a camada do Lambda. **Código ** O código desse padrão está disponível no repositório de amostras da arquitetura [hexagonal GitHub Lambda](https://github.com/aws-samples/lambda-hexagonal-architecture-sample). ## Práticas recomendadas Para usar esse padrão em um ambiente de produção, siga essas práticas recomendadas: + Use chaves gerenciadas pelo cliente no AWS Key Management Service (AWS KMS) para criptografar grupos de [log da Amazon e tabelas do CloudWatch Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) [DynamoDB](https://docs.aws.amazon.com/kms/latest/developerguide/services-dynamodb.html). + Configure o [AWS WAF para o Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-aws-waf.html) para permitir acesso somente a partir da rede da sua organização. + Considere outras opções para autorização do API Gateway se o IAM não atender às suas necessidades. Por exemplo, você pode usar [grupos de usuários do Amazon Cognito](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html) ou [autorizadores do Lambda do API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html). + Use [backups do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html). + Configure as funções do Lambda com uma [implantação de nuvem privada virtual (VPC)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html) para manter o tráfego de rede dentro da nuvem. + Atualize a configuração de origem permitida para o [compartilhamento de recursos de origem cruzada (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) para restringir o acesso somente ao domínio de origem solicitante. + Use [cdk-nag](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/check-aws-cdk-applications-or-cloudformation-templates-for-best-practices-by-using-cdk-nag-rule-packs.html) para verificar as práticas recomendadas de segurança no código do AWS CDK. + Considere o uso de ferramentas de digitalização de código para encontrar problemas de segurança comuns no código. Por exemplo, o [Bandit](https://bandit.readthedocs.io/en/latest/) é uma ferramenta projetada para encontrar problemas de segurança comuns no código Python. O [PIP-Audit](https://pypi.org/project/pip-audit/) verifica os ambientes do Python em busca de pacotes que contenham tenham vulnerabilidades conhecidas. Esse padrão usa o [AWS X-Ray](https://aws.amazon.com/xray/?nc1=h_ls) para rastrear solicitações por meio do ponto de entrada, domínio e adaptadores do aplicativo. O AWS X-Ray ajuda os desenvolvedores a identificar gargalos e determinar altas latências para melhorar o desempenho do aplicativo. ## Épicos ### Inicializar o projeto | Tarefa | Description | Habilidades necessárias | | --- | --- | --- | | Crie seu próprio repositório. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Instale as dependências. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Configure seu IDE. | Recomendamos o Visual Studio Code, mas você pode usar qualquer IDE de sua escolha que ofereça suporte ao Python. As etapas a seguir são para o Visual Studio Code.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Execute testes de unidade, opção 1: usando o Visual Studio Code. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Execute testes de unidade, opção 2: usando comandos shell. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | ### Implante e teste o aplicativo | Tarefa | Description | Habilidades necessárias | | --- | --- | --- | | Solicite credenciais temporárias. | Para obter credenciais da AWS no shell durante a execução do `cdk deploy`, crie credenciais temporárias usando o Centro de Identidade do AWS IAM (sucessor do AWS Single Sign-On). Para obter instruções, consulte a publicação [Como recuperar credenciais de curto prazo para uso da CLI com o Centro de Identidade do AWS IAM](https://aws.amazon.com/blogs/security/aws-single-sign-on-now-enables-command-line-interface-access-for-aws-accounts-using-corporate-credentials/). | Desenvolvedor de aplicativos, AWS DevOps | | Implante o aplicativo . | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos, AWS DevOps | | Teste a API, opção 1: usando o console. | Use o [console do API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-test-method.html) para testar a API. Para obter mais informações sobre as operações e request/response mensagens da [API, consulte a seção Uso da API do arquivo readme](https://github.com/aws-samples/lambda-hexagonal-architecture-sample/blob/main/README.md#api-usage) no GitHub repositório. | Desenvolvedor de aplicativos, AWS DevOps | | Teste a API, opção 2: usando o Postman. | Se você quiser usar uma ferramenta como o [Postman](https://www.postman.com/):[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos, AWS DevOps | ### Desenvolva o serviço | Tarefa | Description | Habilidades necessárias | | --- | --- | --- | | Escreva testes de unidade para o domínio comercial. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Implemente comandos e manipuladores de comandos. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Escreva testes de integração para adaptadores secundários. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Implemente adaptadores secundários. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Escreva end-to-end testes. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | | Implemente adaptadores primários. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Desenvolvedor de aplicativos | ## Recursos relacionados **Guia do APG** + [Criação de arquiteturas hexagonais na AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/hexagonal-architectures/) **Referências da AWS** + [Documentação do AWS Lambda](https://docs.aws.amazon.com/lambda/) + [Documentação do AWS CDK](https://docs.aws.amazon.com/cdk/) + [Seu primeiro aplicativo AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/hello_world.html) + [Documentação do API Gateway](https://docs.aws.amazon.com/apigateway/) + [Controlar o acesso a uma API com permissões do IAM](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html) + [Use o console do API Gateway para testar um método de API REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-test-method.html) + [Documentação do Amazon DynamoDB](https://docs.aws.amazon.com/dynamodb/) **Ferramentas** + [Site git-scm.com](https://git-scm.com/) + [Como instalar o Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + [Criando um novo GitHub repositório](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository) + [Site em Python](https://www.python.org/) + [Powertools do AWS Lambda para Python](https://docs.powertools.aws.dev/lambda/python/latest/) + [Site do Postman](https://www.postman.com/) + [Biblioteca de objetos simulados em Python](https://docs.python.org/3/library/unittest.mock.html) + [Site do Poetry](https://python-poetry.org/) **IDEs** + [Site do Visual Studio Code](https://code.visualstudio.com/) + [PyCharm site](https://www.jetbrains.com/pycharm/)