2 releases
0.1.1 | Mar 20, 2019 |
---|---|
0.1.0 | Mar 19, 2019 |
#8 in #dto
30 downloads per month
27KB
576 lines
#[derive(Dto)]
This crate provides Dto
derive automating the process of mapping DTOs
(Data Transfer Objects) into Entities and vice versa.
It is capable of implementing From
or Into
traits
for DTO structures regarding conversion direction.
Every DTO structure can act as a request or a response, which means that particular DTO structure can be converted either from an Entity or into an Entity. Therefore, a DTO which should be convertible into an Entity is a request DTO and a DTO which should be built from an Entity is a response DTO.
In addition to a simple one-to-one conversion, the crate allows skipping particular fields or renaming them during conversion process. More advanced features, like for example, assigning an external values or field-level attributes are planned for next releases.
Installation and basic usage
Add the following dependency to Cargo.toml
:
[dependencies]
dto_derive = "0.1.0"
Then import Dto
derive by:
use dto_derive::Dto;
And use it like so:
struct Post {
...
}
#[derive(Dto)]
#[dto(entity = "Post")]
struct PostResponse {
...
}
That enables you to convert Post
into PostResponse
in this case:
let post: Post = ...;
let post_response: PostResponse = post.into();
For more examples and use cases check sections below.
Derive associated attributes
-
#[dto(entity = "Entity")]
Required attribute containing a type of a mapped entity. It has to be provided exactly once per DTO structure.
-
#[dto(request)]
,#[dto(response)]
Optional attributes specifying a conversion direction, can be omitted when DTO structure name ends with
...Request
or...Response
, e.g.,PostResponse
, otherwise have to be provided. -
#[dto(map = "a: b")]
Optional attribute telling how to rename field names during conversion. It may be repeated for different fields.
-
#[dto(skip = "a, b, c")]
Optional attribute containing field names which should be omitted during conversion. It may contain multiple fields to skip and/or it may by repeated for different fields. The attribute is only valid for request DTOs.
Examples
Let's start with our Post
entity implementation:
struct Post {
title: String,
body: String,
}
Request DTO
In order to create a new post we may have a DTO representation:
#[derive(Dto)]
#[dto(entity = "Post")]
#[dto(request)]
#[dto(map = "body: content")]
#[dto(skip = "csrf_token")]
struct NewPost {
title: String,
content: String,
csrf_token: String,
}
Above DTO may be converted to the Post
entity using into()
function from Into
trait:
let newPost = NewPost {
title: String::from("Awesome post"),
content: String::from("Awesome content of awesome post."),
csrf_token: String::from("abcde"),
};
let post: Post = newPost.into();
It is possible because NewPost
DTO is implementing Into
trait
due to Dto
derive.
Response DTO
Response DTO may look like:
#[derive(Dto)]
#[dto(entity = "Post")]
#[dto(map = "content: body")]
struct PostResponse {
title: String,
content: String,
}
The conversion from entity to PostResponse
DTO may be done using
into()
function from Into
trait:
let post = Post {
title: String::from("Awesome post"),
body: String::from("Awesome content of awesome post."),
};
let postResponse: PostResponse = post.into();
It is possible because PostResponse
DTO is implementing From
trait
due to Dto
derive.
Under the hood
Adding #[derive(Dto)]
attribute means providing automatic implementation
of From
or Into
trait for a given structure.
Thus, for the NewPost
DTO structure and the Post
entity
(from previous section), below implementation will be automatically provided
(notice the request nature of the NewPost
DTO):
impl Into<Post> for NewPost {
fn into(self) -> Post {
Post {
title: self.title,
body: self.content,
}
}
}
The opposite implementation will be derived for the PostResponse
DTO
which is in fact a response DTO:
impl From<Post> for PostResponse {
fn from(entity: Post) -> Self {
PostResponse {
title: entity.title,
content: entity.body,
}
}
}
It is worth noting that a derive implementation is always provided for DTO structures which allows to import entity structures from another crate without breaking the orphan rule.
License
Licensed under the MIT license (LICENSE or https://opensource.org/licenses/MIT).
Dependencies
~2MB
~46K SLoC