Rustango docs
← Premiers pas

Scaffolding

Rustango dispose de deux niveaux de génération de code — de sorte que vous n'avez presque jamais à câbler de code répétitif à la main :

  1. Le générateur de projet — cargo rustango new crée un tout nouveau projet à partir d'un template.
  2. Les générateurs internes au projet — manage startapp et la famille manage make:* ajoutent des apps, des vues, des sérialiseurs, des jobs, et bien plus au sein d'un projet existant.

cargo rustango new scaffolds a complete, ready-to-run project — Cargo manifest, config tiers, Docker, migrations, and src — in one command

Table des matières


Installer le générateur

cargo rustango est une sous-commande Cargo. Installez-la une fois, globalement :

cargo install cargo-rustango

Cela place un binaire cargo-rustango sur votre PATH ; Cargo l'expose alors comme cargo rustango — une commande globale disponible partout, même en dehors d'un projet. La même installation ajoute cargo-rgo : cargo rgo … est une façon plus courte de taper toute commande cargo rustango ….

La version du générateur est celle que votre projet obtient

cargo rustango new écrit rustango = "MAJOR.MINOR" dans le Cargo.toml généré, en reprenant la version du générateur, et non la plus récente publiée sur crates.io. Quel que soit le générateur que vous installez, c'est la version que votre projet épingle.

C'est presque toujours ce que vous voulez, et c'est pour cela que la commande d'installation ci-dessus n'est pas épinglée : le générateur le plus récent écrit l'épinglage le plus récent, et les deux ne peuvent pas diverger.

Cela vaut la peine de le savoir lorsque vous voulez délibérément une version plus ancienne — pour coller à un projet qui y est déjà, ou pour reproduire un rapport. Épinglez le générateur, pas le projet :

cargo install cargo-rustango --version 0.57.0

Vérifiez laquelle vous avez avec cargo rustango --version. Mettre à jour plus tard, c'est la même commande avec --force, et cela n'affecte que les projets que vous générez ensuite — l'épinglage d'un projet existant est une ligne dans son propre Cargo.toml, que vous modifiez vous-même.


Créer un projet : cargo rustango new

cargo rustango new <name> [--template api|fullstack|tenant]
                          [--backend postgres|sqlite|mysql]
                          [--features <liste>]
  • <name> — le nom du projet (et de la crate). Il doit s'agir d'un nom de crate Cargo valide ([A-Za-z_][A-Za-z0-9_-]*), et le répertoire cible ne doit pas déjà exister.
  • --template / -t — quel template utiliser pour l'échafaudage (par défaut : fullstack).
  • --backend / -b — sur quelle base de données le projet tourne (par défaut : postgres).
  • --features / -F — fonctionnalités Rustango supplémentaires, séparées par des virgules ou des espaces.
  • --alias rgo — nommer la dépendance rgo au lieu de rustango (voir Un nom plus court).
  • --interactive / -i — choisir dans des menus à la place. Un cargo rustango new nu sur un terminal fait de même.
  • --help / -h, --version — usage et version.

Lancé sans argument, il pose les questions :

  rustango — new project
  (enter accepts the default; ctrl-c aborts)

  Project name: shop

  Template
    1) fullstack  ORM + auto-admin + forms — the usual starting point  (default)
    2) api        bare ORM + axum, no admin UI — for JSON-only services
    3) tenant     multi-tenancy: tenant registry + operator console
  > 3

  Database
    1) postgres  every feature, including schema-mode tenancy  (default)
    2) sqlite    a file beside the project — no server to run
    3) mysql     MySQL 8.0+ / MariaDB
  > 1

  Extra features  (numbers, e.g. `1 3 4` — enter for none)
     1) csrf         CSRF protection middleware for form POSTs
     2) sso          OIDC single sign-on for application users
     …
  > 1 2

  Same thing without the wizard:
    cargo rustango new shop --template tenant --backend postgres --features csrf,sso

  Create it? [Y/n]

L'assistant règle exactement les champs que règlent les flags et affiche la ligne de commande équivalente avant d'écrire quoi que ce soit — s'en servir une fois vous apprend les flags, et un seul chemin de code décide de ce que contient un projet. Sans terminal (script, job CI), il échoue avec un message au lieu d'attendre une réponse que personne n'est là pour donner.

Les trois templates

Chacun correspond à une des trois formes d'application de Rustango :

TemplateCe que vous obtenezÀ utiliser quand
apiORM nu + Axum, sans adminServices et microservices JSON uniquement
fullstack (par défaut)ORM + l'admin automatiqueUne application web classique avec un back-office
tenantMulti-tenancy + console opérateur + apps par tenantHébergement SaaS avec de nombreux tenants isolés

Comptes utilisateurs. Seul --template tenant intègre la connexion des utilisateurs de votre app. Avec api ou fullstack, la connexion de l'admin est réservée à l'équipe ; construisez l'inscription et la connexion de vos utilisateurs comme à l'étape 14 de la prise en main.

cargo rustango new myblog                      # fullstack (the default)
cargo rustango new api_demo  --template api
cargo rustango new shop      --template tenant

Choisir la base de données : --backend

cargo rustango new edge --backend sqlite
cargo rustango new shop --backend mysql

--backend décide de ce qu'utilise cargo run, et façonne tout le projet en conséquence — la DATABASE_URL dans .env.example, les services de docker-compose.yml, l'url de chaque palier de configuration et les instructions de démarrage du README. Choisissez sqlite et il n'y a aucun service de base de données : c'est un fichier à côté du projet, créé par le premier cargo run -- migrate.

Les trois backends restent câblés dans les [features] générées, les deux autres sont donc à un flag :

cargo run --no-default-features --features sqlite

Activer plus du framework : --features

cargo rustango new saas --template tenant --features csrf,sso,cache-redis

Un template active un ensemble raisonnable ; --features ajoute les options qu'aucun d'eux n'atteint :

FonctionnalitéCe qu'elle ajoute
csrfMiddleware de protection CSRF pour les POST de formulaires
sso / admin-ssoAuthentification unique OIDC, pour les utilisateurs / pour le site d'admin
passkeyAuthentification WebAuthn / passkey
cache-redis / cache-pageBackend de cache Redis / mise en cache de pages entières
jobs / jobs-postgresFile de tâches en arrière-plan, en processus / adossée à la base et donc résistante aux redémarrages
schedulerTâches d'arrière-plan à intervalle fixe
email-smtpTransport SMTP pour le framework e-mail
mcpServeur Model Context Protocol pour les agents IA (modèle tenant uniquement)
http2Servir HTTP/2 en clair (h2c) à côté de HTTP/1
static-files / security-headersService de fichiers statiques avec noms d'assets hachés / en-têtes de sécurité et constructeur de CSP, sans l'admin
test-clientClient HTTP de test en processus, sans l'admin
testkit / test_utilsConstructeurs de schéma, fabriques et constructeurs réservés aux tests

--features tenancy seul choisit --template tenant ; avec un autre template il est refusé, car seul le main.rs du template tenant sert la multi-tenancy. cargo rustango new --help affiche cette liste. Les backends ne sont pas valides ici — passez par --backend. En nommer un comme fonctionnalité est refusé : cela figerait le backend du framework alors que la fonctionnalité propre au projet resterait éteinte, et #[derive(Model)] aligne ses émissions sur les fonctionnalités du projet.

Un nom plus court : rgo

cargo rgo new shop --alias rgo

--alias rgo déclare la dépendance sous le nom rgo, et le code généré utilise des chemins rgo:: et des attributs #[rgo(...)]. La crate rgo sur crates.io appartient à quelqu'un d'autre ; il s'agit donc d'un renommage du paquet rustango :

[dependencies]
rgo = { package = "rustango", version = "0.67", default-features = false, features = ["batteries"] }

[features]
postgres = ["rgo/postgres"]
use rgo::prelude::*;

#[derive(Model, Debug, Clone)]
#[rgo(table = "item", display = "name")]
pub struct Item {
    #[rgo(primary_key)]
    pub id: Auto<i64>,
    #[rgo(max_length = 64)]
    pub name: String,
}

#[rgo(...)] signifie exactement la même chose que #[rustango(...)], quel que soit le nom donné à la dépendance. Une struct ou un champ utilise un seul nom : mélanger #[rustango(...)] et #[rgo(...)] sur le même élément est une erreur de compilation. manage startapp et les générateurs make:* lisent le Cargo.toml et écrivent eux aussi des chemins rgo:: et #[rgo(...)].


Ce qui est généré

Chaque template écrit un projet Cargo autonome :

<name>/
  Cargo.toml            # the rustango dependency + features for this template
  .env.example          # copy to .env (DATABASE_URL, RUSTANGO_SESSION_SECRET, …)
  .gitignore
  rust-toolchain.toml   # selects the `stable` toolchain + rustfmt/clippy/rust-analyzer
  docker-compose.yml    # the database service (none for sqlite) + a cargo-watch dev container
  Dockerfile            # production image (multi-stage, release, non-root)
  Dockerfile.dev        # the dev image docker-compose.yml builds
  .dockerignore
  README.md
  config/
    default.toml        # settings shared across every environment
    dev_settings.toml   # per-tier overrides …
    staging_settings.toml
    prod_settings.toml
  migrations/           # JSON migration files (committed to git)
  system/migrations/    # the framework's own tables, generated on first migrate (commit them)
  src/
    lib.rs              # the app as a library: `pub mod models; pub mod urls; pub mod views;`
    main.rs             # the single binary — HTTP server + every manage verb
    models.rs           # your #[derive(Model)] structs
    views.rs            # request handlers ("views")
    urls.rs             # pub fn api() -> Router that aggregates your routes

Un seul binaire pour tout

src/main.rs est le seul point d'entrée. Il démarre le serveur HTTP et dispatche chaque verbe manage — il n'y a pas de script manage séparé ni de src/bin/manage.rs. Les modules vivent dans la cible bibliothèque (src/lib.rs), donc main.rs les atteint par le nom du crate, tout comme un binaire worker sous src/bin/. Le main.rs du template api, abrégé :

use myapp::urls;

#[rustango::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _ = dotenvy::dotenv();
    rustango::manage::Cli::new()
        .api(urls::api())
        .with_health()   // /health + /ready endpoints (every template)
        .run()
        .await
}

Ainsi, cargo run démarre le serveur, et cargo run -- <verb> exécute les migrations, les générateurs, et le reste.

En quoi les templates diffèrent à l'intérieur de main.rs / urls.rs :

  • api — pas d'admin ; urls::api() se contente d'agréger vos propres routes.
  • fullstack — le même urls.rs, plus admin_prefix(&settings) et un assistant admin_router(pool, &settings) que main.rs monte avec Cli::try_nest_with(urls::admin_prefix(&settings), …), construit à partir du pool du serveur. Le préfixe est [admin] url_prefix (ou [routes] admin_url), sinon /admin. main.rs charge les réglages une fois et les passe à la Cli avec with_loaded_settings. Il prend un rustango::sql::Pool, donc ne nomme aucun pilote, et se trouve derrière une connexion : créez le compte avec cargo run -- create-admin <username> --superuser (voir Prise en main, étape 11).
  • tenant — main.rs ajoute .tenancy(), servant la console opérateur sur le domaine apex et chaque tenant sous son propre sous-domaine, et .with_tenant_provisioning("migrations") pour les pages New tenant et Database servers de la console (supprimez-le pour les désactiver ; enregistrer un serveur demande RUSTANGO_SECRET_KEY). Les propres tables du framework sont générées dans un dossier system/migrations/ à partir des modèles compilés lors du premier cargo run -- migrate — aucun JSON de bootstrap livré à la main, donc le tout premier migrate fonctionne sans configuration supplémentaire.

Configuration en couches

Les paramètres se chargent d'abord depuis config/default.toml, puis depuis config/<RUSTANGO_ENV>_settings.toml par-dessus. RUSTANGO_ENV vaut dev par défaut, si bien qu'un cargo run juste après l'échafaudage fonctionne sans aucune modification ; définissez RUSTANGO_ENV=prod en production pour prendre en compte prod_settings.toml.

L'environnement l'emporte toujours sur les fichiers. RUSTANGO__SECTION__KEY remplace [section] key, et quelques clés ont aussi une variable d'environnement propre qui passe avant les deux : DATABASE_URL (ou les variables DB_*) pour [database] url, RUSTANGO_BIND pour [server] bind, RUSTANGO_APEX_DOMAIN pour [tenancy] apex_domain. L'URL de la base vient donc de DATABASE_URL / DB_*, puis de RUSTANGO__DATABASE__URL, puis de [database] url ; le niveau prod refuse une URL venant d'un fichier de paramètres. cargo run -- check --settings liste chaque clé et l'origine de sa valeur, secrets masqués.

Les fichiers dev et staging définissent un [brand] tagline valant dev et staging. Pour le changer, ou pour définir votre propre nom et logo, voir Identité visuelle et les clés de configuration de l'admin.

Paramètres sans effet par eux-mêmes

Toutes les clés ne sont pas lues par le framework. Les clés sans effet ont été supprimées en 0.62.0 ([sso], [auth.jwt] issuer / audience, [admin] primary_color / csrf_cookie_secure / session_timeout_minutes) ; un fichier ou une variable RUSTANGO__* qui en définit encore une ne se charge pas et indique quoi utiliser à la place.

CléStatut
[audit] retention_daysLue par audit-cleanup sans --days ni --keep-last ; planifiez cette commande.
[jobs], [i18n], [cache], [mail], [mcp], TTL de [auth.jwt], [admin]Câblés par l'utilisateur : lus uniquement par le constructeur que vous appelez (jobs::inmemory_from_settings, Translator::from_settings, cache::from_settings_async, email::from_settings, mcp::secure_tenant_router_from_settings, auth_routes::Config::with_jwt_settings, admin::Builder::from_settings).

Premier lancement

cd <name>
cp .env.example .env                     # then change `postgres` -> `localhost` in DATABASE_URL
docker compose up -d --no-deps postgres  # only the database: the rust service holds 8080
cargo run -- makemigrations              # generate the framework's (and your) tables
cargo run -- migrate                     # apply them
cargo run -- create-admin admin --superuser  # fullstack: the admin login (any username)
cargo run -- create-operator ops              # tenant: the operator console login
cargo run                                # serve
cargo run -- --help                      # see every manage verb

Ajouter un module fonctionnel : manage startapp

Il échafaude un module autonome regroupant des modèles, des vues et des routes liés entre eux :

cargo run -- startapp blog

Cela écrit src/blog/ contenant mod.rs, models.rs (un modèle de départ nommé d'après l'app mise au singulier — blog → Blog), views.rs, urls.rs, et tests.rs, puis déclare le module dans src/lib.rs (pub mod blog; ; mod blog; dans src/main.rs pour un projet sans lib.rs) et fusionne ses routes dans urls::api().

Options :

  • --into <dir> — échafaude plutôt sous src/<dir>/ (--into apps écrit src/apps/blog/) ; affiche les lignes du module parent et de urls.rs à ajouter.
  • --with-manage-bin — génère aussi un src/bin/manage.rs (pour les architectures qui préfèrent un binaire manage séparé).

Générer des fichiers individuels : les commandes make:*

Au sein d'un projet, les verbes make:* échafaudent un fichier à la fois. La référence complète, drapeau par drapeau, se trouve dans la référence CLI manage ; les formes les plus courantes sont :

CommandeGénère
make:viewset <Name> [--model <M>]Un ViewSet CRUD
make:serializer <Name> [--model <M>]Un sérialiseur pour la mise en forme des requêtes/réponses
make:api_routes <app>Un agrégateur de routes API pour une app
make:form <Name>Un formulaire HTML avec validation
make:job <Name>Un gestionnaire de job en arrière-plan
make:scheduled <Name>Une tâche à intervalle fixe pour scheduler::Scheduler
make:worker <Name>Un binaire worker sous src/bin/ qui vide la file de jobs
make:notification <Name>Une notification par e-mail : une struct qui construit un Email
make:middleware <Name>Un squelette de middleware
make:test <Name>Un module de test utilisant le client de test in-process
cargo run -- make:viewset PostViewSet --model Post
cargo run -- make:serializer PostSerializer --model Post
cargo run -- make:test post_smoke

Un flux typique

cargo rustango new myblog                              # 1. scaffold the project
cd myblog
cargo run -- startapp blog                             # 2. add a feature module
# …rename the starter `Blog` in src/blog/models.rs to `Post`, add fields…
cargo run -- makemigrations                            # 3. generate a migration
cargo run -- migrate                                   # 4. apply it
cargo run -- make:viewset PostViewSet --model Post     # 5. expose a JSON API
# …add `pub mod post_view_set;` to src/lib.rs and the `.nest_with` line from
#    the end of src/post_view_set.rs to src/main.rs…
cargo run                                              # 6. serve the URL make:viewset printed