60 lines
3.3 KiB
Markdown
60 lines
3.3 KiB
Markdown
# DTOs and models
|
|
|
|
Processed complex data in application should be represented with structures of two types:
|
|
|
|
- **DTO (Data Transfer Object)** - for inter-domain data exchange.
|
|
- **Models** - for intra-domain data exchange.
|
|
|
|
Also, models are distinguished by package type:
|
|
|
|
- Domain models - used within domain service and responsible also for converting structures into each other. Have no tags on fields.
|
|
- Storage models - used within storages of all kinds. Have `db` (or similar, depending on used database driver or library) tag on its fields.
|
|
- Client models. Used in integrations with external APIs and may have `json`, `xml` or other tags on its fields.
|
|
- Any other models that might be needed.
|
|
|
|
It is allowed to use embedding and nested structures if needed.
|
|
|
|
## DTOs
|
|
|
|
DTO (Data Transfer Object) is a structure that is responsible for data exchange in inter-domain APIs. This structure should not have any functions except those that are needed to operate on its data itself, e.g. comparators.
|
|
|
|
DTOs are placed in `dto` directory within domain, for example, `internal/domains/core/config/dto` for configuration subsystem DTOs.
|
|
|
|
Also initializer should be placed near it and used when creating new instance for proper structure initialization (especially if embedding is used) as well as to avoid exhaustive-like (exhaustive, exhaustive_v5 and others) linters to whine.
|
|
|
|
## Models
|
|
|
|
Model is a structure that is responsible for intra-domain data exchange and processing. Before operating on any complex data, it should be converted to model.
|
|
|
|
Models placement depends on model type:
|
|
|
|
- Domain models are placed in `models` directory within domain's root, e.g. `internal/domains/core/config/models` for configuration domain's models.
|
|
- Storage models are placed in `models` directory within storage's root, e.g. `internal/domains/core/config/storage/postgresql/models` for PostgreSQL's data models.
|
|
|
|
And so on.
|
|
|
|
All models should contain only data they need, with notable exception of domain models, see below. For example, domain model can have 15 different fields, while storage model can have only 6 fields that represent single database row.
|
|
|
|
### Domain models
|
|
|
|
Domain models are a special kind of models as they contain not only initializers but also converters to different types of structures:
|
|
|
|
- Converter to DTO.
|
|
- Converter to storage models.
|
|
- Converter to client schema.
|
|
- ...and so on.
|
|
- ...and also converters from other models or schemas into domain model (like `NewFromPostgreSQLStorage`).
|
|
|
|
Also, unlike other types of models, domain model should have maximum possible number of fields so it can be converted to other types of models.
|
|
|
|
These models should not go outside of domain's service, when needed they should be converted to DTOs or other types of models:
|
|
|
|
- When working with database, domain models should be converted to storage models.
|
|
- When replying to client, domain models should be converted to API schema models.
|
|
|
|
Point of conversion differs:
|
|
|
|
- When domain service itself calls storage function, domain service should convert data to storage's model and storage function accepts only own models.
|
|
- When returning data to caller within domain, no conversion should be done, converting domain model into appropriate other model is a responsibility of caller.
|
|
- When returning data in function that is used in inter-domain API, it should convert domain models into DTOs.
|