Spring Boot on 方糖猫Blog

Spring Boot + Python 双栈架构：AI 服务的工程化实践

Mon, 20 Apr 2026 14:00:00 +0800

Spring Boot + Python 双栈架构：AI 服务的工程化实践

我开发的方糖猫 AI 视频平台不是一个纯 Python 项目，也不是一个纯 Java 项目。它同时使用了 Spring Boot 3 和 Python 3.11：Java 负责业务系统和 API 服务，Python 负责 AI 推理、渲染和多媒体处理。这篇文章会分享我们为什么要这样做，以及如何解决两个技术栈之间的协作问题。

一、为什么必须双栈？

做一个 AI 视频生成平台，需要两类能力：

能力类型	典型需求	更适合的栈
企业级业务系统	用户、订单、权限、支付、任务管理	Java / Spring Boot
AI 推理与多媒体	LLM 调用、Whisper、RAG、Remotion、FFmpeg	Python

Java 的优势在于生态成熟、工程规范、团队熟悉；Python 的优势在于 AI 库丰富、模型推理和多媒体处理工具链完善。

如果全用 Java，AI 库支持差，很多模型没有 Java SDK；如果全用 Python，业务系统的稳定性、事务处理、监控运维又很难做好。

所以我们的选择是：Java 做业务底盘，Python 做 AI 引擎，两者通过清晰的接口协作。

二、整体架构

flowchart TD
    FE["前端 (Vue 3)"]
    GW["API 网关 / BFF (Spring Boot)<br/>用户认证、请求路由、限流、任务状态查询、SSE 推送"]
    BIZ["业务服务<br/>(Spring Boot)"]
    SCHED["任务调度服务<br/>(Spring Boot)"]
    RES["资源管理服务<br/>(Spring Boot)"]
    AI["AI Worker (Python)<br/>ReAct Agent、RAG 检索、Whisper、TTS、Remotion、FFmpeg"]
    STORE["存储层：MySQL / Redis / OSS / ChromaDB"]

    FE --> GW
    GW --> BIZ
    GW --> SCHED
    GW --> RES
    SCHED -- "RocketMQ / Kafka" --> AI
    AI --> STORE

三、职责划分

3.1 Java 侧职责

API 网关：统一入口、鉴权、限流、日志
用户与任务管理：用户注册登录、任务创建、任务状态机、历史记录
素材元数据管理：素材上传、分类、标签、权限
支付与计费（如有）：订单、套餐、用量统计
任务调度：把渲染/生成任务发送到消息队列
实时通知：SSE 推送任务进度给用户

3.2 Python 侧职责

AI Agent 编排：ReAct 任务规划、Tool 调用
RAG 检索：Embedding 计算、向量库查询
语音识别：Whisper 转写
语音合成：TTS 配音
视频渲染：Remotion 组件化渲染
后处理：FFmpeg 转码、压缩、字幕、多分辨率输出

3.3 边界原则

我们定了几条原则来避免职责混乱：

Python 不直接暴露给用户。所有用户请求都走 Java API。
Python 只做无状态计算。任务状态、用户信息、素材元数据都在 Java 侧维护。
通信以异步为主。AI 任务通常耗时较长，同步调用容易导致超时和耦合。
数据以 ID 为纽带。Java 和 Python 之间不传大对象，只传任务 ID 和必要参数。

四、服务间通信

4.1 异步通信：RocketMQ

AI 生成和渲染任务都走 RocketMQ：

// Java 侧发送任务
SendResult result = rocketMQTemplate.syncSend(
    "video-render",
    MessageBuilder.withPayload(taskMessage).build()
);

# Python 侧消费任务
class RenderConsumer:
    def on_message(self, msg):
        task = json.loads(msg.body)
        result = render_engine.process(task)
        self.update_task_status(task["task_id"], "completed", result)
        return ConsumeStatus.CONSUME_SUCCESS

异步通信的优点：

解耦 Java 和 Python 服务
Python Worker 可以独立扩缩容
任务失败可以重试，不阻塞主流程

4.2 同步通信：HTTP / gRPC

少数场景需要同步调用，比如：

查询 RAG 素材（用户在前端点击「生成」前希望看到素材推荐）
获取任务实时状态
健康检查

我们主要用 HTTP REST，因为：

简单直观，Java 和 Python 生态都完善
调试方便，curl 即可测试
对延迟要求不极端

gRPC 我们也考虑过，但因为团队对 gRPC 熟悉度不高，且收益不明显，暂时没引入。

4.3 数据一致性

双栈架构下，任务状态是核心数据。我们用数据库作为唯一真相源：

flowchart TD
    A["用户提交任务"] --> B["Java 写入任务记录（status=pending）"]
    B --> C["发送 RocketMQ 消息"]
    C --> D["Python Worker 消费"]
    D --> E["Python 更新任务状态（status=processing/completed/failed）"]

Python Worker 更新数据库时，通过乐观锁防止并发冲突：

UPDATE render_task
SET status = 'processing',
    worker_id = 'worker-01',
    updated_at = NOW()
WHERE task_id = 'xxx'
  AND status = 'pending'

五、数据库设计

5.1 按服务分库还是分表？

我们没有完全按微服务分库，而是按业务域分表：

user：用户信息
task：生成任务
material：素材元数据
template：视频模板
subscription：订阅/套餐

所有表都在一个 MySQL 实例里，通过业务 ID 关联。这种方案在业务量不大时性价比最高，未来可按域拆分。

5.2 Python 侧如何访问数据库

Python 侧需要读取/更新任务状态，我们用的是 SQLAlchemy + 只读/写分离：

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine("mysql+pymysql://user:pass@host/db")
Session = sessionmaker(bind=engine)

def update_task_status(task_id: str, status: str):
    with Session() as session:
        session.execute(
            "UPDATE render_task SET status = %s WHERE task_id = %s",
            (status, task_id)
        )
        session.commit()

为了降低耦合，Python 侧只更新少量任务状态字段，不碰业务核心表。

六、部署与运维

6.1 容器化

两个栈都用 Docker 打包：

# Java 服务 Dockerfile
FROM eclipse-temurin:17-jdk
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

# Python Worker Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "worker.py"]

6.2 CI/CD

我们用一个简单的 GitHub Actions / Jenkins 流程：

代码提交触发构建
分别构建 Java 镜像和 Python 镜像
推送到镜像仓库
生产环境滚动更新

6.3 日志与链路追踪

双栈环境下，排查问题最大的难点是链路跨语言。我们的做法：

所有请求携带 trace_id
Java 和 Python 都把 trace_id 打到日志里
用 ELK / Loki 做日志聚合，按 trace_id 查询全链路

import logging

logger = logging.getLogger(__name__)

logger.info("Start render", extra={"trace_id": trace_id, "task_id": task_id})

6.4 监控告警

层级	监控项
Java 服务	JVM 内存、GC、接口响应时间、错误率
Python Worker	CPU/GPU 利用率、任务处理速率、队列堆积
数据库	连接数、慢查询
消息队列	堆积量、消费速率

七、踩过的坑

7.1 序列化不一致

Java 侧用 Jackson，Python 侧用默认 json，时间格式、枚举值、空值处理不一致，导致接口对接时经常报错。

解决：

统一用 ISO 8601 时间格式
枚举值用字符串传递
制定统一的 JSON Schema，用 Pydantic 和 Java Bean Validation 双向校验

7.2 Python 服务内存泄漏

Python Worker 长时间运行后，内存占用越来越高，尤其是加载大模型后。

解决：

Worker 处理一定数量任务后自动重启
模型用单例模式加载，避免重复初始化
显式清理大对象，调用 gc.collect()

7.3 跨语言异常处理

Python 异常信息传到 Java 侧变成一团乱码，前端无法友好展示。

解决：

定义统一的错误码体系
Python 捕获异常后按规范封装错误响应
Java 侧根据错误码映射为用户友好的提示

7.4 开发环境复杂度

开发时需要同时启动 Java 服务、Python Worker、MySQL、Redis、RocketMQ，新成员上手成本高。

解决：

提供 docker-compose.yml 一键启动基础设施
编写本地开发文档
支持 Windows 开发环境降级（Python Worker 用 HTTP 模拟 RocketMQ）

八、双栈架构的收益与代价

8.1 收益

方面	说明
团队分工清晰	Java 工程师做业务，Python 工程师做 AI
技术选型合理	每个栈都用最合适的工具
稳定性高	业务系统独立演进，AI 故障不直接影响用户注册/支付
扩展灵活	Python Worker 可以根据渲染负载单独扩容

8.2 代价

方面	说明
运维复杂	两套构建、部署、监控体系
链路排查难	跨语言日志追踪需要额外设计
接口契约维护	Java 和 Python 之间需要稳定的 API 契约

九、什么情况下不要双栈？

虽然双栈适合我们，但不是所有项目都需要：

纯业务系统：全 Java 即可
纯模型研究/实验：全 Python 即可
团队规模小：双栈会增加认知负担
MVP 早期：先用最熟悉的栈跑通，后期再拆分

我们是在产品验证基本跑通、团队有 5 人以上时才明确拆成双栈。

十、总结

Spring Boot + Python 双栈不是最优架构，而是适合我们团队能力和业务形态的架构。几个关键经验：

职责边界要清晰，否则双栈会变成双倍的混乱。
异步通信是主力，同步只用于低延迟查询场景。
数据库是状态的唯一真相源，避免两端各自维护状态。
日志追踪要跨语言打通，否则线上出问题很难排查。
不要为双栈而双栈，MVP 阶段先用单栈验证。

如果你也在做 Java + Python 的混合架构，欢迎交流接口契约、部署和监控的经验。

我开发的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 幂等，这才是工程上的稳妥做法。

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、接口文档都在仓库里，希望能给做小程序商城的朋友一个可参照的完整样本。

教你打麻将

Wed, 24 Jun 2020 14:00:00 +0800

教你打麻将

文章面向从未接触过联网游戏开发的读者，所以前半部分会把"联网棋牌游戏到底是怎么跑起来的"讲清楚，中间穿插真实代码层面的例子；后半部分专门开一章讲四川麻将的新手实战策略——毕竟做麻将游戏的人，自己先得会打麻将。

服务端：Java + Spring Boot + Netty（netty-socketio）+ Hazelcast + MySQL
客户端：Cocos Creator / JavaScript

一、先搞明白：联网棋牌游戏到底是怎么回事

1.1 单机游戏和联网游戏的本质区别

单机游戏里，所有逻辑都在你自己的设备上运行，规则由你的设备说了算。联网游戏不行——四个人打麻将，谁摸了什么牌、谁点了炮，必须有一个"裁判"说了算，否则每个人的手机都各算各的，立刻就乱套了。

这个"裁判"就是服务器。联网棋牌游戏的基本模型是：

graph TB
    subgraph 玩家设备
        C1[玩家A的手机<br/>Cocos Creator 客户端]
        C2[玩家B的手机]
        C3[玩家C的手机]
        C4[玩家D的手机]
    end
    S[游戏服务器<br/>贝密：Spring Boot + Netty]
    DB[(MySQL<br/>账号/战绩/房卡)]
    CACHE[(内存缓存 Hazelcast<br/>房间/牌局实时状态)]

    C1 <-->|WebSocket 长连接| S
    C2 <--> S
    C3 <--> S
    C4 <--> S
    S --> CACHE
    S -.异步落盘.-> DB

几个关键点：

牌在服务器手里。洗牌、发牌都在服务器上做，客户端只负责"显示"和"发指令"。你在手机上点"打出三万"，本质是给服务器发了一条消息：doplaycards: "12"，服务器校验"现在确实轮到你、你手里确实有三万"之后，才广播给全桌人。
每个人看到的信息不同。服务器把同一局牌的状态，按"你能看到什么"过滤后分别发给四个人——你只能看到自己的手牌和别人打出来的牌。这叫信息不对称，也是棋牌游戏和射击游戏最大的不同：状态同步必须分人定制。
防作弊的第一道防线就是"服务器权威"。客户端想赖牌（打出一张自己没有的牌），服务器直接拒绝。

1.2 为什么用 WebSocket 而不是 HTTP

没接触过联网游戏的人容易问：发消息不就是调接口吗，用 HTTP 不行吗？

不行，因为 HTTP 是"问一句答一句"，服务器没法主动找你。而棋牌游戏里大量事件是服务器主动推的：轮到你出牌了、有人碰了你的牌、房间人齐了……这些都需要服务器随时推消息给客户端。WebSocket 是一条建立后一直保持的双向通道，双方随时可以说话，延迟低、开销小。贝密用的 netty-socketio 就是在 Netty 上实现了 Socket.IO 协议（跑在 WebSocket 上），客户端 Cocos Creator 里直接用 socket.io 的 JS 库连。

1.3 房卡模式：一张"虚拟门票"

贝密 0.8.0 主打房卡模式，这也是 2016-2018 年棋牌游戏爆发的典型商业模式：

你在商城购买"房卡"（虚拟道具，存在 MySQL 里）；
你想和朋友打牌，就"开房"——消耗房卡，服务器生成一个 6 位数字房号（贝密里由 GameEngine.creatGameRoom 生成）；
朋友在大厅输入房号进房（客户端发 searchroom 事件），人齐开局；
打完约定的局数，服务器出结算单，房间销毁。

和陌生人随机撮合的"大厅模式"相比，房卡模式本质上卖的是"熟人社交的场地"，技术上则多了一个"按房号精确找房"的入口。

二、贝密的整体架构拆解

2.1 架构总览

graph LR
    subgraph 客户端
        A[Cocos Creator<br/>dizhu / majiang 模块]
    end
    subgraph 服务端 com.beimi
        B[GameEventHandler<br/>Socket 事件入口]
        C[GameEngine<br/>游戏总调度]
        D[自研状态机<br/>BeiMiStateMachine]
        E[Board 牌局内存模型<br/>MaJiangBoard / DuZhuBoard]
        F[Action/Task<br/>出牌·结算·计时任务]
    end
    subgraph 存储层
        G[(Hazelcast<br/>房间/牌局/玩家/撮合队列)]
        H[(cache2k<br/>过期回调当计时器)]
        I[Disruptor RingBuffer<br/>异步事件]
        J[(MySQL JPA)]
        K[(Elasticsearch)]
    end

    A <-->|WebSocket /game namespace| B
    B --> C --> D --> E
    D --> F
    E --> G
    F --> H
    C --> I
    I --> J
    I --> K

各层职责一句话概括：

GameEventHandler：所有 @OnEvent 端点都在这里，负责把客户端消息翻译成人话（比如把 "12,13" 解析成字节数组），然后交给 GameEngine；
GameEngine：总调度，加房、开局、出牌、杠碰胡、离房、解散房间都从这儿过；
自研状态机：驱动"房间"这个对象的生命周期（后面细讲）；
Board 内存模型：一局牌的完整状态（四家的手牌、桌面牌、轮到谁、倍率），只活在 Hazelcast 内存缓存里；
存储分层：实时状态全在 Hazelcast，MySQL 只存账号/战绩/房卡流水，而且是通过 Disruptor 异步写入——牌局进行中的一秒钟都不等数据库。

2.2 一次出牌的完整旅程（以麻将为例）

这是最核心的一条链路，用实际代码里的事件名走一遍：

sequenceDiagram
    participant P1 as 玩家A客户端
    participant H as GameEventHandler
    participant E as GameEngine
    participant B as MaJiangBoard
    participant T as 计时器(cache2k)
    participant P2 as 其他玩家客户端

    P1->>H: emit("doplaycards", "12")
    H->>E: takeCardsRequest(token, card)
    E->>B: 出牌校验 + 从手牌移除
    E->>T: remove(roomid) 取消A的出牌倒计时
    E-->>P2: 广播 "command": takecards
    E->>E: checkMJCard 遍历其他家<br/>查 杠/碰/吃/胡
    alt 有人能杠碰胡
        E->>T: 挂5秒等待任务(DEAL事件)
        P2->>H: emit("selectaction", "peng")
        H->>E: actionEventRequest 执行碰
    else 无人响应
        E->>B: dealRequest 下家抓牌
        E-->>P2: 广播 "command": dealcard
        E->>T: 挂8秒出牌任务<br/>(超时自动打)
    end

举例说明：假设你打出一张"五筒"，服务器干的事依次是——

校验：轮到你、你有五筒、这张牌合法；
把你 8 秒的出牌倒计时从计时器缓存里删掉（你不主动出，超时会由 CreateMJPlayCardsTask 强制替你出）；
广播给全桌：“A 打了五筒”；
挨个问另外三家：你能碰吗？能杠吗？能胡吗？（定缺了筒子的那家直接跳过——这就是四川麻将的规则在代码里的体现，GameUtils.processMJCard 里定缺花色不参与判断）；
如果 B 能碰，给 B 弹"碰/过"按钮，牌局挂起 5 秒等他决定；B 点了"碰"，就执行碰、轮到 B 出牌；
如果三家都"过"，下家自动摸一张牌，服务器先替他检查一次"摸上来的牌能不能暗杠/自摸"，然后通知他出牌，重新挂上 8 秒倒计时。

整个过程中，客户端只做两件事：把服务器的消息渲染成动画，把玩家的点击发给服务器。

2.3 房间的状态机流转

房间是有生命的：创建、等人、人齐、开局、结算、销毁。贝密没有用 Spring StateMachine，而是自研了一个极简状态机（core/statemachine 包），每种游戏一个 Bean：

stateDiagram-v2
    [*] --> NONE
    NONE --> CRERATED: ENTER 创建房间
    CRERATED --> WAITTING: JOIN 玩家陆续进房
    WAITTING --> READY: ENOUGH 人齐
    WAITTING --> WAITTING: AUTO 超时补AI机器人
    READY --> BEGIN: RAISEHANDS 全员准备
    BEGIN --> LASTHANDS: 发牌完成
    LASTHANDS --> PLAY: 庄家打出首张
    PLAY --> PLAY: DEAL/PLAYCARDS<br/>摸牌出牌循环
    PLAY --> END: ALLCARDS 有人胡牌/牌摸完
    END --> [*]: 结算发战报

状态机里每个"事件"对应一串 Action（比如麻将的链路是 EnterAction → JoinAction → EnoughAction → SelectAction(定缺) → MJRaiseHandsAction → DealMJCardAction → PlayMJCardsAction → AllCardsAction），业务代码只需要一句 game.change(room, event, intervalSeconds)，状态机负责找到对应 Action 执行，并由 Action 顺手创建下一个延时任务，形成闭环。

三、断线重连：联网游戏逃不掉的工程问题

新手最容易低估的就是这块。手机上打牌，来个电话、进个电梯，连接说断就断。贝密的处理方式是"托管 + 快照恢复"：

flowchart TD
    A[玩家网络断开] --> B{服务器收到<br/>OnDisconnect}
    B -->|玩家正在对局中| C[标记 OFFLINE<br/>进入托管状态]
    C --> D[计时器超时后<br/>auto=true 自动出牌]
    D --> E{玩家重连?}
    E -->|emit recovery| F[GameEngine 查缓存<br/>发现该房间有进行中的 Board]
    F --> G[下发 RecoveryData 全量快照:<br/>自己的手牌/桌面牌/轮到谁/剩余倒计时25s]
    G --> H[客户端按快照重建牌桌画面]
    E -->|一直没回来| I[AI托管打到本局结束]

举例：你出牌出了半局断网了，服务器不会暂停牌局等你（其他三个人不答应），而是把你标记为 OFFLINE，由超时任务替你"摸什么打什么"。30 秒后你连回来了，客户端发 recovery，服务器把当前牌局的完整快照发给你，你的手机根据快照把桌面重新画出来，无缝接上。注意重连期间你是被托管的——所以掉线久了回来，往往牌已经很难看了，这是规则的一部分。

四、四川麻将新手致胜策略：一个结构化的决策框架

做了这么久的麻将游戏，经常被问"新手怎么提高胜率"。零散的口诀（“记牌"“防点炮”）新手记不住也用不上，所以这一章我把四川麻将的策略整理成一个结构化框架：先确立唯一的目标函数，再按"战略层 → 信息层 → 战术层 → 概率层"四个层级组织所有决策，最后给出血战到底的特有推论和新手错误清单。逻辑主线只有一句话：

麻将的每一步都是在信息不完备下做期望收益最大化的决策。四个层级分别回答：往哪走（战略）、知道什么（信息）、这巡打哪张（战术）、什么时候切换路线（概率）。

4.0 规则即策略：先立规则，再推结论

定缺：开局后每人必须选一门花色（万/筒/条）作为"缺门”，胡牌时手里不能有这门牌，摸到缺门的牌必须打掉。牌墙只有 108 张（三门花色，无风牌）。
血战到底：一家胡牌不结束牌局，剩下的人继续打，直到牌摸完或只剩一家没胡。点炮只有点炮者付分，最后没胡的人还要给已听牌的人"查叫"赔分。

从这两条规则可以直接推出三条战略推论，整章都是它们的展开：

信息压缩：定缺把每家的"有效牌域"从三门砍到两门，而且是公开信息。读牌成本比别的麻将低一个量级——新手也能读。
时间价值：牌局不因一人胡牌而结束，每张牌的价值随牌墙减少而衰减。“还剩几巡"是所有决策的隐含变量。
止损优先：点炮只由点炮者一人付分、没胡要赔查叫——落后的代价是确定的，追上的收益是概率性的。这决定了"不跟随到最后"在数学上往往是对的。

三条推论的推导关系：

flowchart LR
    R1[规则一: 定缺<br/>缺门公开] --> C1[推论一: 信息压缩<br/>读牌成本低]
    R2[规则二: 血战到底<br/>胡牌不终局] --> C2[推论二: 时间价值<br/>剩几巡是隐含变量]
    R2 --> C3[推论三: 止损优先<br/>点炮独赔+查叫保底]
    C1 --> S[决定 4.2 信息层怎么读]
    C2 --> S2[决定 4.4 何时切换路线]
    C3 --> S3[决定 4.5 防守与保底策略]

4.1 战略层：起手评估与路线选择

拿到起手牌、定缺之前，先给牌打分。不需要精确，三个数就够：

向听数：还差几张牌能听牌。数一下你手里有几个成型搭子/刻子/对子，13 张牌需要 4 副 + 1 将，差几副就是几向听。新手只要会区分"两向听以内（好牌）“和"三向听以上（差牌）"。
对子数：4 对以上 → 七对/大对子路线候选；0~1 对 → 别惦记对子路线。
同花色集中度：9 张以上同花色 → 清一色路线候选。

定缺选择是第一个战略决策，原则按优先级排：

缺张数最少的那门——缺门每张都是必打的废牌，张数越少浪费的巡数越少；
张数相近时，缺结构最差的那门（孤张多、没搭子的）；
还在纠结时，缺端张多的那门（1、9 多），因为端张成搭能力弱。

举例：起手万子 2 张（三万、八万，无关联）、筒子 5 张（两个搭子）、条子 6 张（一个刻子一个边搭）。毫无疑问题缺万——但如果万子是 2 张而筒子是 3 张但全是散牌，就该缺筒子：定缺看的是"废牌数量”，不是"张数”。

定缺公布后立即做第二步战略判断：看三家的缺门，决定做大还是快跑。

三家中有两家缺你这门 → 你要做的花色没人抢，牌墙里全剩给你，做大的绿灯；
三家都不缺你这门 → 四个人抢一门牌，你的关键张会被飞速消耗，果断转快跑。

至此，三条路线已经清晰：

路线	触发条件	目标	核心动作
快跑	牌型一般、向听小、花色被抢	最速听牌、先胡锁定收益	牌效优先，不留废搭
做大	起手 9 张+同花色/4 对+，且无竞争	清一色/大对子/七对	忍受慢听牌，屯关键张
防守	有人已听牌且自己手牌差	不点炮、保查叫底线	只打熟张，听牌优先于胡牌

把起手到定路线的全过程画成一张图：

flowchart TD
    A[拿到13张起手牌] --> B[三个数打分:<br/>向听数 / 对子数 / 同花色集中度]
    B --> C{定缺: 缺哪门?}
    C -->|第一优先| C1[缺张数最少的门]
    C -->|张数相近| C2[缺结构最差的门<br/>孤张多没搭子]
    C -->|还纠结| C3[缺端张多的门<br/>1和9成搭弱]
    C1 & C2 & C3 --> D[公布定缺<br/>观察三家缺门]
    D --> E{有人抢我要做的花色?}
    E -->|两家以上缺我这门<br/>绿灯| F{起手支持做大?<br/>9张+同花色 或 4对+}
    F -->|是| G[做大路线<br/>清一色/大对子/七对]
    F -->|否| H[快跑路线<br/>最速听牌]
    E -->|三家都抢我这门| H
    E -->|牌型差 三向听以上| I[保守推进<br/>随时准备转防守]
    style G fill:#ffe6cc
    style H fill:#d4edda
    style I fill:#f8d7da

路线不是选定就不变——每一巡都可以用新信息重估，4.4 会给出切换的量化标准。

4.2 信息层：记牌与读牌

信息层回答"我知道什么"。它分两半：记牌是对已发生事实的压缩存储，读牌是从事实反推未知信息。

4.2.1 记牌：分层记忆法

让新手背下三家打过的每张牌不现实。按重要性只记三类：

第一层：记"张数"不记"顺序"。 每门花色每张牌只有 4 张。你不需要记住"上家第 3 巡打了七万"，只需在脑子里维护计数：“七万已见 3 张”。重点盯的是你自己将牌和搭子两端的关键牌——你手里 6、8 万等卡 7 万，“7 万见了几张"直接决定这个搭子的死活：见 3 张以上，搭子基本死了，趁早拆。

第二层：记"缺门"和"花色倾向”。 定缺后，对手打出的非缺门花色才是有效信息。下家缺条，从第 2 巡起一直打筒子、摸到万子全留——一句话记住"下家只留万"即可，不用记他打的每一张。

第三层：记"序盘的反常中张"。 序盘（前 4~5 巡）正常人先打孤张边张（1、9）。有人序盘就打 4、5、6 中张，说明这门要么极好（搭子齐了中张多余）要么整门不要，结合缺门大概率能分辨。

口诀：数自己的关键张，记别人的花色倾向，盯序盘的反常中张。

三层记忆的工作量递减、收益递增，像一座金字塔——新手从塔底练起：

flowchart BT
    L1[第三层: 序盘反常中张<br/>一两个反常信号即可<br/>精力占比 ~10%] --> L2[第二层: 缺门与花色倾向<br/>每家一句话: 他只留X<br/>精力占比 ~30%]
    L2 --> L3[第一层: 关键张计数<br/>自己搭子两端的牌各见几张<br/>精力占比 ~60%]
    L3 --> R[收益: 搭子死活判断<br/>直接决定拆不拆]
    L2 --> R2[收益: 知道谁在收哪门<br/>直接决定防什么]
    L1 --> R3[收益: 序盘读出牌型方向]

4.2.2 读牌：他要什么、不要什么、打什么危险

读牌的本质是用别人的"打出"反推他的"留下"——人留下什么牌，才会打出什么牌。按牌局阶段读不同的东西：

序盘读"结构"：缺门 + 反常中张 + 第一碰，拼出每家的大致牌型方向。

中盘读"进度"：看连续动作。上家碰了"二筒"后摸打筒子以外的牌，说明他筒子上还有货；碰完后打的那张牌的邻张往往是他不需要的（碰二筒后打五万，他大概率没有 3-4 万、4-6 万的搭子）；碰了二筒后打的还是筒子，几乎可断定他在做筒子清一色或已听牌。

尾盘读"节奏"：一个人连续摸牌就打（摸打），说明手牌已成型，打出的就是刚摸的；反过来想了很久才打出一张，说明这张是从手里"拆"出来的，他在这张牌附近有搭子变动，其邻张不再安全。

由此得到防点炮 checklist，中后盘（牌墙剩 1/3 以内）每打一张前过一遍：

这张牌见过几张？ 见 2~3 张的熟张相对安全；一张没见的生张风险最高。
有没有人明显在收这门？ 对家在做万子，你手里的生张五万就是高危，宁可拆搭子打熟张。
他是不是单钓/卡张？ 碰了三副、手牌只剩一两张的人，听的牌范围很窄，往往就在他碰的那几副的邻张上——那一片中张全是雷区。

完整例子：对家定缺条子，碰了"三筒"，摸打两巡后思考良久切出"八万"。推断：他在做筒子（碰三筒+留筒），八万是万子里的多余搭子；你手里五、六、七万从此相对安全（他不要万子），但任何生张筒子都是高危，尤其一、二、四筒（三筒邻张）。

读牌的推理链条固定是"观察 → 反推 → 行动"三段，常见信号对照如下：

flowchart LR
    subgraph 观察[他打出/做了什么]
        O1[缺门公布后<br/>一直打筒留万]
        O2[碰二筒后<br/>又打出筒子]
        O3[碰二筒后<br/>打出五万]
        O4[连续摸打]
        O5[长考后拆出八万]
    end
    subgraph 反推[他留下/在想什么]
        I1[在做万子清一色]
        I2[筒子听牌或做筒]
        I3[万子3-4/4-6搭子不存在<br/>→ 万字邻张变安全]
        I4[手牌已成型<br/>打的就是刚摸的]
        I5[八万附近有搭子变动<br/>→ 邻张不安全]
    end
    subgraph 行动[我该怎么办]
        A1[生张万子列为高危]
        A2[生张筒子绝不打]
        A3[手里4万6万可放心打]
        A4[按他已听牌对待<br/>进入防守]
        A5[七万九万扣住观察]
    end
    O1 --> I1 --> A1
    O2 --> I2 --> A2
    O3 --> I3 --> A3
    O4 --> I4 --> A4
    O5 --> I5 --> A5

4.3 战术层：牌效——这一巡到底打哪张

战术层是执行：在路线已定、信息已有的前提下，每张出牌都按同一套优先级评估。

出牌优先级（无安全压力时）：缺门牌（必打）→ 孤立端张（无邻张的 1、9）→ 孤立中张 → 多余搭子中进张最少的那张 → 拆搭子。核心原则是"每一巡都最大化有效进张总数"：假设搭子 A（4-5 万）有 8 张潜在进张、搭子 B（1-2 筒）只有 3 张潜在进张，要拆就先拆 B——哪怕 B 看起来更"连得顺"。注意"潜在进张"还要减去已见张数，见 3 张的两面搭子不如没见过的卡张。

碰/杠决策是新手最容易犯错的地方，默认答案是"不碰"，除非满足以下至少一条：

碰了立刻听牌，或碰的是你的将牌方向（对子路线）；
你在做清一色/大对子，碰能加速成型；
这张牌不碰就被下家吃碰走、你再也等不到。

因为碰有隐性成本：暴露信息（全桌知道你在收这门）、破坏门清弹性（碰完之后手牌变窄，改路线更难）、改变摸牌顺序（可能把本该你摸的关键张让给下家）。杠同理：明杠多摸一张且血战里"杠上花"有额外收益，但同样暴露信息，尾盘还可能给别人开"杠上炮"。起手做大时积极碰杠，快跑路线时能不碰就不碰。

听口选择遵循两个数字：

听口宽度：两面听（8 张潜在）> 卡张/边张（4 张）> 对倒/单钓（2~4 张）。能选宽不选窄；
剩余张数：减去已见的。听见过 2 张的两面（剩 4~6 张），通常不如听没见过的卡张（剩 4 张但还有别人扣牌的空间）。尾盘再加一条修正：听熟张——别人敢打的牌，你才能吃到点炮；听生张只能指望自摸。

把出牌优先级和碰杠决策各画成一张图，实战时按图索骥即可：

flowchart TD
    A[这巡要出牌] --> B{手里有缺门牌?}
    B -->|有| C[打缺门牌]
    B -->|没有| D{有孤立端张?<br/>无邻张的1/9}
    D -->|有| E[打孤立端张]
    D -->|没有| F{有孤立中张?}
    F -->|有| G[打孤立中张]
    F -->|没有| H{搭子进张数比较}
    H -->|拆进张最少的搭子| I[打出该搭子中<br/>价值更低的一张]
    C & E & G & I --> J[打完前最后过一遍<br/>4.2.2 防点炮checklist]

flowchart TD
    P[别人打出一张牌<br/>我可以碰/杠] --> Q{碰了立刻听牌<br/>或是对子路线?}
    Q -->|是| R[碰]
    Q -->|否| S{我在做大<br/>且碰能加速成型?}
    S -->|是| R
    S -->|否| T{不碰就永远<br/>等不到这张?}
    T -->|是| R
    T -->|否| U[不碰, 默认答案]
    U -.成本.-> V1[暴露信息: 全桌知道你收这门]
    U -.成本.-> V2[破坏门清弹性: 手牌变窄]
    U -.成本.-> V3[改变摸牌顺序: 可能放走关键张]
    style U fill:#d4edda
    style R fill:#fff3cd

4.4 概率层：期望值决策——做大、快跑、防守的切换点

这是整个框架的"调度器"，回答"什么时候换路线"。先把 4.3 的直觉量化成一个可心算的模型。

基本概率感觉：任一时刻，你某方向的"期望进展" ≈ 剩余进张数 × 剩余可摸次数。你手里 4-5 万等 3/6 万，若都少见，剩余进张约 6-8 张；牌墙剩 40 张、四家轮流摸，你大约还能摸 8-10 次，摸中概率相当可观。但如果 3/6 万已见 3 张，进张只剩 1~2 张，期望直接砍到四分之一以下——搭子的价值不看牌面，看剩余进张数。

切换到"做大"的条件（需同时满足）：

起手结构支持：9 张以上同花色，或 4 对以上；
进张供给充足：三家缺门不与你抢这门（4.1 的绿灯）；
时间充足：牌墙过半之前。做牌是"用听牌速度换番数"，起手离目标越近、剩余巡数越多，换得越划算；
血战规则加成：一家胡牌不结束牌局，早胡者只是先锁定小收益，晚胡的大牌仍能兑现——大牌的"被截胡损失"比推倒胡小得多，所以四川麻将天然鼓励做牌。

切换到"快跑/止损"的条件（满足任一即执行）：

进张枯竭：关键牌期望进张 < 2，每一巡等待都是负期望——马上换听、拆死搭子；
有人已听牌且你生张密集：此时你的期望收益为负（点炮赔分 + 被查叫），最优解不是"我也赶紧听"，而是只打熟张把点炮概率压到最低，保住查叫底线。这就是"不跟随到最后"——追不上就不再投入，及时止损；
牌墙见底（剩 15 张以内）还没听牌：做牌的时间价值归零，唯一目标是听牌防查叫——往剩余张数最多的熟张方向听，只听一张也比"做了一半的大牌"值钱。

一个简化的期望算账例子（假设平胡 1 番 = 2 分，清一色 4 番 = 16 分）：你听牌了，可以选听口 A——平胡两面听，剩余进张 6 张；或改听口 B——清一色单钓，剩余进张 2 张。若剩余可摸次数约 6 次、点炮胡与自摸混合，A 的期望收益约是正 6~8 分；B 做成的概率约一半不到，做成了 16 分、做不成还要承担被查叫赔 2 分——期望约 6 分，且方差巨大。结论：番数翻倍抵不过进张减半，除非时间足够早或你已经落后必须搏。 新手默认选宽听口，永远是长期正期望。

把"什么时候切换路线"画成一张象限图——横轴是你的剩余进张，纵轴是牌局剩余时间，每巡定位一次自己落在哪个象限：

flowchart TB
    UP[纵轴 ↑ 剩余时间多] --- TOP
    subgraph TOP[ ]
        direction LR
        LEFT2[进张少] ~~~ A[换听调整<br/>时间够但方向死了<br/>例: 卡七万已见三张]
        A ~~~ B[做大<br/>时间够且进张足<br/>例: 起手清一色九张]
        B ~~~ RIGHT2[进张多]
    end
    TOP --- BOT
    subgraph BOT[ ]
        direction LR
        LEFT[进张少] ~~~ C[防守保底<br/>先听牌防查叫<br/>例: 剩十二张没听牌]
        C ~~~ D[快跑<br/>进张还在抢时间<br/>例: 两面听六张剩半局]
        D ~~~ RIGHT[进张多]
    end
    BOT --- DOWN[纵轴 ↓ 剩余时间少]
    style A fill:#fff3cd
    style B fill:#ffe6cc
    style C fill:#f8d7da
    style D fill:#d4edda

两条边界记死：进张 < 2 立刻换方向（左半区行动），剩 15 张只保听牌（下半区行动）。右下象限是血战到底最常见的好局面——进张还在但时间不多，别犹豫，最快胡法锁收益。

4.5 血战到底的三条特有推论

规则特殊，策略就有别处用不上的推论：

先胡是"锁仓"，不是"胜利"。你第一个平胡跑了，只是锁定 2 分；剩下三人继续打，大牌仍在你走后兑现。所以领先时快跑锁收益，落后时反而要做大搏翻盘——这和推倒胡"先胡为王"的直觉相反。
查叫把尾盘变成了保底竞赛。没胡的人要给听牌者赔分，所以尾盘的及格线是"听牌"而不是"胡牌"。最后 15 张，一切决策让位于"听上"。
点炮一人付，防守成本低。别人自摸三家分摊、你点炮你独赔——你打熟张"放生"别人自摸，损失远小于你点炮。所以防守期打熟张不仅是避险，还是把损失转移给全桌分摊的理性选择。

三种结算方式的赔付流向对比，一看就懂为什么"防守打熟张"是理性选择：

flowchart LR
    subgraph 点炮[你点炮: 你独赔]
        Y1[你 -8分] --> H1[胡牌者 +8分]
        O1[另两家 0分]
    end
    subgraph 自摸[对手自摸: 三家分摊]
        Y2[你 -3分] --> H2[胡牌者 +9分]
        O2[另两家各 -3分] --> H2
    end
    subgraph 查叫[流局查叫: 没听赔听牌]
        Y3[你没听 -2分] --> H3[听牌者 +2分]
    end
    style Y1 fill:#f8d7da
    style Y2 fill:#fff3cd
    style Y3 fill:#d4edda

同样是对手胡牌，你点炮亏 8 分、放生他自摸只亏 3 分——防守期每打一张熟张，赚的就是这个差价。

4.6 新手常见错误清单

对照检查，改掉一条涨一截胜率：

只记自己牌，不看池子——搭子死活取决于关键张已见几张，不看池子等于闭眼打牌；
见碰就碰——暴露信息、锁死手牌结构，快跑路线尤其要忍住；
死抱死搭子——7 万已见 3 张还抱着 6、8 万不拆，每巡都在付租金；
做大不看缺门——三家都抢你这门还硬做清一色，供给断了；
尾盘还想着翻盘——剩 15 张没听牌，唯一 KPI 是听牌防查叫；
不跟随到最后反着用——该止损时硬追生张点炮，该搏的时候（落后、时间早）却提前保守。

4.7 一页纸决策框架

把整章压缩成一张每巡都走的决策图：

flowchart TD
    A[每一巡] --> B{信息更新:<br/>关键张已见数/<br/>三家缺门/谁听牌了}
    B --> C{阶段判断}
    C -->|序盘: 定缺+定路线| D{起手支持做大?<br/>9张+同花色/4对+<br/>且三家不抢这门}
    D -->|是| E[做大路线:<br/>积极碰杠, 屯关键张]
    D -->|否| F[快跑路线:<br/>牌效优先, 能不碰不碰]
    C -->|中盘| G{有人已听牌<br/>且我生张密集?}
    G -->|是| H[防守: 只打熟张<br/>放生自摸, 不点炮]
    G -->|否| I{我的关键进张<br/>剩余>=4?}
    I -->|是| J[继续推进<br/>选进张最多的打]
    I -->|否| K[拆死搭子<br/>换听熟张方向]
    C -->|尾盘: 剩15张内| L{已听牌?}
    L -->|否| M[唯一目标: 听牌防查叫<br/>听剩张最多的熟张]
    L -->|是| N[宽听口优先<br/>不为一番改窄]

四个层级的关系：战略层定方向，信息层供弹药，战术层管执行，概率层负责喊停。 新手先把战术层的"进张最大化"练成肌肉记忆，再逐步叠加记牌和读牌，最后学会用期望值喊停——这条学习路径本身也是按依赖关系排的。

五、贝密的技术亮点

最后回到工程，挑几个我认为值得讲的点。

5.1 用 byte 编码整副牌：一副麻将只要几十个字节

贝密把每张麻将牌编码成一个 byte：万/筒/条各占 0~107（每门 36 个编号 = 9 个面值 × 4 张），牌面值 = (card % 36) / 4，花色 = card / 36；风牌用负数。这样 108 张牌的牌墙就是一个 byte[108]，序列化后不到 80 字节。

举例：编号 12 这张牌，12 / 36 = 0（万子），(12 % 36) / 4 = 3（第 4 个面值）——就是"四万"。一个除法一个取模就解出了花色和面值，不用查表、不用对象，广播出牌消息时网络上跑的就是 "12,13" 这样的字符串。

5.2 胡牌判断：不用 3N+2 递归，用"分堆 + 贪心摘顺子"

经典麻将胡牌算法是 3N+2 递归枚举。贝密的 GameUtils.processMJCard 走了一条不同的路：

把 14 张手牌按 key = 面值 + 9 × 花色 放进字典计数，先查定缺——缺门花色还在手里，直接不能胡（四川规则前置拦截）；
按计数把牌分成三堆：others（单张）、pairs（对子）、kezi（刻子）；
对单张堆排序后贪心摘顺子：同花色且 key 连续的 k/k+1/k+2 三张直接移除；
终止条件：单张摘空且恰好剩 1 对将（或 7 对——七对牌型天然被"pairs 堆 = 14 张"覆盖）；
对子多于 1 对时，把多余对子拆开当顺子候选再摘；全无刻子时枚举刻子拆开试。

源码 main() 里作者还放了性能测试：500 万次胡牌判断直接计时。要说明的是，这是个简化实现——作者自己在注释里承认某些"三连对"式的特殊牌型没完整处理。对在线棋牌的实际负载来说，这种"足够快、覆盖主流牌型"的取舍是合理的。

5.3 斗地主牌型识别：频次直方图一把梭

ActionTaskUtils.identification(byte[]) 的做法很干净：先统计同点数张数的分布（几个单张、几个对子、几个三张、几个炸弹），再用 switch(种类数, 最大点数) 一把识别全部牌型——单张、对子、三带一/二、顺子、连对、飞机带翅、四带二、炸弹、王炸。比较两手牌大小的 allow() 则只有三条规则：王炸最大、炸弹管一切非炸弹、同牌型比最大点数。AI 托管出牌也复用这套识别，找"能压住上家的最小牌"。

5.4 自研极简状态机统一驱动两种游戏

斗地主和麻将的流程差异巨大（抢地主 vs 定缺、出牌规则完全不同），但贝密用一个抽象统一了：BeiMiStateMachine + 按事件名查 transition 表 + Action 链。新增一种游戏 = 写一组 Action + 一份状态配置，调度、计时、广播的基础设施全部复用。

5.5 把缓存过期回调当游戏计时器用

这是我觉得最"巧"的设计。棋牌游戏里到处是倒计时：出牌 8 秒、杠碰胡决策 5 秒、抢地主超时自动放弃、房间超时补机器人。贝密没用 Quartz、没开线程池，而是用一个 sharpExpiry 的 cache2k 缓存当计时器：key 是 roomid，value 是任务对象，到期自动触发过期监听器执行任务。玩家主动操作了？remove(roomid) 就把倒计时取消了；要重置？put 一个新任务进去。零额外线程，语义严丝合缝。

5.6 实时状态与持久化彻底解耦

牌局进行中的所有状态（房间、Board、玩家手牌、撮合队列）全在 Hazelcast 分布式内存里，MySQL 只在结算时被异步写入——通过 Disruptor 的 RingBuffer 把变更事件丢给消费者，JPA 和 Elasticsearch 双写（ES 用于运营后台的战绩检索）。注释里还有一条重要的工程纪律：“只有一个地方对 GameRoom 二次写入，避免分布式锁”——用设计约束换掉了锁的开销。另外，房卡模式建房时的局数等规则赋值用了 Drools 规则引擎，规则写在 .drl 文件里，运营改规则不用改代码。

六、总结与反思

回顾这个项目，对新手最有价值的三个认知是：

联网游戏 = 服务器权威 + 按人过滤的状态分发。理解了"客户端只是显示器和遥控器"，就看懂了所有联网游戏的骨架。
棋牌游戏的复杂度不在算法，在工程。胡牌判断几百行就写完了，真正难的是断线重连、超时托管、并发房间这些"无聊"的部分——它们决定了玩家半夜打牌掉线时骂不骂人。
做游戏的人必须会玩游戏。第四章的四川麻将策略——分层记牌、由"打出"反推"留下"、用剩余进张 × 剩余巡数做期望决策——不只是给玩家的攻略，也是当初我们校验 AI 托管和出牌提示是否合理的标尺。

当然也有粗糙之处，如实记录：README 宣称的德州扑克在 0.8.0 里只有枚举占位并未实现；胡牌算法是简化版；源码里散落的 System.out.println 和作者自注的 bug 注释（比如多人同时可碰时先碰者胜出的竞态问题）都还在。但作为一个学习联网游戏开发的开源样本，它把一个房卡棋牌系统该有的零件——长连接、房间状态机、计时器、托管、异步落盘——都真实地摆在了那里，这比完美更有价值。

Spring Boot on 方糖猫Blog

Spring Boot + Python 双栈架构：AI 服务的工程化实践

Spring Boot + Python 双栈架构：AI 服务的工程化实践

一、为什么必须双栈？

二、整体架构

三、职责划分

3.1 Java 侧职责

3.2 Python 侧职责

3.3 边界原则

四、服务间通信

4.1 异步通信：RocketMQ

4.2 同步通信：HTTP / gRPC

4.3 数据一致性

五、数据库设计

5.1 按服务分库还是分表？

5.2 Python 侧如何访问数据库

六、部署与运维

6.1 容器化

6.2 CI/CD

6.3 日志与链路追踪

6.4 监控告警

七、踩过的坑

7.1 序列化不一致

7.2 Python 服务内存泄漏

7.3 跨语言异常处理

7.4 开发环境复杂度

八、双栈架构的收益与代价

8.1 收益

8.2 代价

九、什么情况下不要双栈？

十、总结

我开发的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 任务状态机

四、核心设计要点

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

8.8 谨慎使用 `@LocalCacheClear`

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