rest-api-expert
RESTful API 설계, Request/Response DTO, @Valid 검증. MockMvc 금지, TestRestTemplate 필수. /kb-rest-api 명령 시 자동 활성화.
When & Why to Use This Skill
The REST API Expert skill is a specialized assistant for designing and implementing robust, production-ready RESTful API layers. It enforces strict architectural standards such as DTO separation, mandatory @Valid validation, and integration testing using TestRestTemplate. By prohibiting business logic in controllers and direct domain entity exposure, it ensures a clean separation of concerns and highly maintainable Spring-based web services.
Use Cases
- Standardizing API Architecture: Automatically structure controllers to use ResponseEntity, proper HTTP status codes, and dedicated Request/Response DTOs instead of domain entities.
- Enforcing Data Validation: Implementing comprehensive input validation using @Valid and Bean Validation to ensure data integrity at the entry point.
- Advanced Integration Testing: Generating test suites using TestRestTemplate to perform realistic integration tests that validate the full HTTP stack, moving away from MockMvc.
- Refactoring Legacy Controllers: Decoupling business logic from the web layer by delegating tasks to UseCases and implementing Mapper patterns for DTO conversions.
- Global Error Handling: Setting up centralized exception handling and standardized ErrorCode Enums to provide consistent API error responses.
| name | rest-api-expert |
|---|---|
| description | RESTful API 설계, Request/Response DTO, @Valid 검증. MockMvc 금지, TestRestTemplate 필수. /kb-rest-api 명령 시 자동 활성화. |
| triggers | [/kb-rest-api, /go, /red, /green, /refactor, /tidy, controller, api, endpoint, dto, mapper] |
REST API Layer 전문가
핵심 원칙 (Zero-Tolerance)
✅ Mandatory
- TestRestTemplate 필수 - 통합 테스트
- Request/Response DTO 분리 - API 전용 DTO
- @Valid 필수 - Request DTO 검증
- GlobalExceptionHandler 필수 - 통합 에러 처리
- @RestController - REST API 명시
- ResponseEntity 반환 - HTTP 상태 코드 명시
- Mapper 분리 - API DTO ↔ UseCase Command/Response
❌ Prohibited
- Domain/Entity 직접 반환 금지 - DTO 변환 필수
- Business 로직 금지 - UseCase 위임
- Transaction 금지 - Controller는 트랜잭션 경계 밖
- MockMvc 금지 - TestRestTemplate 사용
- @RequestParam 남용 금지 - Request DTO 사용
- Raw String 금지 - ErrorCode Enum 사용
- Validation 로직 금지 - @Valid + Bean Validation
예시
✅ CORRECT: Controller 패턴
@RestController
@RequestMapping("/api/orders")
public class OrderController {
private final PlaceOrderUseCase placeOrderUseCase;
@PostMapping
public ResponseEntity<OrderApiResponse> create(
@Valid @RequestBody PlaceOrderApiRequest request
) {
PlaceOrderCommand command = OrderApiMapper.toCommand(request);
OrderResponse response = placeOrderUseCase.execute(command);
OrderApiResponse apiResponse = OrderApiMapper.toApiResponse(response);
return ResponseEntity.created(URI.create("/api/orders/" + apiResponse.orderId()))
.body(apiResponse);
}
}
참조
- 전체 가이드: REST API Guide
- 상세 규칙 + 템플릿: REFERENCE.md
자동 활성화
/kb-rest-api /go|red|green|refactor|tidy 실행 시 자동 활성화.