---
name: spring-kotlin-engineer
description: Invoke this skill when building or modifying Spring Boot services in Kotlin — REST endpoints, services, repositories, coroutines, configuration.
---

# Spring Kotlin Engineer Skill

## Workflow

1. **Analyze** – Read existing code; understand the domain before touching anything
2. **Design** – Confirm approach for non-trivial changes before implementing
3. **Implement** – Write idiomatic Kotlin with Spring conventions
4. **Test** – Run `./gradlew test`; all tests must pass
5. **Verify** – Check `/actuator/health` returns `UP`

## Mandatory Patterns

### Constructor injection (no field injection)
```kotlin
@Service
class OrderService(
    private val orderRepository: OrderRepository,
    private val paymentClient: PaymentClient
)
```

### DTO validation with Kotlin field annotations
```kotlin
data class CreateOrderRequest(
    @field:NotNull val customerId: Long,
    @field:NotEmpty val items: List<OrderItemRequest>,
    @field:Positive val totalAmount: BigDecimal
)
```

### Coroutine-based service
```kotlin
@Service
class OrderService(private val repo: OrderRepository) {
    @Transactional
    suspend fun placeOrder(request: CreateOrderRequest): OrderResponse {
        val order = Order.from(request)
        return repo.save(order).toResponse()
    }

    @Transactional(readOnly = true)
    suspend fun findById(id: Long): OrderResponse =
        repo.findById(id)?.toResponse()
            ?: throw EntityNotFoundException("Order $id not found")
}
```

### Extension function for mapping
```kotlin
fun Order.toResponse() = OrderResponse(
    id = id,
    customerId = customerId,
    status = status.name,
    totalAmount = totalAmount
)
```

## Anti-Patterns to Avoid

| Avoid | Use Instead |
|-------|-------------|
| `@Autowired lateinit var repo` | Constructor injection |
| `!!` on nullable | `?: throw` or safe call |
| Blocking calls in suspend fun | `withContext(Dispatchers.IO)` |
| Java-style getters/setters | Kotlin properties |
| Mutable data classes as JPA entities | Separate entity and DTO classes |