@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/java-architect/references/reactive-webflux.md

@@ -0,0 +1,356 @@
+# Reactive WebFlux
+
+## WebFlux Controller
+
+```java
+package com.example.presentation.rest;
+
+import com.example.application.dto.UserRequest;
+import com.example.application.dto.UserResponse;
+import com.example.application.service.UserService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.*;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+@RestController
+@RequestMapping("/api/users")
+@RequiredArgsConstructor
+public class UserController {
+
+    private final UserService userService;
+
+    @GetMapping
+    public Flux<UserResponse> getAllUsers() {
+        return userService.findAll();
+    }
+
+    @GetMapping("/{id}")
+    public Mono<UserResponse> getUserById(@PathVariable Long id) {
+        return userService.findById(id);
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public Mono<UserResponse> createUser(@RequestBody @Valid UserRequest request) {
+        return userService.create(request);
+    }
+
+    @PutMapping("/{id}")
+    public Mono<UserResponse> updateUser(
+        @PathVariable Long id,
+        @RequestBody @Valid UserRequest request
+    ) {
+        return userService.update(id, request);
+    }
+
+    @DeleteMapping("/{id}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    public Mono<Void> deleteUser(@PathVariable Long id) {
+        return userService.delete(id);
+    }
+}
+```
+
+## Reactive Service Layer
+
+```java
+package com.example.application.service;
+
+import com.example.application.dto.UserRequest;
+import com.example.application.dto.UserResponse;
+import com.example.application.mapper.UserMapper;
+import com.example.domain.model.User;
+import com.example.domain.repository.UserRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+@Service
+@RequiredArgsConstructor
+public class UserService {
+
+    private final UserRepository userRepository;
+    private final UserMapper userMapper;
+
+    public Flux<UserResponse> findAll() {
+        return userRepository.findAll()
+            .map(userMapper::toResponse);
+    }
+
+    public Mono<UserResponse> findById(Long id) {
+        return userRepository.findById(id)
+            .map(userMapper::toResponse)
+            .switchIfEmpty(Mono.error(
+                new EntityNotFoundException("User not found: " + id)
+            ));
+    }
+
+    @Transactional
+    public Mono<UserResponse> create(UserRequest request) {
+        return Mono.just(request)
+            .map(userMapper::toEntity)
+            .flatMap(userRepository::save)
+            .map(userMapper::toResponse);
+    }
+
+    @Transactional
+    public Mono<UserResponse> update(Long id, UserRequest request) {
+        return userRepository.findById(id)
+            .switchIfEmpty(Mono.error(
+                new EntityNotFoundException("User not found: " + id)
+            ))
+            .flatMap(existing -> {
+                userMapper.updateEntity(request, existing);
+                return userRepository.save(existing);
+            })
+            .map(userMapper::toResponse);
+    }
+
+    @Transactional
+    public Mono<Void> delete(Long id) {
+        return userRepository.findById(id)
+            .switchIfEmpty(Mono.error(
+                new EntityNotFoundException("User not found: " + id)
+            ))
+            .flatMap(userRepository::delete);
+    }
+}
+```
+
+## R2DBC Repository
+
+```java
+package com.example.domain.repository;
+
+import com.example.domain.model.User;
+import org.springframework.data.r2dbc.repository.Query;
+import org.springframework.data.r2dbc.repository.R2dbcRepository;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+public interface UserRepository extends R2dbcRepository<User, Long> {
+
+    Mono<User> findByEmail(String email);
+
+    Flux<User> findByActiveTrue();
+
+    @Query("""
+        SELECT u.* FROM users u
+        WHERE u.email LIKE CONCAT('%', :domain, '%')
+        ORDER BY u.created_at DESC
+        """)
+    Flux<User> findByEmailDomain(String domain);
+
+    @Query("""
+        SELECT COUNT(*) FROM users
+        WHERE created_at > :since
+        """)
+    Mono<Long> countCreatedSince(Instant since);
+}
+```
+
+## R2DBC Entity
+
+```java
+package com.example.domain.model;
+
+import org.springframework.data.annotation.Id;
+import org.springframework.data.annotation.CreatedDate;
+import org.springframework.data.annotation.LastModifiedDate;
+import org.springframework.data.relational.core.mapping.Table;
+
+import java.time.Instant;
+
+@Table("users")
+public record User(
+    @Id Long id,
+    String email,
+    String username,
+    Boolean active,
+    @CreatedDate Instant createdAt,
+    @LastModifiedDate Instant updatedAt
+) {
+    public User withId(Long id) {
+        return new User(id, email, username, active, createdAt, updatedAt);
+    }
+
+    public User withEmail(String email) {
+        return new User(id, email, username, active, createdAt, updatedAt);
+    }
+}
+```
+
+## R2DBC Configuration
+
+```yaml
+spring:
+  r2dbc:
+    url: r2dbc:postgresql://localhost:5432/demo
+    username: demo
+    password: demo
+    pool:
+      initial-size: 10
+      max-size: 20
+      max-idle-time: 30m
+
+  data:
+    r2dbc:
+      repositories:
+        enabled: true
+```
+
+## WebClient for External APIs
+
+```java
+package com.example.infrastructure.client;
+
+import com.example.application.dto.ExternalUserDto;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+import org.springframework.web.reactive.function.client.WebClient;
+import reactor.core.publisher.Mono;
+import reactor.util.retry.Retry;
+
+import java.time.Duration;
+
+@Component
+@RequiredArgsConstructor
+public class ExternalUserClient {
+
+    private final WebClient webClient;
+
+    public Mono<ExternalUserDto> getUser(Long id) {
+        return webClient
+            .get()
+            .uri("/users/{id}", id)
+            .retrieve()
+            .bodyToMono(ExternalUserDto.class)
+            .retryWhen(Retry.backoff(3, Duration.ofSeconds(1)))
+            .timeout(Duration.ofSeconds(5));
+    }
+
+    public Mono<ExternalUserDto> createUser(ExternalUserDto user) {
+        return webClient
+            .post()
+            .uri("/users")
+            .bodyValue(user)
+            .retrieve()
+            .bodyToMono(ExternalUserDto.class);
+    }
+}
+
+@Configuration
+class WebClientConfig {
+
+    @Bean
+    public WebClient webClient(WebClient.Builder builder) {
+        return builder
+            .baseUrl("https://api.example.com")
+            .defaultHeader("User-Agent", "Demo Service")
+            .build();
+    }
+}
+```
+
+## Reactor Operators
+
+```java
+// Transform data
+Mono<String> mono = Mono.just("hello")
+    .map(String::toUpperCase)
+    .map(s -> s + "!")
+    .defaultIfEmpty("empty");
+
+// Chain async operations
+Mono<UserResponse> result = userRepository.findById(id)
+    .flatMap(user -> orderRepository.findByUserId(user.id())
+        .collectList()
+        .map(orders -> new UserResponse(user, orders))
+    );
+
+// Combine multiple sources
+Mono<UserDetails> combined = Mono.zip(
+    userService.getUser(id),
+    addressService.getAddress(id),
+    (user, address) -> new UserDetails(user, address)
+);
+
+// Error handling
+Mono<User> safe = userRepository.findById(id)
+    .onErrorResume(DatabaseException.class, e ->
+        cacheRepository.findById(id)
+    )
+    .doOnError(e -> log.error("Failed to fetch user", e));
+
+// Backpressure
+Flux<Data> stream = dataRepository.findAll()
+    .buffer(100)  // Process in batches
+    .flatMap(batch -> processBatch(batch), 5);  // Max 5 concurrent
+```
+
+## Testing Reactive Code
+
+```java
+package com.example.application.service;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest {
+
+    @Mock
+    private UserRepository userRepository;
+
+    @InjectMocks
+    private UserService userService;
+
+    @Test
+    void shouldFindUserById() {
+        User user = new User(1L, "test@example.com", "testuser", true, null, null);
+        when(userRepository.findById(1L)).thenReturn(Mono.just(user));
+
+        StepVerifier.create(userService.findById(1L))
+            .expectNextMatches(response ->
+                response.email().equals("test@example.com")
+            )
+            .verifyComplete();
+    }
+
+    @Test
+    void shouldThrowWhenUserNotFound() {
+        when(userRepository.findById(1L)).thenReturn(Mono.empty());
+
+        StepVerifier.create(userService.findById(1L))
+            .expectError(EntityNotFoundException.class)
+            .verify();
+    }
+}
+```
+
+## Quick Reference
+
+| Operator | Purpose |
+|----------|---------|
+| `Mono.just()` | Create Mono from value |
+| `Flux.fromIterable()` | Create Flux from collection |
+| `.map()` | Transform synchronously |
+| `.flatMap()` | Transform to Mono/Flux |
+| `.filter()` | Filter elements |
+| `.switchIfEmpty()` | Fallback for empty |
+| `.zip()` | Combine multiple sources |
+| `.retry()` | Retry on error |
+| `.timeout()` | Set timeout |
+| `.subscribe()` | Trigger execution |

package/skills/java-architect/references/spring-boot-setup.md

@@ -0,0 +1,269 @@
+# Spring Boot Setup
+
+## Project Structure (Clean Architecture)
+
+```
+src/main/java/com/example/
+├── domain/              # Core business logic
+│   ├── model/          # Entities, value objects
+│   ├── repository/     # Repository interfaces
+│   └── service/        # Domain services
+├── application/         # Use cases
+│   ├── dto/            # Request/Response DTOs
+│   ├── mapper/         # Entity <-> DTO mappers
+│   └── service/        # Application services
+├── infrastructure/      # External concerns
+│   ├── persistence/    # JPA implementations
+│   ├── config/         # Spring configuration
+│   └── security/       # Security setup
+└── presentation/        # API layer
+    └── rest/           # REST controllers
+```
+
+## Modern pom.xml (Spring Boot 3.2)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.2.1</version>
+    </parent>
+
+    <groupId>com.example</groupId>
+    <artifactId>demo-service</artifactId>
+    <version>1.0.0</version>
+    <packaging>jar</packaging>
+
+    <properties>
+        <java.version>21</java.version>
+        <mapstruct.version>1.5.5.Final</mapstruct.version>
+        <testcontainers.version>1.19.3</testcontainers.version>
+    </properties>
+
+    <dependencies>
+        <!-- Spring Boot Starters -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-jpa</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+
+        <!-- Database -->
+        <dependency>
+            <groupId>org.postgresql</groupId>
+            <artifactId>postgresql</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-core</artifactId>
+        </dependency>
+
+        <!-- Mappers -->
+        <dependency>
+            <groupId>org.mapstruct</groupId>
+            <artifactId>mapstruct</artifactId>
+            <version>${mapstruct.version}</version>
+        </dependency>
+
+        <!-- Testing -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>postgresql</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>org.mapstruct</groupId>
+                            <artifactId>mapstruct-processor</artifactId>
+                            <version>${mapstruct.version}</version>
+                        </path>
+                        <path>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+```
+
+## Application Configuration
+
+```yaml
+# application.yml
+spring:
+  application:
+    name: demo-service
+
+  datasource:
+    url: ${DATABASE_URL:jdbc:postgresql://localhost:5432/demo}
+    username: ${DATABASE_USER:demo}
+    password: ${DATABASE_PASSWORD:demo}
+    hikari:
+      maximum-pool-size: 10
+      minimum-idle: 5
+      connection-timeout: 20000
+
+  jpa:
+    hibernate:
+      ddl-auto: validate
+    open-in-view: false
+    properties:
+      hibernate:
+        jdbc:
+          batch_size: 20
+        order_inserts: true
+        order_updates: true
+
+  flyway:
+    enabled: true
+    baseline-on-migrate: true
+    locations: classpath:db/migration
+
+server:
+  port: 8080
+  shutdown: graceful
+  error:
+    include-message: always
+    include-binding-errors: always
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  endpoint:
+    health:
+      show-details: when-authorized
+  metrics:
+    export:
+      prometheus:
+        enabled: true
+```
+
+## Main Application Class
+
+```java
+package com.example;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
+
+@SpringBootApplication
+@EnableJpaAuditing
+public class DemoServiceApplication {
+    public static void main(String[] args) {
+        SpringApplication.run(DemoServiceApplication.class, args);
+    }
+}
+```
+
+## Configuration Classes
+
+```java
+package com.example.infrastructure.config;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class OpenApiConfig {
+
+    @Bean
+    public OpenAPI customOpenAPI() {
+        return new OpenAPI()
+            .info(new Info()
+                .title("Demo Service API")
+                .version("1.0.0")
+                .description("Enterprise microservice API"));
+    }
+}
+```
+
+## Exception Handling
+
+```java
+package com.example.infrastructure.config;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ProblemDetail;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.time.Instant;
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(EntityNotFoundException.class)
+    public ProblemDetail handleNotFound(EntityNotFoundException ex) {
+        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
+            HttpStatus.NOT_FOUND,
+            ex.getMessage()
+        );
+        problem.setProperty("timestamp", Instant.now());
+        return problem;
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
+        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
+            HttpStatus.BAD_REQUEST,
+            "Validation failed"
+        );
+        problem.setProperty("errors", ex.getBindingResult()
+            .getFieldErrors()
+            .stream()
+            .map(e -> e.getField() + ": " + e.getDefaultMessage())
+            .toList());
+        return problem;
+    }
+}
+```
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| `@SpringBootApplication` | Main application entry point |
+| `@Configuration` | Configuration classes |
+| `@Bean` | Bean factory method |
+| `@Value` | Inject properties |
+| `@ConfigurationProperties` | Type-safe config |
+| `@Profile` | Environment-specific beans |
+| `@EnableJpaAuditing` | Automatic audit fields |
+| `ProblemDetail` | RFC 7807 error responses |