Rafał Tyński
b2fd7f8940
State that commit messages must be written in English in the DevHeyah and TarninaHub repositories and follow Conventional Commits.
89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
# AGENTS.md — Standardy warstwy Controller
|
|
|
|
Dotyczy projektu `backend` (ASP.NET Core Web API, .NET 10).
|
|
|
|
## Komunikaty commitów
|
|
|
|
- Komunikaty commitów zapisujemy **wyłącznie w języku angielskim**.
|
|
- Zasada obowiązuje **w obu projektach**: repozytorium `DevHeyah` oraz `20_projects/TarninaHub`.
|
|
- Stosujemy konwencję Conventional Commits (typ: `feat`, `fix`, `docs`, `chore` itd.).
|
|
|
|
## Język nazewnictwa
|
|
|
|
- Wszystkie nazwy zmiennych, parametrów, pól, metod, klas i plików są **wyłącznie w języku angielskim**.
|
|
- Zakaz używania polskich nazw w kodzie (np. `uzytkownik`, `zamowienie`), w tym w parametrach tras i modelach.
|
|
- Komentarze i dokumentacja opisowa mogą być w języku polskim, ale identyfikatory w kodzie — tylko po angielsku.
|
|
|
|
## Organizacja kontrolerów
|
|
|
|
- Każdy kontroler w osobnym pliku w katalogu `Controllers/`, nazwa pliku zgodna z nazwą klasy.
|
|
- Nazwa klasy: `<Resource>Controller` (np. `CustomersController`), dziedziczy po `ControllerBase`.
|
|
- Stosuj atrybut `[ApiController]` oraz jawne trasy `[Route("api/<resource>")]` (np. `[Route("api/health")]`) — nie używaj tokenu `[controller]`.
|
|
- Katalog `Controllers/` grupuje wyłącznie kontrolery — logika biznesowa trafia do serwisów.
|
|
|
|
## Konwencje akcji
|
|
|
|
- Metody akcji w czasie teraźniejszym, opisujące operację: `GetById`, `GetAll`, `Create`, `Update`, `Delete`.
|
|
- Używaj atrybutów HTTP: `[HttpGet]`, `[HttpGet("{id}")]`, `[HttpPost]`, `[HttpPut("{id}")]`, `[HttpDelete("{id}")]`.
|
|
- Parametry tras w `{camelCase}` (np. `{customerId}`), zgodnie z nazwami w kodzie.
|
|
- Zwracaj typy wyników `ActionResult<T>` lub `IActionResult` z jawnymi kodami statusu:
|
|
- `200 OK` — pobranie/zaktualizowanie,
|
|
- `201 Created` — utworzenie (`CreatedAtAction`),
|
|
- `204 NoContent` — usunięcie,
|
|
- `400 BadRequest`, `404 NotFound` — błędy.
|
|
- Kontroler nie zawiera logiki biznesowej ani dostępu do bazy — deleguje do serwisów/repozytoriów.
|
|
- Używaj wstrzykiwania zależności przez konstruktor (tylko `readonly` pola).
|
|
|
|
## Modele i DTO
|
|
|
|
- Wejście i wyjście kontrolera stanowią dedykowane DTO, nie modele encji.
|
|
- Nazwy DTO: `<Resource>Request`, `<Resource>Response`.
|
|
- Walidacja wejścia przez adnotacje (`[Required]`, `[StringLength]`, `[Range]`).
|
|
- Nie zwracaj encji bazy bezpośrednio z akcji.
|
|
|
|
## Asynchroniczność
|
|
|
|
- Wszystkie operacje I/O (baza, HTTP) jako `async` z sufiksem `Async` i zwrotem `Task<...>`.
|
|
- Akceptuj `CancellationToken cancellationToken` i przekazuj go dalej.
|
|
|
|
## Przykład
|
|
|
|
```csharp
|
|
[ApiController]
|
|
[Route("api/customers")]
|
|
public class CustomersController : ControllerBase
|
|
{
|
|
private readonly ICustomerService _customerService;
|
|
|
|
public CustomersController(ICustomerService customerService)
|
|
{
|
|
_customerService = customerService;
|
|
}
|
|
|
|
[HttpGet("{customerId:int}")]
|
|
public async Task<ActionResult<CustomerResponse>> GetById(
|
|
int customerId,
|
|
CancellationToken cancellationToken)
|
|
{
|
|
var customer = await _customerService.GetByIdAsync(customerId, cancellationToken);
|
|
|
|
return customer is null
|
|
? NotFound()
|
|
: Ok(customer);
|
|
}
|
|
|
|
[HttpPost]
|
|
public async Task<ActionResult<CustomerResponse>> Create(
|
|
CreateCustomerRequest request,
|
|
CancellationToken cancellationToken)
|
|
{
|
|
var createdCustomer = await _customerService.CreateAsync(request, cancellationToken);
|
|
|
|
return CreatedAtAction(
|
|
nameof(GetById),
|
|
new { customerId = createdCustomer.Id },
|
|
createdCustomer);
|
|
}
|
|
}
|
|
```
|