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 :
- Le générateur de projet —
cargo rustango newcrée un tout nouveau projet à partir d'un template. - Les générateurs internes au projet —
manage startappet la famillemanage make:*ajoutent des apps, des vues, des sérialiseurs, des jobs, et bien plus au sein d'un projet existant.
Table des matières
- Installer le générateur
- Créer un projet :
cargo rustango new - Ce qui est généré
- Ajouter un module fonctionnel :
manage startapp - Générer des fichiers individuels : les commandes
make:* - Un flux typique
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épendancergoau lieu derustango(voir Un nom plus court).--interactive/-i— choisir dans des menus à la place. Uncargo rustango newnu 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 :
| Template | Ce que vous obtenez | À utiliser quand |
|---|---|---|
api | ORM nu + Axum, sans admin | Services et microservices JSON uniquement |
fullstack (par défaut) | ORM + l'admin automatique | Une application web classique avec un back-office |
tenant | Multi-tenancy + console opérateur + apps par tenant | Hé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 |
|---|---|
csrf | Middleware de protection CSRF pour les POST de formulaires |
sso / admin-sso | Authentification unique OIDC, pour les utilisateurs / pour le site d'admin |
passkey | Authentification WebAuthn / passkey |
cache-redis / cache-page | Backend de cache Redis / mise en cache de pages entières |
jobs / jobs-postgres | File de tâches en arrière-plan, en processus / adossée à la base et donc résistante aux redémarrages |
scheduler | Tâches d'arrière-plan à intervalle fixe |
email-smtp | Transport SMTP pour le framework e-mail |
mcp | Serveur Model Context Protocol pour les agents IA (modèle tenant uniquement) |
http2 | Servir HTTP/2 en clair (h2c) à côté de HTTP/1 |
static-files / security-headers | Service de fichiers statiques avec noms d'assets hachés / en-têtes de sécurité et constructeur de CSP, sans l'admin |
test-client | Client HTTP de test en processus, sans l'admin |
testkit / test_utils | Constructeurs 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, plusadmin_prefix(&settings)et un assistantadmin_router(pool, &settings)quemain.rsmonte avecCli::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.rscharge les réglages une fois et les passe à laCliavecwith_loaded_settings. Il prend unrustango::sql::Pool, donc ne nomme aucun pilote, et se trouve derrière une connexion : créez le compte aveccargo run -- create-admin <username> --superuser(voir Prise en main, étape 11). - tenant —
main.rsajoute.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 demandeRUSTANGO_SECRET_KEY). Les propres tables du framework sont générées dans un dossiersystem/migrations/à partir des modèles compilés lors du premiercargo 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_days | Lue 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 soussrc/<dir>/(--into appsécritsrc/apps/blog/) ; affiche les lignes du module parent et deurls.rsà ajouter.--with-manage-bin— génère aussi unsrc/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 :
| Commande | Gé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
