smallphp/small-resource-server

设计背景

Small Resource Server旨在高负载微服务环境中高效处理资源锁定与同步。通过集中化资源访问，它可防止分布式服务间的竞态条件和状态不一致，同时借助Swoole的并发模型保持轻量快速。这能减少资源竞争、提升吞吐量，确保支付、预订或库存更新等关键操作在高并行流量下仍可靠运行，也为多进程/多服务器批量同步提供有效方案。

它提供轻量、语言无关的HTTP API，支持：

• 基于名称获取带可选TTL和所有者令牌的锁
• 共享关联数据

Symfony客户端Bundle为Symfony应用提供便捷、可靠的访问方式：

• HttpClientInterface集成
• 依赖注入配置（base_uri、API密钥、超时）
• 直观的Resource门面/服务API

架构概述（高层）

Small Resource Server

• 运行环境：PHP + Swoole/OpenSwoole HTTP服务器
• 内存映射：resourceName → lease（启用时可选择Redis/DB作为插件式存储）
• Lease数据：owner、token、acquiredAt、ttl、expiresAt
• 后台清理程序：清除过期lease
• 极简REST端点

客户端Bundle（Symfony）

• 注册预配置的命名HTTP客户端（含base_uri、x-api-key头、默认超时）
• 暴露ResourceFactory/ResourceClient服务，支持acquire()、renew()、release()操作
• 可选的 transient错误重试/退避及时钟偏差容忍

HTTP API（服务器端）

创建资源

POST /resource
Headers:
  x-api-key: <WRITE密钥>

Body (JSON):
{
  "name": "printer",
  "timeout": 300            // 可选的服务器端语义
}

201 Created
Content-Type: application/json
{ ...resource... }

获取资源数据（含可选锁）

GET /resource/{resourceName}/{selector}?lock=1
Headers:
  x-api-key: <READ或READ+LOCK>
  x-ticket: <现有ticket | 可选>

Query:
  lock=1  (默认) → 尝试获取/保持锁
  lock=0 → 不锁定直接读取

响应：
- 200 OK + JSON体 → 资源数据可用，Header含x-ticket:<ticket>
- 202 Accepted → 资源不可用（被其他方锁定），Body:{"unavailable":true}，Header含x-ticket:<ticket>（用于重试）
- 404 Not Found → 资源/selector不存在
- 401 Unauthorized → 缺失/无效x-api-key 或 lock=1时无LOCK权限

更新资源数据

PUT /resource/{resourceName}/{selector}
Headers:
  x-api-key: <WRITE密钥>
  x-ticket: <来自GET的ticket>

Body: 待存储的原始JSON payload

204 No Content

解锁资源

POST /resource/{resourceName}/{selector}/unlock
Headers:
  x-api-key: <READ+LOCK>
  x-ticket: <ticket>

200 OK
{ "unlocked": true }

安全提示：接受x-api-key头；建议使用TLS；对滥用客户端进行速率限制。

📦 安装部署

服务器（Docker Hub镜像）

运行服务器最简单的方式是通过Docker：

bash
# 从Docker Hub拉取最新镜像
docker pull smallphp/small-resource-server:latest

# 运行镜像（根据需要调整API_KEY和端口）
docker run -d \
  --name resource-server \
  --volume "./conf/small-swoole-resource-server.conf:/etc/small-swoole-resource-server.conf" \
  -p 8080:9501 \
  smallphp/small-resource-server:latest

现在可通过http://localhost:8080%E8%AE%BF%E9%97%AE%E6%9C%8D%E5%8A%A1%E5%99%A8%E3%80%82

Docker Compose示例：

yaml
version: '3.8'
services:
  resource-server:
    image: smallphp/small-resource-server:latest
    restart: unless-stopped
    ports:
      - "8080:9501"
    volumes:
      - ./conf/small-swoole-resource-server.conf:/etc/small-swoole-resource-server.conf
  database:
    container_name: small-swoole-resource-db
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: secret
    command: ["mysqld", "--mysql-native-password=FORCE"]

配置文件示例：

dotenv
MYSQL_HOST=database
MYSQL_USER=root
MYSQL_PASSWORD=secret
RESOURCE_READ=d8e8fca2dc0f896fd7cb4cb0031ba249
RESOURCE_READ_LOCK=ed4779d230afc18ca8df5213ba02b11e
RESOURCE_WRITE=eadd7e1bbc06f288417df096bbedfa61