python单例模式下线程安全优化

NL2WorkflowService 线程安全优化文档

概述

本文档详细说明了 NL2WorkflowService 在并发环境下的线程安全优化，主要解决单例模式的竞态条件问题和文件写入冲突问题。

优化背景

问题场景

在 FastAPI + Uvicorn 的并发环境下，多个HTTP请求可能同时访问 get_nl2workflow_service() 函数：

# FastAPI 端点中的依赖注入
@nl2workflow_router.post("/stream-events")
async def stream_graph_events(
    request: ChatRequest,
    service: NL2WorkflowService = Depends(get_nl2workflow_service),  # ← 并发访问点
):

并发问题分析

1. 单例创建竞态条件 ：多个线程同时检查 _nl2workflow_service is None
2. 文件写入冲突 ：多个会话写入同一个 dsl.json 文件
3. 资源浪费：重复创建昂贵的 LangGraph 实例

优化方案

1. 线程安全的单例模式

优化前（存在问题的代码）

# ❌ 不安全的单例实现
_nl2workflow_service: Optional[NL2WorkflowService] = None

def get_nl2workflow_service() -> NL2WorkflowService:
    """Get or create LangGraph service instance"""
    global _nl2workflow_service
    if _nl2workflow_service is None:        # ← 竞态条件！
        _nl2workflow_service = NL2WorkflowService()  # ← 可能被多次执行！
    return _nl2workflow_service

问题分析：

• 竞态条件窗口 ：在检查 is None 和创建实例之间存在时间间隙
• 多实例创建：多个线程可能同时通过检查，导致创建多个实例
• 最后写入获胜：只有最后创建的实例会被保存到全局变量

优化后（线程安全的代码）

# ✅ 线程安全的单例实现
import threading as _threading

_nl2workflow_service: _t.Optional[NL2WorkflowService] = None
_service_lock = _threading.Lock()

def get_nl2workflow_service() -> NL2WorkflowService:
    """
    Get or create LangGraph service instance (Thread-safe singleton)
    
    Uses double-checked locking pattern for optimal performance:
    - First check without lock (fast path for already initialized instance)
    - Acquire lock only when instance needs to be created
    - Second check with lock to prevent race conditions
    
    Returns:
        NL2WorkflowService: Thread-safe singleton instance
    """
    global _nl2workflow_service
    
    # 第一次检查（无锁）- 快速路径
    if _nl2workflow_service is not None:
        return _nl2workflow_service
    
    # 获取锁进行实例创建
    with _service_lock:
        # 第二次检查（有锁）- 防止竞态条件
        if _nl2workflow_service is None:
            logger.info("Creating new NL2WorkflowService instance (thread-safe)")
            _nl2workflow_service = NL2WorkflowService()
            logger.info("NL2WorkflowService instance created successfully")
        
    return _nl2workflow_service

双重检查锁定模式详解

设计原理：

1. 第一次检查（快速路径）：

   • 无锁检查，性能最优
   • 适用于服务已初始化的情况（99%的访问）

2. 锁获取：

   • 只在需要创建实例时获取锁
   • 避免不必要的锁竞争

3. 第二次检查（安全路径）：

   • 在锁保护下再次检查
   • 防止在等待锁期间其他线程已创建实例

时序分析：

时刻 T1: 线程A和线程B同时到达第一次检查
线程A: if _service is not None: → False
线程B: if _service is not None: → False

时刻 T2: 线程A获取锁，线程B等待
线程A: with _service_lock: → 获取成功
线程B: with _service_lock: → 等待中...

时刻 T3: 线程A进行第二次检查并创建实例
线程A: if _service is None: → True → 创建实例
线程B: 仍在等待锁...

时刻 T4: 线程A释放锁，线程B获取锁
线程A: 退出 with 块 → 释放锁
线程B: with _service_lock: → 获取成功

时刻 T5: 线程B进行第二次检查
线程B: if _service is None: → False → 跳过创建
线程B: return _service → 返回已存在的实例

2. 文件写入冲突优化

优化前（存在问题的代码）

# ❌ 所有会话写入同一个文件
def invoke(self, message: str, session_id: str, ...):
    # ... 处理逻辑 ...
    
    # 确保 outputs 目录存在并保存 DSL
    output_dir = _ensure_output_dir()
    output_file = output_dir / "dsl.json"  # ← 所有会话共用同一文件！
    with open(output_file, "w", encoding="utf-8") as f:
        f.write(dsl)

问题分析：

• 文件覆盖：后执行的会话会覆盖先执行的结果
• 数据丢失：并发情况下可能丢失某些会话的DSL数据
• 调试困难：无法区分不同会话的输出

优化后（会话隔离的代码）

# ✅ 按会话ID分别保存文件
def invoke(self, message: str, session_id: str, ...):
    # ... 处理逻辑 ...
    
    # 确保 outputs 目录存在并保存 DSL（按session_id分别保存避免并发冲突）
    output_dir = _ensure_output_dir()
    output_file = output_dir / f"dsl-{session_id}.json"  # ← 每个会话独立文件
    with open(output_file, "w", encoding="utf-8") as f:
        f.write(dsl)
    
    logger.info(f"DSL saved at: {output_file}")

优化效果：

• 会话隔离：每个会话有独立的DSL文件
• 并发安全：不同会话不会相互覆盖
• 便于调试：可以追踪特定会话的输出

性能分析

单例模式性能特征

场景	第一次检查	锁获取	第二次检查	实例创建	总耗时
首次访问	✓ (快)	✓ (慢)	✓ (快)	✓ (很慢)	~100ms
后续访问	✓ (快)	✗	✗	✗	~0.001ms
并发首次	✓ (快)	✓ (排队)	✓ (快)	✗ (跳过)	~1ms

性能测试结果

# 测试代码示例
def performance_test():
    # 1000次访问已初始化的服务
    start_time = time.time()
    for _ in range(1000):
        service = get_nl2workflow_service()
    end_time = time.time()
    
    print(f"1000次访问耗时: {(end_time - start_time) * 1000:.3f}ms")
    # 预期结果: < 1ms

并发测试验证

测试用例设计

def test_concurrent_singleton_creation():
    """测试并发单例创建的线程安全性"""
    instances = []
    creation_count = 0
    
    def create_instance():
        nonlocal creation_count
        # 模拟并发访问
        time.sleep(0.01)
        instance = get_nl2workflow_service()
        instances.append(instance)
    
    # Mock 初始化过程来计算创建次数
    def mock_init(self):
        nonlocal creation_count
        creation_count += 1
        time.sleep(0.1)  # 模拟初始化耗时
        self.graph = MagicMock()
    
    with patch.object(NL2WorkflowService, '__init__', mock_init):
        # 3个线程并发访问
        threads = []
        for _ in range(3):
            thread = threading.Thread(target=create_instance)
            threads.append(thread)
        
        # 同时启动所有线程
        for thread in threads:
            thread.start()
        for thread in threads:
            thread.join()
    
    # 验证结果
    assert creation_count == 1, "应该只创建1个实例"
    assert len(instances) == 3, "应该有3个实例引用"
    assert all(inst is instances[0] for inst in instances), "所有实例应该相同"

测试结果对比

优化前：

修复前：不安全的单例实现
  线程 31740: 创建实例 UnsafeService_1
  线程 20776: 创建实例 UnsafeService_2  
  线程 21212: 创建实例 UnsafeService_3
  结果: 创建了 3 个实例 ❌
  唯一实例数: 3 ❌

优化后：

修复后：安全的单例实现
  线程 30044: 创建 NL2WorkflowService 实例 #1
  结果: 创建了 1 个实例 ✅
  获取的实例数: 3
  唯一实例数: 1 ✅

最佳实践建议

1. 单例模式设计原则

# ✅ 推荐的单例模式模板
import threading
from typing import Optional, TypeVar

T = TypeVar('T')

class ThreadSafeSingleton:
    _instance: Optional[T] = None
    _lock = threading.Lock()
    
    @classmethod
    def get_instance(cls) -> T:
        # 快速路径：已初始化的情况
        if cls._instance is not None:
            return cls._instance
        
        # 慢速路径：需要创建实例
        with cls._lock:
            if cls._instance is None:
                cls._instance = cls()
        
        return cls._instance

2. 文件操作安全原则

# ✅ 推荐的文件写入模式
def safe_write_file(content: str, session_id: str, file_type: str = "dsl"):
    """安全的文件写入，避免并发冲突"""
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filename = f"{file_type}-{session_id}-{timestamp}.json"
    
    output_dir = ensure_output_dir()
    output_file = output_dir / filename
    
    # 原子写入：先写临时文件，再重命名
    temp_file = output_file.with_suffix('.tmp')
    try:
        with open(temp_file, "w", encoding="utf-8") as f:
            f.write(content)
        temp_file.rename(output_file)
        logger.info(f"File saved: {output_file}")
    except Exception as e:
        if temp_file.exists():
            temp_file.unlink()
        raise e

3. 监控和调试

# ✅ 推荐的监控代码
import time
from functools import wraps

def monitor_singleton_access(func):
    """监控单例访问的装饰器"""
    @wraps(func)
    def wrapper(*args, **kwargs):
        start_time = time.time()
        thread_id = threading.get_ident()
        
        logger.debug(f"Singleton access start - Thread: {thread_id}")
        
        result = func(*args, **kwargs)
        
        end_time = time.time()
        access_time = (end_time - start_time) * 1000
        
        logger.debug(f"Singleton access end - Thread: {thread_id}, Time: {access_time:.3f}ms")
        
        return result
    return wrapper

@monitor_singleton_access
def get_nl2workflow_service() -> NL2WorkflowService:
    # ... 实现代码 ...

总结

优化成果

1. 线程安全保证：

   • ✅ 解决了单例模式的竞态条件
   • ✅ 使用双重检查锁定模式
   • ✅ 保证只创建一个服务实例

2. 文件操作安全：

   • ✅ 按会话ID分别保存DSL文件
   • ✅ 避免并发写入冲突
   • ✅ 便于调试和追踪

3. 性能优化：

   • ✅ 初始化后无锁快速访问
   • ✅ 避免重复创建昂贵资源
   • ✅ 支持高并发访问

适用场景

• FastAPI + Uvicorn 多线程/多进程环境
• 高并发API服务 需要共享资源
• 长期运行的服务 需要资源复用
• 微服务架构 需要线程安全的组件

注意事项

1. 内存管理：单例实例会持续占用内存，注意生命周期管理
2. 测试隔离：测试时需要重置单例状态
3. 配置变更：运行时配置变更可能需要重新创建实例
4. 异常处理：初始化失败时的错误恢复机制

通过这些优化，NL2WorkflowService 现在可以安全地在高并发环境下运行，为生产环境提供了可靠的线程安全保证。