属性

实体级属性

#[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")] // 仅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 { /* ... */ }
// 生成的repository使用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>,
}

决策矩阵

更新 DTO:PATCH 语义

let patch = UpdateUserRequest::default()
 .set_name("Neo".into())
 .clear_nickname();

// {} → 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)?;

constraint(...)(可选,需配合 typed_constraints)

#[entity(
 table = "orders",
 typed_constraints,
 constraint(name = "orders_currency_fkey", kind = "foreign_key", field = "currency"),
 constraint(name = "orders_window_check", kind = "check"),
)]

事务性 upsert

let mut tx = pool.begin().await?;
sqlx::query("UPDATE users SET username = NULL WHERE ...").execute(&mut *tx).await?;
let user = UserTransactionRepo::new(&mut tx).upsert(dto).await?;
tx.commit().await?;