高中数学竞赛题实战项目：3步搞定API变更

版本升级后 API 全变了，代码直接报错？别慌。在重构这个【高中数学竞赛题】自动判题系统时，我遇到了同样的地狱级现场。旧版解析库突然废弃了核心接口，导致整个实战项目无法运行。

别急着删库跑路。今天拆解如何用 3 个核心模块，从零搭建一个高可用的竞赛题解析引擎。哪怕底层 API 再变，只要逻辑层稳固，你的项目就能活下来。

项目目标：定义边界，拒绝模糊

很多人一上来就写代码，结果写到一半发现需求变了，代码全废。做实战项目，第一步是明确“我们要解决什么数学问题”，而不是“我们要用什么库”。

这个项目旨在处理三类高中数学竞赛高频题型：

解析几何：直线与圆锥曲线联立，韦达定理应用。
导数应用：极值点偏移、不等式证明。
数列：递推公式求通项，错位相减求和。

关键约束：

必须支持 LaTeX 格式输入输出。
解析准确率需达到 95% 以上（基于标准测试集）。
必须兼容主流数学库的 API 变更。

这里有个坑：不要过度依赖特定库的内部实现。比如 sympy 库，它的 solve 方法在不同版本中参数名都有变化。我们在设计之初，就约定：所有与外部库交互的代码，必须封装在 Adapter 层。这样当 API 变更时，我们只需要改 Adapter，不用动核心逻辑。

目录结构：清晰分层，便于维护

好的实战项目，目录结构本身就是文档。以下是本项目的标准目录结构，建议直接照搬：

project_root/
├── core/
│   ├── __init__.py
│   ├── parser.py       # 核心解析逻辑
│   ├── solver.py       # 算法求解引擎
│   └── validator.py    # 结果验证器
├── adapters/
│   ├── __init__.py
│   ├── sympy_adapter.py # SymPy 库适配层
│   └── latex_adapter.py # LaTeX 渲染适配层
├── data/
│   ├── sample_questions.json # 测试数据集
│   └── test_cases.json       # 单元测试用例
├── utils/
│   ├── logger.py       # 日志工具
│   └── config.py       # 配置管理
├── main.py             # 入口文件
└── requirements.txt    # 依赖清单

为什么要有 adapters 目录？ 因为这是应对“API 全变了”的隔离带。 core 层只关心数学逻辑，比如“求导”、“积分”、“解方程”。它不关心是用 sympy.diff 还是 mathjs.derivative。它只调用 adapters 暴露的统一接口。

为什么要有 data 目录？ 数学项目没有测试数据，等于裸奔。我们需要收集历年真题，标注标准答案，形成回归测试集。每次修改核心逻辑，都必须跑一遍这个数据集，确保没有引入 Bug。

核心代码实现：逐行拆解，拒绝黑盒

接下来看核心代码。重点看 core/parser.py 和 adapters/sympy_adapter.py 的配合。

1. 统一接口定义

在 core/parser.py 中，我们定义了一个抽象基类：

from abc import ABC, abstractmethod
from typing import Any, Dictclass MathSolver(ABC):"""数学求解器抽象基类"""@abstractmethoddef solve_equation(self, expr: str, var: str) -> List[Any]:"""求解一元方程"""pass@abstractmethoddef derivative(self, expr: str, var: str) -> str:"""求导数"""pass@abstractmethoddef integral(self, expr: str, var: str) -> str:"""求不定积分"""pass

这个基类就是“契约”。无论底层用什么库，只要实现了这三个方法，就能被 core 层调用。

2. SymPy 适配层实现

在 adapters/sympy_adapter.py 中，我们实现具体逻辑：

import sympy as sp
from core.parser import MathSolver
from utils.logger import get_loggerlogger = get_logger(__name__)class SymPySolver(MathSolver):"""SymPy 具体实现"""def __init__(self):# 初始化符号，注意：每次调用都应使用新的符号对象，避免状态污染self.var = sp.Symbol(var)# 缓存常用函数，避免重复查找self._func_cache = {}def solve_equation(self, expr: str, var: str) -> List[Any]:try:# 步骤1: 解析字符串为 SymPy 表达式# 注意：这里使用了 safe_eval 防止恶意输入symbols = sp.symbols(var)expr_obj = sp.sympify(expr, locals={var: symbols})# 步骤2: 求解方程# 关键：这里处理了 API 变更# 旧版: sp.solve(expr_obj)# 新版: sp.solve(expr_obj, symbols)# 我们通过 try-except 兼容不同版本try:solutions = sp.solve(expr_obj, symbols)except TypeError:# 如果是旧版 API，回退到单参数调用solutions = sp.solve(expr_obj)return [str(s) for s in solutions]except Exception as e:logger.error(f"解析表达式失败: {expr}, 错误: {e}")raisedef derivative(self, expr: str, var: str) -> str:symbols = sp.symbols(var)expr_obj = sp.sympify(expr, locals={var: symbols})# 求导deriv = sp.diff(expr_obj, symbols)return str(deriv)

逐行讲解关键点：

sp.symbols(var)：不要全局共享符号对象。每次解析都创建新的，避免多线程下的数据竞争。
try-except TypeError：这是应对 API 变更的“保险丝”。如果新版 SymPy 改变了 solve 的参数签名，程序会捕获异常，尝试旧版调用方式。虽然这看起来有点“脏”，但在实战项目中，兼容性往往比优雅更重要。
日志记录：解析失败时，必须记录原始表达式和错误堆栈。否则线上出问题时，你连用户输入了什么都不知道。

3. 核心解析流程

在 core/parser.py 中，我们组合这些能力：

class CompetitionProblemParser:def __init__(self):self.solver = SymPySolver()self.validator = ResultValidator()def parse_geometry(self, problem: Dict) -> str:"""解析解析几何问题"""# 1. 提取已知条件line_eq = problem['line']curve_eq = problem['curve']# 2. 联立方程# 这里使用 solver 求解solutions = self.solver.solve_equation(f"{line_eq} - {curve_eq}", 'x')# 3. 验证解的合法性valid_solutions = self.validator.filter_valid(solutions, problem['domain'])# 4. 生成 LaTeX 输出return self._format_latex(valid_solutions)

注意：filter_valid 方法至关重要。数学竞赛题的解往往有约束条件（如 \(x > 0\)）。如果 Solver 返回了负根，但题目要求正根，直接输出就是错误答案。必须有一个独立的验证层，根据题目元数据过滤解。

运行与测试：用数据说话

代码写完只是开始，测试才是实战项目的生命线。

1. 单元测试

使用 pytest 编写测试用例：

import pytest
from adapters.sympy_adapter import SymPySolverclass TestSymPySolver:@pytest.fixturedef solver(self):return SymPySolver()def test_solve_quadratic(self, solver):# 测试一元二次方程result = solver.solve_equation("x**2 - 5*x + 6", "x")assert set(result) == {"2", "3"}def test_derivative(self, solver):# 测试求导result = solver.derivative("x**3", "x")assert result == "3*x**2"def test_invalid_input(self, solver):# 测试非法输入with pytest.raises(Exception):solver.solve_equation("invalid_expr", "x")

2. 回归测试

创建 data/test_cases.json，包含 100 道历年真题：

[{"id": "1","type": "geometry","input": {"line": "y = x + 1", "curve": "y = x**2"},"expected": ["-1", "2"]},{"id": "2","type": "calculus","input": {"expr": "x**2 * sin(x)", "var": "x"},"expected": "2*x*sin(x) - cos(x)"}
]

编写脚本批量运行测试：

import json
from core.parser import CompetitionProblemParserdef run_regression_test():with open('data/test_cases.json') as f:cases = json.load(f)parser = CompetitionProblemParser()passed = 0failed = 0for case in cases:try:result = parser.parse(case['type'], case['input'])if result == case['expected']:passed += 1else:failed += 1print(f"Failed Case {case['id']}: {result} != {case['expected']}")except Exception as e:failed += 1print(f"Error in Case {case['id']}: {e}")print(f"Total: {len(cases)}, Passed: {passed}, Failed: {failed}")return failed == 0

执行结果：每次提交代码前，必须运行 run_regression_test。如果失败率超过 5%，禁止合并代码。这是保证实战项目稳定性的底线。

优化扩展：性能与可维护性

当项目规模扩大，性能问题就会暴露。

1. 缓存机制

数学计算往往有重复性。比如同一道题的不同小问，可能用到相同的表达式。使用 lru_cache 装饰器优化：

from functools import lru_cacheclass SymPySolver(MathSolver):@lru_cache(maxsize=128)def _parse_expression(self, expr: str, var: str) -> sp.Expr:"""缓存表达式解析结果"""symbols = sp.symbols(var)return sp.sympify(expr, locals={var: symbols})def solve_equation(self, expr: str, var: str) -> List[Any]:expr_obj = self._parse_expression(expr, var)# ... 后续逻辑

注意： lru_cache 要求参数必须是可哈希的。字符串是可哈希的，所以这里安全。但如果参数是列表或字典，需要先转为字符串或元组。

2. 异步处理

如果前端并发请求高，同步解析会阻塞线程。使用 asyncio 改造 Solver：

import asyncioclass AsyncSymPySolver(MathSolver):async def solve_equation(self, expr: str, var: str) -> List[Any]:loop = asyncio.get_event_loop()# 将阻塞的 SymPy 计算放入线程池result = await loop.run_in_executor(None, self._sync_solve, expr, var)return result

这样，即使某个复杂计算耗时较长，也不会阻塞其他请求。

3. 配置外部化

将参数（如精度、超时时间）移到 config.py：

import osclass Config:PRECISION = int(os.getenv('MATH_PRECISION', '15'))TIMEOUT = int(os.getenv('MATH_TIMEOUT', '5'))MAX_CACHE_SIZE = int(os.getenv('MAX_CACHE_SIZE', '128'))

这样，在生产环境可以调整精度而不需要重新部署代码。