Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Struttura un progetto Python in architettura esagonale utilizzando AWS Lambda *Furkan Oruc, Dominik Goby, Darius Kunce e Michal Ploski, Amazon Web Services* ## Riepilogo Questo modello mostra come strutturare un progetto Python in architettura esagonale utilizzando AWS Lambda. Il modello utilizza AWS Cloud Development Kit (AWS CDK) come strumento Infrastructure as code (IaC), Amazon API Gateway come API REST e Amazon DynamoDB come livello di persistenza. L'architettura esagonale segue i principi di progettazione basati sul dominio. Nell'architettura esagonale, il software è composto da tre componenti: dominio, porte e adattatori. *Per informazioni dettagliate sulle architetture esagonali e sui relativi vantaggi, consulta la guida [Building hexagonal](https://docs.aws.amazon.com/prescriptive-guidance/latest/hexagonal-architectures/) architectures on AWS.* ## Prerequisiti e limitazioni **Prerequisiti** + Un account AWS attivo + Esperienza in Python + Familiarità con AWS Lambda, AWS CDK, Amazon API Gateway e DynamoDB + [Un GitHub account (consulta le istruzioni per la registrazione)](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account) + Git (vedi [istruzioni di installazione](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)) + Un editor di codice per apportare modifiche e inviare codice GitHub (ad esempio, [Visual Studio Code o [JetBrains PyCharm](https://www.jetbrains.com/pycharm/))](https://code.visualstudio.com/) + Docker installato e il demone Docker attivo e funzionante **Versioni del prodotto** + Git versione 2.24.3 o successiva + Python versione 3.7 o successiva + CDK AWS v2 + Poetry versione 1.1.13 o successiva + AWS Lambda Powertools per Python versione 1.25.6 o successiva + pytest versione 7.1.1 o successiva + Moto versione 3.1.9 o successiva + pydantic versione 1.9.0 o successiva + Boto3 versione 1.22.4 o successiva + mypy-boto3-dynamodb versione 1.24.0 o successiva ## Architecture **Stack tecnologico Target** Lo stack tecnologico di destinazione è costituito da un servizio Python che utilizza API Gateway, Lambda e DynamoDB. Il servizio utilizza un adattatore DynamoDB per rendere persistenti i dati. Fornisce una funzione che utilizza Lambda come punto di ingresso. Il servizio utilizza Amazon API Gateway per esporre un'API REST. L'API utilizza AWS Identity and Access Management (IAM) per l'[autenticazione dei client](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html). **Architettura Target** Per illustrare l'implementazione, questo modello implementa un'architettura di destinazione senza server. I client possono inviare richieste a un endpoint API Gateway. API Gateway inoltra la richiesta alla funzione Lambda di destinazione che implementa il modello di architettura esagonale. La funzione Lambda esegue operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD) su una tabella DynamoDB. | | | Questo modello è stato testato in un ambiente PoC. È necessario condurre una revisione della sicurezza per identificare il modello di minaccia e creare una base di codice sicura prima di implementare qualsiasi architettura in un ambiente di produzione. | | --- | ![\[Architettura di destinazione per strutturare un progetto Python in architettura esagonale\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/images/pattern-img/25bd7169-ea5e-4a21-a865-c91c30a3c0da/images/de0d4f0d-ad19-43ec-bd10-676b25477b64.png) L'API supporta cinque operazioni su un'entità di prodotto: + `GET /products`restituisce tutti i prodotti. + `POST /products`crea un nuovo prodotto. + `GET /products/{id}`restituisce un prodotto specifico. + `PUT /products/{id}`aggiorna un prodotto specifico. + `DELETE /products/{id}`elimina un prodotto specifico. È possibile utilizzare la seguente struttura di cartelle per organizzare il progetto in modo da seguire lo schema di architettura esagonale:   ``` 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 ``` ## Tools (Strumenti) **Servizi AWS** + [Amazon API Gateway](https://aws.amazon.com/api-gateway/) è un servizio completamente gestito che semplifica per gli sviluppatori la creazione, la pubblicazione, la manutenzione, il monitoraggio e la protezione APIs su qualsiasi scala. + [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) è un database NoSQL chiave-valore completamente gestito, serverless e progettato per eseguire applicazioni ad alte prestazioni su qualsiasi scala. + [AWS Lambda](https://aws.amazon.com/lambda/) è un servizio di elaborazione serverless e basato sugli eventi che consente di eseguire codice per praticamente qualsiasi tipo di applicazione o servizio di backend senza dover fornire o gestire server. Puoi lanciare funzioni Lambda da oltre 200 servizi AWS e applicazioni SaaS (Software as a Service) e pagare solo per ciò che usi. **Strumenti** + [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) viene utilizzato come sistema di controllo della versione per lo sviluppo del codice in questo modello. + [Python](https://www.python.org/) è usato come linguaggio di programmazione per questo modello. Python fornisce strutture di dati di alto livello e un approccio alla programmazione orientata agli oggetti. AWS Lambda fornisce un runtime Python integrato che semplifica il funzionamento dei servizi Python. + [Visual Studio Code](https://code.visualstudio.com/) viene utilizzato come IDE per lo sviluppo e il test di questo modello. Puoi usare qualsiasi IDE che supporti lo sviluppo in Python (ad esempio, [PyCharm](https://www.jetbrains.com/pycharm/)). + [AWS Cloud Development Kit (AWS CDK](https://aws.amazon.com/cdk/)) è un framework di sviluppo software open source che consente di definire le risorse delle applicazioni cloud utilizzando linguaggi di programmazione familiari. Questo modello utilizza il CDK per scrivere e distribuire l'infrastruttura cloud come codice. + [La poesia](https://python-poetry.org/) viene utilizzata per gestire le dipendenze del modello. + [Docker](https://www.docker.com/) viene utilizzato da AWS CDK per creare il pacchetto e il layer Lambda. **Codice** Il codice per questo pattern è disponibile nell'archivio di esempi di architettura [esagonale GitHub Lambda](https://github.com/aws-samples/lambda-hexagonal-architecture-sample). ## Best practice Per utilizzare questo pattern in un ambiente di produzione, segui queste best practice: + Utilizza le chiavi gestite dai clienti in AWS Key Management Service (AWS KMS) per crittografare i gruppi di [log di Amazon e le CloudWatch tabelle 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). + Configura [AWS WAF per Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-aws-waf.html) per consentire l'accesso solo dalla rete della tua organizzazione. + Prendi in considerazione altre opzioni per l'autorizzazione dell'API Gateway se IAM non soddisfa le tue esigenze. Ad esempio, puoi utilizzare i [pool di utenti di Amazon Cognito](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html) o gli autorizzatori [API Gateway Lambda](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html). + Usa i backup [DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html). + Configura le funzioni Lambda con un'[implementazione di cloud privato virtuale (VPC)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html) per mantenere il traffico di rete all'interno del cloud. + Aggiorna la configurazione di origine consentita per il [preflight CORS (Cross-Origin Resource Sharing)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) per limitare l'accesso solo al dominio di origine richiedente. + Usa [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) per controllare il codice CDK di AWS per le migliori pratiche di sicurezza. + Prendi in considerazione l'utilizzo di strumenti di scansione del codice per trovare problemi di sicurezza comuni nel codice. Ad esempio, [Bandit](https://bandit.readthedocs.io/en/latest/) è uno strumento progettato per trovare problemi di sicurezza comuni nel codice Python. [PIP-Audit](https://pypi.org/project/pip-audit/) analizza gli ambienti Python alla ricerca di pacchetti che presentano vulnerabilità note. Questo modello utilizza [AWS X-Ray](https://aws.amazon.com/xray/?nc1=h_ls) per tracciare le richieste attraverso il punto di ingresso, il dominio e gli adattatori dell'applicazione. AWS X-Ray aiuta gli sviluppatori a identificare i colli di bottiglia e determinare latenze elevate per migliorare le prestazioni delle applicazioni. ## Epiche ### Inizializza il progetto | Operazione | Description | Competenze richieste | | --- | --- | --- | | Crea il tuo repository. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Installare le dipendenze. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Configura il tuo IDE. | Consigliamo Visual Studio Code, ma puoi usare qualsiasi IDE di tua scelta che supporti Python. I passaggi seguenti si riferiscono a Visual Studio Code.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Esegui test unitari, opzione 1: usa Visual Studio Code. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Esegui test unitari, opzione 2: usa i comandi della shell. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | ### Implementate e testate l'applicazione | Operazione | Description | Competenze richieste | | --- | --- | --- | | Richiedi credenziali temporanee. | Per avere credenziali AWS sulla shell durante l'esecuzione`cdk deploy`, crea credenziali temporanee utilizzando AWS IAM Identity Center (successore di AWS Single Sign-On). Per istruzioni, consulta il post sul blog [Come recuperare le credenziali a breve termine per l'uso della CLI con AWS](https://aws.amazon.com/blogs/security/aws-single-sign-on-now-enables-command-line-interface-access-for-aws-accounts-using-corporate-credentials/) IAM Identity Center. | Sviluppatore di app, AWS DevOps | | Distribuire l'applicazione. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app, AWS DevOps | | Prova l'API, opzione 1: usa la console. | Utilizza la [console API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-test-method.html) per testare l'API. Per ulteriori informazioni sulle operazioni e sui request/response messaggi dell'API, consulta la [sezione sull'utilizzo dell'API del file readme](https://github.com/aws-samples/lambda-hexagonal-architecture-sample/blob/main/README.md#api-usage) nel GitHub repository. | Sviluppatore di app, AWS DevOps | | Prova l'API, opzione 2: usa Postman. | Se vuoi usare uno strumento come [Postman](https://www.postman.com/):[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app, AWS DevOps | ### Sviluppa il servizio | Operazione | Description | Competenze richieste | | --- | --- | --- | | Scrivi test unitari per il dominio aziendale. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Implementa comandi e gestori di comandi. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Scrivi test di integrazione per adattatori secondari. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Implementa adattatori secondari. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Scrivi end-to-end dei test. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | | Implementa gli adattatori primari. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/prescriptive-guidance/latest/patterns/structure-a-python-project-in-hexagonal-architecture-using-aws-lambda.html) | Sviluppatore di app | ## Risorse correlate **Guida APG** + [Creazione di architetture esagonali su AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/hexagonal-architectures/) **Riferimenti AWS** + [Documentazione AWS Lambda](https://docs.aws.amazon.com/lambda/) + [Documentazione CDK AWS](https://docs.aws.amazon.com/cdk/) + [La tua prima app AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/hello_world.html) + [Documentazione API Gateway](https://docs.aws.amazon.com/apigateway/) + [Controlla l'accesso a un'API con autorizzazioni IAM](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html) + [Usa la console API Gateway per testare un metodo API REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-test-method.html) + [Documentazione di Amazon DynamoDB](https://docs.aws.amazon.com/dynamodb/) **Strumenti** + [Sito web git-scm.com](https://git-scm.com/) + [Installazione di Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + [Creare un nuovo GitHub repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository) + [Sito web Python](https://www.python.org/) + [AWS Lambda Powertools per Python](https://docs.powertools.aws.dev/lambda/python/latest/) + [Sito web Postman](https://www.postman.com/) + [Libreria di oggetti fittizi in Python](https://docs.python.org/3/library/unittest.mock.html) + [Sito web di poesia](https://python-poetry.org/) **IDEs** + [Sito Web di Visual Studio Code](https://code.visualstudio.com/) + [PyCharm website](https://www.jetbrains.com/pycharm/)