Andamiaje
Rustango tiene dos capas de generación de código — así rara vez conectas boilerplate a mano:
- El generador de proyectos —
cargo rustango newcrea un proyecto entero nuevo a partir de una plantilla. - Generadores dentro del proyecto —
manage startappy la familiamanage make:*añaden apps, vistas, serializers, jobs y más dentro de un proyecto existente.
Tabla de contenidos
- Instalar el generador
- Crear un proyecto:
cargo rustango new - Qué se genera
- Añadir un módulo de funcionalidad:
manage startapp - Generar archivos sueltos: los comandos
make:* - Un flujo típico
Instalar el generador
cargo rustango es un subcomando de Cargo. Instálalo una vez, de forma global:
cargo install cargo-rustango
Eso coloca un binario cargo-rustango en tu PATH; Cargo lo expone entonces como cargo rustango — un comando global disponible en cualquier parte, incluso fuera de un proyecto. La misma instalación añade cargo-rgo, así que cargo rgo … es una forma más corta de escribir cualquier comando cargo rustango ….
La versión del propio generador es la que obtiene tu proyecto
cargo rustango new escribe rustango = "MAJOR.MINOR" en el Cargo.toml generado, tomada de la versión del generador, no de lo más reciente que haya en crates.io. Sea cual sea el generador que instales, esa es la versión que fija tu proyecto.
Eso es casi siempre lo que quieres, y por eso el comando de instalación de arriba no lleva versión fijada: el generador más nuevo escribe la fijación más nueva, y los dos no pueden separarse.
Conviene saberlo cuando quieres deliberadamente una versión anterior — para que coincida con un proyecto que ya está en ella, o para reproducir un reporte. Fija el generador, no el proyecto:
cargo install cargo-rustango --version 0.57.0
Comprueba cuál tienes con cargo rustango --version. Actualizarlo más adelante es el mismo comando con --force, y solo afecta a los proyectos que generes después — la fijación de un proyecto existente es una línea en su propio Cargo.toml, que editas tú.
Crear un proyecto: cargo rustango new
cargo rustango new <name> [--template api|fullstack|tenant]
[--backend postgres|sqlite|mysql]
[--features <lista>]
<name>— el nombre del proyecto (y de la crate). Debe ser un nombre de crate de Cargo válido ([A-Za-z_][A-Za-z0-9_-]*), y el directorio de destino no debe existir ya.--template/-t— qué plantilla inicial generar (por defecto: fullstack).--backend/-b— sobre qué base de datos corre el proyecto (por defecto: postgres).--features/-F— funcionalidades extra de Rustango, separadas por comas o espacios.--alias rgo— llamar a la dependenciargoen lugar derustango(ver Un nombre más corto).--interactive/-i— elegir desde menús en su lugar. Uncargo rustango newa secas en un terminal hace lo mismo.--help/-h,--version— uso y versión.
Ejecutado sin argumentos, pregunta:
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]
El asistente fija exactamente los campos que fijan los flags e imprime la línea de comandos equivalente antes de escribir nada — usarlo una vez te enseña los flags, y hay un solo camino de código que decide qué contiene un proyecto. Sin terminal (un script, un job de CI) falla con un mensaje en lugar de esperar una respuesta que nadie va a dar.
Las tres plantillas
Cada una se corresponde con una de las tres formas de app de Rustango:
| Plantilla | Lo que obtienes | Recurre a ella cuando |
|---|---|---|
api | ORM + Axum a secas, sin admin | Servicios solo-JSON y microservicios |
fullstack (por defecto) | ORM + el auto-admin | Una app web típica con back-office |
tenant | Multi-tenancy + consola de operador + apps por tenant | SaaS que aloja muchos tenants aislados |
Cuentas de usuario. Solo --template tenant trae integrado el inicio de sesión para los usuarios de tu app. Con api o fullstack, el login del admin es solo para el equipo; construye el registro y el inicio de sesión de tus usuarios como en Primeros pasos, Paso 14.
cargo rustango new myblog # fullstack (the default)
cargo rustango new api_demo --template api
cargo rustango new shop --template tenant
Elegir la base de datos: --backend
cargo rustango new edge --backend sqlite
cargo rustango new shop --backend mysql
--backend decide qué usa cargo run, y da forma a todo el proyecto en consecuencia — la DATABASE_URL de .env.example, los servicios de docker-compose.yml, la url de cada nivel de configuración y las instrucciones de arranque del README. Elige sqlite y no hay servicio de base de datos alguno: es un fichero junto al proyecto, creado por el primer cargo run -- migrate.
Los tres backends siguen cableados en los [features] generados, así que los otros dos quedan a un flag de distancia:
cargo run --no-default-features --features sqlite
Encender más del framework: --features
cargo rustango new saas --template tenant --features csrf,sso,cache-redis
Una plantilla enciende un conjunto razonable; --features añade las opciones que ninguna de ellas alcanza:
| Funcionalidad | Qué añade |
|---|---|
csrf | Middleware de protección CSRF para POST de formularios |
sso / admin-sso | Inicio de sesión único OIDC, para usuarios de la app / para el sitio de admin |
passkey | Autenticación WebAuthn / passkey |
cache-redis / cache-page | Backend de caché Redis / caché de páginas completas |
jobs / jobs-postgres | Cola de trabajos en segundo plano, en proceso / respaldada por la base de datos y por tanto resistente a reinicios |
scheduler | Tareas en segundo plano a intervalos fijos |
email-smtp | Transporte SMTP para el framework de email |
mcp | Servidor Model Context Protocol para agentes de IA (solo plantilla tenant) |
http2 | Servir HTTP/2 sin cifrar (h2c) junto a HTTP/1 |
static-files / security-headers | Servir archivos estáticos con nombres de assets con hash / cabeceras de seguridad y constructor de CSP, sin el admin |
test-client | Cliente HTTP de pruebas en proceso, sin el admin |
testkit / test_utils | Constructores de esquema, factorías y constructores solo para tests |
--features tenancy solo elige --template tenant; con otra plantilla se rechaza, porque solo el main.rs de la plantilla tenant sirve la multi-tenancy. cargo rustango new --help imprime esta lista. Los backends no son válidos aquí — usa --backend. Nombrar uno como funcionalidad se rechaza, porque fijaría el backend del framework mientras la funcionalidad propia del proyecto quedaría apagada, y #[derive(Model)] alinea lo que emite con las funcionalidades del proyecto.
Un nombre más corto: rgo
cargo rgo new shop --alias rgo
--alias rgo declara la dependencia con el nombre rgo, y el código generado usa rutas rgo:: y atributos #[rgo(...)]. La crate rgo de crates.io es de otra persona, así que esto es un renombrado del paquete 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(...)] significa exactamente lo mismo que #[rustango(...)], llames como llames a la dependencia. Un struct o campo usa un solo nombre: mezclar #[rustango(...)] y #[rgo(...)] en el mismo elemento es un error de compilación. manage startapp y los generadores make:* leen el Cargo.toml y también escriben rutas rgo:: y #[rgo(...)].
Qué se genera
Cada plantilla escribe un proyecto de Cargo autocontenido:
<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 binario para todo
src/main.rs es el único punto de entrada. Arranca el servidor HTTP y despacha cada verbo de manage — no hay un script de manage ni un src/bin/manage.rs aparte. Los módulos viven en el target de biblioteca (src/lib.rs), así que main.rs llega a ellos por el nombre del crate, y también un binario worker bajo src/bin/. El main.rs de la plantilla api, recortado:
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
}
Así que cargo run arranca el servidor, y cargo run -- <verb> ejecuta migraciones, generadores y lo demás.
Cómo difieren las plantillas dentro de main.rs / urls.rs:
- api — sin admin;
urls::api()simplemente agrega tus propias rutas. - fullstack — el mismo
urls.rs, másadmin_prefix(&settings)y un ayudanteadmin_router(pool, &settings)quemain.rsmonta conCli::try_nest_with(urls::admin_prefix(&settings), …), construido a partir del pool del servidor. El prefijo es[admin] url_prefix(o[routes] admin_url), si no/admin.main.rscarga los ajustes una vez y los pasa alCliconwith_loaded_settings. Recibe unrustango::sql::Pool, así que no nombra ningún driver, y queda detrás de un inicio de sesión: crea la cuenta concargo run -- create-admin <username> --superuser(consulta Primeros pasos, Paso 11). - tenant —
main.rsañade.tenancy(), sirviendo la consola de operador en el dominio ápice y cada tenant bajo su propio subdominio, y.with_tenant_provisioning("migrations")para las páginas New tenant y Database servers de la consola (bórralo para desactivarlas; guardar un servidor necesitaRUSTANGO_SECRET_KEY). Las propias tablas del framework se generan en una carpetasystem/migrations/a partir de los modelos compilados en el primercargo run -- migrate— sin JSON de bootstrap entregado a mano, así que la primerísima migración funciona sin configuración adicional.
Configuración por capas
Los ajustes cargan primero config/default.toml, luego config/<RUSTANGO_ENV>_settings.toml encima. RUSTANGO_ENV es dev por defecto, así que un cargo run recién generado funciona sin ediciones; establece RUSTANGO_ENV=prod en producción para recoger prod_settings.toml.
El entorno siempre gana sobre los archivos. RUSTANGO__SECTION__KEY sobrescribe [section] key, y algunas claves tienen además una variable de entorno propia que gana sobre ambas: DATABASE_URL (o las variables DB_*) para [database] url, RUSTANGO_BIND para [server] bind, RUSTANGO_APEX_DOMAIN para [tenancy] apex_domain. Así, la URL de la base de datos sale de DATABASE_URL / DB_*, luego de RUSTANGO__DATABASE__URL, luego de [database] url; el nivel prod rechaza una URL que venga de un archivo de ajustes. cargo run -- check --settings lista cada clave y de dónde sale su valor, con los secretos ocultos.
Los archivos de dev y staging definen un [brand] tagline de dev y staging. Para cambiarlo, o para poner tu propio nombre y logo, consulta Marca y las claves de configuración del admin.
Ajustes que no surten efecto por sí solos
No todas las claves las lee el framework. Las claves sin efecto se eliminaron en 0.62.0 ([sso], [auth.jwt] issuer / audience, [admin] primary_color / csrf_cookie_secure / session_timeout_minutes); un archivo o variable RUSTANGO__* que aún defina una no carga y nombra qué usar en su lugar.
| Clave | Estado |
|---|---|
[audit] retention_days | La lee audit-cleanup sin --days ni --keep-last; programa ese comando. |
[jobs], [i18n], [cache], [mail], [mcp], TTLs de [auth.jwt], [admin] | Cableadas por el usuario: solo las lee el constructor al que llamas (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). |
Primera ejecución
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
Añadir un módulo de funcionalidad: manage startapp
Genera un módulo autocontenido de modelos, vistas y rutas relacionados:
cargo run -- startapp blog
Escribe src/blog/ conteniendo mod.rs, models.rs (un modelo inicial nombrado según la forma singular de la app — blog → Blog), views.rs, urls.rs y tests.rs, luego declara el módulo en src/lib.rs (pub mod blog;; mod blog; en src/main.rs en un proyecto sin lib.rs) y fusiona sus rutas en urls::api().
Opciones:
--into <dir>— genera el andamiaje bajosrc/<dir>/(--into appsescribesrc/apps/blog/); imprime las líneas del módulo padre y deurls.rsque hay que añadir.--with-manage-bin— emite además unsrc/bin/manage.rs(para diseños que prefieren un binario de manage aparte).
Generar archivos sueltos: los comandos make:*
Dentro de un proyecto, los verbos make:* generan el andamiaje de un archivo cada vez. La referencia completa por flag vive en la referencia de la CLI de manage; las formas comunes son:
| Comando | Genera |
|---|---|
make:viewset <Name> [--model <M>] | Un ViewSet CRUD |
make:serializer <Name> [--model <M>] | Un serializer para dar forma a request/response |
make:api_routes <app> | Un agregador de rutas de API para una app |
make:form <Name> | Un formulario HTML con validación |
make:job <Name> | Un handler de job en segundo plano |
make:scheduled <Name> | Una tarea de intervalo fijo para scheduler::Scheduler |
make:worker <Name> | Un binario worker bajo src/bin/ que vacía la cola de jobs |
make:notification <Name> | Una notificación por correo: un struct que construye un Email |
make:middleware <Name> | Un esqueleto de middleware |
make:test <Name> | Un módulo de pruebas usando el cliente de pruebas en el mismo proceso |
cargo run -- make:viewset PostViewSet --model Post
cargo run -- make:serializer PostSerializer --model Post
cargo run -- make:test post_smoke
Un flujo típico
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
