Rules Hub
Coding Rules Library
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
Define API boundaries with dedicated DTOs
Do not expose internal domain models directly through APIs; map to explicit DTOs at the boundary to keep contracts stable and enforce validation.
Bad example
| 1 | // Domain model is leaked directly |
| 2 | export type UserEntity = { id: string; email: string; role: string; internalNotes: string }; |
| 3 |
|
| 4 | export async function getUser(req: Request) { |
| 5 | const user = await db.user.findById(req.params.id); |
| 6 | return Response.json(user); // leaks internalNotes and schema changes |
| 7 | } |
Explanation (EN)
The API returns the raw domain entity, so internal fields and schema changes leak to consumers. This couples clients to the database shape and makes safe refactors harder.
Objašnjenje (HR)
API vraća sirovi domain entitet pa interni fieldovi i promjene sheme cure prema klijentima. To veže klijente na bazu i otežava sigurne refaktore.
Good example
| 1 | // DTO separates the external contract from the domain model |
| 2 | export type UserDto = { id: string; email: string }; |
| 3 |
|
| 4 | function toUserDto(user: UserEntity): UserDto { |
| 5 | return { id: user.id, email: user.email }; |
| 6 | } |
| 7 |
|
| 8 | export async function getUser(req: Request) { |
| 9 | const user = await db.user.findById(req.params.id); |
| 10 | const dto = toUserDto(user); |
| 11 | return Response.json(dto); |
| 12 | } |
Explanation (EN)
A DTO makes the external contract explicit and stable. Mapping at the boundary keeps internal changes from breaking clients and is the right place to enforce validation or defaults.
Objašnjenje (HR)
DTO eksplicitno definira vanjski ugovor. Mapiranje na granici sprječava da interne promjene razbiju klijente i pravo je mjesto za validaciju ili default vrijednosti.
Notes (EN)
Apply this to both HTTP APIs and internal service boundaries (RPC, queues).
Bilješke (HR)
Primijeni ovo i na HTTP API-je i na interne granice (RPC, queue).
Exceptions / Tradeoffs (EN)
For quick prototypes you may skip DTOs, but document the risk and plan to add them before production.
Iznimke / Tradeoffi (HR)
Za brze prototipe možeš preskočiti DTO, ali dokumentiraj rizik i dodaj ga prije produkcije.