Skip to content

PROJECT_STATUS.md

Latest commit

 

History

History
242 lines (203 loc) · 6.9 KB

PROJECT_STATUS.md

File metadata and controls

242 lines (203 loc) · 6.9 KB

IronSys Project Status

项目概述

IronSys 是一个基于"四大性能支柱"的高并发分布式预订系统参考实现。

已完成的组件

✅ 核心基础设施

  • Docker Compose 配置 (PostgreSQL, Redis, Kafka, Zookeeper, Prometheus, Grafana)
  • 数据库迁移脚本 (001_init_schema.sql)
  • Makefile 自动化命令
  • 环境变量配置 (.env.example)

✅ Python 实现（完整）

  • FastAPI 应用
    • API 主程序 (app/api/main.py)
    • 配置管理 (app/config/settings.py)
    • 数据模型 (app/models/schemas.py)
  • 服务层
    • 数据库服务 (app/services/database.py) - asyncpg 连接池
    • 缓存服务 (app/services/cache.py) - Redis with SWR 支持
    • Kafka 生产者 (app/services/producer.py) - 分区路由
  • Worker 消费者
    • Kafka 消费者 (app/worker/consumer.py) - Actor 模式处理
    • 幂等性保证
    • 批量处理
    • DLQ 支持
  • Dockerfiles
    • Dockerfile.api - API 服务容器
    • Dockerfile.worker - Worker 服务容器
  • 依赖管理 (requirements.txt)

✅ Go 实现（完整）

  • 数据模型 (internal/models/models.go)
  • 配置管理 (internal/config/config.go)
  • 服务层
    • 数据库服务 (internal/service/database.go) - pgx/v5 连接池
    • 缓存服务 (internal/service/cache.go) - Redis with SWR 支持
    • Kafka 生产者 (internal/service/producer.go) - 分区路由
  • API 处理器 (internal/api/handlers.go)
    • GET / - 根路径
    • GET /health - 健康检查
    • GET /metrics - Prometheus 指标
    • POST /reserve - 创建预订
    • GET /slots/:id - 获取时间槽
  • Worker 消费者 (internal/worker/consumer.go)
    • Actor 模式分区处理
    • 幂等性保证
    • 重试机制
    • DLQ 支持
  • 完整的 go.mod 依赖
  • Dockerfiles (API + Worker)
  • Go 实现文档 (go/README.md)

状态： Go 实现已完成，功能与 Python 版本完全对应。

✅ 监控与可观测性

  • Prometheus 配置
    • 抓取配置 (infra/prometheus/prometheus.yml)
    • Python/Go API 和 Worker 的指标采集
  • Grafana 配置
    • 数据源配置 (infra/grafana/datasources.yml)
    • 仪表板配置 (infra/grafana/dashboards.yml)

✅ 负载测试

  • Locust 测试脚本 (load-tests/locustfile.py)
    • 读写混合场景
    • 读密集型场景
    • 写密集型场景
  • k6 测试脚本 (load-tests/k6-test.js)
    • 阶梯式负载
    • 自定义指标
    • 性能阈值

✅ 文档

  • README.md - 完整的项目文档
    • 快速开始
    • API 文档
    • 架构说明
    • 性能指标
    • 设计决策
  • PROJECT_STATUS.md - 项目状态
  • requirement.md - 需求规格（已有）

四大性能支柱实现状态

1. ✅ Parallel Reads（并行读取）

  • Redis 缓存优先读取
  • Stale-While-Revalidate (SWR) 支持
  • 无锁并发访问
  • 目标：≥50,000 RPS (缓存命中)

2. ✅ Serialized Writes（序列化写入）

  • Kafka 分区键路由（基于 slot_id）
  • Actor 模式：每个分区单一写入者
  • 消除写入竞争
  • 目标：≥5,000 RPS

3. ✅ Read/Write Separation（读写分离）

  • 写入路径：API → Kafka → Worker → DB → Cache
  • 读取路径：API → Cache (→ DB on miss)
  • 完全隔离，防止读取竞争

4. ✅ Asynchronous State（异步状态）

  • 事件驱动架构（Kafka）
  • 幂等性处理
  • 可重放消息处理
  • DLQ 支持

项目结构

IronSys/
├── python/                     # Python 实现（完整）
│   ├── app/
│   │   ├── api/               # FastAPI 应用
│   │   ├── worker/            # Kafka 消费者
│   │   ├── models/            # 数据模型
│   │   ├── services/          # 业务逻辑
│   │   └── config/            # 配置
│   ├── Dockerfile.api
│   ├── Dockerfile.worker
│   └── requirements.txt
│
├── go/                         # Go 实现（完整）
│   ├── cmd/
│   │   ├── api/               # API 入口
│   │   └── worker/            # Worker 入口
│   ├── internal/
│   │   ├── api/               # HTTP 处理器
│   │   ├── config/            # 配置
│   │   ├── models/            # 数据模型
│   │   ├── service/           # 业务逻辑
│   │   └── worker/            # Kafka 消费者
│   ├── Dockerfile.api
│   ├── Dockerfile.worker
│   ├── go.mod
│   └── README.md
│
├── infra/                      # 基础设施配置
│   ├── prometheus/
│   └── grafana/
│
├── load-tests/                 # 负载测试
│   ├── locustfile.py
│   └── k6-test.js
│
├── db/migrations/              # 数据库迁移
│   └── 001_init_schema.sql
│
├── docker-compose.yml          # 服务编排
├── Makefile                    # 自动化命令
├── README.md                   # 项目文档
└── .env.example               # 环境变量示例

快速开始

# 1. 复制环境配置
cp .env.example .env

# 2. 启动所有服务
make up

# 3. 访问服务
# - Python API: http://localhost:8001
# - Go API: http://localhost:8002
# - Kafka UI: http://localhost:8080
# - Grafana: http://localhost:3000 (admin/admin)
# - Prometheus: http://localhost:9090

# 4. 运行负载测试
make bench

下一步工作（可选增强）

高级特性

  • Outbox 模式实现
  • WebSocket 推送通知
  • 水平分片支持
  • DLQ 自动重试机制
  • OpenTelemetry 分布式追踪
  • Grafana 自定义仪表板
  • CI/CD 管道
  • Kubernetes 部署配置

测试增强

  • Python 单元测试
  • Go 单元测试
  • 集成测试
  • 端到端测试
  • 混沌工程测试

关键设计决策

  1. Actor 模式 vs 锁

    • 选择：Actor 模式（通过 Kafka 分区实现）
    • 原因：消除锁竞争，可预测的延迟

  2. 缓存优先 vs 数据库优先

    • 选择：缓存优先 + SWR
    • 原因：超高读取吞吐量，优雅降级

  3. 同步 vs 异步写入

    • 选择：异步写入（202 Accepted）
    • 原因：快速响应，Kafka 处理背压

  4. Python + Go 双实现

    • 原因：展示语言无关的架构模式
    • 好处：团队可选择熟悉的技术栈

性能目标

指标 目标值 状态
写入吞吐量 ≥5,000 RPS 待测试
写入 P99 延迟 <250ms 待测试
读取吞吐量（缓存命中） ≥50,000 RPS 待测试
读取 P95 延迟（缓存命中） <20ms 待测试
读取吞吐量（缓存未命中） ≥10,000 RPS 待测试
Kafka 延迟恢复 有界恢复 待测试

贡献指南

欢迎贡献！请遵循以下原则：

  1. 保持设计模式一致性
  2. 添加适当的测试
  3. 更新相关文档
  4. 遵循代码风格规范

许可证

MIT License

状态更新时间： 2025-10-18

当前版本： v1.0.0（Python 和 Go 双实现完整）