DDD+六边形微服务架构下微服务与Keycloak用户配置同步方案咨询

问题背景 #

基于Java Spring Boot、DDD（领域驱动设计）和六边形架构构建的微服务系统中，新客户注册需完成两项操作：

1. 在Customer Service的PostgreSQL数据库中创建客户记录
2. 在Keycloak中配置用户身份以支持登录

现有核心用例代码：

public CustomerResponse createCustomer(@Valid CreateCustomerRequest request) {
    Customer customer = customerMapper.toDomain(request);
    customer = customerRepository.save(customer);
    return customerMapper.toResponse(customer);
}

疑问1：在Customer Service的基础设施适配器中处理Keycloak配置是否为最佳实践？ #

是，但需严格遵循六边形架构的依赖倒置原则：

• 六边形架构将系统划分为内部核心（领域、应用层）和外部依赖（基础设施、第三方服务），Keycloak属于外部身份服务，相关逻辑必须放在基础设施层的适配器中，绝对不能侵入领域层。
• 具体落地方式：
  1. 在应用层定义抽象端口（Port），比如IdentityManagementPort，包含createUserIdentity(Customer customer)方法，只暴露领域需要的身份创建能力，不涉及任何外部服务细节。
  2. 在基础设施层实现该端口，编写KeycloakIdentityAdapter，内部封装Keycloak Admin API的调用逻辑，完成用户配置。
  3. CreateCustomerUseCase依赖IdentityManagementPort而非具体的Keycloak实现，通过依赖注入完成适配。

这种设计既保持了领域层的纯净性，又符合六边形架构的内外隔离原则，同时便于未来替换身份服务（比如从Keycloak切换到Auth0），无需修改核心业务逻辑。

疑问2：若注册时Keycloak宕机，如何保证数据一致性？是否应使用事务性Outbox模式？ #

必须采用事务性Outbox模式+事件驱动重试机制，原因如下：

• 跨系统操作（PostgreSQL写入+Keycloak调用）无法通过本地事务保证一致性，分布式事务（如XA）复杂度高、性能损耗大，不适合微服务场景。
• 事务性Outbox模式的核心流程：
  1. 在CreateCustomerUseCase中，将保存Customer记录和写入CustomerCreated事件到Outbox表放在同一个PostgreSQL本地事务中，确保两者要么同时成功，要么同时回滚，避免数据不一致。
  2. 启动独立的事件分发组件（可通过定时任务或数据库CDC监听），从Outbox表读取未分发的事件，发送到消息队列（如Kafka、RabbitMQ）。
  3. 消费者（可以是Customer Service内部的基础设施适配器，或专门的身份同步服务）监听消息队列，调用Keycloak Admin API创建用户。
  4. 若Keycloak宕机，消息队列会自动重试（需配置合理的重试次数、间隔），直到调用成功；若多次重试失败，事件会进入死信队列，触发告警或人工补偿流程。

配合幂等性设计（比如用Customer ID作为Keycloak用户的唯一标识，重复调用不会创建重复用户），就能保证数据最终一致。

另外，消费者的选择建议：

• 如果仅Customer Service需要同步Keycloak身份，可由Customer Service内部的适配器消费事件，减少服务复杂度。
• 如果未来有多个服务需要同步身份数据，建议搭建专门的IdentitySyncService作为消费者，更符合单一职责原则。

内容的提问来源于stack exchange，提问作者Nur Sultan ASLAN