ARCHITECTURE_REFACTOR.md 8.37 KB
Edit Raw Blame History


架构重构文档 - 简洁版配置架构
重构概述
本次重构实现了索引结构与搜索行为的完全分离，大幅简化了配置系统，提升了代码可维护性。
重构原则
1. 单一真相来源 (Single Source of Truth)

索引结构 → mappings/search_products.json（ES mapping）
搜索行为 → config/config.yaml（字段权重、搜索域）

2. 职责分离 (Separation of Concerns)


配置文件
职责
内容


mappings/search_products.json
索引结构定义
字段类型、analyzer、索引设置


config/config.yaml
搜索行为配置
字段权重、搜索域、查询策略


3. 配置简化 (Configuration Simplification)
移除冗余的字段定义，避免在多处维护相同信息。
架构变化
Before（旧架构）
config/
├── field_types.py          ← 定义 FieldType、AnalyzerType 枚举
│   ├── FieldConfig 类      ← 字段配置数据类
│   ├── get_es_mapping_for_field() ← 从配置生成mapping
│   └── FIELD_TYPE_MAP 等映射
├── config.yaml             ← 包含详细的字段定义
│   ├── fields:             ← 每个字段的类型、analyzer、boost
│   └── indexes:            ← 搜索域配置
└── config_loader.py        ← 解析字段定义并验证

mappings/
└── search_products.json    ← ES mapping（与config.yaml重复）

问题：
- config.yaml 和 mapping.json 需要保持同步
- FieldConfig 等大量冗余代码
- 修改索引结构需要同时改两个文件

After（新架构）
config/
├── config.yaml             ← 只配置搜索行为（简洁版）
│   ├── field_boosts:       ← 字段权重字典
│   └── indexes:            ← 搜索域配置
├── config_loader.py        ← 简化的配置加载器
└── utils.py                ← 从field_boosts读取权重

mappings/
└── search_products.json    ← 索引结构的唯一定义

优势：
✅ 索引结构只在mapping中定义一次
✅ 无需维护FieldConfig等冗余代码
✅ 配置文件更简洁易读
✅ 修改索引结构只需改mapping文件

删除的文件/代码
完全删除

config/field_types.py（341行）- 整个文件删除


FieldType 枚举
AnalyzerType 枚举
SimilarityType 枚举（死代码）
FieldConfig 数据类
get_es_mapping_for_field() 函数
FIELD_TYPE_MAP、ANALYZER_MAP 映射字典

indexer/data_transformer.py（329行）- 整个文件删除


旧的数据转换器，已被 spu_transformer.py 替代


大幅简化

config/config_loader.py


移除字段定义解析逻辑（_parse_field_config 方法）
移除字段验证逻辑
移除 fields: List[FieldConfig] 字段
添加 field_boosts: Dict[str, float] 字段
从 610行 → 约480行（简化21%）

config/config.yaml


移除详细的字段定义（type、analyzer、store等）
改为简洁的 field_boosts 字典
从 478行 → 143行（简化70%）


新架构示例
config.yaml（简洁版）
# 字段权重配置（用于搜索）
field_boosts:
  title_zh: 3.0
  brief_zh: 1.5
  description_zh: 1.0
  vendor_zh: 1.5
  tags: 1.0
  option1_values: 0.5
  option2_values: 0.5
  option3_values: 0.5

# 搜索域配置
indexes:
  - name: "default"
    label: "默认搜索"
    fields:
      - "title_zh"
      - "brief_zh"
      - "description_zh"
      - "vendor_zh"
      - "tags"
      - "option1_values"
      - "option2_values"
      - "option3_values"
    boost: 1.0

  - name: "title"
    label: "标题搜索"
    fields: ["title_zh"]
    boost: 2.0

# 查询配置
query_config:
  supported_languages: ["zh", "en"]
  enable_translation: true
  enable_text_embedding: true
  text_embedding_field: "title_embedding"

# SPU配置
spu_config:
  enabled: true
  spu_field: "spu_id"
  searchable_option_dimensions: ['option1', 'option2', 'option3']

mappings/search_products.json（索引结构）
{
  "mappings": {
    "properties": {
      "title_zh": {
        "type": "text",
        "analyzer": "hanlp_index",
        "search_analyzer": "hanlp_standard"
      },
      "option1_values": {
        "type": "keyword"
      }
    }
  }
}

代码改动统计


文件
改动类型
行数变化
说明


config/field_types.py
删除
-341
整个文件删除


indexer/data_transformer.py
删除
-329
旧transformer删除


config/config.yaml
重构
-335
从478→143行


config/config_loader.py
重构
-130
从610→480行


config/utils.py
重构
-18
简化逻辑


config/__init__.py
更新
-12
移除旧导出


api/routes/admin.py
更新
-1
num_fields→num_field_boosts


tests/conftest.py
更新
-23
适配新配置


总计

-1189行
代码量减少约30%


功能特性
Option值参与搜索
支持子SKU的option值参与搜索，通过配置控制：
# 配置哪些option参与搜索
spu_config:
  searchable_option_dimensions: ['option1', 'option2', 'option3']

# 配置option值的搜索权重
field_boosts:
  option1_values: 0.5
  option2_values: 0.5
  option3_values: 0.5


数据灌入：spu_transformer.py 自动从子SKU提取option值去重后写入索引。

在线搜索：自动将配置的option字段加入multi_match，应用配置的权重。
使用指南
1. 修改字段权重
只需修改 config/config.yaml：
field_boosts:
  title_zh: 4.0  # 提高标题权重
  option1_values: 0.8  # 提高option1权重

2. 添加新搜索域
只需在 config/config.yaml 中添加：
indexes:
  - name: "price"
    label: "价格搜索"
    fields: ["min_price", "max_price"]
    boost: 1.0

3. 修改索引结构
只需修改 mappings/search_products.json，然后重建索引：
python scripts/recreate_and_import.py --tenant-id 1 --recreate

4. 配置验证
配置加载时自动验证：
from config import ConfigLoader

loader = ConfigLoader()
config = loader.load_config(validate=True)  # 自动验证

兼容性说明
向后兼容
保留了 load_tenant_config() 函数，向后兼容旧代码：
# 旧代码仍然可用
from config import load_tenant_config
config = load_tenant_config(tenant_id="1")  # tenant_id参数被忽略

测试兼容
更新了 tests/conftest.py，所有测试fixture适配新配置结构。
迁移指南
从旧架构迁移
如果您有自定义配置文件，需要进行以下调整：
1. 简化字段定义
Before:
fields:
  - name: "title_zh"
    type: "TEXT"
    analyzer: "hanlp_index"
    search_analyzer: "hanlp_standard"
    boost: 3.0
    index: true
    store: true
    return_in_source: true


After:
field_boosts:
  title_zh: 3.0


字段结构定义移到 mappings/search_products.json。
2. 更新代码导入
Before:
from config import FieldConfig, FieldType, AnalyzerType


After:
# 不再需要这些导入
from config import SearchConfig, IndexConfig

优势总结
✅ 代码量减少30%（-1189行）

✅ 配置文件简化70%（config.yaml）

✅ 单一真相来源（索引结构只在mapping定义）

✅ 职责清晰（mapping定义结构，config定义行为）

✅ 更易维护（修改索引只需改一处）

✅ 更易理解（配置文件更简洁直观）

✅ 向后兼容（保留旧API接口）  
技术债务清理
本次重构清理了以下技术债务：


✅ 删除死代码（SimilarityType）
✅ 删除冗余代码（FieldConfig、get_es_mapping_for_field）
✅ 删除重复配置（config.yaml vs mapping.json）
✅ 删除旧transformer（data_transformer.py）
✅ 简化配置验证逻辑
✅ 统一配置管理接口

下一步改进建议

动态权重调整：支持在运行时动态调整字段权重
A/B测试支持：支持不同权重配置的A/B测试
权重优化工具：提供工具自动优化字段权重
配置热更新：支持配置热更新而不重启服务


重构日期: 2024-12-02

重构版本: v2.0

重构类型: 架构简化 & 技术债务清理