toongri/implementation

Implementation Guide

Overview

This project follows responsibility assignment, object collaboration, and expression consistency.

Quick Decision

digraph layer {
    "Single domain?" [shape=diamond];
    "Service" [shape=box];
    "Multiple domains?" [shape=diamond];
    "Facade" [shape=box];
    "HTTP?" [shape=diamond];
    "Controller" [shape=box];

    "Single domain?" -> "Service" [label="yes"];
    "Single domain?" -> "Multiple domains?" [label="no"];
    "Multiple domains?" -> "Facade" [label="yes"];
    "Multiple domains?" -> "HTTP?" [label="no"];
    "HTTP?" -> "Controller" [label="yes"];
}

Critical Rules (Non-negotiable)

1. Controller Flow

ALWAYS: Controller -> Facade -> Service (never Controller -> Service)

@RestController
public class ProductV1Controller implements ProductV1ApiSpec {

    private final ProductFacade productFacade;  // Facade, NOT Service

    public ProductV1Controller(ProductFacade productFacade) {
        this.productFacade = productFacade;
    }
}

See references/layer-boundaries.md for detailed patterns.

2. Layer Responsibilities

| Layer | @Transactional | Horizontal Dependencies | Why | |-------|---------------|------------------------|-----| | Facade | When atomicity needed | Multiple Services OK | Wraps multiple Services in single transaction | | Service | When atomicity needed | No other Services | Ensures atomicity within single domain |

readOnly usage: Master/Slave DB routing. Use readOnly=true for read-only queries to route to Slave DB.

Facade = COORDINATION ONLY - No business logic (if/when/switch). Delegate to Service/Entity.

See references/layer-boundaries.md for transaction boundaries and anti-patterns.

3. Error Handling

Required: CoreException + ErrorType (single exception type)

throw new CoreException(ErrorType.NOT_FOUND, "[id = " + id + "] 엔티티를 찾을 수 없습니다.");

See references/error-handling.md for ErrorType enum and patterns.

4. DTO Flow

Request.toCriteria() -> Criteria.toCommand() -> Command -> Entity -> Info.from() -> Response.from()

See references/dto-patterns.md for complete layer structure.

5. Domain Events

| Requirement | Pattern | |-------------|---------| | Naming | {Action}EventV{n} (version suffix required) | | Interface | Must implement DomainEvent | | Fields | occurredAt: Instant required | | Factory | public static from(entity) | | Children | Use snapshots, not entity references |

public record OrderCreatedEventV1(
    Long orderId,
    List<OrderItemSnapshot> items,  // Snapshot, not entity
    Instant occurredAt
) implements DomainEvent {
    public static OrderCreatedEventV1 from(Order order) {
        return new OrderCreatedEventV1(order.getId(), order.getItemSnapshots(), Instant.now());
    }
}

6. EventListener Pattern

| Type | Phase | Error Handling | |------|-------|---------------| | Sync | BEFORE_COMMIT | Failure rolls back tx | | Async | AFTER_COMMIT | try-catch required, log errors |

Always: @TransactionalEventListener(phase = TransactionPhase.XXX) - never plain @EventListener

Logging format: logger.info("[Event] {Action} start/complete - eventType: " + event.getClass().getSimpleName() + ", id: " + id)

7. Entity Encapsulation

Seven Rules:

1. BaseEntity: ALL entities extend BaseEntity (provides id, createdAt, updatedAt, deletedAt)
2. @Table indexes: ALWAYS define indexes for query optimization
3. private fields + @Getter: ALL mutable fields private, no @Setter
4. Behavior methods: State changes via domain verbs (use(), pay()), not setters
5. Immutable VOs: final fields, operations return new instances
6. Constructor/Factory validation: Validate in constructor or factory, never create invalid objects
7. registerEvent(): Publish events for business-significant state changes

8. Naming Conventions

| Component | Pattern | Example | |-----------|---------|---------| | Controller | {Domain}V{n}Controller | ProductV1Controller | | ApiSpec | {Domain}V{n}ApiSpec | ProductV1ApiSpec | | Facade | {Domain}Facade | ProductFacade | | Service | {Domain}Service | ProductService | | Event | {Action}EventV{n} | OrderCreatedEventV1 | | Query | {Domain}PageQuery | ProductPageQuery |

Methods: Domain verbs (use, expire, cancel), not technical (process, handle, execute)

Variables: Full names (totalAmount, quantity), not abbreviations (amt, qty)

Booleans: is{Adjective}, has{Noun}, canBe{Verb}

9. Domain Purity

Direction: interfaces -> application -> domain <- infrastructure

Domain imports NOTHING from other layers.

| Allowed in Domain | Forbidden in Domain | |------------------|---------------------| | JPA: @Entity, @Table, @Column | @Transactional | | @Component on Service | @JsonProperty, @JsonIgnore | | | Spring Data imports |

Repository Abstraction: Interface in domain, implementation in infrastructure.

10. Null Safety

| Rule | Pattern | |------|---------| | Required fields | Non-nullable (never assign null) | | Not found | if (x == null) throw new CoreException(ErrorType.NOT_FOUND, "[id = " + id + "] ...") | | Optional | if (x != null) { ... }, Stream.of(a, b, c).filter(Objects::nonNull).toList() | | Forbidden | Unchecked null dereference |

11. API Patterns

• ApiSpec interface: Swagger annotations go here, Controller implements it
• Query/PageQuery: Encapsulate pagination with compact constructor validation

public record ProductPageQuery(int page, int size) {
    public ProductPageQuery {
        if (page < 0) throw new CoreException(ErrorType.BAD_REQUEST, "[page = " + page + "] 페이지는 0 이상이어야 합니다.");
        if (size < 1 || size > 100) throw new CoreException(ErrorType.BAD_REQUEST, "[size = " + size + "] 페이지 크기는 1~100이어야 합니다.");
    }
}

record vs class selection:

• Default: record + compact constructor — for 2–3 required parameters
• Allowed: class + @Getter + private constructor + static factory — when 4+ parameters AND optional parameters exist
• Validation must always occur in the constructor or static factory, regardless of choice

12. Messages

• Error messages: Korean, [field = value] prefix AT START
• Javadoc: Korean

// Correct
"[userId = " + userId + "] 사용자를 찾을 수 없습니다."

// Wrong (prefix at end)
"사용자를 찾을 수 없습니다. [userId = " + userId + "]"

13. Caching

| Rule | Pattern | |------|---------| | Layer | Application Layer(Facade) ONLY | | Pattern | Manual Cache-Aside with CacheTemplate | | Cache Key | Sealed interface + TTL embedded | | Cache Model | CachedXxxV1 versioned DTO (never Entity/Response) | | List Caching | IDs only + separate Detail cache | | Invalidation | Domain Event + @TransactionalEventListener(AFTER_COMMIT) |

See references/caching-patterns.md for detailed patterns, examples, and forbidden patterns.

Red Flags (Top 25)

| Thought | Reality | |---------|---------| | "Controller calling Service directly" | Controller -> Facade -> Service is MANDATORY | | "Facade is unnecessary for simple cases" | Facade is ALWAYS required | | "Service calling Service" | Coordinate in Facade | | "Facade->Facade dependency" | Use domain events | | "@Transactional on Service" | Only readOnly or managed in Facade | | "require() is fine" | Use CoreException: if (!cond) throw new CoreException(...) | | "Domain exception per domain" | Single CoreException + ErrorType | | "Return Entity directly" | DTO layer required | | "English error message" | Korean with [field = value] prefix | | "Entity without BaseEntity" | ALL entities MUST extend BaseEntity | | "public field or @Setter" | ALL mutable fields need private + @Getter, no @Setter | | "@Table without indexes" | ALWAYS define indexes | | "Event without V1 suffix" | Version suffix required | | "Just @EventListener" | Use @TransactionalEventListener with phase | | "Async listener without try-catch" | Async failures must be caught and logged | | "Inject JpaRepository directly" | Define interface in domain | | "@JsonProperty in domain" | JSON is infrastructure concern | | "Nullable for required fields" | Non-nullable by default | | "Unchecked null dereference" | Use explicit null check + CoreException | | "process/handle method names" | Use domain verbs | | "Short variable names (amt, qty)" | Full descriptive names required | | "Business logic in Facade" | Facade coordinates only, logic in Service/Entity | | "External call inside @Transactional" | Use AFTER_COMMIT event listener | | "Entity is just data holder" | Anemic domain model anti-pattern - entities MUST have behavior | | "Skip validation in constructor/factory" | Invalid objects are forbidden | | "@Cacheable is simpler" | Use CacheTemplate for control | | "Cache in Service/Repository" | Caching belongs in Facade ONLY | | "Cache Response directly" | Use CachedXxxV1 dedicated DTO | | "String cache key" | Use sealed interface with TTL | | "@CacheEvict allEntries" | Domain Event + selective evict |

References

Load these files ONLY when working on specific areas:

| File | When to Load | |------|-------------| | references/layer-boundaries.md | Code placement, Service vs Facade, transactions | | references/error-handling.md | Exception creation, validation failures, ErrorType enum | | references/dto-patterns.md | API endpoints, Request/Response/Criteria/Command/Info classes | | references/domain-events.md | Event publishing, EventListener patterns, cross-domain communication | | references/entity-patterns.md | Entity design, encapsulation rules, null safety, domain purity | | references/naming-conventions.md | Method/variable/message naming, Korean messages | | references/api-patterns.md | ApiSpec interface, Query/PageQuery patterns | | references/caching-patterns.md | Cache-Aside in Facade, CacheKey sealed interface, CachedXxxV1 DTOs, invalidation |