Controller ve route’lar

HTTP method’larını, path parametrelerini ve route eşleştirme davranışını tanımlayın.

Controller, birbiriyle ilgili endpoint’leri aynı base path altında toplar. Lily controller’ları link sırasında bulur ve uygulama kurulurken oluşturur.

Controller sözleşmesi#

#[derive(Controller)], tek #[base_path], ControllerTrait::new ve #[controller] impl birlikte kullanılır. Action’lar async olmalı ve &self almalıdır. Yardımcı method’ları ayrı normal impl bloğuna yerleştirin.

Parametreli route ve oluşturma#

use std::sync::Arc;
use lilyrs::http_api::{
    controller, Controller, ControllerInitError, ControllerTrait, Created,
    Extensions, HttpApiError, Json, Path, Query,
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct UserPath { id: u64 }
#[derive(Deserialize)]
struct UserQuery { language: Option<String> }
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct CreateUser { name: String }
#[derive(Serialize)]
struct UserView { id: u64, name: String }

#[derive(Controller)]
#[base_path("/users")]
struct UsersController;

#[lilyrs::http_api::async_trait::async_trait]
impl ControllerTrait for UsersController {
    async fn new(_: Arc<Extensions>) -> Result<Self, ControllerInitError> { Ok(Self) }
}

#[controller]
impl UsersController {
    #[get("/:id")]
    async fn read(&self, Path(path): Path<UserPath>, Query(query): Query<UserQuery>)
        -> Result<UserView, HttpApiError>
    {
        Ok(UserView { id: path.id, name: query.language.unwrap_or_else(|| "tr".into()) })
    }

    #[post("/")]
    async fn create(&self, Json(input): Json<CreateUser>)
        -> Result<Created<UserView>, HttpApiError>
    {
        if input.name.trim().is_empty() {
            return Err(HttpApiError::ValidationError("name is required".into()));
        }
        // Öğretim örneği: gerçek uygulamada bu sonucu domain service üretir.
        Ok(Created::new("/users/42", UserView { id: 42, name: input.name }))
    }
}

GET /users/42?language=tr parametreleri typed DTO’lara ayırır. POST /users başarılıysa 201 ve Location: /users/42 döner. Örnek kalıcı kayıt yapmaz; HTTP sözleşmesini gösterir. Gerçek kayıt işlemini DI ile aldığınız domain servisine taşıyın.

Controller’ın base path’i /users, action yolu / ise birleşen route /users olur; sonuna otomatik slash eklenmez. İstek adresini bu kayıtlı yola göre seçin.

Route sözdizimi#

Yol	Eşleşme
`/users/me`	Sabit yol
`/users/:id`	Tek segment parametresi
`/files/*path`	Sondaki kalan yol

Catch-all son segmentte bulunmalıdır. Sabit route parametreli route’tan önceliklidir. Aynı method/path veya aynı öncelikte belirsiz parametre yolları build hatasıdır.

get, post, put, patch, delete, head ve options hazır attribute’lardır. Özel method için #[route(method = "CUSTOM", path = "/...")] kullanılır. OpenAPI etkinse standart dışı method’u #[openapi(skip)] ile dışarıda bırakın.

HEAD, 404 ve 405#

Açık HEAD route’u yoksa GET’e fallback yapılır; transport yanıt gövdesini göndermez. Yol bulunduğu halde method eşleşmiyorsa 405 ve Allow header’ı, yol bulunmuyorsa 404 üretilir.