4. 数据结构选型：列表、字典、集合在合同数据存储中的应用、JSON与YAML格式解析

在构建合同版本比对系统时，选择合适的数据结构直接决定了代码的可读性、运行效率以及后续差异检测算法的复杂度。Python 内置的列表（list）、字典（dict）和集合（set）各自适用于不同的合同数据存储场景。同时，JSON 与 YAML 作为两种主流的序列化格式，在合同数据的持久化与交换中扮演着关键角色。

4.1 核心数据结构选型对比

下表从存储模型、查询效率、去重能力与典型合同场景四个维度，对比三种内置数据结构：

4.2 列表：有序条款序列与附件管理

合同条款通常具有明确的先后顺序，列表天然适合存储这类线性数据。在版本比对中，列表常用于保存解析后的条款文本序列，以便逐条进行差异检测。

# 示例：存储合同条款列表
clauses_v1 = [
    "1.1 甲方应于合同签订后5个工作日内支付预付款。",
    "1.2 乙方应在收到预付款后10个工作日内交付首批货物。",
    "2.1 任何一方违约，需向对方支付合同总金额10%的违约金。"
]

clauses_v2 = [
    "1.1 甲方应于合同签订后3个工作日内支付预付款。",
    "1.2 乙方应在收到预付款后15个工作日内交付首批货物。",
    "2.1 任何一方违约，需向对方支付合同总金额15%的违约金。",
    "3.1 本协议适用中华人民共和国法律。"
]

# 通过索引访问特定条款
print(clauses_v1[0])  # 输出：1.1 甲方应于合同签订后5个工作日内支付预付款。

4.3 字典：键值映射与元数据建模

字典是合同数据建模的核心工具。每个合同对象可以抽象为一个字典，键为字段名，值为对应的数据。在版本比对中，字典的键唯一性保证了每个字段只有一个值，便于直接比较新旧版本的同名字段。

# 示例：合同元数据字典
contract_meta_v1 = {
    "contract_id": "CT2024-001",
    "party_a": "北京科技有限公司",
    "party_b": "上海供应链有限公司",
    "total_amount": 500000.00,
    "sign_date": "2024-03-01",
    "clauses_count": 12
}

contract_meta_v2 = {
    "contract_id": "CT2024-001",
    "party_a": "北京科技有限公司",
    "party_b": "上海供应链有限公司",
    "total_amount": 550000.00,  # 金额变更
    "sign_date": "2024-03-15",  # 日期变更
    "clauses_count": 14
}

# 比对两个版本的差异字段
changed_fields = {}
for key in contract_meta_v1:
    if contract_meta_v1[key] != contract_meta_v2.get(key):
        changed_fields[key] = (contract_meta_v1[key], contract_meta_v2[key])

print(changed_fields)
# 输出：{'total_amount': (500000.0, 550000.0), 'sign_date': ('2024-03-01', '2024-03-15')}

4.4 集合：高效差异检测与去重

集合的哈希表实现使其在求交集、并集、差集时具有 O(min(len(s1), len(s2))) 的平均性能，非常适合快速定位新增、删除和未变的条款编号。

# 示例：使用集合快速计算条款变更
clause_ids_v1 = {"1.1", "1.2", "2.1", "3.1", "4.0"}
clause_ids_v2 = {"1.1", "1.2", "2.1", "3.2", "5.0"}

# 新增条款（在v2中但不在v1中）
added = clause_ids_v2 - clause_ids_v1
# 删除条款（在v1中但不在v2中）
removed = clause_ids_v1 - clause_ids_v2
# 未变条款（两个版本中都存在）
unchanged = clause_ids_v1 & clause_ids_v2

print(f"新增条款编号: {added}")    # {'5.0', '3.2'}
print(f"删除条款编号: {removed}")  # {'4.0', '3.1'}
print(f"未变条款编号: {unchanged}") # {'1.1', '1.2', '2.1'}

4.5 JSON 与 YAML 格式解析

合同数据通常以文件形式存储和交换。JSON 和 YAML 是两种最常用的序列化格式，Python 标准库和第三方库提供了成熟的解析支持。

4.5.1 JSON：通用性与标准解析

JSON 格式简洁、跨语言支持好，是 API 交互和配置文件的首选。Python 的 json 模块可以轻松实现字典与 JSON 字符串之间的转换。

import json

# 将字典序列化为 JSON 字符串
contract_data = {
    "contract_id": "CT2024-001",
    "clauses": [
        {"id": "1.1", "content": "预付款条款", "amount": 100000},
        {"id": "1.2", "content": "交付条款", "amount": 200000}
    ]
}

json_str = json.dumps(contract_data, ensure_ascii=False, indent=2)
print(json_str)

# 从 JSON 字符串反序列化为字典
parsed_data = json.loads(json_str)
print(parsed_data["contract_id"])  # 输出：CT2024-001

4.5.2 YAML：可读性与复杂结构

YAML 格式对人工读写更友好，支持注释、锚点和多行字符串，适合编写复杂的合同模板或配置规则。Python 需安装 PyYAML 库进行解析。

import yaml

# YAML 格式的合同模板示例
yaml_str = """
contract:
  id: CT2024-002
  template_version: 2.1
  parties:
    - role: 甲方
      name: 深圳科技有限公司
    - role: 乙方
      name: 广州物流有限公司
  clauses:
    - id: 1.1
      content: |
        甲方应于合同生效后
        10个工作日内支付预付款。
      amount: 300000
    - id: 1.2
      content: 乙方应在收到预付款后20个工作日内完成交付。
      amount: 500000
"""

# 解析 YAML 字符串为 Python 字典
parsed_yaml = yaml.safe_load(yaml_str)
print(parsed_yaml["contract"]["id"])  # 输出：CT2024-002
print(parsed_yaml["contract"]["clauses"][0]["content"])

4.6 数据结构与序列化格式协同架构

下图展示了在合同版本比对系统中，数据结构与序列化格式如何协同工作：

4.7 选型决策流程

在实际开发中，可以按照以下步骤快速确定数据结构：

1. 确定数据访问模式： 是否需要按键快速检索？→ 是则用字典；否则考虑列表。
2. 判断顺序重要性： 条款顺序是否影响比对结果？→ 是则用列表维护顺序，字典仅做辅助索引。
3. 识别去重需求： 是否需要快速判断元素是否存在或计算差异集？→ 是则用集合。
4. 选择序列化格式： 需要跨语言交换或 API 对接？→ 用 JSON；需要人工频繁编辑或复杂注释？→ 用 YAML。