layered-architecture

Name: layered-architecture
Author: rrezartprebreza

174stars33forks

How to install layered-architecture?

rrezartprebreza/spring-boot-skills/layered-architecture

$npx -y skills add rrezartprebreza/spring-boot-skills --skill layered-architecture

Installs into the current project.

Summary

Use when generating or modifying any Spring Boot class — controllers, services, repositories, DTOs, mappers, or configuration. Enforces strict layer separation and prevents business logic from leaking across boundaries.

Files · 1

View on GitHub

SKILL.md

1	# Layered Architecture
2
3	## Layer Rules
4
5	```
6	@RestController ← HTTP only. No business logic. No JPA entities in responses.
7	↓ DTOs
8	@Service ← All business logic lives here. Orchestrates repositories.
9	↓ Domain objects / Entities
10	@Repository ← Data access only. No business logic. Returns entities or projections.
11	↓ JPA / JDBC
12	Database
13	```
14
15	## Controller Layer
16	- Handles HTTP: parsing requests, validating input (`@Valid`), returning responses
17	- Calls ONE service method per endpoint — no orchestration in controllers
18	- Never returns `@Entity` classes directly — always map to response DTOs
19	- Never injects `@Repository` — always goes through a `@Service`
20	- Exception handling via `@ControllerAdvice`, never try/catch in controllers
21
22	```java
23	// ✅ GOOD
24	@PostMapping("/orders")
25	public ResponseEntity<OrderResponse> createOrder(@Valid @RequestBody CreateOrderRequest request) {
26	Order order = orderService.createOrder(request);
27	return ResponseEntity.status(HttpStatus.CREATED).body(OrderResponse.from(order));
28	}
29
30	// ❌ BAD — business logic in controller
31	@PostMapping("/orders")
32	public ResponseEntity<Order> createOrder(@RequestBody CreateOrderRequest request) {
33	if (request.getItems().isEmpty()) throw new RuntimeException("No items");
34	Order order = orderRepository.save(new Order(request)); // direct repo access
35	return ResponseEntity.ok(order); // returning entity
36	}
37	```
38
39	## Service Layer
40	- Contains all business logic, validation rules, and orchestration
41	- `@Transactional` lives here, not in controllers or repositories
42	- Constructor injection only — never `@Autowired` field injection
43	- One service per aggregate root (OrderService, not OrderAndPaymentService)
44	- Returns domain objects or DTOs — never `HttpServletRequest` / `HttpServletResponse`
45
46	```java
47	// ✅ GOOD
48	@Service
49	@RequiredArgsConstructor
50	public class OrderService {
51	private final OrderRepository orderRepository;
52	private final InventoryService inventoryService;
53
54	@Transactional
55	public Order createOrder(CreateOrderRequest request) {
56	inventoryService.reserve(request.getItems());
57	Order order = Order.from(request);
58	return orderRepository.save(order);
59	}
60	}
61
62	// ❌ BAD — field injection, HTTP concern in service
63	@Service
64	public class OrderService {
65	@Autowired private OrderRepository orderRepository;
66
67	public ResponseEntity<Order> createOrder(...) { ... } // HTTP type in service
68	}
69	```
70
71	## Repository Layer
72	- Extends `JpaRepository<Entity, ID>` or `CrudRepository`
73	- Custom queries via `@Query` or query derivation — no raw SQL unless unavoidable
74	- Returns entities or Spring Data Projections — never raw `Object[]`
75	- No business logic — pure data access
76
77	## DTOs
78	- Separate Request / Response DTOs — never use the same class for both
79	- Validation annotations (`@NotNull`, `@Size`, etc.) on Request DTOs only
80	- Static factory method `ResponseDto.from(Entity entity)` for mapping
81	- Use records for immutable DTOs (Java 16+)
82
83	```java
84	// ✅ GOOD
85	public record OrderResponse(UUID id, String status, List<LineItemResponse> items) {
86	public static OrderResponse from(Order order) {
87	return new OrderResponse(order.getId(), order.getStatus().name(),
88	order.getItems().stream().map(LineItemResponse::from).toList());
89	}
90	}
91	```
92
93	## Mapper Pattern
94	- Keep mapping logic out of controllers and services — use dedicated mapper classes or static factory methods
95	- Mapper is a plain class or utility — not a Spring bean unless it needs injected dependencies
96	- Entity → Response DTO: static method on the response DTO (`OrderResponse.from(order)`)
97	- Request DTO → Entity: static factory on the entity (`Order.from(request)`) or a mapper class
98	- Collection mapping: use `.stream().map(OrderResponse::from).toList()` — never manual loops
99
100	```java
101	// ✅ GOOD — dedicated mapper for complex mappings
102	public class OrderMapper {
103
104	public static OrderResponse toResponse(Order order) {
105	return new OrderResponse(
106	order.getId(),
107	order.getStatus().name(),
108	order.getItems().stream().map(OrderMapper::toLineItem).toList(),
109	order.getCreatedAt()
110	);
111	}
112
113	public static Order toEntity(CreateOrderRequest request, User user) {
114	Order order = Order.create(request.customerEmail(), user);
115	request.items().forEach(item ->
116	order.addItem(item.productId(), item.quantity()));
117	return order;
118	}
119
120	private static LineItemResponse toLineItem(OrderItem item) {
121	return new LineItemResponse(item.getProductId(), item.getQuantity(), item.getPrice());
122	}
123	}
124	```
125
126	## Configuration Layer
127	- `@Configuration` classes live in a `config/` package — never in

People who liked this also viewed

6 picks

Type

layered-architecture

174stars33forks

View on GitHub

How to install layered-architecture?

rrezartprebreza/spring-boot-skills/layered-architecture

$npx -y skills add rrezartprebreza/spring-boot-skills --skill layered-architecture

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Layered Architecture
2
3	## Layer Rules
4
5	```
6	@RestController ← HTTP only. No business logic. No JPA entities in responses.
7	↓ DTOs
8	@Service ← All business logic lives here. Orchestrates repositories.
9	↓ Domain objects / Entities
10	@Repository ← Data access only. No business logic. Returns entities or projections.
11	↓ JPA / JDBC
12	Database
13	```
14
15	## Controller Layer
16	- Handles HTTP: parsing requests, validating input (`@Valid`), returning responses
17	- Calls ONE service method per endpoint — no orchestration in controllers
18	- Never returns `@Entity` classes directly — always map to response DTOs
19	- Never injects `@Repository` — always goes through a `@Service`
20	- Exception handling via `@ControllerAdvice`, never try/catch in controllers
21
22	```java
23	// ✅ GOOD
24	@PostMapping("/orders")
25	public ResponseEntity<OrderResponse> createOrder(@Valid @RequestBody CreateOrderRequest request) {
26	Order order = orderService.createOrder(request);
27	return ResponseEntity.status(HttpStatus.CREATED).body(OrderResponse.from(order));
28	}
29
30	// ❌ BAD — business logic in controller
31	@PostMapping("/orders")
32	public ResponseEntity<Order> createOrder(@RequestBody CreateOrderRequest request) {
33	if (request.getItems().isEmpty()) throw new RuntimeException("No items");
34	Order order = orderRepository.save(new Order(request)); // direct repo access
35	return ResponseEntity.ok(order); // returning entity
36	}
37	```
38
39	## Service Layer
40	- Contains all business logic, validation rules, and orchestration
41	- `@Transactional` lives here, not in controllers or repositories
42	- Constructor injection only — never `@Autowired` field injection
43	- One service per aggregate root (OrderService, not OrderAndPaymentService)
44	- Returns domain objects or DTOs — never `HttpServletRequest` / `HttpServletResponse`
45
46	```java
47	// ✅ GOOD
48	@Service
49	@RequiredArgsConstructor
50	public class OrderService {
51	private final OrderRepository orderRepository;
52	private final InventoryService inventoryService;
53
54	@Transactional
55	public Order createOrder(CreateOrderRequest request) {
56	inventoryService.reserve(request.getItems());
57	Order order = Order.from(request);
58	return orderRepository.save(order);
59	}
60	}
61
62	// ❌ BAD — field injection, HTTP concern in service
63	@Service
64	public class OrderService {
65	@Autowired private OrderRepository orderRepository;
66
67	public ResponseEntity<Order> createOrder(...) { ... } // HTTP type in service
68	}
69	```
70
71	## Repository Layer
72	- Extends `JpaRepository<Entity, ID>` or `CrudRepository`
73	- Custom queries via `@Query` or query derivation — no raw SQL unless unavoidable
74	- Returns entities or Spring Data Projections — never raw `Object[]`
75	- No business logic — pure data access
76
77	## DTOs
78	- Separate Request / Response DTOs — never use the same class for both
79	- Validation annotations (`@NotNull`, `@Size`, etc.) on Request DTOs only
80	- Static factory method `ResponseDto.from(Entity entity)` for mapping
81	- Use records for immutable DTOs (Java 16+)
82
83	```java
84	// ✅ GOOD
85	public record OrderResponse(UUID id, String status, List<LineItemResponse> items) {
86	public static OrderResponse from(Order order) {
87	return new OrderResponse(order.getId(), order.getStatus().name(),
88	order.getItems().stream().map(LineItemResponse::from).toList());
89	}
90	}
91	```
92
93	## Mapper Pattern
94	- Keep mapping logic out of controllers and services — use dedicated mapper classes or static factory methods
95	- Mapper is a plain class or utility — not a Spring bean unless it needs injected dependencies
96	- Entity → Response DTO: static method on the response DTO (`OrderResponse.from(order)`)
97	- Request DTO → Entity: static factory on the entity (`Order.from(request)`) or a mapper class
98	- Collection mapping: use `.stream().map(OrderResponse::from).toList()` — never manual loops
99
100	```java
101	// ✅ GOOD — dedicated mapper for complex mappings
102	public class OrderMapper {
103
104	public static OrderResponse toResponse(Order order) {
105	return new OrderResponse(
106	order.getId(),
107	order.getStatus().name(),
108	order.getItems().stream().map(OrderMapper::toLineItem).toList(),
109	order.getCreatedAt()
110	);
111	}
112
113	public static Order toEntity(CreateOrderRequest request, User user) {
114	Order order = Order.create(request.customerEmail(), user);
115	request.items().forEach(item ->
116	order.addItem(item.productId(), item.quantity()));
117	return order;
118	}
119
120	private static LineItemResponse toLineItem(OrderItem item) {
121	return new LineItemResponse(item.getProductId(), item.getQuantity(), item.getPrice());
122	}
123	}
124	```
125
126	## Configuration Layer
127	- `@Configuration` classes live in a `config/` package — never in

People who liked this also viewed

6 picks

Type