ddd-hexagonal-architecture

适用场景

当用户希望进行以下操作时，使用此技能：

• 使用六边形（端口与适配器）架构设计应用程序
• 将领域层与外部系统（数据库、API、消息传递）隔离
• 实现依赖倒置，让领域定义接口，由适配器实现这些接口
• 绘制或实现六边形架构图和分层结构
• 使用内存或模拟适配器隔离测试领域

使用方法

工作流

1. 定义领域模型，包含实体、值对象和领域服务
2. 在领域层中为所有外部交互定义端口（接口）
3. 实现适配器以履行端口契约（入站：HTTP、消息传递；出站：数据库、API）
4. 连接依赖项，确保所有箭头都指向领域

1. 端口定义（领域层）

// Domain port — no framework dependencies
public interface UserRepository {
    Optional<User> findById(UserId id);
    void save(User user);
}

public interface EventPublisher {
    void publish(DomainEvent event);
}

2. 入站适配器（HTTP 控制器）

@RestController
@RequestMapping("/api/users")
public class UserController {
    private final CreateUserUseCase createUserUseCase;

    public UserController(CreateUserUseCase createUserUseCase) {
        this.createUserUseCase = createUserUseCase;
    }

    @PostMapping
    public ResponseEntity<UserDto> create(@RequestBody CreateUserRequest request) {
        User user = createUserUseCase.execute(request.toCommand());
        return ResponseEntity.ok(UserDto.from(user));
    }
}

3. 出站适配器（数据库）

@Repository
public class JpaUserRepository implements UserRepository {
    private final SpringDataUserRepository springRepo;

    @Override
    public Optional<User> findById(UserId id) {
        return springRepo.findById(id.value()).map(UserEntity::toDomain);
    }

    @Override
    public void save(User user) {
        springRepo.save(UserEntity.fromDomain(user));
    }
}

4. 包结构

com.example.app/
├── domain/
│   ├── model/         # Entities, Value Objects
│   ├── port/          # Repository and service interfaces
│   └── service/       # Domain services
├── application/
│   └── usecase/       # Use cases orchestrating domain logic
├── adapter/
│   ├── inbound/       # HTTP controllers, message consumers
│   └── outbound/      # Database, HTTP clients, message publishers
└── config/            # Dependency injection wiring

最佳实践

• 领域层必须不依赖任何框架；应能通过内存或模拟适配器进行测试
• 一个端口可以有多个适配器（例如，不同的存储后端、不同的传输方式）
• 可与 COLA 或整洁架构结合：六边形本质上就是“一个领域层 + 多个适配器”
• 在适配器边界保留 DTO；领域层绝不暴露持久化或传输模型

资源

• Alistair Cockburn 的原始文章：https://alistair.cockburn.us/hexagonal-architecture/
• DDD 与六边形架构：https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/

关键词

六边形架构、端口与适配器、领域隔离、依赖倒置、入站适配器、出站适配器、清晰边界、DDD