development-rule

Instruction file imported from JianwenShaw/mediask-be (.cursor/rules/development-rule.mdc). Copyright stays with the author.

alwaysApply: true description: Java development standards, code standards, DDD domain-driven design layered architecture, architecture design naming conventions, JDK21 features, high cohesion low coupling, ApplicationService, DomainService, Infrastructure layer, DAL layer, Request DTO VO DO, Utils, Helper, code style, best practices. IMPORTANT: You must be able to understand and respond to user queries in both English and Chinese. When users ask questions in Chinese, respond in clear, fluent Chinese.

Project Architecture

Layered Architecture (DDD)

This project adopts DDD (Domain-Driven Design) layered architecture with the following module division:

mediask-api          # API Layer - REST controllers, request/response, parameter validation
mediask-service      # Application Service Layer - business orchestration, use case implementation, Request/DTO conversion
mediask-domain       # Domain Layer - entities, value objects, domain services, repository interfaces (core business logic)
mediask-infra        # Infrastructure Layer - repository implementations, cache, distributed locks, file storage, AI clients
mediask-dal          # Data Access Layer - DO entities, Mapper interface definitions
mediask-common       # Common Layer - utility classes, constants, exceptions, unified responses

Dependency Rules (Strictly Follow)

API → Service → Domain
     ↓         ↓
   Common   Infra → Domain, DAL, Common
              ↓
            DAL → Common

Key Constraints:

• ✅ API layer can only depend on Service layer and Common layer
• ✅ Service layer can only depend on Domain layer, Infra layer and Common layer
• ✅ Domain layer can only depend on Common layer (core business logic, no infrastructure dependencies)
• ✅ Infra layer implements Domain layer repository interfaces, depends on Domain, DAL, Common
• ✅ DAL layer only contains DO and Mapper, depends on Common layer
• ❌ Cross-layer dependencies are prohibited (e.g., API directly depends on Domain or Infra)
• ❌ Circular dependencies are prohibited

Naming Conventions (Enforced)

Application Layer Naming

Common Object Type Descriptions

Important Notes

1. Request vs Command:

   • ✅ Use Request (more aligned with traditional DDD practices)
   • ❌ Do not use Command (unless explicitly adopting CQRS pattern)

2. DTO vs VO:

   • Service layer output uses DTO (Data Transfer Object)
   • API layer output uses Response or VO (View Object)
   • Note: VO is View Object, do not confuse with DDD's Value Object

3. DO vs PO:

   • This project uniformly uses DO (Data Object) as database table mapping objects
   • Do not use PO (Persistence Object) naming
   • DO is placed in DAL layer, uses MyBatis-Plus annotations

4. Utils vs Helper:

   • Utils: Utility classes providing static methods, usually stateless
   • Helper: Helper classes that may contain state or more complex logic
   • Both are placed in Common layer

5. Domain Service Naming:

   • Domain services use XxxDomainService suffix to distinguish from application services
   • Application services use XxxApplicationService suffix

Code Style

Reference Documentation

Please strictly refer to the code style documentation:

• /home/ethan/dev/mediask-be/MediAskDocs/docs/02-CODE_STANDARDS.md

Core Principles

1. Clear Naming: Variable, method, and class names must clearly express business meaning, abbreviations and pinyin are prohibited
2. Single Responsibility: Each class and method does one thing only
3. High Cohesion Low Coupling: Related functionality is aggregated, module dependencies are minimized
4. Elegant and Concise: Code should be readable and maintainable, avoid over-engineering

JDK 21 Features Usage Guide

Recommended Features

1. Record Classes: For immutable data transfer objects

   public record LoginResponseDTO(Long userId, String username, String token) {}

2. Pattern Matching: Switch expressions and pattern matching

   return switch (userType) {
       case ADMIN -> List.of("schedule:create", "schedule:update");
       case DOCTOR -> List.of("schedule:update");
       case PATIENT -> Collections.emptyList();
   };

3. Text Blocks: Multi-line strings

   String sql = """
       SELECT * FROM users
       WHERE id = ?
       """;

4. Sealed Classes: Restrict class inheritance (for value objects or enum extensions)

5. var Keyword: Local variable type inference (use moderately, maintain readability)

Virtual Threads Notes ⚠️

1. Database Connection Pool:

   • MySQL driver may have performance degradation in virtual thread environment
   • Use traditional thread pool for database operations, avoid virtual threads
   • Connection pool size needs to be adjusted based on actual situation

2. I/O Intensive Operations:

   • File operations and network requests can use virtual threads
   • But actual performance needs to be verified

3. Principle: Performance first, don't blindly use new features

DDD Development Guidelines

Domain Layer

1. Entity:

   • Contains business identity and business logic
   • Created through factory methods or constructors
   • Encapsulates business rules, does not expose internal state

2. Value Object:

   • Immutable, equality determined by value
   • Implemented using Record or final class

3. Domain Service:

   • Handles business logic across entities
   • Naming: XxxDomainService
   • Does not depend on infrastructure, only depends on domain objects and Common

4. Repository Interface:

   • Defined in Domain layer
   • Uses domain objects as parameters and return values
   • Implementation is placed in Infra layer

Application Layer

1. Application Service:

   • Coordinates domain services and repositories to complete use cases
   • Manages transaction boundaries
   • Handles Request/DTO conversion
   • Naming: XxxApplicationService

2. Request/DTO:

   • Request: Application layer input parameters (XxxRequest)
   • DTO: Application layer output objects (XxxDTO)
   • Placed in application/request and application/dto packages

Infrastructure Layer

1. Repository Implementation:

   • Implements Domain layer repository interfaces
   • Uses MyBatis-Plus or JPA
   • Conversion between DO and domain objects

2. Infrastructure Components:

   • Redis configuration, distributed locks
   • File storage, AI clients
   • JWT service, password encoder
   • All technical implementation details

Data Access Layer (DAL)

1. DO (Data Object):

   • Database table mapping object (equivalent to traditional PO)
   • Uses MyBatis-Plus annotations
   • Naming: XxxDO
   • Note: This project uniformly uses DO, does not use PO naming

2. Mapper:

   • MyBatis Mapper interface
   • Only contains data access methods
   • Does not contain business logic

Common Layer

1. Utility Classes (Utils):

   • Utility classes providing static methods
   • Usually stateless
   • Naming: XxxUtils
   • Examples: DateUtils, StringUtils, CollectionUtils

2. Helper Classes:

   • Helper classes that assist with certain operations
   • May contain state or more complex logic
   • Naming: XxxHelper
   • Examples: EncryptHelper, ValidationHelper, FileHelper

Spring Security Component Layering

1. API Layer:

   • SecurityConfig - Web security configuration
   • JwtAuthenticationFilter - JWT authentication filter
   • Exception handlers (JwtAuthenticationEntryPoint, JwtAccessDeniedHandler)

2. Infra Layer:

   • PasswordEncoderConfig - Password encoder configuration
   • JwtService - JWT service
   • JwtProperties - JWT configuration properties

3. Service Layer:

   • Uses PasswordEncoder through dependency injection (does not directly depend on Spring Security)

Code Quality Requirements

1. Exception Handling:

   • Use project's unified exception system (BizException)
   • Do not swallow exceptions, log them
   • Exception messages should be clear for troubleshooting

2. Logging Standards:

   • Use SLF4J + Logback
   • Record INFO logs for key business operations
   • Record ERROR logs for exceptions, include context information

3. Transaction Management:

   • Use @Transactional on application service methods
   • Explicitly specify rollbackFor = Exception.class
   • Avoid using transaction annotations directly in domain objects

4. Parameter Validation:

   • API layer uses @Valid or @Validated
   • Service layer uses AssertUtil for business validation
   • Validation failures throw clear business exceptions

5. Null Value Handling:

   • Use Optional to handle potentially null values
   • Avoid null passing, use null object pattern or explicit handling

Performance Optimization Principles

1. Database Queries:

   • Avoid N+1 query problems
   • Use indexes appropriately
   • Use batch methods for batch operations

2. Caching Strategy:

   • Use Redis cache for hot data
   • Pay attention to cache penetration, breakdown, and avalanche issues
   • Use distributed locks to ensure data consistency

3. Object Conversion:

   • Use MapStruct for object conversion (compile-time generation, high performance)
   • Avoid manual getter/setter conversion

Prohibited Practices

1. ❌ Prohibited to use Spring annotations in Domain layer (except @Service for domain services)
2. ❌ Prohibited to directly depend on DAL layer in Domain layer
3. ❌ Prohibited to directly use Mapper in Service layer (through Repository interface)
4. ❌ Prohibited to directly call Domain layer from API layer
5. ❌ Prohibited to use abbreviations and pinyin in naming
6. ❌ Prohibited to perform database queries in loops
7. ❌ Prohibited to ignore exceptions or use empty catch blocks

Best Practices

1. Prefer composition over inheritance
2. Use dependency injection, avoid hard-coded dependencies
3. Keep methods short, single responsibility
4. Use meaningful variable and method names
5. Refactor promptly, keep code clean
6. Write clear comments explaining "why" rather than "what"