Redis on 方糖猫Blog

Ruby on Rails 高级篇：接入 Redis、Elasticsearch、消息队列与大数据组件的工程实践

Mon, 14 Sep 2026 14:00:00 +0800

Ruby on Rails 高级篇：接入 Redis、Elasticsearch、消息队列与大数据组件的工程实践

姊妹篇：《Ruby on Rails 从零基础到精通》——入门篇讲「把功能写出来」，这一篇讲「把系统接出去」。目标读者：已经能独立写 Rails CRUD，现在产品要接搜索、接缓存、接消息队列、接大数据管道，想知道「正确姿势」而不是「能跑就行」的开发者。

入门篇的应用是自包含的：一个 Rails 进程 + 一个数据库就是全世界。真实系统不是这样——搜索要 ES、缓存要 Redis、异步要 MQ、报表要大数据平台。每接一个组件，就多一种故障模式。这一篇的结构：

flowchart LR
    A["一 Redis<br/>缓存 队列 数据结构"] --> B["二 Elasticsearch<br/>搜索与索引同步"]
    B --> C["三 消息队列<br/>RabbitMQ / Kafka"]
    C --> D["四 大数据组件<br/>Spark / Flink / ClickHouse"]
    D --> E["五 通用纪律<br/>超时 重试 熔断 幂等"]
    style E fill:#e8f4e8

前四篇每个组件都回答三个问题：用什么 gem、数据怎么流动、生产上死在哪。第五篇是把前四篇的教训抽象成通用清单——以后接任何新组件，照着过一遍就行。

第一篇 Redis：一个组件，四种角色

Rails 接 Redis 最大的误区是「装个 redis gem 存取字符串」。Redis 在 Rails 生态里实际承担四种完全不同的角色，配置和运维要求都不一样：

flowchart TD
    R[("Redis")]
    R1["角色1 缓存<br/>Rails.cache"] --- R
    R2["角色2 任务队列<br/>Sidekiq"] --- R
    R3["角色3 实时推送<br/>Action Cable"] --- R
    R4["角色4 业务数据结构<br/>计数器/排行榜/锁"] --- R

1.1 角色一：缓存（最常用）

# config/environments/production.rb
config.cache_store = :redis_cache_store, {
  url: ENV["REDIS_CACHE_URL"],
  connect_timeout: 1,     # 连接超时 1s，别用默认的 5s
  read_timeout: 0.5,
  write_timeout: 0.5,
  error_handler: ->(method:, returning:, exception:) {
    # 关键：Redis 挂了降级为「缓存 miss」，而不是整个请求 500
    Sentry.capture_exception(exception)
    nil
  }
}

之后入门篇第六篇讲的 Rails.cache.fetch、俄罗斯套娃缓存全部自动走 Redis。两个生产级要点：

error_handler 必须配。缓存的定位是加速器，Redis 抖动不该打垮主站——miss 只是变慢，异常才是事故。
缓存和队列用不同的 Redis 实例/库。缓存实例可以随便清、可以开 allkeys-lru 淘汰；队列实例丢数据就是丢任务。混在一个实例上，运维策略互相打架。

三大经典问题的 Rails 解法：

问题	解法
穿透（查不存在的数据）	`Rails.cache.fetch` 缓存 nil（`skip_nil: false` 是默认行为，nil 也会被缓存），恶意枚举 ID 时考虑布隆过滤器
击穿（热点 key 过期被并发回源）	`Rails.cache.fetch(key, race_condition_ttl: 10)`——过期后第一个进程回源，其余继续用旧值撑 10 秒
雪崩（大面积同时过期）	TTL 加随机抖动：`expires_in: 30.minutes + rand(300).seconds`

1.2 角色二：Sidekiq 任务队列

入门篇讲过 ActiveJob 的 API，生产上吞吐量要求高的场景底层换成 Sidekiq：

# config/application.rb
config.active_job.queue_adapter = :sidekiq

# config/sidekiq.yml —— 队列优先级：重要队列权重高
:queues:
  - [critical, 3]
  - [default, 2]
  - [low, 1]

Sidekiq 与 ActiveJob 的关系：ActiveJob 是 Rails 的标准接口（可换后端），Sidekiq 是高性能实现。建议业务代码只写 ActiveJob API，但有两件事只有原生 Sidekiq 做得好：定时任务（sidekiq-cron / sidekiq-scheduler）和中间件链（统一埋点、限流）。队列 Redis 的内存要按「任务堆积三天不丢」规划，持久化开 AOF。

1.3 角色三：Action Cable 实时推送

入门篇的 Turbo Streams 底层就是 Action Cable，默认用 Redis pub/sub 做进程间广播：

# config/cable.yml
production:
  adapter: redis
  url: <%= ENV.fetch("REDIS_CABLE_URL") %>

多实例部署时这个是必须的（甲请求打到实例 A，乙的浏览器连着实例 B，靠 Redis 广播互通）。流量大了可以换 anycable（Go 实现，单机连接数高一个数量级），Rails 代码不用改。

1.4 角色四：业务数据结构

排行榜、计数器、分布式锁、去重集合——这些直接用 Redis 数据结构，比塞进 MySQL 合适：

# Kredis：Rails 官方出品的 Redis 数据结构封装
class Post < ApplicationRecord
  kredis_list :recent_viewer_ids, limit: 100
  kredis_counter :views
  kredis_unique_list :tag_cache, limit: 50
end

post.views.increment                    # INCR，原子计数
post.recent_viewer_ids.prepend(user.id) # 自动截断到 100

分布式锁用 redis-mutex 或 Sidekiq 生态的 sidekiq-unique-jobs（防止同一任务并发执行，这是任务系统最常用的锁场景）。

1.5 追问：有没有 JetCache 那种「本地 + Redis」两级缓存？

Java 的 JetCache/多层缓存方案（Caffeine 进程内 + Redis 远端 + pub/sub 广播失效）在 Ruby 生态没有对等的成熟 gem，原因在部署模型：Java 是单进程多线程，Caffeine 缓存被整个 JVM 共享，L1 收益巨大；Ruby 应用服务器是多进程模型（Puma 5 个 worker = 5 个独立进程，内存互不相通），进程内缓存每个 worker 各存一份，命中率被摊薄、失效还得跨进程广播——收益/复杂度比不划算，生态便没有收编出「JetCache.rb」。

Rails 的现实替代分三层：

请求级 L1（内建，你已经在用）：所有 ActiveSupport::Cache store 都内置 LocalCache 策略——同一次请求内重复读同一个 key 走进程内存，不打 Redis，请求结束自动清空，无一致性问题。它解决的是「一次请求内 N+1 次读缓存」。
跨请求 L1（手卷，二十来行）：配置/字典类「变很少、读极多」的数据，用 Concurrent::Map + 短 TTL + Redis pub/sub 主动失效：

class ConfigCache
  TTL = 30  # 短 TTL 兜底：pub/sub 丢消息最多脏 30s

  def self.fetch(key)
    entry = store[key]
    return entry[:value] if entry && entry[:exp] > Time.now
    store[key] = { value: yield, exp: TTL.seconds.from_now }
    store[key][:value]
  end

  def self.store = (@store ||= Concurrent::Map.new)

  # 启动时订阅失效广播（多 worker 各自订阅）
  def self.listen(redis)
    Thread.new { redis.subscribe("config:invalidate") { |m| store.delete(m.message) } }
  end
end

Rails 8 的官方答案：Solid Cache 用本地 NVMe 当「超大 L1」：与其在内存里抠几千条 entry，不如把缓存放本机 SSD（SQLite 本地文件）——容量大两个数量级、无网络往返、持久化重启不丢。思路是不优化单次读取延迟，而是把「几乎什么都缓存」变便宜。

第二篇 Elasticsearch：搜索是数据同步问题

Rails 接 ES，写查询语法是简单的一半，难的一半是「MySQL 里的数据怎么进 ES、怎么保持一致」。

2.1 Gem 选型

Gem	特点	建议
Searchkick	封装好、中文分词/高亮/聚合开箱即用	大多数项目的首选
`elasticsearch-model`	官方 gem，贴近原生 DSL	查询复杂、需要完全控制力时

以 Searchkick 为例：

class Post < ApplicationRecord
  searchkick word_middle: [:title],   # title 支持中间匹配（类 LIKE %x%）
             settings: { number_of_shards: 1 }

  # 控制哪些字段进 ES、以什么形态进
  def search_data
    {
      title: title,
      body: body,
      user_name: user.name,      # 关联字段打平进索引
      published_at: published_at,
      comment_count: comments.size
    }
  end
end

# 中文分词：ES 集群装 IK 插件后
# Post.search "视频", fields: [:title], 自动走配置的分析器
Post.search "ruby 教程",
            where: { published_at: { lt: Time.current } },
            order: { comment_count: :desc },
            page: params[:page], per_page: 20

search_data 是核心设计点：ES 文档是反范式的。关联表的字段（作者名、评论数）要打平进文档，否则查询时要回库 join，ES 的意义就没了。代价是：用户名改了，所有相关文档都要重建索引——这就是下一节的问题。

2.2 索引同步：三种策略的取舍

flowchart TD
    W["业务写入 MySQL"] --> S1["策略A Model 回调<br/>同步写 ES"]
    W --> S2["策略B 后台 Job<br/>异步写 ES"]
    W --> S3["策略C CDC<br/>binlog 监听管道"]

策略 A：回调同步写（Searchkick 默认 after_commit）。简单强一致，但 ES 抖动直接拖慢/打挂业务写入，只适合内部系统。
策略 B：回调只入队，Job 异步写（Searchkick 配置 Searchkick.callbacks = :async，或自写 after_commit { ReindexJob.perform_later(self) }）。大多数项目的正确选择：写入不被 ES 拖累，失败可重试。注意 Job 里要重新从 DB 读数据再写 ES（防止任务执行时数据已过期，写入陈旧版本）。
策略 C：CDC 管道（MySQL binlog → Canal/Debezium → Kafka → 消费写 ES）。业务代码零侵入，适合写入量大、文档来源多的大系统，代价是多维护一条数据管道。

2.3 零停机重建索引

Mapping 变更（加字段、改分词）必须重建索引。标准流程靠别名：

# 1. 建新索引 posts_v2，全量灌数据
Post.reindex  # Searchkick 自动建带时间戳的新索引并切换别名

# 底层原理：读永远走别名 posts → 指向 posts_v1 或 posts_v2
# reindex 完成后别名原子切换，全程无读中断

Searchkick 的 reindex 默认就是这个模式，手工玩原生 API 时记住同一原则：读别名，不写别名；切换原子操作。

2.4 生产上死在哪

写放大：热门对象高频更新（计数器、状态），每次都触发 reindex → 把高频字段拆出搜索文档，或改用 update 部分更新。
深分页：from + size 超过 1 万直接报错，列表导出场景用 scroll 或 search_after。
ES 当主库用：ES 不是数据库——近实时（默认 1s 刷新）、无事务。写后立刻要读的场景，读 MySQL 兜底，别调 refresh 硬扛。

第三篇消息队列：ActiveJob 不是 MQ

先澄清一个普遍误解：ActiveJob/Sidekiq 是「任务队列」，不是「消息队列」。两者的区别决定了选型：

	任务队列（Sidekiq）	消息队列（RabbitMQ/Kafka）
语义	「替我执行这段代码」	「广播一个事实，谁关心谁消费」
消费方	只有自己系统的 worker	可以是任意多个异构系统
典型场景	发邮件、生成报表	订单已支付 → 通知库存/物流/积分/大数据

Rails 内部异步用 ActiveJob 就够了；当事件的消费者不止你的 Rails 应用（要对接 Java 服务、数据团队、第三方），才需要真 MQ。

3.1 RabbitMQ：可靠投递优先

# bunny 是 Ruby 的 RabbitMQ 客户端
conn = Bunny.new(ENV["RABBITMQ_URL"]).tap(&:start)
ch = conn.create_channel
exchange = ch.topic("orders", durable: true)

# 发布：持久化消息 + 发送方确认
exchange.publish(
  { order_id: order.id, event: "paid" }.to_json,
  routing_key: "order.paid",
  persistent: true,
  message_id: SecureRandom.uuid   # 供消费方幂等去重
)

消费侧用 sneakers（基于 bunny 的 worker 框架）。RabbitMQ 的关键概念是 exchange/routing key/queue 三层路由，灵活但概念多；适合「企业内部可靠事件通知」。

3.2 Kafka：吞吐与回放优先

Rails 社区接 Kafka 的标准答案是 Karafka（用法神似 Rails 路由）：

# app/consumers/order_events_consumer.rb
class OrderEventsConsumer < ApplicationConsumer
  def consume
    messages.each do |message|
      event = JSON.parse(message.payload)
      OrderEventHandler.call(event)
    end
  end
end

# karafka.rb —— 声明消费哪个 topic
routes.draw do
  topic "order_events" do
    consumer OrderEventsConsumer
  end
end

发布侧用 WaterDrop（Karafka 配套的 producer）：

WaterDrop::SyncProducer.call(
  { event: "order.paid", order_id: order.id }.to_json,
  topic: "order_events",
  key: order.id.to_s   # 同 key 进同分区 → 同一订单的事件保序
)

Kafka 相比 RabbitMQ 的独特价值：消息可回放（消费位点重置就能重跑历史事件）和分区保序。大数据团队要全量订单事件时，只有 Kafka 这条路合适。

3.3 消费侧的三个生死问题

幂等：MQ 的投递语义是「至少一次」，重复消费是常态不是异常。每个消费者都必须能安全重放：

def call(event)
  # 用 message_id 去重，或用业务唯一键 upsert
  return if ProcessedEvent.exists?(message_id: event["message_id"])
  ActiveRecord::Base.transaction do
    ProcessedEvent.create!(message_id: event["message_id"])
    handle(event)
  end
end

死信：处理失败不能无限重试（一条坏消息卡死整个分区）。重试 N 次后进死信队列，告警 + 人工/延时处理。Karafka 有 Dead Letter Queue 原生支持，RabbitMQ 配 DLX。
发布可靠性：「先写库后发消息」存在窗口期——库写了、进程挂了、消息没发。解法是 Outbox 模式：业务数据和 outbox 事件表在同一个事务里写库，后台进程轮询 outbox 表投递 MQ，投递成功标记已发。数据一致性要求高的链路（钱、库存）必须上 outbox，不能裸发。

第四篇大数据组件：先想清楚 Rails 的角色

标题里最常见的认知偏差是「Rails 怎么接 Spark」。正确的问题其实是：在大数据架构里，Rails 应用应该站在什么位置？ 答案是——Rails 几乎从不「接」Spark，它站在管道的两端：

flowchart LR
    A["Rails 应用<br/>业务数据库 MySQL/PG"] -->|"CDC / 事件 Kafka / 定时导出"| B["数据管道<br/>Kafka"]
    B --> C["计算引擎<br/>Spark / Flink"]
    C --> D["分析存储<br/>ClickHouse / ES / Hive"]
    D -->|"API / 只读库 / 回写"| E["Rails 应用<br/>展示分析结果"]

4.1 上游角色：把数据交出去

Rails 是业务数据的源头，交出去的方式按实时性递增：

定时导出（小时/天级）：find_each 分批读库导 CSV/Parquet 上传对象存储。简单可靠，报表场景够用。注意 find_each 默认按主键分批，千万别在导大表时用 each（全量加载内存爆炸）或 offset 分页（越深越慢）。
Kafka 事件（秒级）：重要业务事件按第三篇的方式发 Kafka，数据团队自己消费。
CDC（准实时、全量变更）：Debezium/Canal 监听 binlog，业务代码零侵入。数据团队的最爱——不用求你在每个 Model 里埋事件。

原则：同一份数据只选一条路，既发 Kafka 又跑 CDC 会造成数据团队收到双份口径。

4.2 下游角色：把结果拿回来

Spark/Flink 算完的结果（用户画像、推荐列表、统计报表），Rails 消费的方式：

读分析库：ClickHouse/ES 直接开只读连接给 Rails（用 establish_connection 配第二数据源），OLAP 查询走它，别打 MySQL。
回写业务库：推荐结果、用户分群这类要参与业务逻辑的，由数据管道回写 MySQL/Redis，Rails 无感知地读——首选方案，耦合最低。
内部 HTTP API：数据团队提供服务接口，Rails 用 Faraday/HTTParty 调。适用跨团队边界，记得按第五篇配超时熔断。

4.3 反模式警告

不要在 Rails 进程里嵌 Spark 客户端跑计算——Ruby 不在 JVM 大数据生态里，硬接只有痛苦。
不要让 Spark 作业直接写 Rails 的在线 MySQL 主库——批量回写打爆主库的事故年年有，回写写从库同步的旁表或走限速的 API。

第五篇通用纪律：接入任何组件前的检查清单

前四篇的教训抽象出来，是一套与具体组件无关的纪律。以后接任何外部服务（HTTP API、对象存储、AI 模型接口都一样），按这张清单过一遍：

5.1 超时：永远不依赖默认值

# HTTP 客户端：连接/读/写三个超时分开设
Faraday.new(url: "https://api.example.com") do |f|
  f.options.timeout = 3        # 读超时
  f.options.open_timeout = 1   # 连接超时必须更短
end

默认超时几乎都是灾难（Ruby 的 Net::HTTP 读超时默认 60s——下游挂了，你的 Puma 线程全部吊死 60 秒，线程池耗尽，全站 500）。所有跨进程调用必须显式设超时，且要比上游网关的超时短。

5.2 重试：只对幂等操作，且带退避

retry_on Net::OpenTimeout, wait: :exponentially_longer, attempts: 5

重试放大故障——下游已经过载，你的重试是在 DDoS 它。规则：GET/幂等操作才可重试；次数有上限；间隔指数退避加抖动。

5.3 熔断：下游持续失败就快速失败

# stoplight gem：失败率超阈值 → 熔断器打开，直接抛错不发起请求
light = Stoplight("es-search") { Post.search(query) }
light.with_fallback { Post.where("title LIKE ?", "%#{query}%").limit(20) }  # 降级：回退 DB 模糊查
                       .run

没有熔断的系统，下游慢 = 全站慢。熔断器的意义是保护自己的线程池，顺带给下游喘息时间。配一个配置中心的降级开关（如 features.es_search = false 时直接走 DB），是大流量系统的标准配置。

5.4 幂等：写操作带唯一键

对外发消息：带 message_id（见第三篇）。
对外调写 API：带 Idempotency-Key header（Stripe 系 API 的标准）。
自己提供写接口：用唯一索引兜底（add_index :payments, :idempotency_key, unique: true），重复请求撞索引返回原结果。

5.5 连接池与背压

每个组件的连接池都要和 Puma 并发模型对齐：Puma 5 workers × 16 threads = 80 并发 → DB/Redis 连接池至少 80 → 而下游服务/数据库能不能扛 80 个长连接，要算。Sidekiq 的并发（默认 5~25）单独算一份。连接数规划错位是生产事故的高发区。

5.6 可观测性：每次外部调用都埋点

# 用 instrument 包裹外部调用，自动记录耗时，可接入 StatsD/Prometheus
ActiveSupport::Notifications.instrument("external.es_search", index: "posts") do
  Post.search(query)
end

加上 SkyWalking/OpenTelemetry 做分布式追踪（Rails 侧 opentelemetry-instrumentation-rails 一行接入），每个外部组件的耗时、错误率、QPS 都要能在监控面板上单独看到——出问题时你才知道是哪个组件在拖。

5.7 生态边界：不是所有中间件都有 Ruby 版

接入任何组件前先问一句：这是本生态的活法吗？ 最典型的例子是 Nacos/Sentinel 这类 Spring Cloud 全家桶——Nacos 官方只维护 Java/Go/Python 客户端，Ruby 没有可用 SDK。这不是生态缺陷，而是因为它们解决的问题在 Rails 世界各有归宿：

服务发现：Nacos 是客户端发现模式（Feign 需要实例列表），Rails 文化是单体优先；即使微服务化，K8s Service DNS / 云 LB 这类服务端发现已把注册中心吃掉了，调用方根本不需要知道实例列表。
配置中心：部署期配置用 ENV + ConfigMap，密钥用 credentials，动态开关用 flipper，业务热配置一张 config 表加短 TTL 缓存就够。
限流降级：Sentinel 没有 Ruby 版，对应物是 Rack::Attack（限流）+ stoplight（熔断）。

如果公司基础设施已经是 Nacos（Rails 服务必须融入），原则是让平台层消化异构，不要在应用里养半成品客户端：优先走 K8s 部署 + 网关适配（Rails 应用完全无感知）；必须注册进 Nacos 时，用 OpenAPI 在启动脚本里注册实例 + 定时心跳（十几行脚本的事），配置拉取同理。SDK 的连接管理、本地缓存、监听重连这些核心行为没有维护好的 Ruby 实现，自己扛就是给自己找事故。

5.8 对象存储：文件别过应用服务器

入门篇 §6.3 讲了 Active Storage 的用法，生产接 S3/OSS 时核心纪律只有一条：文件不经过 Rails 进程。

默认链路是浏览器 → Rails → S3：一个 100MB 上传占住一个 Puma worker 几十秒，几个并发上传就能吃光线程池（入门篇 §8.2 的并发模型在这里兑现成事故）。正确姿势是 Direct Upload：浏览器先向 Rails 申请预签名 URL（Active Storage 自带 /rails/active_storage/direct_uploads 端点），然后直传 S3，表单提交时只带一个 signed_id：

# 视图里一行开启
form.file_field :video, direct_upload: true

配套三件事：

公开资源走 CDN 回源：别让每个头像请求都打到 S3（流量费 + 延迟双输）。
私有文件用短时效签名 URL：rails_blob_url 的链接永久有效且经 Rails 代理；敏感文件用 avatar.url(expires_in: 5.minutes) 直出 S3。
图片变体改异步预热：默认首次访问才懒生成缩略图（慢且占 worker），上传完成后用 Job 预生成（avatar.variant(resize_to_limit: [200, 200]).processed）。

还有两个自动化问题必须回答，否则上线就是给运维埋雷：

垃圾谁来清？不会自动发生，要两道工序。 一是应用侧：浏览器直传成功但用户没提交表单，留下「传了但没关联」的孤儿 blob——Rails 不自动清，挂周期任务扫：

ActiveStorage::Blob.unattached.where("created_at < ?", 2.days.ago).find_each(&:purge_later)

二是存储侧：分片上传（multipart）中断会在 S3 留下残片，S3 对残片照常收费——bucket 上必须配 Lifecycle 规则 AbortIncompleteMultipartUpload（如 7 天后中止），不配就是漏水的账单。

传完后怎么触发后续处理？有现成挂点。 blob 关联到记录时，Active Storage 自动排 AnalyzeJob 提取元数据（宽高、时长、校验和），这是内置的「消息」；业务级处理（转码、扫毒、抽帧）挂在自己模型的回调上：

class Video < ApplicationRecord
  has_one_attached :file
  after_save_commit :enqueue_transcode, if: -> { file.attached? }

  private

  def enqueue_transcode
    TranscodeJob.perform_later(id)   # 走 §6.1 的 Active Job 链路，别在请求里做
  end
end

只有绕过 Active Storage 直接对接桶事件的大文件管道，才需要 S3 Event Notification → SQS → 消费者的路子——那是第三篇 MQ 的地盘，一般项目用不上。

收尾：集成的本质是边界管理

回头看这五篇，真正难的技术点一个都没有——gem 都现成，文档都齐全。难的是边界上的纪律：数据跨进程之后，一致性、时序、失败语义全都变了。最后三条心法：

每接一个组件，先写「它挂了怎么办」。缓存挂了降级、ES 挂了回 DB、MQ 挂了走 outbox 堆积——降级路径没设计的集成，等于给系统埋雷。
数据流向永远是单向的。业务库 → 搜索/分析/缓存，反向只读不写。双向同步的系统没有一个不出数据事故的。
组件越少越好。每接一个组件都要回答「现有组件真的解决不了吗」。SQLite 能扛的缓存别上 Redis，Sidekiq 能扛的异步别上 Kafka——架构的复杂度成本是持续的运维和认知负担，不是一次性接入。

至此，从入门篇的「一个人写一个应用」，到这一篇的「让应用成为系统版图里可靠的一环」，Rails 工程师的完整拼图就齐了。

我开发的keCache：面向 Spring Boot 3 的 L1 + L2 两级缓存框架

Thu, 04 Sep 2025 14:16:44 +0800

在高并发 Java 业务里，缓存几乎是标配。但“用缓存”这件事从来不是只有“加 Redis”一种答案：本地缓存快却解决不了多机一致，Redis 能共享却多了网络与序列化开销。我最近实现一个把两者结合起来、并针对集群一致性做了不少细节处理的小而美框架 —— keCache，现在做一次系统梳理。

一、keCache 是什么

keCache 是一个基于 Java 17 + Spring Boot 3.x + Caffeine + Redisson 的本地缓存框架，采用 L1（Caffeine 本地缓存）+ L2（Redis 分布式缓存） 两级架构，同时提供：

声明式注解（@LocalCacheable、@LocalCacheEvict、@LocalCacheClear）
编程式 API（CacheTemplate）
集群失效广播（Redisson Pub/Sub）
空值保护（防止缓存穿透）
数据一致性校准 SPI

它的定位不是“又一个 Redis 客户端”，而是“让本地缓存能在集群环境下安全使用”的胶水层。

1.1 整体架构

graph TD
    App[业务 Service] -->|注解或 API| Facade["CacheTemplate / AOP 切面"]
    Facade --> L1{L1 Caffeine}
    L1 -->|命中| Return[返回数据]
    L1 -->|未命中| L2{L2 Redis}
    L2 -->|命中| Deserialize[Jackson 反序列化]
    Deserialize --> Backfill[回填 L1]
    Backfill --> Return
    L2 -->|未命中| Load["执行方法 / 加载数据"]
    Load --> Write["写入 L1 & L2"]
    Write --> Return
    PubSub["Redisson Pub/Sub"] -->|失效事件| L1
    Calibration[CalibrationProvider SPI] -->|定时校准| L2

二、开源地址

Gitee：https://gitee.com/soulnew/ke-cache

三、为什么需要 keCache？与纯 Redis / 纯 Caffeine 的对比

很多团队在选择缓存方案时，常常在“纯 Redis”和“纯 Caffeine”之间摇摆。keCache 试图在二者之间取得平衡。

维度	纯 Caffeine	纯 Redis	keCache（L1 + L2）
读取延迟	极低（内存内）	较高（网络 + 序列化）	热数据近似 Caffeine，冷数据走 Redis
单机内存压力	大（全部数据在本 JVM）	小（Redis 承担）	小（只有热数据在本地）
集群一致性	无，各节点独立加载	强一致	最终一致，写操作广播失效
缓存穿透保护	需自行实现	需自行实现	内置 NullValue 短 TTL 保护
多机共享	不支持	支持	支持（L2 Redis）
适用场景	只读/准静态数据、单节点	写多读少、需要强一致	读多写少、可接受最终一致

3.1 相比纯 Caffeine 的好处

Caffeine 是 JVM 内缓存的佼佼者，但它天然只服务于当前进程。在集群部署时：

每台机器都要独立加载数据，导致数据库在启动/预热时被打 N 次。
数据更新后其他节点无法感知，容易出现 A 节点已更新、B 节点仍读旧值的“ stale data ”问题。
内存占用随节点数线性增长，同样一份热数据在每个 JVM 都存一份。

keCache 用 L2 Redis 作为共享底座：首次加载从 Redis 取，后续读请求命中本地 Caffeine；写操作时通过 Redis Pub/Sub 通知其他节点清除本地缓存。这样既保留了 Caffeine 的本地速度，又解决了多机一致性难题。

3.2 相比纯 Redis 的好处

Redis 虽然性能好，但毕竟跨进程：

网络 RTT 不可忽视：高频读取时，哪怕 1ms 也会累积成可观的延迟。
序列化/反序列化开销：Java 对象要先转成 JSON/二进制，再还原，CPU 和 GC 都有压力。
热点 Key 风险：大促期间某些热 Key 会被反复打到同一个 Redis 节点。

keCache 把最热的数据放在本地 JVM 里，只有本地未命中或更新时才访问 Redis，显著降低网络和序列化开销，也分散了 Redis 热点压力。

3.3 方案选型速查

flowchart TD
    Start([开始选缓存方案]) --> Q1{是否需要多机共享?}
    Q1 -->|否| Q2{数据是否只读 /<br/>准静态?}
    Q2 -->|是| Caffeine[纯 Caffeine<br/>简单高效]
    Q2 -->|否| Q3{能否接受最终一致?}
    Q3 -->|能| KeCache[keCache<br/>L1 + L2 加速]
    Q3 -->|否| RedisOnly[纯 Redis /<br/>DB 强一致]
    Q1 -->|是| Q4{写多读少 /<br/>强一致?}
    Q4 -->|是| RedisOnly
    Q4 -->|否| KeCache

3.4 一句话总结

keCache 适合“读多写少、能接受最终一致、希望兼顾本地速度与集群共享”的业务场景；如果你的业务对实时一致性要求极高（如库存扣减、金融记账），建议直接走 Redis 或数据库方案。

四、核心能力速览

能力	说明
声明式缓存	`@LocalCacheable` / `@LocalCacheEvict` / `@LocalCacheClear`，支持 SpEL
多键映射	`@LocalCacheable.Multi` 一次方法返回构建多个索引 key
编程式 API	`CacheTemplate.get/put/evict/clear`，类型安全
二级缓存	L1 Caffeine + L2 Redis，读时先 L1 再 L2，未命中回调加载
空值保护	DB 不存在的 key 缓存短 TTL 的 NullValue，防止缓存穿透
集群一致性	Redisson Pub/Sub 广播失效事件，其他 JVM 清除本地 L1
自失效屏蔽	事件携带 `sourceId`，本机忽略自己发出的事件，避免误清本地缓存
广播风暴防护	远程失效事件只清 L1，不再次广播
数据校准	`CalibrationProvider` SPI，支持时间戳扫描或 CDC 扩展

4.1 读取流程

flowchart TD
    Start([读请求]) --> L1[查 L1 Caffeine]
    L1 -->|命中| A[直接返回]
    L1 -->|未命中| L2[查 L2 Redis]
    L2 -->|命中| Deserialize[Jackson 反序列化]
    Deserialize --> Backfill[回填 L1]
    Backfill --> Return[返回数据]
    L2 -->|未命中| Method[执行真实方法]
    Method --> NullCheck{结果是否为 null?}
    NullCheck -->|是| NullVal[写入 NullValue 到 L1/L2<br/>TTL: null-value-ttl]
    NullCheck -->|否| RealVal[写入真实值到 L1/L2]
    NullVal --> ReturnNull[返回 null]
    RealVal --> Return

4.2 写入与集群失效广播流程

sequenceDiagram
    participant A as 节点 A（写请求）
    participant DB as 数据库
    participant R as Redis（L2）
    participant P as Redis Pub/Sub
    participant B as 节点 B
    participant C as 节点 C

    A->>DB: 更新数据
    A->>R: 删除/覆盖 L2 Key
    A->>P: 发布 EvictEvent（携带 sourceId）
    A->>A: 清除本机 L1

    P->>B: 接收 EvictEvent
    B->>B: sourceId ≠ 本机？
    B->>B: 清除本地 L1
    Note over B: 只清 L1，不再次广播

    P->>C: 接收 EvictEvent
    C->>C: sourceId ≠ 本机？
    C->>C: 清除本地 L1

五、快速开始

5.1 引入 Starter

<dependency>
    <groupId>com.keke</groupId>
    <artifactId>kecache-spring-boot-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

5.2 启用缓存

import com.keke.kecache.starter.annotation.EnableKeCache;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableKeCache
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

5.3 基础配置

local-cache:
  enabled: true
  namespace: kecache.sample
  default-ttl: 30m
  null-value-ttl: 5m

  caffeine:
    default:
      maximum-size: 1000
      expire-after-write: 10m
      record-stats: true

  redis:
    address: redis://127.0.0.1:6379
    broadcast-channel: kecache:evict
    default-ttl: 30m

  calibration:
    enabled: false

5.4 声明式使用示例

@Service
public class AccountService {

    @LocalCacheable(
        cacheNames = "tve_account_info",
        key = "'id_' + #accountId",
        unless = "#result == null"
    )
    public AccountInfo getById(long accountId) {
        return accountDao.loadById(accountId);
    }

    // 一次查询构建多个索引 key
    @LocalCacheable.Multi({
        @LocalCacheable(cacheNames = "tve_account_info", key = "'id_' + #accountId"),
        @LocalCacheable(cacheNames = "tve_account_info", key = "'nm_' + #result.accountName", unless = "#result == null")
    })
    public AccountInfo getByIdMultiIndex(long accountId) {
        return accountDao.loadById(accountId);
    }

    @LocalCacheEvict(cacheNames = "tve_account_info", key = "'id_' + #accountId")
    public void updateById(long accountId, AccountInfo info) {
        accountDao.update(accountId, info);
    }

    @LocalCacheClear(cacheNames = "tve_account_info")
    public void clearAll() {
        accountDao.clear();
    }
}

5.5 编程式使用

@Service
public class AccountService {

    @Autowired
    private CacheTemplate cacheTemplate;

    public AccountInfo getById(long accountId) {
        return cacheTemplate.get("tve_account_info", "id_" + accountId, key -> {
            return accountDao.loadById(accountId);
        });
    }
}

六、模块结构

graph TD
    Parent[kecache-parent] --> API[kecache-api<br/>注解 / SPI / 配置模型 / 事件]
    Parent --> Core[kecache-core<br/>统一门面 / Key策略 / 空值保护]
    Parent --> Caffeine[kecache-provider-caffeine<br/>L1 Caffeine 实现]
    Parent --> Redisson[kecache-provider-redisson<br/>L2 Redis + 失效广播]
    Parent --> Calibration[kecache-calibration<br/>数据一致性校准]
    Parent --> Starter[kecache-spring-boot-starter<br/>自动配置 + AOP]
    Parent --> Sample[kecache-spring-boot-sample<br/>示例应用 + 测试]

    Starter --> API
    Starter --> Core
    Core --> Caffeine
    Core --> Redisson
    Core --> Calibration

七、关键约定（写代码前必读）

L1 key：cacheName#dataKey
L2 key：{namespace|cacheName}:dataKey（使用 hash tag 避免集群模式下 slot 分散）
默认读写策略：Cache-Aside
失效广播频道：默认 kecache:evict
序列化：Jackson 启用 default typing，保留类型信息

八、使用注意点与避坑指南

8.1 Redis 是硬性依赖

L2 缓存和失效广播都依赖 Redis，测试与运行前请确保 Redis 可达。运行全部测试需要本地启动 Redis：

mvn clean test

8.2 集群一致性是“最终一致”，不是实时一致

本地缓存存在一致窗口：A 节点写入并广播，B 节点收到消息前仍可能读到旧值。对于库存、余额、订单状态等强一致场景，建议绕过本地缓存，直接走 Redis 或数据库。

8.3 空值保护是把双刃剑

默认对 null 结果缓存 5 分钟，可防止缓存穿透。但如果业务刚刚从 DB 写入了一条新记录，而之前查询时正好命中了 NullValue，就会出现“写入后 5 分钟内查不到”的延迟。需要时可：

缩短 null-value-ttl
在写入后主动 @LocalCacheEvict
对新增数据敏感的 cacheName 关闭空值保护

8.4 序列化类型变更要兼容

Redis 层使用 Jackson 并保留类型信息。如果缓存对象发生不兼容的类结构变更（如字段类型改变、删除字段、包名调整），旧数据反序列化可能失败。建议：

对缓存 DTO 做版本控制
重大变更时清空 Redis 对应 key 或切换 cacheName
避免把接口、匿名类、动态代理对象放入缓存

8.5 注意 Key 的命名空间隔离

L2 key 格式为 {namespace|cacheName}:dataKey。如果多个业务共用同一个 Redis 实例，务必设置不同的 namespace，否则可能出现 Key 冲突。

8.6 `@LocalCacheable.Multi` 的 `result` 引用要判空

多索引注解里如果通过 #result.xxx 取字段，必须配合 unless = "#result == null"，否则方法返回 null 时会触发 SpEL 计算异常。

8.7 AOP 自调用不会生效

和 Spring Cache 一样，keCache 的注解基于 AOP。同类方法内部调用（this.method()）不会走代理，缓存注解不会生效。需要时注入自身代理或改用编程式 CacheTemplate。

8.8 谨慎使用 `@LocalCacheClear`

@LocalCacheClear 会清空整个 cacheName 的本地缓存并广播。在高并发场景下，频繁全量清除会：

导致本地缓存命中率骤降
引发集体回源，DB 压力陡增
产生大量广播消息

建议优先使用 @LocalCacheEvict 精确驱逐。

8.9 校准任务不是开箱即用的

CalibrationProvider 目前只是 SPI 骨架，需要业务方自己实现 fetchChanges(Instant start, Instant end) 逻辑（如查变更表、CDC 日志）。开启 local-cache.calibration.enabled=true 后才会按 Cron 触发。

8.10 当前 Redis 部署模式限制

自动配置里的 RedissonClient 目前只实现了 single 单节点模式。如果生产环境使用 Redis Cluster、Sentinel 或主从，需要自行扩展配置。

8.11 关注 Caffeine 内存与统计

默认开启 record-stats: true，本地缓存命中率、加载次数等都会被记录。建议配合 actuator / Micrometer（后续可扩展）监控：

maximum-size 是否设置合理
本地缓存命中率
加载耗时与异常率

九、许可证

keCache 采用 MIT 协议开源。

十、总结

keCache 是一个目标聚焦、实现克制的两级缓存框架：

如果你想要 Caffeine 的速度 + Redis 的共享能力，它值得尝试。
如果你希望 声明式注解即可解决集群本地缓存一致性问题，它提供了失效广播与自失效屏蔽。
如果你的业务对 实时一致性零容忍，请把它当作“加速层”而非“唯一数据源”。

有兴趣可以直接到 Gitee 查看源码与示例：https://gitee.com/soulnew/ke-cache。

我开发的KE Reliable Executor：基于 Redis/MySQL 的 Spring Boot 可靠任务执行框架

Mon, 04 Aug 2025 17:10:00 +0800

我开发的KE Reliable Executor：基于 Redis/MySQL 的 Spring Boot 可靠任务执行框架

在微服务里，异步任务随处可见：支付后通知第三方、订单超时取消、批量对账、报表生成……这些任务有一个共同诉求——不能丢、不能重复执行、失败能重试、状态要能查。

传统做法是直接引入 Kafka、RocketMQ 这类重型消息中间件。但对于很多中小型业务来说，这未免太重：

需要额外维护 Broker、Topic、消费组；
团队要熟悉一套新的运维和监控体系；
为了“可靠”还要配置死信队列、事务消息等高级特性。

如果你的系统里已经有 Redis（或 MySQL），并且任务量级尚未达到 MQ 的吞吐上限，那么完全可以基于 Redis 搭一个轻量且可靠的异步任务执行框架。

我开发是这样一个框架：KE Reliable Executor。

开源地址：https://gitee.com/soulnew/reliableexecutor

一、为什么需要这个工具？

先回顾一下常见异步任务场景里的痛点：

痛点	说明
任务丢失	服务重启或执行线程异常退出后，未执行的任务找不到了
重复执行	多实例部署时，同一个任务被多个节点同时消费
失败即结束	业务异常或网络抖动后，没有自动重试机制
状态黑盒	无法查询任务当前是成功、失败、执行中还是已取消
接入成本高	引入 MQ 需要改代码、加依赖、搭集群

KE Reliable Executor 要解决的就是这些问题。它把“可靠任务执行”抽象成一个 Spring Boot Starter：

业务方只负责定义任务处理器和提交任务；
框架负责存储、调度、加锁、重试、状态流转、清理；
所有状态都可通过 API 查询，也可通过 Micrometer 指标监控。

适合什么场景？

已有 Redis/MySQL，不想额外维护 MQ；
任务量中等，对可靠性和重试有要求；
需要任务状态可查询、可人工介入；
团队希望以最小成本获得“类 MQ”的可靠执行能力。

不适合什么场景？

海量消息、高吞吐（Kafka/RocketMQ 更合适）；
严格顺序消费（ZSET 按时间排序，不保证业务绝对顺序）；
需要复杂路由、死信队列、事务消息等高级 MQ 特性。

二、与竞品的对比

2.1 与 Kafka / RocketMQ 对比

维度	Kafka / RocketMQ	KE Reliable Executor
基础设施	需要独立 Broker 集群	复用 Redis 或 MySQL
运维成本	高（Topic、消费组、监控）	低（Spring Boot Starter）
接入成本	需要学习 SDK 与语义	注解 + 注入接口即可
吞吐量	极高	中等
状态查询	需自建审计表	内置状态查询
重试机制	需配置消费重试	内置可配置重试
适用阶段	大型业务、高并发	中小型业务、快速落地

结论：KE Reliable Executor 不是取代 MQ，而是在“已有 Redis/MySQL、任务量可控”的场景下，提供一个更轻量的选择。

2.2 与 Spring `@Scheduled` + 数据库轮询对比

很多团队最早会用数据库表 + @Scheduled 轮询来实现异步任务。这种做法的问题：

无分布式锁：多实例同时轮询会重复执行；
无状态机：任务状态全靠字段控制，容易混乱；
无统一重试策略：重试间隔、重试次数需要手写；
无优雅关闭：应用关闭时可能丢失正在执行的任务。

KE Reliable Executor 把这些都封装好了：

Master 选举 + 任务级锁保证不重复；
明确的状态机（CREATED → RUNNING → PENDING/COMPLETED/FAILED）；
可配置的重试间隔与次数；
优雅释放锁与线程池关闭。

2.3 与 XXL-JOB / PowerJob 对比

XXL-JOB 和 PowerJob 是优秀的分布式任务调度平台，但它们更适合定时任务和调度中心模式：

需要单独部署调度中心；
适合 Cron 表达式触发的批处理任务；
任务由业务主动提交的场景下，接入不够自然。

KE Reliable Executor 更像一个嵌入式任务队列：

无额外服务，随业务应用启动；
任务由业务代码主动提交；
强调“提交即可靠执行”，而非定时触发。

三、整体架构

3.1 模块解构图

graph TD
    A[业务服务] -->|submitTask| B(ReliableExecutor API)
    B --> C[TaskScheduler]
    C --> D{Master 锁}
    D -->|持有锁| E[扫描 ZSET 任务]
    E --> F[任务级锁]
    F -->|获取成功| G[提交线程池]
    G --> H[TaskExecutor]
    H --> I["任务处理器 @ReliableTaskHandler"]
    I -->|成功| J[移入 FINISHED]
    I -->|失败| K[更新为 PENDING 等待重试]
    C --> L[TaskStorage]
    L --> M[RedisTaskStorage]
    L --> N[JdbcTaskStorage]
    H --> O[ReliableTaskListener]
    C --> P[ReliableExecutorMetrics]

3.2 两层锁模型

graph TB
    subgraph 全局层
        A[Master 锁] -->|仅一个实例| B[负责调度扫描]
    end
    subgraph 任务层
        C["任务级锁 task-lock:{taskId}"] -->|仅一个线程| D[执行任务]
    end
    B --> C

Master 锁：同一时刻只有一个实例负责扫描任务，避免多节点拉取同一批任务。
任务级锁：针对每个 CREATED 任务，提交执行前再抢一次锁，保证同一任务不会被并发执行。

3.3 队列设计

graph LR
    A[提交任务] -->|add| B[Redis ZSET running-task-zset]
    B -->|ZRANGE 按 score| C[调度器]
    C -->|执行成功/失败/超时| D[Lua 原子转移]
    D -->|RPUSH + ZREM| E[Redis List finished-task-list]

使用 ZSET 而非 List 的核心原因：

天然支持时间调度：score 编码创建时间或下次重试时间；
任务唯一：同一个 member 在队列中只有一份；
状态分区：CREATED 与 PENDING 使用不同 score 基数，一次范围查询即可区分。

Score 编码规则：

score = BASE + epochMillis * 100 + retryCount

CREATED 基数：1_000_000_000_000_000
PENDING 基数：2_000_000_000_000_000

3.4 任务状态机

stateDiagram-v2
    [*] --> CREATED: submitTask
    CREATED --> RUNNING: 调度/立即执行
    RUNNING --> COMPLETED: 执行成功
    RUNNING --> PENDING: 执行失败，未超重试
    PENDING --> RUNNING: 到达重试时间
    RUNNING --> FAILED: 超过重试次数
    RUNNING --> TIMEOUT: 超过最大时长
    CREATED --> CANCELLED: 取消任务
    PENDING --> CANCELLED: 取消任务
    RUNNING --> ERROR: 无处理器/参数错误

四、核心设计要点

4.1 Lua 原子转移

任务进入终态时，必须保证“写入 finished list”和“从 ZSET 移除”是原子的，否则可能出现：

任务已判定成功但还在 ZSET 里，被下一次调度捞出来；
任务已从 ZSET 移除但 finished list 没写入，查询不到结果。

框架使用 Lua 脚本完成这一转移：

local score = redis.call('ZSCORE', KEYS[1], ARGV[1]);
redis.call('RPUSH', KEYS[2], ARGV[2]);
if score then
    redis.call('ZREM', KEYS[1], ARGV[1]);
    return 1;
else
    return 0;
end

逻辑：先查 ZSET，无论是否存在都把终态信息写入 finished list，如果存在再删除。整个脚本在 Redis 单线程执行，天然原子。

4.2 Double-Check

调度器拿到任务级锁后、提交线程池前，会再次回查 Redis：

任务是否仍在 running ZSET 中？
任务状态是否仍是 CREATED？

任一条件不满足，立即释放锁并跳过。这是经典的双重检查模式，把“检查-执行”串在锁保护的临界区内。

4.3 双存储后端

graph TD
    A[TaskStorage 接口] --> B[RedisTaskStorage]
    A --> C[JdbcTaskStorage]
    B --> D[Redisson ZSET + List]
    C --> E[reliable_executor_task 表]
    F[配置 reliable-executor.task-storage] -->|redis/mysql| A

redis：默认，适合已有 Redis 的场景；
mysql：适合不希望引入 Redis 或需要更强持久化的场景。

两种后端通过 Spring 条件装配切换，业务代码无感知。

五、快速开始

5.1 引入依赖

dependencies {
    implementation 'com.ftmao:ke-reliable-executor:1.0.0-SNAPSHOT'
    implementation 'org.redisson:redisson-spring-boot-starter:3.27.2'
}

5.2 配置

spring:
  application:
    name: my-app
  redis:
    redisson:
      config: |
        singleServerConfig:
          address: "redis://127.0.0.1:6379"

reliable-executor:
  task-storage: redis
  core-pool-size: 5
  max-pool-size: 10
  queue-capacity: 100

5.3 定义处理器

@Component
public class OrderTaskHandler {

    @ReliableTaskHandler(name = "process_order", paramType = OrderParam.class)
    public void processOrder(OrderParam param) {
        // 业务逻辑
    }

    @ReliableTaskHandler(name = "send_notify")
    public void sendNotify() {
        // 无参任务
    }
}

5.4 提交任务

@Service
@RequiredArgsConstructor
public class OrderService {

    private final ReliableExecutor reliableExecutor;

    public void submitOrder(OrderParam param) {
        TaskSubmitRequest request = TaskSubmitRequest.builder()
                .taskId(UUID.randomUUID().toString())
                .taskName("process_order")
                .taskParameter(param)
                .retryLimit(3)
                .retryInterval(2000)
                .maxDurationMillis(60000)
                .build();
        reliableExecutor.submitTask(request);
    }
}

5.5 监听生命周期

@Component
public class MyTaskListener implements ReliableTaskListener {

    @Override
    public void onTaskCompleted(String taskId, String taskName) {
        // 任务成功
    }

    @Override
    public void onTaskFailed(String taskId, String taskName, String status) {
        // 任务最终失败
    }
}

六、使用注意点与避坑指南

6.1 业务幂等仍然是最后一道防线

框架通过两层锁、double-check、Lua 原子转移把重复执行的概率降到极低，但任何分布式系统都无法 100% 保证幂等。业务 Handler 仍然应该保证幂等，尤其是涉及写数据库、调用外部接口的场景。

6.2 taskId 需要业务保证唯一

框架使用业务传入的 taskId 作为任务唯一标识。如果同一业务单据重复提交相同 taskId，第二次提交会生成新的 ZSET member（如果业务字段不同）或覆盖（如果完全相同）。建议用业务主键 + 操作类型组合生成 taskId，例如 order_12345_pay。

6.3 重试间隔与最大时长的权衡

reliable-executor:
  retryInterval: 2000      # 失败后 2s 再试
  maxDurationMillis: 60000 # 任务最长存活 60s

retryInterval 过小会导致失败任务快速反复执行，放大下游压力；
maxDurationMillis 是从任务创建时间算起，不是单次执行时间；
建议失败任务采用指数退避（当前版本为固定间隔，后续可扩展）。

6.4 MySQL 分支需要自行引入 JPA

框架中 spring-boot-starter-data-jpa 是 compileOnly，使用 MySQL 存储时需要在业务应用里显式引入：

implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
runtimeOnly 'com.mysql:mysql-connector-j'

并执行建表脚本 db/migration/V1__create_reliable_executor_tables.sql。

6.5 Redis 集群环境注意 Key 前缀

框架默认使用 spring.application.name 作为 Redis Key 前缀。如果多个应用共用同一个 Redis 实例，务必设置不同的 spring.application.name，否则任务会互相串扰。

6.6 线程池队列满载时会跳过调度

当线程池队列达到 queueCapacity 时，调度器会跳过本次周期，避免无限制堆积。如果业务出现持续高峰，建议：

调大 maxPoolSize 和 queueCapacity；
监控 reliable_executor_threadpool_queue_size 指标；
必要时配合业务限流。

6.7 不要忽略超时任务

maxDurationMillis 是从创建时间算起的总时长。如果一个任务在队列里排队太久，可能还没执行就触发 TIMEOUT。对于允许较长延迟的任务，要把这个值设大；对于实时性任务，要把重试间隔和排队容量一起考虑。

6.8 本地开发无 Redis 怎么办？

使用 MySQL 分支（H2 也可以跑测试）；
或者本地启动一个 Redis Docker 容器；
框架的 Redis 集成测试会在无 Redis 时自动跳过，不影响 CI。

七、监控指标

框架内置 Micrometer 指标，可接入 Prometheus/Actuator：

指标名	含义
`reliable_executor_is_master`	当前节点是否为 Master
`reliable_executor_tasks_scheduled_total`	累计调度任务数
`reliable_executor_tasks_executed_total`	累计执行任务数
`reliable_executor_tasks_completed_total`	累计成功任务数
`reliable_executor_tasks_failed_total`	累计失败任务数
`reliable_executor_tasks_timeout_total`	累计超时任务数
`reliable_executor_tasks_retried_total`	累计重试次数
`reliable_executor_threadpool_queue_size`	线程池队列大小
`reliable_executor_task_execution_seconds`	任务执行耗时

八、开源与示例

开源地址：https://gitee.com/soulnew/reliableexecutor
示例模块：example/ 子项目包含可运行的 Spring Boot 应用和 REST 接口示例，可直接启动体验任务提交与执行。

九、总结

KE Reliable Executor 是一个轻量、可靠、易接入的异步任务执行框架。它用 Redis ZSET + 两层锁 + Lua 原子转移，在“不引入重型 MQ”的前提下，提供了任务提交、调度、重试、状态查询、监控等完整能力；同时通过 MySQL 分支提供了另一种存储选择。

如果你的业务符合以下特征，不妨试试它：

已有 Redis/MySQL；
任务量中等，重视可靠性；
希望快速落地，不想为 MQ 付出额外运维成本；
需要任务状态可观测、可人工介入。

记住：框架层负责把重复消费的概率降到极低，业务层仍应保证 Handler 幂等，这才是工程上的稳妥做法。

Lua 入门：写给 Redis 脚本使用者的极简教程

Sun, 03 Oct 2021 10:00:00 +0800

Lua 入门：写给 Redis 脚本使用者的极简教程

Redis 从 2.6 开始支持 Lua 脚本，核心目的是把多个命令打包成原子操作。本文面向已经会用 Redis、但还没写过 Lua 脚本的同学，只讲最常用、最实用的部分，学完就能写出常见的限流、加锁、库存扣减脚本。

一、为什么 Redis 需要 Lua

Redis 单条命令是原子的，但多条命令组合起来就不是了。比如经典的「查库存 → 判断 → 扣减」：

GET stock:1001      # 返回 10
# 业务代码判断 10 > 0
DECR stock:1001     # 返回 9

并发时两个客户端可能都读到 10，然后都执行 DECR，导致超卖。

Lua 脚本在 Redis 里作为一个整体执行，中间不会被其他命令打断，天然解决了这类问题。而且脚本在 Redis 服务端执行，还能减少网络往返。

二、本地 Lua 环境准备

2.1 安装 Lua

macOS：

brew install lua
lua -v

Ubuntu / Debian：

sudo apt update
sudo apt install lua5.1
lua5.1 -v

Windows：

从 Lua 官方下载源码或预编译二进制，也可以直接用 Lua for Windows。

Docker（最省事）：

docker run --rm -it nickblah/lua:5.1 lua -v

2.2 第一个本地 Lua 程序

创建 hello.lua：

print("hello, lua")

运行：

lua hello.lua

2.3 用 Redis 验证脚本

如果你本地有 Redis，可以直接用 redis-cli 跑脚本文件：

redis-cli --eval myscript.lua key1 key2 , arg1 arg2

注意 , 前后都有空格：, 左边是 KEYS，右边是 ARGV。

2.4 编辑器推荐

VS Code：插件 Lua（sumneko）或 Lua Language Server。
IDEA / WebStorm：安装 EmmyLua 插件。
Neovim：lua_ls + lspconfig。

三、Hello World：第一个 Redis Lua 脚本

EVAL "return 'hello, redis lua'" 0

EVAL 是执行 Lua 脚本的命令。
后面的 0 表示脚本用到的 key 数量是 0。
return 把结果返回给客户端。

带 key 和参数的版本：

EVAL "return redis.call('GET', KEYS[1])" 1 user:1
# 等同于 GET user:1

EVAL "return redis.call('SET', KEYS[1], ARGV[1])" 1 user:1 alice
# 等同于 SET user:1 alice

KEYS[1] 对应第 1 个 key，KEYS[2] 对应第 2 个，以此类推。
ARGV[1] 对应第 1 个额外参数。
所有 ARGV 都是字符串，如果需要数字，要在 Lua 里做类型转换。

四、Lua 基础：Redis 场景够用的子集

4.1 变量与类型

Lua 是动态类型语言，常用类型有：nil、boolean、number、string、table。

local name = "alice"      -- 字符串
local age = 30            -- 数字，不区分 int / float
local ok = true           -- 布尔
local empty = nil         -- 空

注意：

局部变量用 local，否则会成为全局变量。Redis 脚本里建议一律用 local。
条件判断时，0 和空字符串 '' 都是 true，只有 nil 和 false 是 false。

local a = 0
if a then
    return "yes"    -- 会执行这里
end

4.2 字符串与数字转换

local s = "42"
local n = tonumber(s)      -- 转成数字 42
local s2 = tostring(n)     -- 转成字符串 "42"

local a = "10"
local b = "3"
local c = a + b            -- 13，自动把字符串当数字

在 Redis 脚本里，更推荐显式转换，避免意外：

local count = tonumber(redis.call('GET', KEYS[1])) or 0

4.3 表（table）：数组 + 字典

表是 Lua 唯一的数据结构，既能当数组用，也能当字典用。

-- 数组（下标从 1 开始）
local arr = {"a", "b", "c"}
return arr[1]    -- "a"

-- 字典
local dict = {name = "alice", age = 30}
return dict.name -- "alice"

遍历数组：

local arr = {"a", "b", "c"}
for i, v in ipairs(arr) do
    print(i, v)
end
-- 输出：
-- 1 a
-- 2 b
-- 3 c

遍历字典：

local dict = {name = "alice", age = 30}
for k, v in pairs(dict) do
    print(k, v)
end

4.4 条件判断

local n = 10
if n > 20 then
    return "big"
elseif n > 5 then
    return "medium"   -- 会返回这个
else
    return "small"
end

4.5 循环

-- for 循环
for i = 1, 5 do
    print(i)
end

-- while 循环
local i = 1
while i <= 5 do
    print(i)
    i = i + 1
end

Redis 脚本里循环要慎用，避免执行时间过长阻塞主线程。

4.6 函数

local function add(a, b)
    return a + b
end

return add(1, 2)  -- 3

五、Lua 原理浅析

理解 Lua 的运行机制，能帮你写出更稳的 Redis 脚本。

5.1 解释器与字节码

Lua 不是纯解释执行。它会把源码编译成字节码（bytecode），然后在 Lua 虚拟机（VM）上运行。

luac -o hello.luac hello.lua    -- 编译成字节码
lua hello.luac                   -- 运行字节码

Redis 内部集成的也是 Lua VM，脚本第一次执行时会先编译成字节码，之后再执行就复用这个结果。所以长脚本第一次跑会慢一点，后续重复执行会快一些。

5.2 内存回收机制

Lua 使用自动垃圾回收（Garbage Collection, GC），主要策略是增量式标记-清除（incremental mark-and-sweep）。Lua 5.4 还引入了分代 GC 模式。

对 Redis 脚本来说，关键点是：

脚本运行期间创建的 table、string 等临时对象，由 Lua GC 自动回收。
Redis 脚本通常很短，GC 压力不大。
不要在脚本里构造超大 table 或缓存大量中间结果，否则可能触发 GC 暂停，阻塞 Redis。

5.3 Table 是核心

Lua 的 table 本质上是一个哈希表 + 数组的混合结构：

用连续整数索引时，底层按数组优化，访问快。
用字符串或其他类型当 key 时，底层是哈希表。

这也是 Lua 能用 table 模拟数组、字典、对象、模块的原因。

5.4 Redis 中的 Lua 沙箱

Redis 对 Lua 做了严格限制：

不能加载外部库（如 io、os 大部分功能被禁用）。
不能发起网络请求。
不能访问文件系统。
只能调用 Redis 提供的 API（如 redis.call、redis.log）。

这个沙箱保证了脚本安全，但也意味着你不能直接在脚本里读系统时间（os.time 被禁用），需要把时间作为 ARGV 传进去。

六、Redis 脚本核心 API

6.1 redis.call 与 redis.pcall

redis.call(...)：调用 Redis 命令，出错时直接抛出 Lua 错误，脚本会终止。
redis.pcall(...)：调用 Redis 命令，出错时返回错误对象，脚本继续执行。

-- call 版本：key 不存在会报错
local v = redis.call('GET', 'non_existent_key')

-- pcall 版本：可以捕获错误
local ok, err = pcall(redis.call, 'GET', 'non_existent_key')
if not ok then
    return "error: " .. tostring(err)
end

一般推荐：

简单脚本用 redis.call，逻辑更清晰。
需要容错时用 redis.pcall 或外层 pcall。

6.2 返回值

Lua 脚本可以返回单个值、数组或表：

-- 返回单个值
return redis.call('GET', KEYS[1])

-- 返回多个值
return {redis.call('GET', KEYS[1]), redis.call('GET', KEYS[2])}

Redis 会把 Lua 的 table 转成数组返回给客户端。

6.3 KEYS 与 ARGV 的规范

Redis Cluster 要求脚本里用到的 key 都必须放在 KEYS 中，这样 Redis 才能判断脚本是否跨 slot。ARGV 里只能放非 key 参数。

EVAL "return redis.call('SET', KEYS[1], ARGV[1])" 1 mykey myvalue

这里 mykey 是 key，myvalue 是 value。

七、实战：常见 Redis Lua 模式

7.1 限流（滑动窗口）

限制某个用户在 60 秒内最多请求 100 次：

local key = KEYS[1]
local window = tonumber(ARGV[1])      -- 窗口大小，毫秒
local limit = tonumber(ARGV[2])       -- 限制次数
local now = tonumber(ARGV[3])         -- 当前时间戳，毫秒

-- 清理窗口外的请求记录
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)

-- 统计当前窗口内的请求数
local count = redis.call('ZCARD', key)

if count < limit then
    redis.call('ZADD', key, now, now .. "_" .. count)
    redis.call('PEXPIRE', key, window)
    return 1   -- 允许通过
else
    return 0   -- 拒绝
end

调用：

EVAL "...脚本..." 1 rate:user:1 60000 100 1690000000000

7.2 分布式锁（可重入简化版）

local key = KEYS[1]
local token = ARGV[1]
local ttl = tonumber(ARGV[2])

local current = redis.call('GET', key)
if current == false or current == token then
    redis.call('SET', key, token, 'PX', ttl)
    return 1
else
    return 0
end

7.3 库存扣减（防超卖）

local key = KEYS[1]
local delta = tonumber(ARGV[1])

local stock = tonumber(redis.call('GET', key)) or 0
if stock < delta then
    return -1    -- 库存不足
end

redis.call('DECRBY', key, delta)
return stock - delta

7.4 批量删除符合某种前缀的 key

注意：生产环境慎用 KEYS 命令，这里仅作语法示例，大数据量请用 SCAN。

local pattern = ARGV[1]
local keys = redis.call('KEYS', pattern)

for i, k in ipairs(keys) do
    redis.call('DEL', k)
end

return #keys

7.5 条件更新（CAS 简化版）

local key = KEYS[1]
local expected = ARGV[1]
local newValue = ARGV[2]

local current = redis.call('GET', key)
if current == expected then
    redis.call('SET', key, newValue)
    return 1
else
    return 0
end

八、调试、常见坑与最佳实践

8.1 调试脚本

先用本地 Redis 跑：redis-cli --eval script.lua key1 key2 , arg1 arg2
- 注意 , 前后有空格，, 左边是 KEYS，右边是 ARGV。
打印日志：Lua 脚本里不能直接用 print 输出到客户端，但可以用 redis.log(redis.LOG_NOTICE, msg) 写到 Redis 日志。

redis.log(redis.LOG_NOTICE, "current stock: " .. tostring(stock))

本地先用 lua 命令跑语法：不依赖 Redis 也能检查基础语法错误。

8.2 常见踩坑清单

坑	说明	建议
ARGV 全是字符串	数字运算前必须 `tonumber()`	每个数字参数都显式 `tonumber()`
全局变量	忘了 `local` 可能污染全局环境，Redis 甚至会杀掉脚本	所有变量一律加 `local`
脚本执行时间	循环、大 key 操作会阻塞 Redis 主线程	脚本尽量短，避免复杂循环
集群 key 位置	所有 key 必须写在 `KEYS` 里，跨 slot 会报错	业务 key 设计时确保同一 slot
脚本缓存	长脚本每次 EVAL 都传输浪费带宽	生产环境用 `EVALSHA` 或客户端自动缓存
`nil` 中断数组	table 中间出现 `nil` 会导致 `#` 长度计算出错	避免在数组中间塞 `nil`
`pairs` 遍历顺序	`pairs` 不保证顺序，`ipairs` 才按数组顺序	需要顺序时用 `ipairs` 或自己维护索引
字符串拼接性能	`..` 在循环里反复拼接是 O(n²)	用 `table.concat` 批量拼接
`redis.call` 报错	命令执行失败会直接抛错终止脚本	需要容错时改用 `redis.pcall`
缺失 key 的返回值	`GET` 不存在的 key 返回 `false`，不是 `nil`	判断时用 `== false` 或 `if not current`
写命令必须确定性的	主从复制/持久化要求相同的脚本产生相同结果	不要用随机数、`TIME`、`SRANDMEMBER` 等做写决策
浮点数比较	`0.1 + 0.2 ~= 0.3`	用整数存储金额/库存，避免浮点

8.3 性能建议

脚本尽量短小，只处理一个原子逻辑单元。
不要在 Lua 里做复杂计算或大量循环。
大 key 操作（如 HGETALL 几十万字段）不要在脚本里做。
热 key 尽量缩短 TTL 或做拆分，避免单脚本长时间占用。
对执行时间没把握的脚本，先用 redis-cli --latency-history 或 SLOWLOG 观察影响。

九、总结

Redis Lua 脚本不需要你成为 Lua 专家，掌握下面几点就能覆盖 80% 的场景：

本地能跑 Lua，能写 .lua 文件并用 redis-cli --eval 测试。
local 变量、number / string / table 三种类型。
tonumber() / tostring() 转换，ipairs() / pairs() 遍历，table.concat 拼接。
Lua 是编译成字节码在 VM 上运行，GC 自动回收，Redis 里是沙箱环境。
redis.call() 调用命令，KEYS[n] 和 ARGV[n] 传参，集群 key 必须放 KEYS。
脚本整体原子执行，适合「读 → 判断 → 写」的复合操作。
注意 ARGV 是字符串、缺失 key 返回 false、避免长脚本阻塞、写命令要确定性。

限流、分布式锁、库存扣减、条件更新这些高频场景，本质上都是同一个模式：先读数据，在脚本里做判断，再决定写什么。把这一点练熟，Redis Lua 就入门了。

如果你在 Redis Lua 脚本里踩过什么坑，欢迎在评论区分享。

从Redis核心原理到 IPTV 视频项目落地

Tue, 28 Sep 2021 10:00:00 +0800

从Redis核心原理到 IPTV 视频项目落地

先系统梳理 Redis 的核心原理与面试高频知识点，再结合 IPTV（交互式网络电视）视频业务场景，给出可直接运行的 Demo。最后讨论 Redis 为什么不适合长期存储、常见踩坑点，以及 List / Pub/Sub / Stream 三种消息队列实现。

一、Redis 是什么？一句话定位

Redis（Remote Dictionary Server）是一个开源的、基于内存的高性能键值对数据库，支持多种数据结构、持久化、高可用与分布式扩展。

graph LR
    A[Redis] --> B[内存存储]
    A --> C[数据结构服务器]
    A --> D[单线程命令执行]
    A --> E[IO 多路复用]
    A --> F[持久化 + 高可用]
    B --> G[读写毫秒级]
    C --> H[String/Hash/List/Set/ZSET/Stream/Bitmap/Geo/HyperLogLog]
    F --> I[RDB/AOF/主从/哨兵/Cluster]

与 Memcached 等纯缓存不同，Redis 的核心价值在于丰富的数据结构与原子操作，可以直接在内存中完成排序、计数、限流、去重、队列等复杂逻辑。

二、Redis 为什么快？

面试常问「Redis 为什么快」，通常从四个层面回答：

原因	说明
内存操作	数据存于内存，无需磁盘寻道，访问速度是 SSD 的千倍以上。
单线程命令执行	避免多线程上下文切换、锁竞争，CPU 缓存命中率更高。
IO 多路复用	基于 epoll/kqueue/select 用一个线程处理大量连接。
高效数据结构	String 底层 SDS、ZSET 底层跳表+字典、List 底层 quicklist 等。

graph TB
    subgraph Redis 6/7 线程模型
        M[主线程<br/>命令执行 + IO 多路复用]
        IO[IO 线程池<br/>仅网络读写]
        BG[后台进程<br/>RDB fork / AOF rewrite]
    end
    C1[Client 1] --> M
    C2[Client 2] --> M
    C3[Client 3] --> M
    M <--> IO
    M -.-> BG

注意：Redis 6/7 引入的多线程只用于网络 IO 读写，命令执行依旧是单线程。所以单条慢命令仍会阻塞整个实例。

三、Redis 数据类型与使用场景

3.1 五种基本数据类型

类型	底层结构	典型场景
String	SDS（简单动态字符串）	缓存、计数器、分布式锁、Session
Hash	ziplist / hashtable	对象缓存、用户信息、EPG 节目单
List	quicklist（ziplist + 双向链表）	消息队列、最新 N 条记录
Set	intset / hashtable	去重、共同关注、抽奖
ZSET	ziplist / skiplist + dict	排行榜、延时队列、范围查询

注：表中 ziplist 在 Redis 7 起已被 listpack 替代（动机见 §4.2），配置项改名 *-max-listpack-*，旧名仍兼容。

3.2 三种特殊数据类型

类型	说明	场景
Bitmap	位数组，按位操作	用户签到、在线状态、UV 统计
HyperLogLog	基数估计算法	海量 UV 去重计数，误差约 0.81%
Geo	地理位置坐标	附近的人、POI 搜索

3.3 String：最常用却被低估

String 不仅能存字符串，还能存整数、浮点数、二进制数据。常用命令：

SET key value EX 3600
GET key
INCR view_count
INCRBY view_count 10
SETNX lock:order:123 true EX 30  # 分布式锁核心命令

SDS 的优势（相对 C 字符串）：

O(1) 获取长度。
二进制安全，可存图片、序列化数据。
预分配空间，减少内存重分配次数。
杜绝缓冲区溢出。

3.4 Hash：对象缓存首选

Hash 适合存「一组字段」的对象，比 JSON String 更节省内存、更新更灵活。

HSET user:1001 name "张三" age 30 city "北京"
HGET user:1001 name
HGETALL user:1001
HINCRBY user:1001 age 1

3.5 ZSET：排行榜的王牌

ZSET 底层同时维护「跳表」和「字典」：

跳表（skiplist）：支持 O(log N) 的范围查询和排序。
字典（dict）：支持 O(1) 按 member 查 score。

ZADD hot:tv 1000 "庆余年"
ZADD hot:tv 800 "狂飙"
ZINCRBY hot:tv 50 "狂飙"
ZREVRANGE hot:tv 0 9 WITHSCORES
ZREVRANK hot:tv "狂飙"

3.6 List 与 Stream：队列双雄

List 适合简单队列，Stream 适合生产级消息队列，后面第十四部分会详细对比。

3.7 Bitmap 与 HyperLogLog：海量 UV 统计的利器

Bitmap 为什么能天然去重？

Bitmap 本质是一个超长 bit 数组，每个 bit 只能是 0 或 1。把 user_id 作为偏移量（offset），用户访问一次就把对应位置 1：

天然去重：同一用户重复访问，置的都是同一个 bit，无需额外判断。
极致省内存：1 亿用户只需 1 亿 bit ≈ 12MB；而 Set 存 1 亿个 ID 要占用数 GB。
支持位运算：BITOP AND/OR 可以直接算多日留存（今天访问 AND 昨天也访问）。

SETBIT uv:20210928 10086 1   # 用户 10086 访问
SETBIT uv:20210928 10086 1   # 重复访问，结果不变
BITCOUNT uv:20210928         # 直接得出 UV 数

局限：要求 user_id 是连续整数，ID 稀疏时浪费内存。

HyperLogLog 为什么 12KB 能数一亿？

HyperLogLog 基于概率估计算法：把每个元素 hash 成均匀分布的随机数，观察 hash 值二进制串中前导零的最大个数。

类比抛硬币：想连续抛出 N 次正面，平均要抛 2^N 次。反过来，如果见过最长连续 N 次正面，就估计大约抛了 2^N 次——前导零越多，说明见过的不同元素越多。
单次估计误差大，所以内部用 16384 个分桶（寄存器，每个 6 bit） 分别记录，再取调和平均数消除偶然性，最终误差稳定在 0.81% 左右。
内存恒定 约 12KB，与元素个数无关：统计 1 亿 UV 还是 10 亿 UV 都是 12KB。

PFADD uv:20210928 "user:10086"
PFADD uv:20210928 "user:10086"  # 重复添加不影响计数
PFCOUNT uv:20210928             # 估算 UV

局限：有误差、不可逆（不能取出具体是哪些用户）。

怎么选：

需求	推荐
精确计数、算多日留存（交并集）、ID 是连续整数	Bitmap
只要近似 UV、数据量极大、ID 是任意字符串	HyperLogLog

四、Redis 底层数据结构速览

graph TD
    A[Redis 数据类型] --> B[String]
    A --> C[Hash]
    A --> D[List]
    A --> E[Set]
    A --> F[ZSET]
    B --> G[SDS]
    C --> H[ziplist]
    C --> I[hashtable]
    D --> J[quicklist]
    E --> K[intset]
    E --> L[hashtable]
    F --> M[ziplist]
    F --> N[skiplist + dict]

底层结构	特点
SDS	带长度、预分配、二进制安全。
ziplist	紧凑列表，小数据量时省内存；大数据量时改为 hashtable/skiplist。
listpack	ziplist 的修正版（Redis 7+）：entry 只记自身长度，消灭连锁更新。
quicklist	List 的底层，由多个紧凑块（Redis 7 前是 ziplist，之后是 listpack）节点组成的双向链表。
hashtable	标准哈希表，渐进式 rehash 避免一次性阻塞。
intset	Set 在元素全为整数且数量少时的紧凑实现。
skiplist	多层索引链表，实现 ZSET 的有序范围查询。

下面把 5 种核心结构「画」出来。

4.1 SDS（Simple Dynamic String）

Redis 没有直接用 C 字符串，而是包了 SDS：

flowchart LR
    L["len<br/>已用长度（4B）<br/>= 5"] --- A["alloc<br/>总容量<br/>= 8"] --- F["flags<br/>编码位<br/>= 0"] --- B["buf[]<br/>实际字符/二进制数据<br/>H e l l o \0 ..."]
    N1["O(1) 取长度"] -.-> L
    N2["末尾保留 \0<br/>兼容 C 字符串函数"] -.-> B

len：已用长度，取长度 O(1)。
alloc：分配的总空间；free = alloc - len 可减少内存重分配。
二进制安全：内容中间可以有 \0，长度由 len 决定。
预分配：修改时若 free 足够就不 realloc；不足时按 2 倍或 1MB 上限预分配。

4.2 ziplist（压缩列表）

ziplist 是一块连续内存，把所有 entry 紧凑排列：

flowchart LR
    A["zlbytes<br/>总字节数<br/>4B"] --- B["zltail<br/>尾偏移量<br/>4B"] --- C["zllen<br/>节点数<br/>2B"] --- D["entry1<br/>变长字节"] --- E["entry2<br/>变长字节"] --- F["..."] --- G["zlend<br/>0xFF<br/>1B"]

每个 entry 的内部结构：

flowchart LR
    A["prevlen<br/>前节点长度<br/>1B 或 5B"] --- B["encoding<br/>编码/长度类型<br/>1B 或更多"] --- C["content<br/>实际数据<br/>变长"]

连续内存、无额外指针，所以省内存。
插入/删除需要整体 memmove，因此只用于小数据量。
Hash/List/ZSET 元素少且单元素短时先用 ziplist，超过阈值升级为 hashtable/skiplist。

listpack（Redis 7 的替代者）：ziplist 的致命伤就藏在 prevlen 里——每个 entry 要记录前一个 entry 的长度：前 entry 小于 254 字节时 prevlen 占 1B，达到 254 字节时占 5B。于是一个 entry 从 253 涨到 254 字节，会让后面每个 entry 的 prevlen 从 1B 膨胀到 5B，膨胀又可能触发下一个 entry 继续膨胀——连锁更新，最坏 O(N²)。

listpack 的修法：每个 entry 只记录自己的总长度，且存在 entry 末尾，entry 之间互不引用——改任何一个 entry 都不会波及邻居，连锁更新从根上消失。Redis 7 起 Hash/List/ZSET 的小对象编码全部换成 listpack，配置项同步改名（hash-max-listpack-entries 等，旧的 *-ziplist-* 名仍兼容）。面试回答「ziplist 和 listpack 的区别」，核心就是这一句：ziplist 记前驱长度所以连锁更新，listpack 记自身长度所以免疫。

4.3 quicklist（快速列表）

Redis 3.2 后，List 的底层是 quicklist = 双向链表 + ziplist：

flowchart LR
    H["head"] --> A["ziplist A<br/>[a|b|c]<br/>count=3<br/>sz=..."] <--> B["ziplist B<br/>[d|e|f|g]<br/>count=4<br/>sz=..."] <--> C["..."]
    N["每个节点是一个 ziplist<br/>节点之间用 prev/next 指针连接"] -.-> A

quicklistNode 结构：

flowchart LR
    A["prev<br/>指针"] --- B["next<br/>指针"] --- C["zl<br/>ziplist"] --- D["sz<br/>字节数"] --- E["count<br/>元素个数"] --- F["encoding<br/>是否压缩"]

结合了双向链表「插入删除快」和 ziplist「省内存」的优点。
每个节点只存少量元素，避免单个 ziplist 太大导致 memmove 开销。
Redis 7 起节点从 ziplist 换成 listpack（动机见 §4.2），但 quicklist 的「链表 + 紧凑块」思想不变。

4.4 intset（整数集合）

Set 在元素全为整数且数量少时使用 intset，否则升级为 hashtable：

flowchart LR
    A["encoding<br/>编码类型<br/>2B/4B/8B"] --- B["length<br/>元素个数<br/>4B"] --- C["contents[]<br/>有序整数数组<br/>[1] [3] [5] [7] [9] ..."]

有序数组，支持二分查找 O(log N)。
所有元素用同一 encoding；加入更大范围整数时可能整体升级（如 int16 → int32），升级是 O(N)。
无重复元素（Set 语义）。

4.5 skiplist（跳表）

ZSET 同时维护 skiplist + dict：

skiplist：按 score 排序，支持范围查询 / 排名 O(log N)。
dict：按 member 查 score，O(1)。

普通有序链表只能顺序扫描，跳表加了多层「快速通道」：

flowchart LR
    subgraph L3["level 3"]
        A3["1"] --> B3["9"] --> C3["15"]
    end
    subgraph L2["level 2"]
        A2["1"] --> B2["5"] --> C2["9"] --> D2["13"] --> E2["15"]
    end
    subgraph L1["level 1"]
        A1["1"] --> B1["3"] --> C1["5"] --> D1["7"] --> E1["9"] --> F1["11"] --> G1["13"] --> H1["15"]
    end
    A3 --- A2 --- A1
    B3 --- C2 --- E1
    C3 --- E2 --- H1
    HEAD["头节点"] -.-> A1
    H1 -.-> TAIL["尾节点"]

跳表节点结构：

flowchart LR
    A["member<br/>成员字符串<br/>（sds）"] --- B["score<br/>分数<br/>（double）"] --- C["forward[] 数组<br/>[L1指针， L2指针， L3指针， ...]<br/>最高层数 = 随机 1~32"]

概率平衡：不用像红黑树那样做复杂旋转。
查找 score=11 时，先在高层大步跳跃，再逐层下降，平均 O(log N)。
配合 dict 实现 ZSCORE 的 O(1) 查询。

五、Redis 持久化：RDB 与 AOF

Redis 提供两种持久化方式，各有优劣。

5.1 RDB（Redis Database）

在指定时间间隔内将内存数据集快照写入磁盘。

save 900 1      # 900 秒内至少 1 次修改则触发
save 300 10     # 300 秒内至少 10 次修改则触发
save 60 10000   # 60 秒内至少 10000 次修改则触发

优点：

文件紧凑，适合备份和灾难恢复。
恢复速度快。

缺点：

两次快照之间数据可能丢失。
bgsave 通过 fork() 子进程生成，大数据集时可能阻塞主线程。

5.2 AOF（Append Only File）

将每次写操作命令追加到日志文件。

appendonly yes
appendfsync everysec  # 每秒刷盘一次（推荐）
# appendfsync always  # 每次写都刷盘，最安全但最慢
# appendfsync no      # 由操作系统决定，最快但不安全

优点：

数据安全性更高，默认最多丢失 1 秒数据。

缺点：

文件体积大。
恢复速度慢。
AOF 重写（rewrite）时会占用额外资源。

5.3 混合持久化（Redis 4.0+）

AOF 重写时先写入 RDB 全量数据，再追加增量 AOF，兼顾恢复速度和数据安全。

aof-use-rdb-preamble yes

graph LR
    A[持久化选择] --> B[RDB]
    A --> C[AOF]
    A --> D[混合持久化]
    B --> E[适合备份/快速恢复]
    C --> F[适合低丢失容忍]
    D --> G[生产推荐]

八股重点：Redis 的持久化是「灾难恢复手段」，不是「主存储方案」。

六、过期删除与内存淘汰

6.1 过期删除策略

Redis 对过期 Key 采用两种策略结合：

策略	说明	优点	缺点
惰性删除	访问 Key 时检查是否过期，过期则删除。	CPU 开销小	过期 Key 可能长期占用内存
定期删除	每隔一段时间随机抽查部分 Key 删除。	平衡内存与 CPU	仍可能有漏网之鱼

6.2 内存淘汰策略

当内存达到 maxmemory 时，根据 maxmemory-policy 决定如何淘汰：

策略	说明
`noeviction`	不淘汰，写操作直接报错。
`allkeys-lru`	所有 Key 中淘汰最近最少使用。
`volatile-lru`	只在设置了 TTL 的 Key 中淘汰最近最少使用。
`allkeys-random`	所有 Key 中随机淘汰。
`volatile-random`	只在设置了 TTL 的 Key 中随机淘汰。
`volatile-ttl`	淘汰即将过期的 Key。
`allkeys-lfu`	所有 Key 中淘汰使用频率最低的。
`volatile-lfu`	只在设置了 TTL 的 Key 中淘汰使用频率最低的。

生产建议：

必须设置 maxmemory。
缓存场景推荐 allkeys-lru 或 allkeys-lfu。
有冷热区分时可用 volatile-lru，但必须给 Key 设置 TTL。

七、Redis 高可用架构

7.1 主从复制（Replication）

一主多从，读流量分摊到从节点。

graph LR
    M[Master<br/>写 + 读] -->|全量/增量同步| S1[Slave 1<br/>读]
    M --> S2[Slave 2<br/>读]
    M --> S3[Slave 3<br/>读]

复制过程：

Slave 发送 PSYNC runId offset。
如果 runId 一致且 offset 在复制积压缓冲区中，则增量同步。
否则全量同步：Master 执行 bgsave 生成 RDB，发送给 Slave。

复制延迟问题：

主从异步复制必然存在延迟。
读从库时可能读到旧数据，需要业务容忍或强制走主库。

7.2 哨兵（Sentinel）

实现自动故障转移，解决主节点宕机问题。

graph TB
    subgraph Sentinel 集群
        Se1[Sentinel 1]
        Se2[Sentinel 2]
        Se3[Sentinel 3]
    end
    M[Master] --> S1[Slave 1]
    M --> S2[Slave 2]
    Se1 -->|监控| M
    Se2 -->|监控| M
    Se3 -->|监控| M
    Se1 -.-> Se2
    Se2 -.-> Se3

核心机制：

主观下线（SDOWN）：单个 Sentinel 认为 Master 不可用。
客观下线（ODOWN）：多数 Sentinel 达成一致。
Leader 选举：Sentinel 之间通过 Raft 算法选举出执行故障转移的 Leader。
故障转移：选一个 Slave 提升为 Master，通知其他 Slave 和客户端。

7.3 Cluster 集群

Redis Cluster 采用无中心架构，数据按槽位分布。

graph TB
    subgraph Redis Cluster
        N1[Node 1<br/>0-5460]
        N2[Node 2<br/>5461-10922]
        N3[Node 3<br/>10923-16383]
    end
    N1 <--> N2
    N2 <--> N3
    N1 <--> N3

关键概念：

集群共有 16384 个槽（slot）。
每个 Key 通过 CRC16(key) % 16384 计算所属槽。
每个 Master 负责一部分槽，可配置 Slave 做高可用。
客户端访问错误节点时，会收到 MOVED 或 ASK 重定向。

MOVED vs ASK：

MOVED：槽已经永久迁移到目标节点。
ASK：槽正在迁移中，先访问目标节点一次。

八、事务与 Lua 脚本

8.1 事务（MULTI/EXEC/DISCARD/WATCH）

MULTI
SET a 1
INCR b
EXEC

特点：

命令按顺序入队，EXEC 时一次性执行。
执行期间不会被其他客户端打断。
但没有回滚机制：如果某条命令语法错误，整个事务不执行；如果运行时错误（如 INCR 字符串），后续命令仍会执行。

8.2 Lua 脚本

EVAL "return redis.call('incr', KEYS[1])" 1 counter

特点：

整个脚本作为一个整体在单线程中原子执行。
适用于需要多个命令且要保证原子性的场景，如秒杀、分布式锁、限流。
集群模式下所有 Key 必须落在同一 slot，否则需要加 hash tag，如 {user}:1001:profile。

九、缓存经典问题

9.1 缓存穿透

问题：查询不存在的数据，缓存不命中，请求直接打到数据库。

解法：

缓存空值（设置短 TTL）。
使用布隆过滤器预先判断 Key 是否存在。

9.2 缓存击穿

问题：热点 Key 突然过期，大量请求同时打到数据库。

解法：

热点 Key 设置永不过期，异步更新。
加互斥锁（SETNX），只允许一个线程重建缓存。

9.3 缓存雪崩

问题：大量 Key 同时过期，或 Redis 宕机，数据库压力陡增。

解法：

给 TTL 加随机值，避免同时失效。
多级缓存（本地 + Redis）。
熔断降级。

9.4 缓存与数据库一致性

常见策略：

策略	说明	问题
Cache Aside	读：先读缓存，未命中读 DB 并写回缓存；写：先更新 DB，再删缓存。	短暂不一致
Read/Write Through	由缓存层统一维护 DB 和缓存。	实现复杂
Write Behind	先写缓存，异步写 DB。	可能丢数据

最常用的是 Cache Aside，配合「先更新数据库，再删除缓存」+ 延时双删 + 消息队列补偿，能在大多数场景下保证最终一致。

十、Redis 在 IPTV 系统中的角色

IPTV 系统的特点是：高并发读、强实时性、热点集中、写流量脉冲式。用户在换台、看 EPG、播放点播、抢购付费节目时，系统需要在毫秒级返回结果。

flowchart TB
    subgraph 用户层
        A[机顶盒 / 手机 / Web]
    end

    subgraph 接入层
        B[CDN / 边缘节点]
        C[API Gateway]
    end

    subgraph 应用层
        D[鉴权服务]
        E[EPG 服务]
        F[播放调度服务]
        G[订单 / 秒杀服务]
    end

    subgraph 数据层
        H[(MySQL / 长视频元信息)]
        I[(对象存储 OSS)]
        J[(Redis 缓存 + 实时计算)]
    end

    A --> B --> C
    C --> D & E & F & G
    D --> J
    E --> J
    F --> J
    G --> J
    E --> H
    F --> I
    G --> H
    J -.-> H

场景	Redis 数据结构	作用
用户会话 / Token	String + EXPIRE	毫秒级鉴权
EPG 节目单缓存	Hash / JSON String	减少数据库查询
热播榜单 / 推荐位	Sorted Set (ZSET)	实时排序
播放限速 / 防刷	Lua + INCR + EXPIRE	滑动窗口限流
秒杀 / 付费解锁	SETNX + DECR + Lua	库存扣减
消息通知 / 任务队列	List / Stream	异步解耦

十一、IPTV 项目 Demo

11.1 用户会话缓存

import redis
import uuid
import time

r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)

def login(user_id: str, device_id: str, ttl: int = 3600) -> str:
    token = str(uuid.uuid4())
    key = f"session:{token}"
    r.hset(key, mapping={
        "user_id": user_id,
        "device_id": device_id,
        "login_at": str(time.time())
    })
    r.expire(key, ttl)
    return token

def auth(token: str) -> dict | None:
    return r.hgetall(f"session:{token}")

11.2 EPG 节目单缓存

import json
from datetime import datetime

def cache_epg(channel_id: str, programs: list[dict]):
    key = f"epg:{channel_id}:{datetime.today().strftime('%Y%m%d')}"
    pipe = r.pipeline()
    for p in programs:
        pipe.hset(key, p['start_time'], json.dumps(p))
    pipe.expire(key, 86400 * 2)
    pipe.execute()

def get_program(channel_id: str, start_time: str) -> dict | None:
    data = r.hget(f"epg:{channel_id}:{datetime.today().strftime('%Y%m%d')}", start_time)
    return json.loads(data) if data else None

11.3 热播排行榜

def record_view(program_id: str, score: float = 1.0):
    r.zincrby("hot:tv:daily", score, program_id)

def top_n(n: int = 10) -> list[tuple[str, float]]:
    return r.zrevrange("hot:tv:daily", 0, n - 1, withscores=True)

11.4 滑动窗口限流

LIMIT_SCRIPT = """
local key = KEYS[1]
local window = tonumber(ARGV[1])
local limit = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local min = now - window

redis.call('zremrangebyscore', key, '-inf', min)
local count = redis.call('zcard', key)
if count < limit then
    redis.call('zadd', key, now, now)
    redis.call('expire', key, math.ceil(window / 1000))
    return 1
else
    return 0
end
"""

limiter = r.register_script(LIMIT_SCRIPT)

def allow(user_id: str, max_qps: int = 10, window_ms: int = 1000) -> bool:
    key = f"rate_limit:{user_id}"
    now = int(time.time() * 1000)
    return bool(limiter(keys=[key], args=[window_ms, max_qps, now]))

11.5 秒杀 / 限时解锁

SECKILL_SCRIPT = """
local key = KEYS[1]
local user_id = ARGV[1]
local stock = tonumber(redis.call('get', key) or '0')
if stock <= 0 then
    return -1
end
if redis.call('sismember', key .. ':users', user_id) == 1 then
    return 0
end
redis.call('decr', key)
redis.call('sadd', key .. ':users', user_id)
return 1
"""

seckill = r.register_script(SECKILL_SCRIPT)

def try_buy(activity_id: str, user_id: str, total_stock: int) -> int:
    key = f"seckill:{activity_id}:stock"
    r.setnx(key, total_stock)
    return int(seckill(keys=[key], args=[user_id]))

十二、为什么 Redis 不适合做长期存储？

12.1 持久化不是主存储

RDB 会丢数据，AOF 文件大且恢复慢。Redis 的持久化定位是「灾难恢复」，不是「可靠主存」。

12.2 内存成本过高

内存价格是 SSD 的 10-50 倍。IPTV 的媒资、播放记录、订单流水动辄几十 TB，全放 Redis 不现实。

12.3 单线程执行风险

大数据集下，一个 KEYS *、HGETALL 或慢查询可能阻塞整个实例。

12.4 缺乏复杂查询能力

Redis 不支持 SQL、JOIN、二级索引。长期业务数据需要分析统计时，应使用 MySQL / PostgreSQL / ClickHouse。

结论：

Redis 适合「热数据 + 临时状态 + 实时计算」，价值在于速度；长期存储应交给磁盘数据库 + 对象存储。

十三、Redis 容易踩坑的地方

坑	说明	解法
大 Key	String > 10MB，集合元素百万级	拆分、分片、UNLINK 异步删除
热 Key	单个 Key 被高频访问	本地缓存、Key 分片、Cluster
缓存穿透/击穿/雪崩	缓存失效导致 DB 被打挂	布隆过滤器、互斥锁、随机 TTL
未设置 maxmemory	内存打满后写操作报错	设置 maxmemory 和淘汰策略
误用 KEYS	`KEYS *` 扫描全库阻塞主线程	生产禁用，改用 SCAN
Lua 跨 slot	Cluster 下脚本 Key 不在同一 slot	使用 hash tag `{user}:1001:xxx`
事务没有回滚	EXEC 后某命令失败不会撤销前面命令	业务层保证幂等，或用 Lua
主从延迟	读从库可能读到旧数据	对一致性要求高的读走主库

十四、Redis 做消息队列的方法

14.1 List：轻量队列

flowchart LR
    P[Producer] -->|LPUSH queue:transcode task| R[(Redis List)]
    C[Consumer] -->|BRPOP queue:transcode 5| R
    C --> S[执行转码]

r.lpush("queue:transcode", json.dumps({"video_id": "v123"}))
_, task = r.brpop("queue:transcode", timeout=5)

优点：简单、阻塞读。缺点：无 ACK、无多消费者组、无消息回溯。

14.2 Pub/Sub：实时广播

r.publish("live:start", json.dumps({"channel_id": "cctv1"}))

优点：实时、多订阅者。缺点：不持久化，消费者断线期间消息丢失。

14.3 Stream：生产级队列

r.xadd("mq:events", {"event": "video:play", "user_id": "u10086"})

r.xgroup_create("mq:events", "group_log", id="0", mkstream=True)

messages = r.xreadgroup(
    groupname="group_log",
    consumername="worker_1",
    streams={"mq:events": ">"},
    count=10,
    block=5000
)
for stream, entries in messages:
    for msg_id, fields in entries:
        process(fields)
        r.xack("mq:events", "group_log", msg_id)

优点：支持消费者组、ACK、消息回溯。

方式	推荐场景
List	简单任务队列
Pub/Sub	实时广播
Stream	生产级消息队列

十五、总结

《Redis in Action》的核心思想可以概括为一句话：把 Redis 当成内存里的数据结构工具箱，而不是数据库。

Redis 适合：

缓存加速（会话、配置、热点数据）。
实时计算（排行榜、计数器、限流、秒杀）。
异步解耦（List / Pub/Sub / Stream）。

Redis 不适合：

长期持久化存储。
复杂查询与大数据分析。
超大数据集主存储。

避免踩坑的关键是：控制 Key 大小、设置合理 TTL、配置淘汰策略、慎用阻塞命令、理解持久化边界。Redis 用好了是神兵利器，用错了就是生产事故的导火索。

starmall：一个微信小程序电商系统的全栈实战——预约、支付与订单架构解析

Tue, 20 Jul 2021 10:00:00 +0800

starmall：一个微信小程序电商系统的全栈实战——预约、支付与订单架构解析

这是我 2021 年做的一套完整电商系统 starmall（六爻星辰）：微信小程序端 + Java 后端 + PC 管理后台，支持商品购买、老师咨询时段预约、择吉日查询、在线咨询等业务。整理开源出来，写篇文章做一次完整的技术复盘。

前端（uni-app 小程序）：https://gitee.com/soulnew/starmall
后端（Java + 管理端）：https://gitee.com/soulnew/crm_server
技术栈：Spring Boot 2.2 + MyBatis-Plus + MySQL + Redis / uni-app + uView / Vue 2 + Element UI（管理端）
说明：后端是在开源商城 CRMEB Java 版 基础上二次开发的，分销/秒杀/拼团/砍价等营销能力来自底座，预约系统、择吉日、名片、咨询聊天等是自研部分

一、整体架构

graph TD
    MP["微信小程序端<br/>starmall uni-app + uView"] -->|"https://ftmao.com/api/front/**"| API["SpringBoot 单体后端<br/>62 个 Mapper / 23 个前台 Controller"]
    H5["H5 / App<br/>uni-app 多端编译"] --> API
    ADMIN["PC 管理后台<br/>Vue 2 + Element UI + ECharts"] -->|"后台接口"| API
    API --> MYSQL["MySQL 5.7<br/>62 张表 Druid 连接池"]
    API --> REDIS["Redis<br/>token / 订单缓存 / 任务队列 / 配置缓存"]
    API --> WX["微信开放平台<br/>登录 / 支付 V2 / 订阅消息"]
    API --> QN["七牛云 OSS<br/>图片上传"]
    API --> QY["企业微信机器人<br/>部署结果通知"]
    MP -->|"wss://... websocket"| CHAT["咨询聊天服务"]

代码规模：后端约 850 个 Java 文件、12.6 万行；小程序前端业务代码约 1.2 万行；数据库初始化 SQL 全量在仓库里，共 62 张表。后端按业务分包：front（小程序接口）、order/payment、marketing、seckill、task（定时任务）、wechat，以及自研的 appoint（预约）、lunar（黄历）等模块。

二、功能介绍

2.1 商品购买全流程

标准的商城闭环：商品详情（多规格 SKU）→ 立即购买/加购物车 → 确认订单（优惠券、积分抵扣、运费计算）→ 创建订单 → 微信支付 → 轮询支付结果 → 收货评价 → 退款/售后。支付是真实对接的微信支付 V2——后端手工实现 XML 报文 + MD5 签名调统一下单（WeChatPayServiceImpl，746 行），前端弹起 wx.requestPayment，不是 mock。

此外还支持：余额支付、运费模板（满额包邮/指定城市包邮/按件数重量体积三种首续费）、物流查询、自提核销码、再次下单。营销玩法（秒杀、砍价、拼团、优惠券）来自 CRMEB 底座，一应俱全。

2.2 老师咨询时段预约（自研核心）

这是这个项目区别于普通商城的地方——卖的不只是实物商品，还有"老师的时间"：

商品分类为"老师类"时，商品详情页出现一个时段选择器（每天 6 个时段：9/11/13/15/17/19 点）；
teacher_plan 表按「日期 × 时段」预生成号源，被约走的时段前端置灰；
下单时携带 teacherPlanId，创建订单的同一个事务里把该时段标记为已约——号源占用和订单创建要么一起成功要么一起回滚，不会出现"钱付了时段没了"；
号源由定时任务 TeacherPlanTask 每 8 小时自动向前补齐未来 8 天，并清理过期的空闲号源。

2.3 其他自研功能

择吉日查询：4.7 万行黄历数据入库（lunar 系列表），按"宜"事反查吉日，比如查"最近适合搬家的日子"；
在线咨询：基于 WebSocket 长连接的实时聊天，支持文字/语音/图片消息（详见第三章「长连接聊天」）；
老师名片、文章资讯、签到积分、充值、小程序订阅消息提醒；
管理后台：商品/订单/营销/分销/财务/短信/按钮级权限/数据统计大屏（ECharts）。

三、后端能力全景

后端虽然是 SpringBoot 单体，但能力面相当完整：前台 23 个 Controller、62 个 MyBatis Mapper，按业务分包组织：

graph TD
    subgraph M1["业务模块"]
        A1["front 前台接口<br/>23 个 Controller"]
        A2["order / payment<br/>订单与支付"]
        A3["marketing / seckill / bargain / combination<br/>优惠券 秒杀 砍价 拼团"]
        A4["appoint / lunar / businessCard<br/>预约 择吉日 名片（自研）"]
        A5["finance / statistics / export<br/>充值提现 数据统计 Excel 导出"]
        A6["wechat / wechatMessage / sms<br/>微信生态与短信"]
        A7["task<br/>定时任务体系"]
    end
    subgraph M2["公共层"]
        B1["拦截器链<br/>前台 Token / 后台 Token+权限 / Swagger"]
        B2["工具层 RedisUtil / WxPayUtil / CrmebUtil"]
        B3["ThreadLocal 上下文传递当前用户"]
    end
    A1 --> B1
    A2 --> B2
    B1 --> B3

商城主链路之外，后端还有一批容易被忽略的能力：

微信公众号消息自动回复：wechatMessage 模块支持文字/语音/图片/图文四种回复类型，关注、取关、扫码等事件都有对应处理；
模板消息与订阅消息：小程序订阅消息、公众号模板消息的增删查与群发，且发送走异步任务（AsyncWeChatProgramTempMessage 等），不阻塞主流程；
渠道二维码与素材管理：带参数的推广二维码、微信素材的上传管理；
数据导出与统计：POI 实现的 Excel 导出、交易/商品/用户多维统计接口（配合管理端 ECharts 大屏）；
短信与物流：短信验证码/通知、快递物流轨迹查询；
接口文档：Swagger 在线文档 + 仓库内置 admin/app/公共三份离线接口文档。

3.1 长连接聊天（WebSocket）架构

在线咨询是这个系统的"第二前台"，采用的是 WebSocket 长连接 + HTTP 接口的组合方案。部署上两个服务跑在同一台服务器，由 nginx 按路径前缀分流：

graph TD
    MP["小程序聊天页<br/>pages/chat"] -->|"wss://.../websocket/userId/sessionId"| NGX["nginx 按路径分流"]
    MP -->|"HTTP /chat/session/**  /chat/msg/**"| NGX
    MP -->|"HTTP /api/front/**"| NGX
    NGX --> CHAT["聊天服务<br/>WebSocket 长连接 + 会话/消息接口"]
    NGX --> MALL["商城后端 crm_server<br/>SpringBoot 18080"]

从开源的小程序端实现和接口契约，可以看到这套长连接聊天的几个设计要点：

连接即身份：WebSocket 握手 URL 直接携带 userId/sessionId，连接建立的同时就完成了身份识别与会话路由，不需要额外的登录帧；
实时走长连接，持久化走 HTTP：收发消息走 WebSocket（消息体为 JSON）；会话绑定（session/bindSession）、会话列表、删除会话、历史消息拉取（msg/msgList）都走 /chat/ 前缀的 HTTP 接口——长连接管"实时推送"，HTTP 管"可查询、可回溯"，职责分得很干净；
统一的消息类型协议：contentType 1=文字、2=语音（带 contentDuration 时长）、3=图片（先经 user/upload/image 上传拿到 URL，再把 URL 作为消息内容发出）；
语音消息的移动端交互：按住说话（touchstart/touchend 控制录音起止）、上滑取消（touchmove/touchcancel），体验和微信原生聊天对齐；
发送体验乐观化：消息发出后先本地 push 进消息列表立即上屏，send 的 fail 回调再 toast 兜底提示。

需要如实说明：聊天服务端的代码没有随这两个仓库开源（它部署在同一台服务器上，由 nginx 分流），仓库里能看到的生产实现是小程序端；crm_server 里的 com/im/SocketServer.java 只是当时练手的原生 TCP Socket demo（12345 端口），并非线上实现。

四、技术亮点

4.1 下单幂等：两段式 + 唯一键兜底

小程序网络环境下用户双击、重试、断网重发是常态，下单接口必须幂等。这里用了一个两段式设计：

graph TD
    A["order/confirm 确认订单页"] --> B["订单数据序列化存 Redis<br/>key = md5 当前时间<br/>有效期 60 分钟"]
    B --> C["order/create/orderKey 创建订单"]
    C --> D{"第一步:查库判重<br/>StoreOrder.unique = orderKey"}
    D -->|"已存在"| E["直接返回已有订单<br/>不重复创建"]
    D -->|"不存在"| F{"第二步:校验 Redis 缓存<br/>是否过期/被用过"}
    F -->|"过期"| G["拒绝 提示重新确认"]
    F -->|"有效"| H["事务内创建订单<br/>成功后删除缓存"]

unique 字段是最后的兜底——即使 Redis 挂了、缓存丢了，数据库唯一约束也保证同一个 orderKey 不会建出两张单。

4.2 原子扣库存防超卖

库存扣减没有用"先查后改"，而是一条 SQL 完成：

// setSql + 条件改写，数据库层面原子完成
stock = stock - n   且要求   stock - n >= 0

数据库单行更新的原子性天然挡住并发超卖，不需要分布式锁。秒杀/砍价/拼团场景更复杂：同一事务内要扣活动表 + 活动 SKU 表 + 商品表 + 商品 SKU 表四份库存，任何一步失败整体回滚。

4.3 编程式事务包住整个建单过程

创建订单是个多写操作：扣库存、占预约时段、写订单主表、写订单详情、核销优惠券、写订单日志。代码用 TransactionTemplate 编程式事务（而不是 @Transactional 注解）把这一串操作包起来——好处是事务边界精确可控，不会把整个方法（包括不需要事务的远程调用）都圈进去。订单核心逻辑集中在 OrderUtils.java（1500+ 行）和 OrderServiceImpl.java（近 1000 行）。

4.4 支付回调：防重 + 异步化

微信支付的回调处理（CallbackServiceImpl.weChat，448 行）有几个关键点：

解析 XML、校验 return_code/result_code，按 attach 里携带的 userId + type 区分是订单支付还是充值；
已支付直接返回 SUCCESS——微信会多次重推回调，幂等是回调接口的生死线；
事务内完成 updatePaid（置订单已支付）+ 扣积分 + 拼团状态处理；
后续的"慢动作"——发短信、推订阅消息、分销结算——不放在回调里同步做，而是 lPush 进 Redis 队列异步执行，回调接口尽快给微信返回，避免超时重推。

4.5 没有 MQ：Redis List + 定时任务的务实替代

项目没有引入 RabbitMQ/RocketMQ，而是用 Redis List 当队列 + Spring @Scheduled 定时任务消费，撑起了一整套异步任务体系：

graph LR
    A["下单成功<br/>lPush ORDER_AUTO_CANCEL_KEY"] --> Q["Redis List 队列"]
    P["支付成功回调<br/>lPush 后续动作"] --> Q
    Q --> T1["OrderAutoCancelTask<br/>每分钟消费<br/>超时未支付自动取消 + 回滚库存"]
    Q --> T2["自动收货 / 自动好评"]
    Q --> T3["优惠券过期 / 砍价截止<br/>佣金解冻"]
    Q --> T4["TeacherPlanTask<br/>每8小时补齐号源"]

task/order/ 下共有 8 个定时任务。对这个体量的系统，省掉一个 MQ 的部署运维成本，换来的是完全够用的可靠性——这是小项目技术选型上我很认可的一个取舍。

4.6 鉴权链路：UUID Token + Redis + ThreadLocal

没有用 JWT，而是更传统的方案：登录后签发 UUID 存 Redis（按模块区分 key 前缀），拦截器 FrontTokenInterceptor → CheckFrontToken → TokenManagerImpl 逐级校验，通过后把当前用户放进 ThreadLocal 供全链路取用。管理端是 Token + 权限双拦截器。好处是服务端可随时踢人下线（删 Redis key 即可），这是纯 JWT 做不到的。

4.7 其他值得提的实现

订单快照：下单时把购物车内容序列化成 JSON 存进 StoreOrderInfo.info，之后商品改价改名都不影响历史订单的展示；
运费计算引擎：getOrderPriceGroup 支持满额包邮、指定城市包邮（件数 + 金额双条件）、按件数/重量/体积三种首续计费模式；
XSS 转义：用户输入统一 escapeHtml4；
部署脚本：start.sh nohup 启动 + 轮询日志判断启动成功 + 企业微信机器人推送部署结果——单机部署也搞出了仪式感。

五、复盘与遗憾

底座与自研的边界：秒杀/拼团/砍价/分销这些"重"能力直接复用 CRMEB 底座，把精力集中在业务差异化（预约、择吉日、聊天）上——对个人开发者来说这是正确的杠杆；
单体的局限：所有东西在一个 SpringBoot 应用里，定时任务、支付、前台接口互相影响，量大了必然要拆；
原子扣库存的返回值没检查：setSql 扣减失败（库存不足）时影响的行数为 0，但代码没有校验这个返回值，极端情况下会漏判超卖——这是现在回头看想补的一个洞；
聊天服务端未开源：如第三章所述，长连接聊天的服务端实现没有随仓库开源，小程序端和接口契约是完整的，算是开源的一点遗憾。

六、写在最后

这个项目让我完整走了一遍"真实收钱"的系统该有的样子：幂等、事务、防超卖、回调防重、异步补偿——每一个点背后都是电商系统趟过的坑。代码在 https://gitee.com/soulnew/starmall 和 https://gitee.com/soulnew/crm_server，建库 SQL、接口文档都在仓库里，希望能给做小程序商城的朋友一个可参照的完整样本。

Redis on 方糖猫Blog

Ruby on Rails 高级篇：接入 Redis、Elasticsearch、消息队列与大数据组件的工程实践

Ruby on Rails 高级篇：接入 Redis、Elasticsearch、消息队列与大数据组件的工程实践

第一篇 Redis：一个组件，四种角色

1.1 角色一：缓存（最常用）

1.2 角色二：Sidekiq 任务队列

1.3 角色三：Action Cable 实时推送

1.4 角色四：业务数据结构

1.5 追问：有没有 JetCache 那种「本地 + Redis」两级缓存？

第二篇 Elasticsearch：搜索是数据同步问题

2.1 Gem 选型

2.2 索引同步：三种策略的取舍

2.3 零停机重建索引

2.4 生产上死在哪

第三篇 消息队列：ActiveJob 不是 MQ

3.1 RabbitMQ：可靠投递优先

3.2 Kafka：吞吐与回放优先

3.3 消费侧的三个生死问题

第四篇 大数据组件：先想清楚 Rails 的角色

4.1 上游角色：把数据交出去

4.2 下游角色：把结果拿回来

4.3 反模式警告

第五篇 通用纪律：接入任何组件前的检查清单

5.1 超时：永远不依赖默认值

5.2 重试：只对幂等操作，且带退避

5.3 熔断：下游持续失败就快速失败

5.4 幂等：写操作带唯一键

5.5 连接池与背压

5.6 可观测性：每次外部调用都埋点

5.7 生态边界：不是所有中间件都有 Ruby 版

5.8 对象存储：文件别过应用服务器

收尾：集成的本质是边界管理

我开发的keCache：面向 Spring Boot 3 的 L1 + L2 两级缓存框架

一、keCache 是什么

1.1 整体架构

二、开源地址

三、为什么需要 keCache？与纯 Redis / 纯 Caffeine 的对比

3.1 相比纯 Caffeine 的好处

3.2 相比纯 Redis 的好处

3.3 方案选型速查

3.4 一句话总结

四、核心能力速览

4.1 读取流程

4.2 写入与集群失效广播流程

五、快速开始

5.1 引入 Starter

5.2 启用缓存

5.3 基础配置

5.4 声明式使用示例

5.5 编程式使用

六、模块结构

七、关键约定（写代码前必读）

八、使用注意点与避坑指南

8.1 Redis 是硬性依赖

8.2 集群一致性是“最终一致”，不是实时一致

8.3 空值保护是把双刃剑

8.4 序列化类型变更要兼容

8.5 注意 Key 的命名空间隔离

8.6 @LocalCacheable.Multi 的 result 引用要判空

8.7 AOP 自调用不会生效

8.8 谨慎使用 @LocalCacheClear

8.9 校准任务不是开箱即用的

8.10 当前 Redis 部署模式限制

8.11 关注 Caffeine 内存与统计

九、许可证

十、总结

我开发的KE Reliable Executor：基于 Redis/MySQL 的 Spring Boot 可靠任务执行框架

我开发的KE Reliable Executor：基于 Redis/MySQL 的 Spring Boot 可靠任务执行框架

一、为什么需要这个工具？

适合什么场景？

不适合什么场景？

二、与竞品的对比

2.1 与 Kafka / RocketMQ 对比

2.2 与 Spring @Scheduled + 数据库轮询对比

2.3 与 XXL-JOB / PowerJob 对比

三、整体架构

3.1 模块解构图

3.2 两层锁模型

3.3 队列设计

3.4 任务状态机

第三篇消息队列：ActiveJob 不是 MQ

第四篇大数据组件：先想清楚 Rails 的角色

第五篇通用纪律：接入任何组件前的检查清单

8.6 `@LocalCacheable.Multi` 的 `result` 引用要判空

8.8 谨慎使用 `@LocalCacheClear`

2.2 与 Spring `@Scheduled` + 数据库轮询对比