java-architect by 404kidwiz/claude-supercode-skills
npx skills add https://github.com/404kidwiz/claude-supercode-skills --skill java-architect提供专业的 Java 架构专业知识,专精于 Java 21、Spring Boot 3 和 Jakarta EE 生态系统。设计具有现代 Java 特性(虚拟线程、模式匹配)、微服务架构和全面的企业集成模式的企业级应用程序,以构建可扩展、可维护的系统。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
Application Requirements
│
├─ Need reactive, non-blocking I/O?
│ └─ Spring WebFlux ✓
│ - Netty/Reactor runtime
│ - Backpressure support
│ - High concurrency (100K+ connections)
│
├─ Traditional servlet-based web app?
│ └─ Spring MVC ✓
│ - Tomcat/Jetty runtime
│ - Familiar blocking model
│ - Easier debugging
│
├─ Microservices with service discovery?
│ └─ Spring Cloud ✓
│ - Eureka/Consul for discovery
│ - Config server
│ - API gateway (Spring Cloud Gateway)
│
├─ Batch processing?
│ └─ Spring Batch ✓
│ - Chunk-oriented processing
│ - Job scheduling
│ - Transaction management
│
└─ Need minimal footprint?
└─ Spring Boot with GraalVM Native Image ✓
- AOT compilation
- Fast startup (<100ms)
- Low memory (<50MB)
| 因素 | 使用 JPA/Hibernate | 使用 JDBC (Spring JdbcTemplate) |
|---|---|---|
| 复杂度 | 具有关系的复杂领域模型 | 简单查询、报表 |
| 性能 | 带缓存的 OLTP(二级缓存) | OLAP、批量操作 |
| 类型安全 | Criteria API、类型安全查询 | 带有 RowMapper 的普通 SQL |
| 维护 | 通过迁移实现模式演进 | 直接 SQL 控制 |
| 学习曲线 | 较陡峭(延迟加载、级联) | 更简单、明确 |
| N+1 查询 | 有风险(需要 @EntityGraph、fetch join) | 显式控制 |
决策示例:具有关系的电商订单系统 → JPA (Order → OrderItems → Products)
决策示例:带有聚合的分析仪表板 → JDBC(复杂 SQL、性能关键)
Concurrency Requirements
│
├─ High thread count (>1000 threads)?
│ └─ Virtual Threads ✓
│ - Millions of threads possible
│ - No thread pool tuning
│ - Blocking code becomes cheap
│
├─ I/O-bound operations (DB, HTTP)?
│ └─ Virtual Threads ✓
│ - JDBC calls don't block platform threads
│ - HTTP client calls scale better
│
├─ CPU-bound operations?
│ └─ Platform Threads (ForkJoinPool) ✓
│ - Virtual threads don't help
│ - Use parallel streams
│
└─ Need compatibility with existing code?
└─ Virtual Threads ✓
- Drop-in replacement for Thread
- No code changes required
| 观察现象 | 为何上报 | 示例 |
|---|---|---|
| JPA N+1 查询导致 1000+ 次数据库调用 | 复杂的延迟加载问题 | "单页面加载触发 500 次 SELECT 查询" |
| Spring bean 中的循环依赖 | 架构设计问题 | "启动期间出现 BeanCurrentlyInCreationException" |
| 尽管进行了 GC 调优仍存在内存泄漏 | 复杂的对象保留 | "尽管进行了 Full GC,堆仍增长到最大值,堆转储显示神秘的保留" |
| 跨越多个微服务的分布式事务 | SAGA 模式或补偿事务 | "需要跨 Order、Payment、Inventory 服务的 ACID" |
| 响应式流背压过载 | 复杂的响应式管道 | "Flux 生产过剩,下游无法跟上" |
场景:为订单服务实现事件溯源
步骤 1:配置 Spring Kafka
// Configuration/KafkaConfig.java
@Configuration
@EnableKafka
public class KafkaConfig {
@Value("${spring.kafka.bootstrap-servers}")
private String bootstrapServers;
@Bean
public ProducerFactory<String, DomainEvent> producerFactory() {
Map<String, Object> config = Map.of(
ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers,
ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class,
ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, JsonSerializer.class,
ProducerConfig.ACKS_CONFIG, "all",
ProducerConfig.RETRIES_CONFIG, 3,
ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true
);
return new DefaultKafkaProducerFactory<>(config);
}
@Bean
public KafkaTemplate<String, DomainEvent> kafkaTemplate() {
return new KafkaTemplate<>(producerFactory());
}
@Bean
public ConsumerFactory<String, DomainEvent> consumerFactory() {
Map<String, Object> config = Map.of(
ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers,
ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class,
ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, JsonDeserializer.class,
ConsumerConfig.GROUP_ID_CONFIG, "order-service",
ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest",
ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false,
JsonDeserializer.TRUSTED_PACKAGES, "com.example.order.domain.events"
);
return new DefaultKafkaConsumerFactory<>(config);
}
}
步骤 2:定义领域事件
// Domain/Events/DomainEvent.java
public sealed interface DomainEvent permits
OrderCreated, OrderItemAdded, OrderProcessingStarted, OrderCompleted, OrderCancelled {
UUID aggregateId();
LocalDateTime occurredAt();
long version();
}
public record OrderCreated(
UUID aggregateId,
UUID customerId,
LocalDateTime occurredAt,
long version
) implements DomainEvent {}
public record OrderItemAdded(
UUID aggregateId,
UUID productId,
int quantity,
BigDecimal unitPrice,
LocalDateTime occurredAt,
long version
) implements DomainEvent {}
public record OrderCompleted(
UUID aggregateId,
BigDecimal totalAmount,
LocalDateTime occurredAt,
long version
) implements DomainEvent {}
步骤 3:事件发布器
// Infrastructure/EventPublisher.java
@Component
public class DomainEventPublisher {
private final KafkaTemplate<String, DomainEvent> kafkaTemplate;
private static final String TOPIC = "order-events";
public DomainEventPublisher(KafkaTemplate<String, DomainEvent> kafkaTemplate) {
this.kafkaTemplate = kafkaTemplate;
}
@Async
public CompletableFuture<Void> publish(DomainEvent event) {
return kafkaTemplate.send(TOPIC, event.aggregateId().toString(), event)
.thenAccept(result -> {
var metadata = result.getRecordMetadata();
log.info("Published event: {} to partition {} offset {}",
event.getClass().getSimpleName(),
metadata.partition(),
metadata.offset());
})
.exceptionally(ex -> {
log.error("Failed to publish event: {}", event, ex);
return null;
});
}
}
步骤 4:事件消费者
// Infrastructure/OrderEventConsumer.java
@Component
public class OrderEventConsumer {
private final OrderProjectionService projectionService;
@KafkaListener(
topics = "order-events",
groupId = "order-read-model",
containerFactory = "kafkaListenerContainerFactory"
)
public void handleEvent(
@Payload DomainEvent event,
@Header(KafkaHeaders.RECEIVED_PARTITION) int partition,
@Header(KafkaHeaders.OFFSET) long offset
) {
log.info("Received event: {} from partition {} offset {}",
event.getClass().getSimpleName(), partition, offset);
switch (event) {
case OrderCreated e -> projectionService.handleOrderCreated(e);
case OrderItemAdded e -> projectionService.handleOrderItemAdded(e);
case OrderCompleted e -> projectionService.handleOrderCompleted(e);
case OrderCancelled e -> projectionService.handleOrderCancelled(e);
default -> log.warn("Unknown event type: {}", event);
}
}
}
预期成果:
用例:类型安全的动态查询
// Specification for dynamic filtering
public class OrderSpecifications {
public static Specification<Order> hasCustomerId(CustomerId customerId) {
return (root, query, cb) ->
cb.equal(root.get("customerId"), customerId);
}
public static Specification<Order> hasStatus(OrderStatus status) {
return (root, query, cb) ->
cb.equal(root.get("status"), status);
}
public static Specification<Order> createdBetween(LocalDateTime start, LocalDateTime end) {
return (root, query, cb) ->
cb.between(root.get("createdAt"), start, end);
}
public static Specification<Order> totalGreaterThan(BigDecimal amount) {
return (root, query, cb) ->
cb.greaterThan(root.get("totalAmount"), amount);
}
}
// Usage: Combine specifications
Specification<Order> spec = Specification
.where(hasCustomerId(customerId))
.and(hasStatus(new OrderStatus.Pending()))
.and(createdBetween(startDate, endDate));
List<Order> orders = orderRepository.findAll(spec);
用例:独立于写操作优化读操作
// Write model (domain entity)
@Entity
public class Order {
// Rich behavior, complex relationships
public void addItem(Product product, int quantity) { ... }
public void complete() { ... }
}
// Read model (denormalized projection)
@Entity
@Table(name = "order_summary")
@Immutable
public class OrderSummary {
@Id
private UUID orderId;
private UUID customerId;
private String customerName;
private int itemCount;
private BigDecimal totalAmount;
private String status;
private LocalDateTime createdAt;
// Getters only (no setters, immutable)
}
// Read repository (optimized queries)
public interface OrderSummaryRepository extends JpaRepository<OrderSummary, UUID> {
@Query("""
SELECT os FROM OrderSummary os
WHERE os.customerId = :customerId
ORDER BY os.createdAt DESC
""")
List<OrderSummary> findByCustomerId(@Param("customerId") UUID customerId);
}
表现形式:
@Service
@Transactional
public class OrderService {
public Order findById(OrderId id) {
return orderRepository.findById(id).orElseThrow();
}
}
@RestController
public class OrderController {
@GetMapping("/orders/{id}")
public OrderDto getOrder(@PathVariable UUID id) {
Order order = orderService.findById(new OrderId(id));
// Transaction already closed!
var items = order.getItems(); // LazyInitializationException!
return new OrderDto(order, items);
}
}
失败原因:
正确方法:
// Option 1: Eager fetch with @EntityGraph
@Repository
public interface OrderRepository extends JpaRepository<Order, OrderId> {
@EntityGraph(attributePaths = {"items", "items.product"})
Optional<Order> findById(OrderId id);
}
// Option 2: DTO projection (no lazy loading)
@Query("""
SELECT new com.example.dto.OrderDto(
o.id, o.customerId, o.totalAmount,
COUNT(i.id), o.status, o.createdAt
)
FROM Order o
LEFT JOIN o.items i
WHERE o.id = :id
GROUP BY o.id, o.customerId, o.totalAmount, o.status, o.createdAt
""")
Optional<OrderDto> findOrderDtoById(@Param("id") OrderId id);
// Option 3: Open Session in View (not recommended for APIs)
spring.jpa.open-in-view: false // Disable to catch lazy loading issues early
每周安装数
119
代码仓库
GitHub Stars
61
首次出现
Jan 24, 2026
安全审计
安装于
opencode103
gemini-cli97
codex96
github-copilot89
claude-code89
cursor88
Provides expert Java architecture expertise specializing in Java 21, Spring Boot 3, and Jakarta EE ecosystem. Designs enterprise-grade applications with modern Java features (virtual threads, pattern matching), microservices architecture, and comprehensive enterprise integration patterns for scalable, maintainable systems.
Application Requirements
│
├─ Need reactive, non-blocking I/O?
│ └─ Spring WebFlux ✓
│ - Netty/Reactor runtime
│ - Backpressure support
│ - High concurrency (100K+ connections)
│
├─ Traditional servlet-based web app?
│ └─ Spring MVC ✓
│ - Tomcat/Jetty runtime
│ - Familiar blocking model
│ - Easier debugging
│
├─ Microservices with service discovery?
│ └─ Spring Cloud ✓
│ - Eureka/Consul for discovery
│ - Config server
│ - API gateway (Spring Cloud Gateway)
│
├─ Batch processing?
│ └─ Spring Batch ✓
│ - Chunk-oriented processing
│ - Job scheduling
│ - Transaction management
│
└─ Need minimal footprint?
└─ Spring Boot with GraalVM Native Image ✓
- AOT compilation
- Fast startup (<100ms)
- Low memory (<50MB)
| Factor | Use JPA/Hibernate | Use JDBC (Spring JdbcTemplate) |
|---|---|---|
| Complexity | Complex domain models with relationships | Simple queries, reporting |
| Performance | OLTP with caching (2nd-level cache) | OLAP, bulk operations |
| Type safety | Criteria API, type-safe queries | Plain SQL with RowMapper |
| Maintenance | Schema evolution with migrations | Direct SQL control |
| Learning curve | Steeper (lazy loading, cascades) | Simpler, explicit |
| N+1 queries | Risk (needs @EntityGraph, fetch joins) | Explicit control |
Example decision : E-commerce order system with relationships → JPA (Order → OrderItems → Products)
Example decision : Analytics dashboard with aggregations → JDBC (complex SQL, performance-critical)
Concurrency Requirements
│
├─ High thread count (>1000 threads)?
│ └─ Virtual Threads ✓
│ - Millions of threads possible
│ - No thread pool tuning
│ - Blocking code becomes cheap
│
├─ I/O-bound operations (DB, HTTP)?
│ └─ Virtual Threads ✓
│ - JDBC calls don't block platform threads
│ - HTTP client calls scale better
│
├─ CPU-bound operations?
│ └─ Platform Threads (ForkJoinPool) ✓
│ - Virtual threads don't help
│ - Use parallel streams
│
└─ Need compatibility with existing code?
└─ Virtual Threads ✓
- Drop-in replacement for Thread
- No code changes required
| Observation | Why Escalate | Example |
|---|---|---|
| JPA N+1 queries causing 1000+ DB calls | Complex lazy loading issue | "Single page load triggers 500 SELECT queries" |
| Circular dependency in Spring beans | Architectural design problem | "BeanCurrentlyInCreationException during startup" |
| Memory leak despite GC tuning | Complex object retention | "Heap grows to max despite Full GC, heap dump shows mysterious retention" |
| Distributed transaction spanning multiple microservices | SAGA pattern or compensating transactions | "Need ACID across Order, Payment, Inventory services" |
| Reactive stream backpressure overload | Complex reactive pipeline | "Flux overproducing, downstream can't keep up" |
Scenario : Implement event sourcing for order service
Step 1: Configure Spring Kafka
// Configuration/KafkaConfig.java
@Configuration
@EnableKafka
public class KafkaConfig {
@Value("${spring.kafka.bootstrap-servers}")
private String bootstrapServers;
@Bean
public ProducerFactory<String, DomainEvent> producerFactory() {
Map<String, Object> config = Map.of(
ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers,
ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class,
ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, JsonSerializer.class,
ProducerConfig.ACKS_CONFIG, "all",
ProducerConfig.RETRIES_CONFIG, 3,
ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true
);
return new DefaultKafkaProducerFactory<>(config);
}
@Bean
public KafkaTemplate<String, DomainEvent> kafkaTemplate() {
return new KafkaTemplate<>(producerFactory());
}
@Bean
public ConsumerFactory<String, DomainEvent> consumerFactory() {
Map<String, Object> config = Map.of(
ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers,
ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class,
ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, JsonDeserializer.class,
ConsumerConfig.GROUP_ID_CONFIG, "order-service",
ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest",
ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false,
JsonDeserializer.TRUSTED_PACKAGES, "com.example.order.domain.events"
);
return new DefaultKafkaConsumerFactory<>(config);
}
}
Step 2: Define domain events
// Domain/Events/DomainEvent.java
public sealed interface DomainEvent permits
OrderCreated, OrderItemAdded, OrderProcessingStarted, OrderCompleted, OrderCancelled {
UUID aggregateId();
LocalDateTime occurredAt();
long version();
}
public record OrderCreated(
UUID aggregateId,
UUID customerId,
LocalDateTime occurredAt,
long version
) implements DomainEvent {}
public record OrderItemAdded(
UUID aggregateId,
UUID productId,
int quantity,
BigDecimal unitPrice,
LocalDateTime occurredAt,
long version
) implements DomainEvent {}
public record OrderCompleted(
UUID aggregateId,
BigDecimal totalAmount,
LocalDateTime occurredAt,
long version
) implements DomainEvent {}
Step 3: Event publisher
// Infrastructure/EventPublisher.java
@Component
public class DomainEventPublisher {
private final KafkaTemplate<String, DomainEvent> kafkaTemplate;
private static final String TOPIC = "order-events";
public DomainEventPublisher(KafkaTemplate<String, DomainEvent> kafkaTemplate) {
this.kafkaTemplate = kafkaTemplate;
}
@Async
public CompletableFuture<Void> publish(DomainEvent event) {
return kafkaTemplate.send(TOPIC, event.aggregateId().toString(), event)
.thenAccept(result -> {
var metadata = result.getRecordMetadata();
log.info("Published event: {} to partition {} offset {}",
event.getClass().getSimpleName(),
metadata.partition(),
metadata.offset());
})
.exceptionally(ex -> {
log.error("Failed to publish event: {}", event, ex);
return null;
});
}
}
Step 4: Event consumer
// Infrastructure/OrderEventConsumer.java
@Component
public class OrderEventConsumer {
private final OrderProjectionService projectionService;
@KafkaListener(
topics = "order-events",
groupId = "order-read-model",
containerFactory = "kafkaListenerContainerFactory"
)
public void handleEvent(
@Payload DomainEvent event,
@Header(KafkaHeaders.RECEIVED_PARTITION) int partition,
@Header(KafkaHeaders.OFFSET) long offset
) {
log.info("Received event: {} from partition {} offset {}",
event.getClass().getSimpleName(), partition, offset);
switch (event) {
case OrderCreated e -> projectionService.handleOrderCreated(e);
case OrderItemAdded e -> projectionService.handleOrderItemAdded(e);
case OrderCompleted e -> projectionService.handleOrderCompleted(e);
case OrderCancelled e -> projectionService.handleOrderCancelled(e);
default -> log.warn("Unknown event type: {}", event);
}
}
}
Expected outcome :
Use case : Type-safe dynamic queries
// Specification for dynamic filtering
public class OrderSpecifications {
public static Specification<Order> hasCustomerId(CustomerId customerId) {
return (root, query, cb) ->
cb.equal(root.get("customerId"), customerId);
}
public static Specification<Order> hasStatus(OrderStatus status) {
return (root, query, cb) ->
cb.equal(root.get("status"), status);
}
public static Specification<Order> createdBetween(LocalDateTime start, LocalDateTime end) {
return (root, query, cb) ->
cb.between(root.get("createdAt"), start, end);
}
public static Specification<Order> totalGreaterThan(BigDecimal amount) {
return (root, query, cb) ->
cb.greaterThan(root.get("totalAmount"), amount);
}
}
// Usage: Combine specifications
Specification<Order> spec = Specification
.where(hasCustomerId(customerId))
.and(hasStatus(new OrderStatus.Pending()))
.and(createdBetween(startDate, endDate));
List<Order> orders = orderRepository.findAll(spec);
Use case : Optimize reads independently from writes
// Write model (domain entity)
@Entity
public class Order {
// Rich behavior, complex relationships
public void addItem(Product product, int quantity) { ... }
public void complete() { ... }
}
// Read model (denormalized projection)
@Entity
@Table(name = "order_summary")
@Immutable
public class OrderSummary {
@Id
private UUID orderId;
private UUID customerId;
private String customerName;
private int itemCount;
private BigDecimal totalAmount;
private String status;
private LocalDateTime createdAt;
// Getters only (no setters, immutable)
}
// Read repository (optimized queries)
public interface OrderSummaryRepository extends JpaRepository<OrderSummary, UUID> {
@Query("""
SELECT os FROM OrderSummary os
WHERE os.customerId = :customerId
ORDER BY os.createdAt DESC
""")
List<OrderSummary> findByCustomerId(@Param("customerId") UUID customerId);
}
What it looks like:
@Service
@Transactional
public class OrderService {
public Order findById(OrderId id) {
return orderRepository.findById(id).orElseThrow();
}
}
@RestController
public class OrderController {
@GetMapping("/orders/{id}")
public OrderDto getOrder(@PathVariable UUID id) {
Order order = orderService.findById(new OrderId(id));
// Transaction already closed!
var items = order.getItems(); // LazyInitializationException!
return new OrderDto(order, items);
}
}
Why it fails:
Correct approach:
// Option 1: Eager fetch with @EntityGraph
@Repository
public interface OrderRepository extends JpaRepository<Order, OrderId> {
@EntityGraph(attributePaths = {"items", "items.product"})
Optional<Order> findById(OrderId id);
}
// Option 2: DTO projection (no lazy loading)
@Query("""
SELECT new com.example.dto.OrderDto(
o.id, o.customerId, o.totalAmount,
COUNT(i.id), o.status, o.createdAt
)
FROM Order o
LEFT JOIN o.items i
WHERE o.id = :id
GROUP BY o.id, o.customerId, o.totalAmount, o.status, o.createdAt
""")
Optional<OrderDto> findOrderDtoById(@Param("id") OrderId id);
// Option 3: Open Session in View (not recommended for APIs)
spring.jpa.open-in-view: false // Disable to catch lazy loading issues early
Weekly Installs
119
Repository
GitHub Stars
61
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode103
gemini-cli97
codex96
github-copilot89
claude-code89
cursor88
Kotlin Ktor 服务器模式指南:构建健壮 HTTP API 的架构与最佳实践
1,000 周安装
阿里云备份HBR技能:使用OpenAPI和SDK管理云备份资源的完整指南
271 周安装
阿里云 Milvus 向量搜索教程:使用 PyMilvus 连接 Serverless 服务进行 AI 搜索
271 周安装
阿里云DashScope Z-Image Turbo文生图API:快速AI图像生成教程与调用指南
271 周安装
阿里云Model Studio路由指南:一站式调用文生图、语音、视频等AI技能
272 周安装
Supabase 表数据访问测试技能:安全审计与 RLS 策略验证
96 周安装
阿里云通义千问实时TTS语音合成 - 低延迟流式语音输出模型与SDK指南
272 周安装