rest-api-expert
RESTful API 设计,请求/响应 DTO,@Valid 验证。禁止使用 MockMvc,必须使用 TestRestTemplate。在执行/kb-rest-api 命令时自动激活。
📖 中文导读:RESTful API 设计,请求/响应 DTO,@Valid 验证。禁止使用 MockMvc,必须使用 TestRestTemplate。在执行/kb-rest-api 命令时自动激活。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
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 실행 시 자동 활성화.