속성

엔티티 레벨 속성

#[derive(Entity)]
#[entity(
 table = "users",
 schema = "core",
 sql = "full",
 dialect = "postgres",
 uuid = "v7",
 soft_delete,
 returning = "full",
 error = "AppError",
 events,
 hooks,
 commands
)]
pub struct User { /* ... */ }

빠른 참조

table (필수)

#[entity(table = "users")] // → FROM users
#[entity(table = "user_profiles")] // → FROM user_profiles

schema (선택)

#[entity(table = "users")] // → FROM public.users
#[entity(table = "users", schema = "core")] // → FROM core.users
#[entity(table = "users", schema = "auth")] // → FROM auth.users

sql (선택)

#[entity(table = "users", sql = "full")] // 전체 자동화 (기본값)
#[entity(table = "users", sql = "trait")] // 트레이트만, SQL은 직접 구현
#[entity(table = "users", sql = "none")] // 데이터베이스 레이어 없음

dialect (선택)

uuid (선택)

#[entity(table = "users", uuid = "v7")] // 시간순 정렬 (기본값)
#[entity(table = "sessions", uuid = "v4")] // 랜덤 UUID

soft_delete (선택)

#[derive(Entity)]
#[entity(table = "documents", soft_delete)]
pub struct Document {
 #[id]
 pub id: Uuid,
 #[field(create, response)]
 pub title: String,
 #[field(skip)]
 pub deleted_at: Option<DateTime<Utc>>, // 필수 필드
}

returning (선택)

#[entity(table = "logs", returning = "none")] // 가장 빠름
#[entity(table = "users", returning = "full")] // DB 생성 값 가져오기
#[entity(table = "events", returning = "id, created_at")] // 커스텀 컬럼

events(outbox) (선택)

#[derive(Entity, Serialize, Deserialize)]
#[entity(table = "orders", events(outbox), migrations)]
pub struct Order { /* ... */ }
sqlx::query(Order::MIGRATION_OUTBOX).execute(&pool).await?;
struct Notifier;
#[async_trait::async_trait]
impl entity_core::outbox::OutboxHandler for Notifier {
 type Error = anyhow::Error;
 async fn handle(&self, row: &OutboxRow) -> Result<(), Self::Error> {
 deliver(&row.entity, &row.payload).await
 }
}
entity_core::outbox::OutboxDrainer::new(pool, Notifier).run().await;

upsert(...) (선택)

#[derive(Entity)]
#[entity(table = "users", upsert(conflict = "email"))]
pub struct User {
 #[id]
 pub id: Uuid,
 #[field(create, response)]
 #[column(unique)]
 pub email: String,
 #[field(create, update, response)]
 pub name: String,
}

api(guard = "...") (선택)

pub struct RequireAuth;
impl<S: Send + Sync> FromRequestParts<S> for RequireAuth {
 type Rejection = StatusCode;
 async fn from_request_parts(parts: &mut Parts, _: &S) -> Result<Self, Self::Rejection> {
 parts.headers.contains_key("authorization")
 .then_some(Self)
 .ok_or(StatusCode::UNAUTHORIZED)
 }
}
#[derive(Entity)]
#[entity(table = "users", api(tag = "Users", handlers, guard = "RequireAuth", guard(list = "none")))]
pub struct User { /* ... */ }

error (선택)

#[derive(Debug)]
pub enum AppError {
 Database(sqlx::Error),
 NotFound,
 Validation(String),
}
impl std::error::Error for AppError {}
impl std::fmt::Display for AppError { /* ... */ }
// 필수: sqlx::Error에서 변환
impl From<sqlx::Error> for AppError {
 fn from(err: sqlx::Error) -> Self {
 AppError::Database(err)
 }
}
#[derive(Entity)]
#[entity(table = "users", error = "AppError")]
pub struct User { /* ... */ }
// 생성된 리포지토리는 AppError를 사용:
// impl UserRepository for PgPool {
// type Error = AppError;
// ...
// }

events (선택)

#[entity(table = "orders", events)]

pub enum OrderEvent {
 Created(Order),
 Updated { id: Uuid, changes: UpdateOrderRequest },
 Deleted(Uuid),
}

hooks (선택)

#[entity(table = "users", hooks)]

#[async_trait]
pub trait UserHooks: Send + Sync {
 type Error: std::error::Error + Send + Sync;
 async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error>;
 async fn after_create(&self, entity: &User) -> Result<(), Self::Error>;
 async fn before_update(&self, id: &Uuid, dto: &mut UpdateUserRequest) -> Result<(), Self::Error>;
 async fn after_update(&self, entity: &User) -> Result<(), Self::Error>;
 async fn before_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
 async fn after_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
}

commands (선택)

#[entity(table = "users", commands)]
#[command(Register)]
#[command(Deactivate, requires_id)]

필드 레벨 속성

#[id]

#[id]
pub id: Uuid,

#[auto]

#[auto]
#[field(response)]
pub created_at: DateTime<Utc>,

#[field(...)]

#[field(create)] // CreateRequest에만
#[field(update)] // UpdateRequest에만
#[field(response)] // Response에만
#[field(create, response)] // Create와 Response에
#[field(create, update, response)] // 세 가지 모두에
#[field(skip)] // 모든 DTO에서 제외

create

#[field(create)]
pub email: String,
// 생성됨:
pub struct CreateUserRequest {
 pub email: String,
}

update

#[field(update)]
pub name: String, // Option 아님
// 생성됨:
pub struct UpdateUserRequest {
 pub name: Option<String>, // 자동으로 래핑됨
}

response

#[field(response)]
pub email: String,
// 생성됨:
pub struct UserResponse {
 pub id: Uuid, // 항상 포함 (#[id] 있음)
 pub email: String, // 포함됨
}

skip

#[field(skip)]
pub password_hash: String,

#[column(pg_enum = "...")]

#[derive(ValueObject, Debug, Clone, Serialize, Deserialize)]
#[value_object(pg_type = "order_status", sqlx)]
pub enum OrderStatus { Pending, Shipped, Delivered }
#[derive(Entity)]
#[entity(table = "orders", migrations)]
pub struct Order {
 #[id]
 pub id: Uuid,
 #[field(create, update, response)]
 #[column(pg_enum = "order_status")]
 pub status: OrderStatus,
}
for ddl in Order::MIGRATION_TYPES {
 sqlx::query(ddl).execute(&pool).await?;
}
sqlx::query(Order::MIGRATION_UP).execute(&pool).await?;

#[owner]

#[derive(Entity)]
#[entity(table = "orders")]
pub struct Order {
 #[id]
 pub id: Uuid,
 #[owner]
 pub user_id: Uuid,
 #[field(create, update, response)]
 pub note: String,
}
let mine = pool.list_by_owner(user_id, 20, 0).await?;
let order = pool.find_by_id_scoped(id, user_id).await?;
let updated = pool.update_scoped(id, user_id, patch).await?;
let removed = pool.delete_scoped(id, user_id).await?;

#[filter] / #[filter(...)]

#[filter] // 정확히 일치: WHERE field = $n
#[filter(eq)] // 위와 동일
#[filter(like)] // 패턴 일치: WHERE field ILIKE $n
#[filter(range)] // 범위: WHERE field >= $n AND field <= $m

#[belongs_to(Entity)]

#[belongs_to(User)]
pub user_id: Uuid,

#[has_many(Entity)]

#[has_many(Post)]
pub struct User { /* ... */ }

#[projection(Name: fields)]

#[projection(Public: id, name, avatar)]
#[projection(Admin: id, name, email, role)]
pub struct User { /* ... */ }

커맨드 속성

빠른 참조

전체 예제

#[derive(Entity)]
#[entity(
 table = "posts",
 schema = "blog",
 sql = "full",
 dialect = "postgres",
 uuid = "v7",
 soft_delete,
 returning = "full",
 events,
 hooks,
 commands
)]
#[has_many(Comment)]
#[projection(Summary: id, title, author_id, created_at)]
#[command(Publish)]
#[command(Archive, requires_id)]
pub struct Post {
 #[id]
 pub id: Uuid,
 #[field(create, update, response)]
 #[filter(like)]
 pub title: String,
 #[field(create, update, response)]
 pub content: String,
 #[field(create, response)]
 #[belongs_to(User)]
 #[filter]
 pub author_id: Uuid,
 #[field(update, response)]
 pub published: bool,
 #[field(response)]
 #[filter(range)]
 pub view_count: i64,
 #[field(skip)]
 pub moderation_notes: String,
 #[field(skip)]
 pub deleted_at: Option<DateTime<Utc>>,
 #[auto]
 #[field(response)]
 #[filter(range)]
 pub created_at: DateTime<Utc>,
 #[auto]
 #[field(response)]
 pub updated_at: DateTime<Utc>,
}

결정 매트릭스

Update DTO: PATCH 시맨틱

// {} → nothing changes
// {"nickname": null} → nickname = NULL
// {"nickname": "neo"} → nickname = 'neo'
let patch: UpdateProfileRequest = serde_json::from_str(body)?;
let profile = pool.update(id, patch).await?;

migrations(...) 옵션

#[entity(table = "articles", migrations(touch_updated_at, audit, extensions = "pg_trgm"))]
pub struct Article { /* ... */ }
for ddl in Article::MIGRATION_EXTENSIONS { sqlx::query(ddl).execute(&pool).await?; }
sqlx::query(Article::MIGRATION_UP).execute(&pool).await?;
for ddl in Article::MIGRATION_TRIGGERS { sqlx::query(ddl).execute(&pool).await?; }

#[version]

#[derive(Entity)]
#[entity(table = "orders", migrations)]
pub struct Order {
 #[id] pub id: Uuid,
 #[field(create, update, response)] pub note: String,
 #[version] #[field(response)] #[auto] pub version: i32,
}
let patch = UpdateOrderRequest { note: Some("v2".into()), expected_version: order.version };
let updated = pool.update(order.id, patch).await?;

typed_constraints (선택)

#[entity(table = "users", typed_constraints, error = "AppError")]
pub struct User {
 #[id] pub id: Uuid,
 #[field(create, response)] #[column(unique)] pub email: String,
}
match pool.create(dto).await {
 Err(AppError::Constraint(v)) if v.field == Some("email") => conflict_409(),
 other => other?,
}

#[embed(prefix = "...", fields(...))]

pub struct Money { pub amount_cents: i64, pub currency: String }
#[derive(Entity)]
#[entity(table = "products", migrations)]
pub struct Product {
 #[id] pub id: Uuid,
 #[field(create, update, response)]
 #[embed(prefix = "price_", fields(amount_cents: i64, currency: String))]
 pub price: Money,
}

garde 피처 (검증 백엔드)

#[field(create, update, response)]
#[validate(length(min = 3, max = 8))]
pub name: String,
let dto: CreateUserRequest = serde_json::from_str(body)?;
garde::Validate::validate(&dto)?;