配置参考#

soda-core 的配置分成两块：

soda.event#

EventProperties 标注了 @ConfigurationProperties(prefix = "soda.event") 和 @Validated，所以配置写错会在启动时抛异常，而不是运行时才暴露。

soda.event.bus-type#

可选值：

soda.event.spring#

SpringProperties 是一个空类 —— 没有任何可配置项。保留它只是为了配置结构的完整性。

soda.event.serialization#

序列化配置。目前只有两个键，而且它们在 17.0.1 里实际上没有被任何代码读取 —— 序列化已经完全交给 EventSerializer 抽象处理了。

CircularReferenceHandler 的三个取值：

soda.event.redis#

Redis 相关配置。只有在 soda.event.bus-type=redis 时才生效。

soda.event.redis.topic#

Redis Stream 的 key 名。发布的事件写进这个 Stream，消费组从这里拉取。

soda.event.redis.host#

soda.event.redis.port#

soda.event.redis.password#

soda.event.redis.database#

soda.event.redis.stream#

Redis Stream 的消费参数。

soda.event.redis.stream.group-name#

消费者组名。同一组内的多个消费者分摊消息。启动时用 XGROUP CREATE 创建，已存在则忽略。

soda.event.redis.stream.consumer-name#

消费者名。默认带上 server.port，这样同一台机器上跑多个实例不会撞名。

concurrency > 1 时，实际的消费者名会加后缀：consumerName-0、consumerName-1……

soda.event.redis.stream.concurrency#

并发消费线程数。每个线程一个 Redis Stream 订阅。

soda.event.redis.stream.batch-size#

单次 XREADGROUP 拉取的最大条数。

soda.event.redis.stream.maxlen#

Stream 的最大长度。超过后旧消息被裁剪。

soda.event.redis.stream.poll-timeout#

拉取阻塞的超时时间。

soda.event.redis.stream.acknowledge-timeout#

确认超时。

soda.event.redis.stream.max-retries#

处理失败时的最大重试次数。重试循环是 for (int retryCount = 0; retryCount <= maxRetries; retryCount++)，所以总共尝试 maxRetries + 1 次。

soda.event.redis.stream.initial-retry-delay#

首次重试的延迟。

soda.event.redis.stream.exponential-backoff#

是否指数退避。开启时延迟计算是：

private long calculateRetryDelay(int retryCount) {
    if (exponentialBackoff) {
        return (long) (initialRetryDelay * Math.pow(2, retryCount));
    }
    return initialRetryDelay;
}

默认配置下，重试延迟依次是 1s、2s、4s。

soda.event.redis.stream.dead-letter-stream#

死信流名。重试耗尽后，消息连同失败原因写进这个流：

Map<String, String> deadLetterEntry = new HashMap<>(message.getValue().size() + 4);
deadLetterEntry.putAll(message.getValue());
deadLetterEntry.put("deadLetterReason", reason);
deadLetterEntry.put("deadLetterTimestamp", String.valueOf(System.currentTimeMillis()));
deadLetterEntry.put("originalStream", message.getStream());
deadLetterEntry.put("originalId", message.getId().getValue());

soda.event.redis.stream.idempotency.enabled#

是否启用幂等。跨服务场景建议开启。

soda.event.redis.stream.idempotency.redis-key-prefix#

幂等状态的 Redis key 前缀。完整 key 是 前缀:eventId。

soda.event.redis.stream.idempotency.expire-time#

幂等状态的过期时间。

soda.event.redis.stream.idempotency.retry-interval#

幂等状态检查的重试间隔。

scoda.ddd.cqrs.async#

AsyncConfig 用的前缀是 scoda.ddd.cqrs.async。它由 SpringBusAutoConfiguration 的 @EnableConfigurationProperties(AsyncConfig.class) 启用。

线程池的其它参数是硬编码的（不在配置里）：

完整示例#

soda:
  event:
    bus-type: redis
    redis:
      topic: soda-events
      host: 127.0.0.1
      port: 6379
      password: ${REDIS_PASSWORD:}
      database: 0
      stream:
        group-name: soda-events-group
        consumer-name: soda-events-consumer
        concurrency: 2
        batch-size: 20
        maxlen: 50000
        poll-timeout: 1000
        acknowledge-timeout: 30000
        max-retries: 3
        initial-retry-delay: 1000
        exponential-backoff: true
        dead-letter-stream: soda-events-dead-letter
        idempotency:
          enabled: true
          redis-key-prefix: soda-events-idempotency
          expire-time: 86400
          retry-interval: 100

scoda:
  ddd:
    cqrs:
      async:
        core-pool-size: 16
        max-pool-size: 32
        queue-capacity: 200
        thread-name-prefix: "cqrs-async-"

配置项速查表#

下一步#

• 每个配置项背后的机制：事件总线与切面
• 怎么替换框架的默认实现：扩展点
• 升级时会变哪些配置：从 v16 升级