API 设计 × AI 生成

先冻结 REST 契约与 JSON 示例，再让 AI 生成路由与 handler。

AI CODING · 场景三 · API

契约是验收真源。curl 输出与示例不一致，就贴两端 JSON 纠偏——先别重构框架。

端点 3 只读验收 curl时间 半晚～一晚

开始本节 →

本节要点

• 状态码约定 + 可贴的实现 Prompt
• 四条 curl 验收命令与期望 JSON 片段
• 合格 / 漂移对照，知道何时打回

契约步骤curl对照自检

冻结契约

沿用 场景三总览 的三个 GET。再补状态码：

情况	状态码
成功	200 + JSON 数组/对象
未知 id	404 + error 体
非法 scene 查询	422 或 400 + error 体（二选一，写进合同后别变）

分层（写进给 AI 的 Prompt）：

路由：解析参数、调 service、返回 JSON
service：字段映射、业务规则（过滤、404）
repository：读写存储（本页可先内存）

跟做步骤

1. 把场景三总览的合同 + 字段对照表贴进仓库文档或本对话。
2. 贴下方给 AI 的 Prompt；先看复述（三端点示例是否一致）。
3. 确认后生成；本地起服务。
4. 跑「验收命令」四条；字段漂移用纠错卡，只贴两端 JSON。
5. 全绿后再进 数据库表设计。

给 AI 的 Prompt · 按契约实现

给 AI · Prompt · 只读 API

【目标】按契约实现 meal-scenes 列表、dishes 按 scene 过滤、dish 详情。
框架按仓库已有约定（如 FastAPI）；若无约定，选单一框架并写进 README。

【分层】
- 路由薄、业务在 service；SQL 不进路由文件

【字段】
- 附上与前端 Mock 的对照表（sceneId vs scene_id 等）
- 响应 JSON key 使用合同中的 camelCase 或统一一种并说明

【数据】
- 第一版可用内存列表；表结构下一页再接
- 至少 seed 出能演示主路径的数据（含 dish-tomato-egg / solo）

【不要】
- 鉴权、分页花活、微服务拆分、换语言
- 做成「阶段推荐」接口名（stages / recommendations）

【请你】
1. 复述三个端点的请求/响应示例
2. 列出将改动的文件
3. 等我确认后再写代码
4. 写完给出 curl 验收命令

验收命令（示例）

curl -s http://127.0.0.1:8000/api/meal-scenes | python -m json.tool | head
curl -s "http://127.0.0.1:8000/api/dishes?scene=solo" | python -m json.tool | head
curl -s http://127.0.0.1:8000/api/dishes/dish-tomato-egg | python -m json.tool | head
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/api/dishes/no-such-id

最后一条期望 404（或你合同写明的码）。

期望 JSON 片段（列表一项）

{
  "id": "dish-tomato-egg",
  "title": "番茄炒蛋",
  "summary": "番茄炒出汁，加一点糖提鲜；鸡蛋先炒再合。",
  "sceneId": "solo"
}

详情在列表字段基础上增加 body、reason、tip。若 curl 出现 rationale / hint，按漂移打回，对齐场景二 Mock。

对照：合格 vs 漂移

不合格示例 · 字段漂移

scene / sceneId 混用无说明；404 空 body 或 HTML 页；永远返回全表；路由里拼 SQL；又生成 stages / recommendations。

合格示例

key 与合同一致；404 有 error 体；按 scene 过滤生效；路由无 SQL；端点是 meal-scenes / dishes。

验收要点： 贴合同 JSON 与实际 curl 两端对照；不一致只改使二者对齐的最小处，先别重构框架。

纠错卡

给 AI · 纠错 · 字段漂移

【合同响应】（粘贴）
【实际 curl】（粘贴）
【请你】只改使二者对齐的最小处；不要重写框架。

联调前自检

• [ ] OpenAPI 或手写合同与 curl 一致
• [ ] 404/422 行为写明
• [ ] 与前端 Mock 对照表已贴进仓库文档
• [ ] 内存版可演示后，再换数据库（下一页）

下一页：数据库表设计 × AI。