API与结构化校验：把模型输出当候选数据

接口是双方都遵守的约定

应用程序接口，通常简称API，是组件之间交换请求和结果的约定。星桥手作社材料接口可以要求输入活动编号、人数和每人用量，输出需求、缺口、说明和状态。字段名称、类型、必填项和错误含义必须明确。不能每次让模型自由决定输出今天是列表、明天是故事，因为界面与存储需要稳定结构。初学者可以先用纸面表格定义契约，再看简短代码，本课不发送任何网络请求。

能解析不代表可以使用

结构化输出常用JSON，但一段文本可以成功解析成JSON，并不表示内容合法。人数可能是字符串，数量可能为负，说明可能超过长度限制，必填字段也可能缺失。校验应分层：首先能否解析，其次字段和类型是否符合约定，再检查业务关系。例如需求必须等于人数乘以每人用量，缺口不能小于零。模型声称符合结构不算校验通过，必须由明确程序或人工规则判断。

读一个离线模拟例子

import json

def mock_model():
    return json.dumps({'needed': 20, 'missing': 2, 'note': '需补两张纸'})

data = json.loads(mock_model())
valid = (
    type(data.get('needed')) is int
    and type(data.get('missing')) is int
    and data['needed'] == 10 * 2
    and data['missing'] == max(0, 20 - 18)
    and isinstance(data.get('note'), str)
    and len(data['note']) <= 100
)
print('草案合格' if valid else '草案校验失败')

模拟函数只返回固定字符串，没有真实API、密钥或费用。解析把字符串变成字典，后续条件核对类型、算术和说明长度。严格整数检查避免把真假值误当数量。示例只演示校验核心，正式程序还应捕获解析失败并按接口返回错误状态，而不是让异常直接变成成功。

校验失败后不要无限修补

坏格式可以有限重试或转为人工确认，但不要不断把失败输出递给模型直到预算耗尽。重试时保留同一业务输入和明确错误，不能让模型改人数以迎合输出。涉及关键数字，优先由程序计算后交给模型表达，减少需要信任的生成部分。若说明文本包含特殊符号，网页展示应作为文本或正确转义，不直接当HTML执行。本课代码中的比较符号已经转义，页面仅展示代码，不承诺在页面运行。

建立四张接口测试卡

准备正常返回、缺字段、数量错误和无法解析四类模拟字符串，逐一写预期结果。正常返回可以作为草案，另外三类应有明确错误状态，不保存成正式记录。接口还要区分未授权、输入不合法和暂时失败，方便用户与日志理解。不要把HTTP或程序成功状态等同业务成功，拿到一个响应只是交换完成，是否能用于活动准备仍要通过约定的类型与业务验收。