Controllers & Response Envelope

This chapter covers:

1. Designing thin async Axum controller handlers
2. Extracting inputs with Json, Query, Path, and Extension
3. Mastering the unified ApiResponse<T> envelope
4. Understanding automatic HTTP status code mapping with AppError

Foundry promotes the “Thin Controller” paradigm:

• Controller Responsibilities: Request parameter extraction, DTO validation, invoking domain services, and returning ApiResponse.
• Not in Controllers: Heavy business calculations, cross-model transactions, or raw database queries. Push these down into domain services (src/systems/<slug>/logic/).

Axum uses type-driven extractors declared directly in the handler signature:

use foundry::prelude::*;

pub async fn handle_sample_action(
    Extension(ctx): Extension<SystemContext>,
    Extension(state): Extension<AppState>,
    Path(id): Path<i64>,
    Query(query): Query<OrderQuery>,
    Json(payload): Json<CreateOrderRequest>,
) -> AppResult<ApiResponse<OrderResponse>> {
    // Business logic...
}

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "meta": null
}

use foundry::prelude::*;

// Success responses
ApiResponse::ok(data)
ApiResponse::created(new_order)
ApiResponse::paginated(items, page, page_size, total_count)

[!TIP] ApiResponse<T> implements Axum’s IntoResponse for all T: Serialize. You can return Ok(ApiResponse::ok(data)) directly without wrapping in Json(...).

pub type AppResult<T> = Result<T, AppError>;

Next chapter: Request Validation & DTOs