2. 量子算法封装的需求分析与接口设计

把量子算法封装成可复用组件，第一步不是写代码，而是把“谁在用、怎么用、用完得到什么”这三件事说清楚。需求分析决定封装边界，接口设计决定调用契约，两者共同决定这个组件能否被稳定集成到真实系统中。本节围绕用户场景识别、输入输出契约定义、版本兼容 API 规范三条主线展开，并给出可直接参考的接口设计示例。

一、识别用户场景：先分清谁在调用

量子算法组件的调用者通常不是同一类人。若不加区分，接口会同时承担“教学演示”和“生产调度”两种矛盾诉求。实践中可按调用深度分为三类典型场景：

• 算法研究者：关心哈密顿量、拟设结构、优化器与收敛曲线，需要暴露中间态与迭代信息，允许传入自定义算符。
• 应用开发者：只关心“给定问题数据，返回解或能量”，希望输入是经典数据结构（矩阵、列表、字典），输出是可直接消费的数值或比特串。
• 平台调度者：关心资源估算、后端选择、超时与重试，需要接口提供量子比特数、门深度、shots 等元信息，而不关心算法内部。

场景识别的产出不是文字描述，而是调用频次、输入规模、延迟容忍度、精度要求四类可量化约束。例如某组合优化组件，应用开发者场景要求单次调用返回近似最优解，延迟容忍 30 秒；平台调度场景要求先返回资源估算再决定是否提交。这两条约束会直接决定接口是否需要拆成“估算”和“执行”两个方法。

二、定义输入输出契约：把“约定”写成可校验的结构

契约的核心是：输入必须可校验，输出必须可解释。量子算法常见的输入包括问题规模、系数矩阵、约束条件、迭代参数、后端配置；输出包括最优值、解向量、测量计数、收敛状态、资源消耗。设计时应遵循三条原则：

1. 经典数据优先：输入尽量用经典可序列化结构（JSON、NumPy 数组、稀疏矩阵），避免要求调用者理解量子态表示。
2. 显式单位与约定：能量单位、比特顺序（大端/小端）、符号约定必须在文档和字段名中固定，不能依赖默认习惯。
3. 失败可判别：输出必须包含状态字段，区分“成功收敛”“达到迭代上限”“后端不可用”“输入非法”等情况，而不是仅返回一个数值。

下面给出一个组合优化封装组件的接口契约示例，采用 Python 类型注解表达，字段名与单位均显式声明：

from dataclasses import dataclass, field
from typing import Optional, Literal
import numpy as np

@dataclass
class QAOAInput:
    # 问题定义：QUBO 矩阵 Q，目标为 min x^T Q x，x ∈ {0,1}^n
    qubo: np.ndarray            # 形状 (n, n)，对称，单位：无量纲
    num_qubits: int             # n，必须与 qubo 维度一致
    p_layers: int = 1           # QAOA 层数，正整数
    shots: int = 4096           # 测量次数，正整数
    optimizer: Literal["COBYLA", "SPSA", "ADAM"] = "COBYLA"
    max_iter: int = 200         # 经典优化最大迭代次数
    backend: str = "statevector_sim"  # 后端标识
    seed: Optional[int] = None  # 随机种子，None 表示不固定

@dataclass
class QAOAOutput:
    status: Literal["converged", "max_iter", "backend_error", "invalid_input"]
    best_bitstring: Optional[str]   # 比特顺序：索引 0 为最高位
    best_cost: Optional[float]      # 对应目标函数值，单位同 Q
    counts: Optional[dict]          # 测量计数，键为比特串
    iterations: int                 # 实际迭代次数
    resource_estimate: dict         # {"num_qubits": n, "depth": d, "shots": s}
    message: str = ""               # 失败时的可读说明

该契约中，status 是判别结果的关键；best_bitstring 明确约定索引 0 为最高位，避免大小端歧义；resource_estimate 让调度者在不执行的情况下也能读取资源信息。输入校验应在进入量子线路构造前完成，例如检查 qubo 是否对称、num_qubits 是否匹配、p_layers 是否为正，校验失败直接返回 invalid_input，不消耗后端资源。

三、版本兼容的 API 规范

量子算法封装面临一个特殊问题：底层 SDK（如 Qiskit、Cirq、PennyLane）版本迭代快，算法实现和接口都可能变化。若接口直接暴露底层对象，调用者会被迫跟随升级。因此 API 规范应做到接口稳定、实现可替换。

推荐采用语义化版本 MAJOR.MINOR.PATCH，并明确兼容规则：

• MAJOR：输入输出契约发生不兼容变更，例如字段重命名、单位改变、status 取值集合变化。
• MINOR：新增可选字段或新增方法，旧调用仍可运行。
• PATCH：修复实现缺陷，不改变契约。

在实现层面，建议用适配器隔离底层 SDK：对外只暴露 QAOAInput/QAOAOutput，内部把输入转换为具体 SDK 的线路与算符。这样当 Qiskit 从 0.x 升级到 1.x 时，只需修改适配器，调用方代码不变。同时应在输出中携带 api_version 与 backend_version，便于排障时定位是接口问题还是后端问题。

四、从需求到接口的映射关系

三类用户场景与接口要素并非一一对应，而是交叉影响。下图给出本节核心关系的可视化：左侧是场景约束，中间是契约要素，右侧是版本规范，箭头表示约束如何传导到接口设计。

图中左侧三类场景分别向中间契约传导不同约束：研究者场景要求输出携带迭代信息，开发者场景要求输入输出为经典结构，调度场景要求输出含资源估算。中间契约的稳定性又决定右侧版本策略：字段与状态集合一旦固定，变更即触发 MAJOR；新增可选字段走 MINOR；实现修复走 PATCH。适配器层则保证底层 SDK 升级不穿透到调用方。

五、接口设计中的常见陷阱

实际封装中，以下问题最容易导致集成失败：其一，把量子态或线路对象直接作为输入输出，调用方被迫依赖特定 SDK；其二，能量单位不声明，调用方误把 Hartree 当 eV；其三，比特顺序未约定，同一比特串在不同后端解释相反；其四，失败时抛出底层异常而非返回状态字段，调度层无法区分“输入错误”和“后端超时”。规避方式是在契约层统一收口：输入只接受经典可序列化结构，输出只返回带状态的经典结构，所有单位、顺序、取值集合写入文档并在校验中强制执行。