Returning Entity from Service method is a bad practice?

Question

I've heard when you want to return some object from a service method, you have to define a DTO object (or POJO object generated with JSON Schema) instead of using an Entity.

To make it clear, here is the example:

We have an entity and a jpa repository for it:

@Data
@Entity
@Table(name = "tables")
public class Table {
    @Id
    private Long id;
    private String brand;
}

This is a bad practice:

@Service
public class MyService {
    @Autowired
    private TableRepository tableRepository;

    @Transactional
    public Table create() {
        Table table = new Table();
        // Some logic for creating and saving table
        return table;
    }
}

This is a good practice:

@Service
public class MyService {
    @Autowired
    private TableRepository tableRepository;

    @Transactional
    public TableDTO create() {
        Table table = new Table();
        // Some logic for creating and saving table
        // Logic for converting Table object to TableDTO object
        return tableDTO;
    }
}

Why is this so?

Thank you!

Answer 1

Probably you mean a DTO (Data Transfer Object), not DAO (Data Access Object). Let me clarify this:

Data Transfer Object:

A Pojo that represents a piece of information. Usually it has aggregated data in it.

Data Access Object:

An object that performs access to some kind of persistence storage for retrieving information, someone considers it a synonym of Repository, someone not.

Entity:

An object that represents data that has been retrieved from the database.

Why is returning an Entity from the Service considered a bad practice?

The reason is that the Entity is something that is very close to the database. It contains primary key, someone could guess your database structure from it and the set of the data in case of query can be verbose. Hence, it is preferable to have some kind of logic, usually a mapper, that hides primary key and aggregates data to be less verbose and to not expose the db structure. Also, while the Entity is built on the table structure, the DTO can be customized in base of caller needs. Usually it contains exactly the data that is needed for some action and nothing more than this. Suppose you have third party software that calls your backend services: you should not expose the db structure (Entities) to this service. It is better to define a contract, with the minimal information needed for this third party service to operate, and expose only this part of the information, hiding all the rest.

Hope that's a little bit more clear now.

Edit: Of course there are other good reasons for using DTOs instead of Entities, this is only an introductory explanation to the subject.