Pacchetti di regole di conformità

Rules grouped by type, with packs and a browsable catalog

I pacchetti di regole sono raccolte curate di regole di conformità che codificano le best practice dei pattern architetturali più comuni. Invece di scrivere le regole da zero, installa un pacchetto e ottieni in pochi secondi un set di regole collaudato e con una linea precisa.

Perché i pacchetti di regole?

La maggior parte dei team segue pattern ben noti: microservizi, clean architecture, sistemi event-driven. Ogni pattern comporta vincoli che andrebbero applicati automaticamente:

  • I microservizi non dovrebbero condividere i database
  • I livelli di dominio non dovrebbero importare codice di infrastruttura
  • Gli eventi dovrebbero rispettare un contratto di schema

I pacchetti di regole trasformano questi principi in guardrail eseguibili.

Pacchetti disponibili

Pacchetto Regole Obiettivo
Microservices 10 Confini dei servizi, deployment indipendente, comunicazione delimitata
Clean Architecture 9 Confini tra livelli, isolamento del dominio, applicazione di port/adapter
Event-Driven 8 Conformità dei canali, requisiti di schema, dead letter queue
API-First 8 Requisiti di contratto, versionamento, documentazione dell'autenticazione
Security Baseline 8 Obbligo del gateway, gestione dei segreti, controlli sugli accessi esterni

Installare un pacchetto

Tramite la skill archyl-developer

Chiedi al tuo agente di programmazione IA:

Install the microservices conformance rules pack

L'agente chiama il server MCP di Archyl e crea tutte le regole in un'unica operazione.

Tramite l'SDK

import { ArchylClient } from "@archyl/sdk";

const client = new ArchylClient({
  apiKey: process.env.ARCHYL_API_KEY,
  organizationId: "your-org-id",
});

// Install a pack by name
await client.governance.installPack("microservices");

Tramite l'interfaccia

Vai su Hub Agenti > Packs e clicca su Installa su un pacchetto qualsiasi.

Cosa contiene ogni pacchetto

Microservices (10 regole)

  • Nessun database condiviso — Ogni servizio deve possedere i propri dati. Le query tra servizi passano solo tramite API.
  • Deployment indipendente — Nessuna dipendenza in fase di compilazione tra servizi. Le librerie condivise devono essere versionate.
  • Comunicazione delimitata — I servizi comunicano tramite contratti API o canali di eventi definiti, non con accesso diretto al database o condivisione di file.
  • Isolamento dei servizi — Nessun import tra servizi. Ogni servizio ha il proprio albero delle dipendenze.

Clean Architecture (9 regole)

  • Purezza del livello di dominio — Il codice di dominio non ha alcun import esterno. Nessun framework, nessun ORM, nessun HTTP.
  • Direzione delle dipendenze — Le dipendenze puntano verso l'interno. Gli handler dipendono dai servizi, i servizi dipendono dal dominio, mai il contrario.
  • Applicazione di port/adapter — Gli aspetti infrastrutturali (DB, HTTP, messaggistica) risiedono nei package adapter, non nei livelli di dominio o di servizio.
  • Confini tramite interfacce — I servizi usano interfacce (port), non implementazioni concrete.

Event-Driven (8 regole)

  • Conformità dei canali — Produttori e consumatori di eventi devono usare i canali di eventi dichiarati. Nessuna creazione di topic improvvisata.
  • Requisiti di schema — Ogni evento deve avere uno schema definito. Nessun payload non tipizzato.
  • Dead letter queue — I consumatori devono configurare una DLQ per gestire i messaggi non elaborati.
  • Convenzioni di denominazione dei topic — I topic seguono uno schema di denominazione coerente (ad es. domain.entity.event).

API-First (8 regole)

  • Contratto obbligatorio — Ogni endpoint pubblico deve avere un contratto OpenAPI, gRPC o AsyncAPI registrato.
  • Versionamento — Gli endpoint API devono includere un prefisso di versione (/v1/, /v2/).
  • Documentazione dell'autenticazione — Gli schemi di sicurezza devono essere documentati nel contratto.
  • Nessun endpoint non documentato — I file handler senza documentazione di contratto corrispondente generano una violazione.

Security Baseline (8 regole)

  • Obbligo del gateway — Il traffico esterno deve passare da un API gateway o da un load balancer. Nessun servizio esposto direttamente.
  • Gestione dei segreti — Nessun segreto, chiave API o password scritti nel codice sorgente. Usa variabili d'ambiente o un secret manager.
  • Controlli sugli accessi esterni — I servizi che accettano richieste esterne devono applicare autenticazione e rate limiting.
  • TLS obbligatorio — Tutta la comunicazione tra servizi deve usare TLS. Nessun HTTP in chiaro tra servizi.

Personalizzare le regole

Dopo aver installato un pacchetto, ogni regola è completamente modificabile:

  • Cambia la gravità — Declassa una regola da critical a medium se non corrisponde alla tua tolleranza al rischio
  • Disattiva regole specifiche — Disattiva le singole regole che non ti servono senza rimuovere l'intero pacchetto
  • Modifica la configurazione — Adatta glob dei file, pattern, import consentiti o definizioni dei livelli alla struttura del tuo progetto

Vai su Hub Agenti e clicca sull'icona di modifica di una regola qualsiasi per modificarla.

Combinare i pacchetti

I pacchetti si sommano. Installane più di uno per coprire aspetti architetturali diversi:

Combinazione Caso d'uso
Microservices + API-First + Security Baseline Piattaforma di microservizi basata su API con guardrail di sicurezza
Clean Architecture + Security Baseline Monolite con confini rigorosi tra livelli e buone pratiche di sicurezza
Event-Driven + Microservices Sistema di microservizi event-sourced
API-First + Clean Architecture Monolite o monolite modulare guidato dai contratti

Se due pacchetti contengono regole sovrapposte, Archyl le deduplica: nessun conflitto.

Contribuire

I pacchetti di regole sono open source. Puoi proporre nuovi pacchetti, aggiungere regole a quelli esistenti o segnalare problemi:

Prossimi passi