Java微服务开发规范

技能文档

---
name: java-weifuwu-kaifa
description: 强制执行后端Java微服务项目标准，涵盖架构分层、设计模式、代码复用、Lombok、TDD测试驱动开发、异常处理以及现代Java特性。
title: Java微服务开发规范
category: 开发工具
---

# Java微服务开发规范

强制执行后端 Java 微服务项目标准，确保代码质量和架构一致性。在使用 Spring Boot、Quarkus、Micronaut 或其他 Java 微服务框架编写、修改或审查代码时应用此规范。

## 架构分层标准

### 六边形架构（端口-适配器）
```
src/main/java/com/example/
├── domain/              # 领域层（核心业务逻辑）
│   ├── model/           # 领域模型
│   ├── service/         # 领域服务
│   ├── event/           # 领域事件
│   └── repository/      # 仓储接口（端口）
├── application/         # 应用层（用例编排）
│   ├── service/         # 应用服务
│   ├── dto/             # 数据传输对象
│   └── mapper/          # DTO ↔ Domain 映射
├── infrastructure/      # 基础设施层（适配器）
│   ├── persistence/     # 数据库实现
│   ├── messaging/       # 消息队列实现
│   ├── external/        # 外部服务调用
│   └── config/          # 基础设施配置
└── interfaces/          # 接口层（入站适配器）
    ├── rest/            # REST控制器
    ├── grpc/            # gRPC服务
    └── mq/              # 消息监听器
```

### 层间依赖规则
- domain 层零外部依赖
- application 层仅依赖 domain
- infrastructure 层实现 domain 定义的接口
- interfaces 层仅调用 application 层

## 设计模式规范

### 必须使用的模式
- **Repository 模式**：数据访问抽象
- **Strategy 模式**：业务规则切换
- **Observer 模式**：领域事件通知
- **Factory 模式**：复杂对象创建

### 推荐使用的模式
- **CQRS**：读写分离场景
- **Saga**：分布式事务
- **Circuit Breaker**：外部服务调用
- **Event Sourcing**：审计要求高的场景

## 编码标准

### Lombok 规范
```java
// 实体类
@Entity
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Order {
    @Id
    private UUID id;
    private OrderStatus status;
    private LocalDateTime createdAt;
}

// DTO（使用 record）
public record CreateOrderRequest(
    @NotNull UUID customerId,
    @NotEmpty List<OrderItemRequest> items
) {}
```

### 异常处理
```java
// 领域异常
public class OrderNotFoundException extends DomainException {
    public OrderNotFoundException(UUID orderId) {
        super("订单不存在: " + orderId);
    }
}

// 全局异常处理
@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(DomainException.class)
    public ResponseEntity<ErrorResponse> handleDomain(DomainException ex) {
        return ResponseEntity.badRequest()
            .body(new ErrorResponse(ex.getCode(), ex.getMessage()));
    }
}
```

### TDD 规范
```java
@ExtendWith(MockitoExtension.class)
class OrderServiceTest {
    @Mock OrderRepository orderRepository;
    @InjectMocks OrderService orderService;

    @Test
    @DisplayName("创建订单 - 正常流程")
    void shouldCreateOrder() {
        // Given-When-Then 结构
        // 每个方法至少覆盖 happy path + 1 个 edge case
    }
}
```

## 微服务通信规范

### 同步通信
- 服务间调用使用 Feign/gRPC
- 必须配置超时、重试、熔断
- 幂等性设计

### 异步通信
- 领域事件通过消息队列发布
- 消息格式使用 CloudEvents 标准
- 消费者必须实现幂等处理

## 现代 Java 特性

- Java 21+ Virtual Threads 用于高并发 IO
- Record 类定义不可变 DTO
- Sealed 类限制领域模型层次
- Pattern Matching 简化类型分支
- Text Block 用于 JSON/SQL 模板

## 触发词

Java微服务、微服务规范、后端架构、分布式Java、Spring Cloud、微服务开发、服务治理、Java后端标准、微服务代码规范、六边形架构

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。