redislabs/redisstatemachine

redis-state-machine

https://img.shields.io/github/v/release/redislabsmodules/redis-state-machine?label=latest](https://github.com/redislabsmodules/redis-state-machine/releases/latest) https://img.shields.io/badge/dockerhub-redislabs/redisstatemachine-blue](https://hub.docker.com/r/redislabs/redisstatemachine/tags/)

一个https://redis.io/docs/modules%EF%BC%8C%E7%94%A8%E4%BA%8E%E5%9C%A8%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%AB%AF%E7%BB%B4%E6%8A%A4%E7%8A%B6%E6%80%81%E6%9C%BA%E3%80%82

注意：此模块为实验性项目，正在积极开发中。

镜像概述和主要用途

redis-state-machine是一个扩展Redis功能的模块，允许用户在Redis服务器端定义和管理状态机。状态机以JSON格式存储，包含状态映射、当前状态和初始状态，支持状态转换规则配置及状态变更操作，适用于需要状态跟踪、工作流控制或有限状态机实现的场景。

核心功能和特性

• 状态机定义：通过JSON格式定义状态机结构，包含初始状态、状态映射（转换规则）和当前状态
• 状态管理命令：提供SM.TEMPLATE、SM.SET、SM.GET、SM.MUTATE等命令操作状态机
• 状态转换验证：仅允许按照预定义的状态映射进行状态转换，确保状态变更合法性
• 无缝集成Redis：作为Redis模块运行，可直接通过Redis客户端（如redis-cli、redis-py）操作

使用场景和适用范围

• 工作流状态管理（如订单状态、审批流程）
• 设备状态跟踪（如物联网设备在线/离线/故障状态转换）
• 有限状态机（FSM）实现
• 需要严格状态转换规则的业务逻辑

使用方法和配置说明

安装与启动

最简单的使用方式是拉取Docker镜像并运行：

bash
docker run -p 6379:6379 -it docker.xuanyuan.run/redislabs/redisstatemachine:edge

上述命令会启动一个包含状态机模块的Redis实例，监听默认6379端口。

基本使用

获取状态机模板

使用SM.TEMPLATE命令获取状态机模板：

bash
redis-cli
SM.TEMPLATE

返回的模板结构如下：

json
{"current":"","map":{},"initial":""}

• current：当前状态
• map：状态转换规则映射（键为当前状态，值为可转换的目标状态列表）
• initial：初始状态

创建状态机

使用SM.SET命令创建状态机，需指定状态机名称和JSON格式的状态机定义：

bash
redis-cli
SM.SET mymachine '{"current":"","map":{},"initial":"foo"}'

获取状态机信息

使用SM.GET命令查看状态机详情：

bash
redis-cli
SM.GET mymachine

若未指定current状态，将自动使用initial状态作为当前状态，返回结果：

json
{"current":"foo","map":{},"initial":"foo"}

实际示例（Python）

以下示例使用Python和https://github.com/redis/redis-py%E5%AE%A2%E6%88%B7%E7%AB%AF%E6%93%8D%E4%BD%9C%E7%8A%B6%E6%80%81%E6%9C%BA%E3%80%82

准备工作

python
import redis
import json

# 连接Redis（确保已启动包含状态机模块的Redis实例）
r = redis.Redis(decode_responses=True)

# 获取状态机模板
tmpl = json.loads(r.execute_command("SM.TEMPLATE"))

定义状态机

创建一个名为mystatemachine的状态机，初始状态为bar，状态转换规则：

• bar可转换至blee和boo
• boo可转换至blee

python
tmpl['initial'] = 'bar'
tmpl['map'] = {"bar": ["blee", "boo"], "boo": ["blee"]}

# 保存状态机
r.execute_command("SM.SET", "mystatemachine", json.dumps(tmpl))

状态转换操作

使用SM.MUTATE命令进行状态转换：

• 转换至无效状态（返回None）：

  python
  x = r.execute_command("SM.MUTATE", "mystatemachine", "notastate")
  print(x)  # 输出: None
  

• 转换至有效状态（返回OK）：

  python
  x = r.execute_command("SM.MUTATE", "mystatemachine", "blee")
  print(x)  # 输出: OK
  

查看状态机当前状态

python
state_machine = r.execute_command("SM.GET", "mystatemachine")
print(state_machine)
# 输出: {"current":"blee","map":{"bar":["blee","boo"],"boo":["blee"]},"initial":"bar"}

命令参考

完整命令集可查看https://github.com/redislabsmodules/redis-state-machine/blob/main/commands.json%E6%96%87%E4%BB%B6%EF%BC%8C%E4%BD%BF%E7%94%A8%E6%B5%8B%E8%AF%95%E5%8F%AF%E5%8F%82%E8%80%83https://github.com/redislabsmodules/redis-state-machine/blob/main/tests/test_commands.py%E3%80%82

构建与贡献

工具要求

• https://www.rust-lang.org
• GNU Make
• Python（版本需满足https://github.com/redislabsmodules/redis-state-machine/blob/main/.python-version%E6%96%87%E4%BB%B6%E8%A6%81%E6%B1%82%EF%BC%89
• Redis

构建与运行

bash
make run

测试

模块测试基于集成测试，使用pytest和Python：

1. 创建虚拟环境并安装依赖：

   bash
   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   pip install -r tests/requirements.txt
   

2. 运行测试：

   bash
   pytest