题目元数据的结构化设计：JSON Schema 在算法题库管理中的应用

题目元数据的结构化设计：JSON Schema 在算法题库管理中的应用

一、深度引言与场景痛点：当题库越来越大，维护成本指数级增长

刚开始做刷题系统时，题库只有 20 道题。题目的元数据（标题、描述、难度、标签、测试用例）直接硬编码在 Java 代码里，用一个 enum 就解决了。但随着题库膨胀到 200 道题以上，噩梦开始了：

• 新增一道题需要修改 Java 代码、重新编译、重新部署。运营同学想加题？找开发。
• 同一道题需要同时维护中文和英文版本，两个版本的一致性无法保证。
• 测试用例的格式没有约束。有人写 [1,2,3]，有人写 1 2 3，解析逻辑越来越复杂。
• 题目之间的关系（前置题、相似题、进阶题）散落在各处，无法结构化查询。

这些问题的根源在于：缺乏统一的元数据模型和校验机制。而 JSON Schema 恰好是解决这类问题的标准工具。

二、底层机制与原理深度剖析

JSON Schema 是一套用于描述 JSON 数据结构的规范语言。它的核心价值有三个：

下面是我们为算法题目设计的 JSON Schema 核心结构：

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://oj.example.com/schemas/problem.schema.json",
"type": "object",
"required": ["id", "title", "difficulty", "content", "testCases"],
"properties": {
"id": {}
}
}

关键设计理念：题目元数据与业务逻辑解耦。开发不再需要为每道题写代码，运营可以自助管理题库。

三、生产级代码实现与最佳实践

题目 Schema 的完整定义

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "算法题目元数据",
"type": "object",
"required": ["id", "title", "difficulty", "description", "testCases"],
"properties": {
"id": {
"type": "string",
"pattern": "^P[0-9]{4}$",
"description": "题目唯一标识，格式 P0001 ~ P9999"
},
"title": {
"type": "string",
"minLength": 5,
"maxLength": 100,
"description": "题目标题"
},
"difficulty": {
"type": "string",
"enum": ["EASY", "MEDIUM", "HARD"],
"description": "题目难度等级"
},
"tags": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true,
"minItems": 1,
"maxItems": 10,
"description": "题目标签，至少 1 个最多 10 个，不可重复"
},
"testCases": {
"type": "array",
"items": {
"type": "object",
"required": ["input", "expectedOutput"],
"properties": {
"input": { "type": "string" },
"expectedOutput": { "type": "string" },
"isHidden": { "type": "boolean", "default": false },
"timeLimitMs": { "type": "integer", "minimum": 100, "default": 1000 }
}
},
"minItems": 1,
"maxItems": 50
},
"relatedProblems": {
"type": "array",
"items": {
"type": "object",
"required": ["problemId", "relation"],
"properties": {
"problemId": { "type": "string", "pattern": "^P[0-9]{4}$" },
"relation": {
"type": "string",
"enum": ["PREREQUISITE", "SIMILAR", "ADVANCED"]
}
}
}
}
}
}

Java 端校验实现

// Schema 校验服务 —— 统一入口，所有题目入库前必须通过此校验
@Service
public class ProblemSchemaValidator {

private final JsonSchema schema;
private final ObjectMapper objectMapper;

public ProblemSchemaValidator() throws Exception {
this.objectMapper = new ObjectMapper();

// 从 classpath 加载 Schema 定义文件
// 这样 Schema 版本可以独立于代码发布
String schemaContent = new String(
Files.readAllBytes(Path.of(
getClass().getClassLoader()
.getResource("schemas/problem.schema.json")
.toURI()
))
);

// 使用 networknt/json-schema-validator 库进行校验
JsonSchemaFactory factory = JsonSchemaFactory.getInstance(
SpecVersion.VersionFlag.V202012
);
this.schema = factory.getSchema(schemaContent);
}

public ValidationResult validate(String problemJson) {
try {
JsonNode node = objectMapper.readTree(problemJson);
Set<ValidationMessage> errors = schema.validate(node);

if (errors.isEmpty()) {
return ValidationResult.success();
}

// 将校验错误翻译为人类可读的中文信息
// 这样运营同学能清楚知道哪里填错了
List<String> humanReadableErrors = errors.stream()
.map(this::translateErrorMessage)
.collect(Collectors.toList());

return ValidationResult.failure(humanReadableErrors);
} catch (JsonProcessingException e) {
return ValidationResult.failure(
List.of("JSON 格式解析失败: " + e.getMessage())
);
}
}

// 将英文校验信息转换为运营人员能理解的中文提示
private String translateErrorMessage(ValidationMessage msg) {
// 核心思路：把技术性的校验信息翻译为业务语义
String path = msg.getPath();
String keyword = msg.getKeyword();

return switch (keyword) {
case "required" -> String.format(
"字段 `%s` 为必填项，当前缺少该字段", path
);
case "enum" -> String.format(
"字段 `%s` 的值不在允许范围内", path
);
case "minLength" -> String.format(
"字段 `%s` 的长度不足，需要至少 %d 个字符",
path, msg.getArguments().get("minLength").intValue()
);
case "pattern" -> String.format(
"字段 `%s` 的格式不符合要求，请检查格式规范", path
);
default -> String.format("字段 `%s` 校验失败: %s", path, msg.getMessage());
};
}
}

# Python 端批量导入题目的脚本 —— 支持从 Markdown 自动生成题目 JSON
import json
import re
from pathlib import Path
from jsonschema import validate, ValidationError

# 加载 Schema（与 Java 端使用同一份定义，保证校验一致性）
SCHEMA_PATH = Path(__file__).parent / "schemas" / "problem.schema.json"
with open(SCHEMA_PATH) as f:
SCHEMA = json.load(f)

def parse_problem_from_markdown(md_path: str) -> dict:
"""从 Markdown 文件解析题目元数据

Markdown 格式约定：
# P0001 两数之和
– 难度: EASY
– 标签: 数组, 哈希表

## 题目描述
…

## 测试用例
– 输入: [2,7,11,15], 9 → 输出: [0,1]
"""
content = Path(md_path).read_text(encoding="utf-8")

# 解析标题行
title_match = re.match(r"^# (P\\d{4})\\s+(.+)$", content, re.MULTILINE)
if not title_match:
raise ValueError(f"无法解析题目 ID 和标题: {md_path}")
problem_id, title = title_match.groups()

# 解析难度和标签
difficulty = re.search(r"难度:\\s*(EASY|MEDIUM|HARD)", content).group(1)
tags_line = re.search(r"标签:\\s*(.+)$", content, re.MULTILINE).group(1)
tags = [t.strip() for t in tags_line.split(",")]

return {
"id": problem_id,
"title": title,
"difficulty": difficulty,
"tags": tags,
"description": "…",
"testCases": […]
}

def batch_import(problems_dir: str):
"""批量导入题目目录下的所有 Markdown 文件"""
success, failed = 0, 0
for md_file in Path(problems_dir).glob("*.md"):
try:
problem = parse_problem_from_markdown(str(md_file))
validate(instance=problem, schema=SCHEMA) # Schema 校验
# 校验通过后，写入数据库或 JSON 文件
save_to_database(problem)
success += 1
except ValidationError as e:
print(f"[校验失败] {md_file.name}: {e.message}")
failed += 1
print(f"导入完成: 成功 {success} 道, 失败 {failed} 道")

四、边界分析与架构权衡

Schema 的版本管理

Schema 不是一成不变的。当需要新增字段（比如增加"题目来源"字段）时，需要考虑几个问题：

• 向后兼容：新字段应该设置为可选（非 required），这样旧数据不需要立即迁移
• 数据迁移：当字段从可选变必填时，需要提供默认值或批量回填脚本
• 消费者通知：判题服务、前端展示页面都是 Schema 的消费者，Schema 变更需要提前通知

为什么不直接用数据库表结构？

有人会问：既然数据最终存在数据库里，为什么不直接用数据库的 DDL 来约束字段？答案有三：

为什么不直接用 YAML？

YAML 对人类更友好，但在程序中处理时有几个坑：

• 缩进敏感，容易出现难以排查的格式错误
• yes/no 会被解析为布尔值 true/false
• 不像 JSON 那样有原生的 Schema 校验生态

五、总结

题目元数据的结构化设计看似是一个"细节问题"，但它直接决定了题库系统的可维护性。当题目数量从 20 道增长到 2000 道时，设计良好的元数据模型能让你保持从容。

JSON Schema 不是银弹，但它解决了题库管理中最核心的三个问题：格式统一、自动校验、自助管理。运营同学可以自己编写题目，提交后自动校验；开发不再需要为每道新题写模板代码；所有消费者都能信任数据的完整性。

如果只能给一个建议：从第一道题开始就用 Schema 约束。事后补 Schema 的成本，远远高于一开始就规范。