Download the PHP package nermif/php-redis-stock without Composer

PHP Redis 库存与销售管理库

基于 Redis Lua 脚本的原子化库存扣减与销售记录组件，专为高并发电商场景设计。
提供门面 (Facade) 与底层原子类两种模式，兼顾易用性与灵活性。

✨ 特性

• 原子操作 – 购买下单、取消订单均封装在 Redis Lua 脚本中，杜绝超卖、脏读。
• 售罄快照 – 库存归零时自动生成售罄标记，网关可据此快速拦截无效请求。
• 幂等 & 限购 – 基于订单 ID 的防重处理，支持用户维度的限购控制。
• 集群兼容 – 内置 {} Hash Tag，确保相关 Key 落在同一 Redis Cluster Slot。
• 状态自愈 – 提供 monitor() / repair() 检测并修复库存与售罄标记的不一致。
• 自动重试 – 瞬态故障（网络抖动、主从切换）采用指数退避重试，对业务透明。
• 统一响应 – 门面所有方法返回 [success, code, message, data] 结构，调用方解析简单。
• PSR‑3 日志 – 可注入 PSR‑3 兼容的日志组件，便于生产监控。

⚙️ 快速开始

安装

基础使用（推荐门面）

统一响应格式

门面所有方法均返回：

🏁 错误码一览

门面类和底层类都实现了 StockSalesCodes 接口，可以直接通过 类名::CODE_XXX 判断返回值。

🗂️ 示例项目

示例代码位于 examples/ 目录：

运行示例前确保 Redis 已启动：

🧩 高级用法（直接使用底层类）

如果需要门面未提供的能力（如批量扣减、自定义重试），可以直接操作 RedisStock 和 RedisSales：

底层类同样实现 StockSalesCodes，可使用统一的错误码常量。

🔧 框架集成

Laravel

ThinkPHP

🏗️ 内部架构（面向高阶开发者）

系统通过门面模式组织对外接口，内部分工清晰：

购买流程：purchase() 内部调用 recordPurchaseWithStock Lua 脚本，一次性原子完成：
库存校验 → 限购检查 → 库存扣减 → 售罄标记 → 记录销量/销售额/排行榜 → 订单幂等标记。

用户无需分别调用 decrStock() + recordPurchase()，也无需在业务层手动判断售罄。

⚠️ 生产环境建议

1. Key 前缀 – 务必使用 {} 包裹前缀核心部分（如 {stock}:），否则多 Key 操作在集群下会报 CROSSSLOT。
2. Redis 配置 – maxmemory-policy 建议设为 volatile-lru，避免意外驱逐导致售罄标记丢失。
3. 日志注入 – 建议注入 PSR‑3 日志器。当 repair() 触发修复时可通过日志追踪底层异常。
4. 批量操作 – decrMultiStocks 虽然支持原子扣减，但单次 SKU 数建议不超过 20，避免长时间阻塞 Redis。
5. 限购过期的理解 – 用户购买记录的 TTL 默认为 30 天，超时后限购计数自动清零，请按业务需求调整。

🧪 测试

测试套件包含 120+ 用例，覆盖库存、销售、门面层及边界场景。

📄 许可

MIT License. 可自由用于个人或商业项目。