모범 사례

엔티티 설계

엔티티를 집중적으로 유지

// 좋음: 별도의 엔티티
#[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, // 참조, 임베딩 아님
 #[field(create, update, response)]
 pub title: String,
}
// 나쁨: 관계를 임베딩하려는 시도
pub struct User {
 pub id: Uuid,
 pub posts: Vec<Post>, // 이렇게 하지 마세요
}

의미 있는 필드 속성 사용

// 좋음: 명확한 의도
#[field(create, response)] // 한 번 설정, 항상 표시
pub email: String,
#[field(update, response)] // 변경 가능, 항상 표시
pub display_name: Option<String>,
#[field(response)] // 읽기 전용, 다른 곳에서 계산/관리
pub post_count: i64,
#[field(skip)] // 절대 노출되지 않음
pub password_hash: String,
// 나쁨: 모든 곳에 전부
#[field(create, update, response)] // 정말 전부에 필요한가?
pub internal_id: String,

Nullable 필드에 Option 선호

// 데이터베이스: email VARCHAR NOT NULL
#[field(create, update, response)]
pub email: String,
// 데이터베이스: bio TEXT NULL
#[field(update, response)]
pub bio: Option<String>,

보안

민감한 데이터에는 항상 #[field(skip)] 사용

// 비밀번호
#[field(skip)]
pub password_hash: String,
// API 키
#[field(skip)]
pub api_key: String,
// 내부 토큰
#[field(skip)]
pub refresh_token: Option<String>,
// 응답에 포함되면 안 되는 개인정보
#[field(skip)]
pub ssn: String,
// 내부 감사 데이터
#[field(skip)]
pub created_by_ip: String,

내부와 외부 엔티티 분리

// 공개 엔티티
#[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>,
}
// 관리자 전용 엔티티 (같은 테이블, 다른 뷰)
#[derive(Entity)]
#[entity(table = "users", sql = "trait")]
pub struct AdminUser {
 #[id]
 pub id: Uuid,
 #[field(response)]
 pub name: String,
 #[field(update, response)] // 이제 표시되고 편집 가능
 pub admin_notes: Option<String>,
 #[field(response)]
 pub last_login_ip: Option<String>,
}

성능

복잡한 쿼리에는 sql = "trait" 사용

// 단순 CRUD - 전체 생성 사용
#[entity(table = "categories", sql = "full")]
// 복잡한 쿼리 필요 - 직접 구현
#[entity(table = "posts", sql = "trait")]

배치 작업

#[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);
 // 트랜잭션 내에서 삽입
 }
 tx.commit().await?;
 Ok(())
 }
}

N+1 쿼리 방지

// 나쁨: 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개의 쿼리!
}
// 좋음: JOIN을 사용한 단일 쿼리
let posts_with_authors = pool.list_with_authors(100, 0).await?; // 1개의 쿼리

테스트

별도의 테스트 데이터베이스 사용

#[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();
 // 마이그레이션 실행
 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");
 }
}

DTO 별도 테스트

#[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는 UserResponse에 없음
 assert_eq!(response.username, "test");
 // response를 통해 password_hash에 접근할 방법 없음
}
#[test]
fn test_update_request_is_partial() {
 let update = UpdateUserRequest {
 username: Some("new_name".into()),
 email: None, // 이메일 업데이트 안 함
 };
 assert!(update.username.is_some());
 assert!(update.email.is_none());
}

프로젝트 구성

권장 구조

src/
├── entities/ # 엔티티 정의
│ ├── mod.rs
│ ├── user.rs
│ ├── post.rs
│ └── comment.rs
├── repositories/ # 커스텀 리포지토리 확장
│ ├── mod.rs
│ └── post_search.rs
├── handlers/ # HTTP 핸들러
│ ├── mod.rs
│ ├── users.rs
│ └── posts.rs
├── services/ # 비즈니스 로직
│ ├── mod.rs
│ └── auth.rs
└── main.rs

생성된 타입 재내보내기

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

관련 엔티티 그룹화

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

흔한 실수

1. 민감한 필드에 #[field(skip)] 잊음

// 잘못됨: password_hash가 Response에 포함됨!
pub struct User {
 pub password_hash: String,
}
// 올바름
#[field(skip)]
pub password_hash: String,

2. JOIN이 필요할 때 sql = "full" 사용

3. 옵셔널 업데이트 제대로 처리 안 함

// 생성된 UpdateUserRequest는 name에 대해 Option<String>을 가짐
// 업데이트 로직은 None(변경 없음) vs Some(변경)을 처리해야 함

4. 비즈니스 로직 중복

// 좋음: 서비스 레이어
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)
 }
}
// 나쁨: 핸들러에 로직 분산
pub async fn create_user(pool: State<PgPool>, request: Json<CreateUserRequest>) -> ... {
 // 검증 여기
 // 비즈니스 규칙 여기
 // 리포지토리 호출 여기
 // 전부 섞여있음
}

체크리스트