02 · JSON、HTTP 与 API 契约

本站原创入门导读与合成教学示例。原始资料核实：2026-09-05。建议先读：01 · 用 Python 写出可重复的小实验。

理解概念

HTTP 请求由方法、地址、头部和正文组成。GET 通常读取资源，POST 提交数据；状态码描述传输结果，业务字段描述任务结果。收到 200 不代表答案可信，收到 429 通常需要减速而不是无限重试。

JSON 是数据格式，字符串用双引号，布尔值是 true/false，空值是 null；它不是可以执行的 Python 字典。接口契约约定字段、类型、必填项和限制。服务端必须再次验证输入，网页表单校验只改善体验。API Key 只放服务端环境变量，日志应脱敏。

一个最小例子

import json
raw = '{"title":"数学练习","minutes":25}'
task = json.loads(raw)
if not isinstance(task.get("title"), str):
    raise ValueError("title 必须是字符串")
# bool 在 Python 中是 int 的子类，这里要求精确类型
if type(task.get("minutes")) is not int or not 0 < task["minutes"] <= 180:
    raise ValueError("minutes 必须是 1–180 的整数")
print(json.dumps(task, ensure_ascii=False))

动手练习

分别用合法记录、缺少 minutes、minutes 为字符串、minutes 为 true 四种输入运行。写一张请求—预期响应表，并解释登录凭证为什么不能跟着截图公开。

验收与预期结果

仅合法记录通过；其余三类被明确拒绝。能区分 401 认证问题、403 权限问题、429 限流与 5xx 服务故障，且不把重试用于所有错误。

• 我能解释输入、过程与结果。
• 我保留了一个失败例与运行记录。

常见误区

把模型返回的字符串直接传给 eval 会执行代码。JSON 解析后仍需类型、范围和权限检查；只把 URL 改成兼容端点也不保证所有模型参数兼容。

延伸阅读

以下是相关方向的原始资料；本站练习不是官方课程作业或逐字翻译。

• Google · Gemini API · Function calling
• 阿里云百炼 · OpenAI-compatible DashScope API

课程状态与先修说明 · 核心术语