# RequestContext 使用指南
  
  ## 概述
  
  `RequestContext` 是一个请求粒度的上下文管理器，用于跟踪和管理搜索请求的整个生命周期。它提供了统一的数据存储、性能监控和日志记录功能。
  
  ## 核心功能
  
  ### 1. 查询分析结果存储
  - 原始查询、规范化查询、重写查询
  - 检测语言和翻译结果
  - 查询向量（embedding）
  - 布尔查询AST
  
  ### 2. 各检索阶段中间结果
  - 解析后的查询对象
  - 布尔查询语法树
  - ES查询DSL
  - ES响应数据
  - 处理后的搜索结果
  
  ### 3. 性能监控
  - 自动计时各阶段耗时
  - 计算各阶段耗时占比
  - 识别性能瓶颈
  - 详细的性能摘要日志
  
  ### 4. 错误处理和警告
  - 统一的错误信息存储
  - 警告信息收集
  - 完整的上下文错误跟踪
  
  ## 支持的搜索阶段
  
  ```python
  class RequestContextStage(Enum):
      TOTAL = "total_search"                    # 总搜索时间
      QUERY_PARSING = "query_parsing"          # 查询解析
      BOOLEAN_PARSING = "boolean_parsing"      # 布尔查询解析
      QUERY_BUILDING = "query_building"        # ES查询构建
      ELASTICSEARCH_SEARCH = "elasticsearch_search"  # ES搜索
      RESULT_PROCESSING = "result_processing"  # 结果处理
      RERANKING = "reranking"                  # 重排序
  ```
  
  ## 基本使用方法
  
  ### 1. 创建RequestContext
  
  ```python
  from context import create_request_context, RequestContext
  
  # 方式1: 使用工厂函数
  context = create_request_context(reqid="req-001", uid="user-123")
  
  # 方式2: 直接创建
  context = RequestContext(reqid="req-001", uid="user-123")
  
  # 方式3: 作为上下文管理器使用
  with create_request_context("req-002", "user-456") as context:
      # 搜索逻辑
      pass  # 自动记录性能摘要
  ```
  
  ### 2. 阶段计时
  
  ```python
  from context import RequestContextStage
  
  # 开始计时
  context.start_stage(RequestContextStage.QUERY_PARSING)
  
  # 执行查询解析逻辑
  # parsed_query = query_parser.parse(query, context=context)
  
  # 结束计时
  duration = context.end_stage(RequestContextStage.QUERY_PARSING)
  print(f"查询解析耗时: {duration:.2f}ms")
  ```
  
  ### 3. 存储查询分析结果
  
  ```python
  context.store_query_analysis(
      original_query="红色连衣裙",
      normalized_query="红色 连衣裙",
      rewritten_query="红色 女 连衣裙",
      detected_language="zh",
      translations={"en": "red dress"},
      query_vector=[0.1, 0.2, 0.3, ...],  # 如果有向量
      is_simple_query=True
  )
  ```
  
  ### 4. 存储中间结果
  
  ```python
  # 存储解析后的查询对象
  context.store_intermediate_result('parsed_query', parsed_query)
  
  # 存储ES查询DSL
  context.store_intermediate_result('es_query', es_query_dict)
  
  # 存储ES响应
  context.store_intermediate_result('es_response', es_response)
  
  # 存储处理后的结果
  context.store_intermediate_result('processed_hits', hits)
  ```
  
  ### 5. 错误处理和警告
  
  ```python
  try:
      # 可能出错的操作
      risky_operation()
  except Exception as e:
      context.set_error(e)
  
  # 添加警告信息
  context.add_warning("查询结果较少，建议放宽搜索条件")
  
  # 检查是否有错误
  if context.has_error():
      print(f"搜索出错: {context.metadata['error_info']}")
  ```
  
  ## 在Searcher中使用
  
  ### 1. 自动创建Context（向后兼容）
  
  ```python
  searcher = Searcher(config, es_client)
  
  # Searcher会自动创建RequestContext
  result = searcher.search(
      query="无线蓝牙耳机",
      size=10,
      enable_embedding=True
  )
  
  # 结果中包含context信息
  print(result.context.get_summary())
  ```
  
  ### 2. 手动创建和传递Context
  
  ```python
  # 创建自己的context
  context = create_request_context("my-req-001", "user-789")
  
  # 传递给searcher
  result = searcher.search(
      query="运动鞋",
      context=context  # 传递自定义context
  )
  
  # 使用context进行详细分析
  summary = context.get_summary()
  print(f"总耗时: {summary['performance']['total_duration_ms']:.1f}ms")
  ```
  
  ## 性能分析
  
  ### 1. 获取性能摘要
  
  ```python
  summary = context.get_summary()
  
  # 基本信息
  print(f"请求ID: {summary['request_info']['reqid']}")
  print(f"总耗时: {summary['performance']['total_duration_ms']:.1f}ms")
  
  # 各阶段耗时
  for stage, duration in summary['performance']['stage_timings_ms'].items():
      percentage = summary['performance']['stage_percentages'].get(stage, 0)
      print(f"{stage}: {duration:.1f}ms ({percentage:.1f}%)")
  
  # 查询分析信息
  query_info = summary['query_analysis']
  print(f"原查询: {query_info['original_query']}")
  print(f"重写查询: {query_info['rewritten_query']}")
  print(f"检测语言: {query_info['detected_language']}")
  ```
  
  ### 2. 识别性能瓶颈
  
  ```python
  summary = context.get_summary()
  
  # 找出耗时超过20%的阶段
  bottlenecks = []
  for stage, percentage in summary['performance']['stage_percentages'].items():
      if percentage > 20:
          bottlenecks.append((stage, percentage))
  
  if bottlenecks:
      print("性能瓶颈:")
      for stage, percentage in bottlenecks:
          print(f"  - {stage}: {percentage:.1f}%")
  ```
  
  ### 3. 自动性能日志
  
  RequestContext会在以下时机自动记录详细的性能摘要日志：
  
  - 上下文管理器退出时 (`with context:`)
  - 手动调用 `context.log_performance_summary()`
  - Searcher.search() 完成时
  
  日志格式示例：
  ```
  [2024-01-01 10:30:45] [INFO] [request_context] 搜索请求性能摘要 | reqid: req-001 | 总耗时: 272.6ms | 阶段耗时: |   - query_parsing: 35.3ms (13.0%) |   - elasticsearch_search: 146.0ms (53.6%) |   - result_processing: 18.6ms (6.8%) | 查询: '红色连衣裙' -> '红色 女 连衣裙' (zh) | 结果: 156 hits ES查询: 2456 chars
  ```
  
  ## 线程安全
  
  RequestContext是线程安全的，支持并发请求处理。每个请求使用独立的context实例，互不干扰。
  
  ```python
  import threading
  from context import create_request_context
  
  def worker(request_id, query):
      context = create_request_context(request_id)
      # 搜索逻辑
      # context自动跟踪此线程的请求
      pass
  
  # 多线程并发处理
  threads = []
  for i in range(5):
      t = threading.Thread(target=worker, args=(f"req-{i}", f"query-{i}"))
      threads.append(t)
      t.start()
  
  for t in threads:
      t.join()
  ```
  
  ## 调试支持
  
  ### 1. 检查中间结果
  
  ```python
  # 获取查询解析结果
  parsed_query = context.get_intermediate_result('parsed_query')
  
  # 获取ES查询DSL
  es_query = context.get_intermediate_result('es_query')
  
  # 获取ES响应
  es_response = context.get_intermediate_result('es_response')
  
  # 获取原始搜索结果
  raw_hits = context.get_intermediate_result('raw_hits')
  
  # 获取最终处理后的结果
  processed_hits = context.get_intermediate_result('processed_hits')
  ```
  
  ### 2. 错误诊断
  
  ```python
  if context.has_error():
      error_info = context.metadata['error_info']
      print(f"错误类型: {error_info['type']}")
      print(f"错误消息: {error_info['message']}")
  
      # 检查是否有警告
      if context.metadata['warnings']:
          print("警告信息:")
          for warning in context.metadata['warnings']:
              print(f"  - {warning}")
  ```
  
  ## 最佳实践
  
  ### 1. 统一使用Context
  
  ```python
  # 推荐：在整个搜索流程中传递同一个context
  result = searcher.search(query, context=context)
  
  # 不推荐：在各个环节创建不同的context
  ```
  
  ### 2. 合理设置阶段边界
  
  ```python
  # 只在有意义的大阶段之间计时
  context.start_stage(RequestContextStage.QUERY_PARSING)
  # 整个查询解析逻辑
  context.end_stage(RequestContextStage.QUERY_PARSING)
  
  # 避免在细粒度操作间频繁计时
  ```
  
  ### 3. 及时存储关键数据
  
  ```python
  # 在每个阶段完成后及时存储结果
  context.store_intermediate_result('parsed_query', parsed_query)
  context.store_intermediate_result('es_query', es_query)
  
  # 便于后续调试和分析
  ```
  
  ### 4. 适当使用警告
  
  ```python
  # 使用警告记录非致命问题
  if total_hits < 10:
      context.add_warning("搜索结果较少，建议放宽搜索条件")
  
  if query_time > 5.0:
      context.add_warning(f"查询耗时较长: {query_time:.1f}秒")
  ```
  
  ## 集成示例
  
  ### API接口集成
  
  ```python
  from flask import Flask, request, jsonify
  from context import create_request_context
  
  app = Flask(__name__)
  
  @app.route('/search')
  def api_search():
      # 从请求中获取参数
      query = request.args.get('q', '')
      uid = request.args.get('uid', 'anonymous')
  
      # 创建context
      context = create_request_context(uid=uid)
  
      try:
          # 执行搜索
          result = searcher.search(query, context=context)
  
          # 返回结果（包含性能信息）
          response = {
              'results': result.to_dict(),
              'performance': context.get_summary()['performance']
          }
  
          return jsonify(response)
  
      except Exception as e:
          context.set_error(e)
          context.log_performance_summary()
  
          return jsonify({
              'error': str(e),
              'request_id': context.reqid
          }), 500
  ```
  
  ## 总结
  
  RequestContext提供了一个强大而灵活的框架，用于管理搜索请求的整个生命周期。通过统一的上下文管理、自动性能监控和详细的日志记录，它显著提升了搜索系统的可观测性和调试能力。
  
  主要优势：
  
  1. **统一管理**: 所有请求相关数据集中存储
  2. **自动监控**: 无需手动计时，自动跟踪性能
  3. **详细日志**: 完整的请求生命周期记录
  4. **向后兼容**: 现有代码无需修改即可受益
  5. **线程安全**: 支持高并发场景
  6. **易于调试**: 丰富的中间结果和错误信息
  
  通过合理使用RequestContext，可以构建更加可靠、高性能和易维护的搜索系统。