Mejores Prácticas

Diseño de Entidades

Mantén las Entidades Enfocadas

// Bueno: Entidades separadas
#[derive(Entity)]
#[entity(table = "users")]
pub struct User {
 #[id]
 pub id: Uuid,
 #[field(create, update, response)]
 pub name: String,
}
#[derive(Entity)]
#[entity(table = "posts")]
pub struct Post {
 #[id]
 pub id: Uuid,
 #[field(create, response)]
 pub author_id: Uuid, // Referencia, no embeber
 #[field(create, update, response)]
 pub title: String,
}
// Malo: Intentar embeber relaciones
pub struct User {
 pub id: Uuid,
 pub posts: Vec<Post>, // No hagas esto
}

Usa Atributos de Campo Significativos

// Bueno: Intención clara
#[field(create, response)] // Se establece una vez, siempre visible
pub email: String,
#[field(update, response)] // Puede cambiar, siempre visible
pub display_name: Option<String>,
#[field(response)] // Solo lectura, calculado/gestionado externamente
pub post_count: i64,
#[field(skip)] // Nunca expuesto
pub password_hash: String,
// Malo: Todo en todas partes
#[field(create, update, response)] // ¿Es realmente necesario para todo?
pub internal_id: String,

Prefiere Option para Campos Nulables

// Base de datos: email VARCHAR NOT NULL
#[field(create, update, response)]
pub email: String,
// Base de datos: bio TEXT NULL
#[field(update, response)]
pub bio: Option<String>,

Seguridad

Siempre Usa #[field(skip)] para Datos Sensibles

// Contraseñas
#[field(skip)]
pub password_hash: String,
// Claves API
#[field(skip)]
pub api_key: String,
// Tokens internos
#[field(skip)]
pub refresh_token: Option<String>,
// PII que no debería estar en respuestas
#[field(skip)]
pub ssn: String,
// Datos de auditoría interna
#[field(skip)]
pub created_by_ip: String,

Separa Entidades Internas y Externas

// Entidad pública
#[derive(Entity)]
#[entity(table = "users")]
pub struct User {
 #[id]
 pub id: Uuid,
 #[field(create, update, response)]
 pub name: String,
 #[field(skip)]
 pub admin_notes: Option<String>,
}
// Entidad solo admin (misma tabla, vista diferente)
#[derive(Entity)]
#[entity(table = "users", sql = "trait")]
pub struct AdminUser {
 #[id]
 pub id: Uuid,
 #[field(response)]
 pub name: String,
 #[field(update, response)] // Ahora visible y editable
 pub admin_notes: Option<String>,
 #[field(response)]
 pub last_login_ip: Option<String>,
}

Rendimiento

Usa sql = "trait" para Consultas Complejas

// CRUD simple - usa generación completa
#[entity(table = "categories", sql = "full")]
// Consultas complejas necesarias - implementa tú mismo
#[entity(table = "posts", sql = "trait")]

Operaciones por Lotes

#[entity(table = "events", sql = "trait")]
pub struct Event { /* ... */ }
pub trait EventBatchRepository {
 async fn create_batch(&self, events: Vec<CreateEventRequest>) -> Result<(), sqlx::Error>;
}
#[async_trait]
impl EventBatchRepository for PgPool {
 async fn create_batch(&self, events: Vec<CreateEventRequest>) -> Result<(), sqlx::Error> {
 let mut tx = self.begin().await?;
 for event in events {
 let entity = Event::from(event);
 let insertable = InsertableEvent::from(&entity);
 // Insertar dentro de transacción
 }
 tx.commit().await?;
 Ok(())
 }
}

Evita Consultas N+1

// Malo: Consultas N+1
let posts = pool.list(100, 0).await?;
for post in &posts {
 let author = pool.find_user_by_id(post.author_id).await?; // ¡N consultas!
}
// Bueno: Una sola consulta con join
let posts_with_authors = pool.list_with_authors(100, 0).await?; // 1 consulta

Testing

Usa Base de Datos de Prueba Separada

#[cfg(test)]
mod tests {
 use sqlx::PgPool;
 async fn setup_test_db() -> PgPool {
 let url = std::env::var("TEST_DATABASE_URL")
 .expect("TEST_DATABASE_URL must be set");
 let pool = PgPool::connect(&url).await.unwrap();
 // Ejecutar migraciones
 sqlx::migrate!("./migrations")
 .run(&pool)
 .await
 .unwrap();
 pool
 }
 #[tokio::test]
 async fn test_create_user() {
 let pool = setup_test_db().await;
 let request = CreateUserRequest {
 username: "test_user".into(),
 email: "test@example.com".into(),
 };
 let user = pool.create(request).await.unwrap();
 assert_eq!(user.username, "test_user");
 }
}

Prueba DTOs Separadamente

#[test]
fn test_user_response_excludes_password() {
 let user = User {
 id: Uuid::new_v4(),
 username: "test".into(),
 email: "test@example.com".into(),
 password_hash: "secret_hash".into(),
 created_at: Utc::now(),
 };
 let response = UserResponse::from(&user);
 // password_hash no está en UserResponse
 assert_eq!(response.username, "test");
 // No hay forma de acceder a password_hash a través de response
}
#[test]
fn test_update_request_is_partial() {
 let update = UpdateUserRequest {
 username: Some("new_name".into()),
 email: None, // No actualizando email
 };
 assert!(update.username.is_some());
 assert!(update.email.is_none());
}

Organización del Proyecto

Estructura Recomendada

src/
├── entities/ # Definiciones de entidades
│ ├── mod.rs
│ ├── user.rs
│ ├── post.rs
│ └── comment.rs
├── repositories/ # Extensiones de repository personalizadas
│ ├── mod.rs
│ └── post_search.rs
├── handlers/ # Handlers HTTP
│ ├── mod.rs
│ ├── users.rs
│ └── posts.rs
├── services/ # Lógica de negocio
│ ├── mod.rs
│ └── auth.rs
└── main.rs

Re-exporta Tipos Generados

// src/entities/mod.rs
mod user;
mod post;
pub use user::*;
pub use post::*;

Agrupa Entidades Relacionadas

// src/entities/auth/mod.rs
mod user;
mod session;
mod api_key;
pub use user::*;
pub use session::*;
pub use api_key::*;

Errores Comunes

1. Olvidar #[field(skip)] en Campos Sensibles

// Incorrecto: password_hash estará en Response!
pub struct User {
 pub password_hash: String,
}
// Correcto
#[field(skip)]
pub password_hash: String,

2. Usar sql = "full" Cuando Necesitas Joins

3. No Manejar Actualizaciones Opcionales

// UpdateUserRequest generado tiene Option<String> para name
// Tu lógica de actualización debería manejar None (sin cambio) vs Some (cambio)

4. Duplicar Lógica de Negocio

// Bueno: Capa de servicio
impl UserService {
 pub async fn create_user(&self, request: CreateUserRequest) -> Result<User, AppError> {
 self.validate_email(&request.email)?;
 self.check_username_available(&request.username).await?;
 self.pool.create(request).await.map_err(Into::into)
 }
}
// Malo: Lógica dispersa en handlers
pub async fn create_user(pool: State<PgPool>, request: Json<CreateUserRequest>) -> ... {
 // Validación aquí
 // Reglas de negocio aquí
 // Llamada al repository aquí
 // Todo mezclado
}

Lista de Verificación

Ver También