java-developer

Files (2)

• SKILL.md
• package.json

SKILL.md (first lines)

# Java Developer

## Architecture

```text
service-name/

├── application/

│   ├── domain/model/        ← @Builder @Getter @Setter, zero JPA

│   ├── domain/service/      ← @Service implements *InPort

│   ├── port/in/             ← Driving ports (XxxInPort)

│   ├── port/out/            ← Driven ports (XxxRepositoryPort, XxxEventOutPort)

│   └── exception/           ← Domain exceptions

└── infrastructure/

    ├── adapter/web/         ← @RestController + WebAdapter + *DtoMapper

    ├── adapter/persistence/ ← @Entity + RepositoryAdapter + JpaRepository + *Mapper

    ├── adapter/event/       ← Implements XxxEventOutPort

    └── handler/event/       ← @Async @TransactionalEventListener(AFTER_COMMIT)

```
## Data Shapes

| Shape | Type | Package |
|-------|------|---------|
| API DTO | `record` | `infrastructure/adapter/web/dto/` |
| Domain Model | `class` with `@Builder` | `application/domain/model/` |
| Entity | `class` with JPA | `infrastructure/adapter/persistence/entity/` |

## Rules

- NO `@ManyToOne`, `@OneToMany`, `@OneToOne`, `@ManyToMany`, `@JoinColumn`

- FK columns as primitives: `private UUID receiptId;`

- UUID `@Id`: `@GeneratedValue(strategy = GenerationType.UUID)`

- Long `@Id`: `@GeneratedValue(strategy = GenerationType.IDENTITY)`

- Ports return **nullable**, never `Optional<T>`

- Unwrap Spring Data `Optional` at adapter boundary

## Null Handling

```java
Objects.isNull(x)

Objects.nonNull(x)

StringUtils.isBlank(x)

ObjectUtils.defaultIfNull(x, fallback)

ObjectUtils.getOrNull(x, X::getY)

ObjectUtils.getOrDefault(x, X::getY, fallback)

ValidationUtils.requireNonNull(x, "name")

NumberUtils.toDouble(x)

JsonUtils.extractItems(json)

HashUtils.sha256(bytes)

```
## Exception Handling

- Custom exceptions in `application/exception/`: extend `RuntimeException`

- Messages from `ErrorMessageConstants`

- `@RestControllerAdvice` with `GlobalExceptionHandler`

- Use `ErrorCodes` for error codes

**Project exceptions:**

- `NotFoundException` → 404 (static factories: `price(id)`, `product(id)`, `receipt(id)`, `store(id)`)

- `IllegalArgumentException` → 400 (invalid inputs)

- `RateLimitExceededException` → 429

- `DuplicateReceiptException` → 409

- `Exception` → 500 (catch-all)

## Mapper Pattern

Every conversion in dedicated `*Mapper` / `*DtoMapper`. Never in adapters.

Naming: `*DtoMapper` (domain → API DTO), `*Mapper` (domain ↔ entity). Methods named `toXxx`.

**Project example:**

```java
@Component

@RequiredArgsConstructor

public class ProductDtoMapper implements DtoMapperSupport {

    public Product toApiProduct(ProductDomain domain, ProductPriceSummary summary) {

        return mapIfNotNull(domain, d -> {

            var result = new Product();

From RizkiRachman/workflow-state-engine, MIT.

More from RizkiRachman/workflow-state-engine