52 lines
2.1 KiB
Markdown
52 lines
2.1 KiB
Markdown
# API 兼容层策略
|
||
|
||
这份文档用于说明 DreamWeaver 求职版如何处理旧生成接口。目标不是立刻删除所有旧 API，而是把主线收敛到统一生成工作流，并让历史入口变成可迁移、可监控、可解释的兼容层。
|
||
|
||
## 背景
|
||
|
||
项目早期分别提供过普通故事、完整故事、绘本、封面生成和资产重试接口：
|
||
|
||
- `POST /api/stories/generate`
|
||
- `POST /api/stories/generate/full`
|
||
- `POST /api/storybook/generate`
|
||
- `POST /api/image/generate/{story_id}`
|
||
- `POST /api/stories/{story_id}/assets/retry`
|
||
|
||
这些接口都能工作，但对前端和面试讲解不够友好：故事、绘本和资产补全看起来像多条产品链路，容易掩盖真正的核心能力。
|
||
|
||
## 目标入口
|
||
|
||
求职版主入口统一为：
|
||
|
||
- `POST /api/generations`
|
||
- `GET /api/generations/{story_id}`
|
||
- `POST /api/generations/{story_id}/retry-assets`
|
||
- `GET /api/generations/jobs/{job_id}`
|
||
- `GET /api/generations/{story_id}/jobs`
|
||
- `GET /api/generations/{story_id}/provider-stats`
|
||
|
||
前端创建弹窗、绘本阅读器、故事详情页的资产重试应优先使用这些入口。
|
||
|
||
## 当前策略
|
||
|
||
1. 保留旧接口，避免破坏已有测试和潜在调用方。
|
||
2. 旧接口内部继续复用同一套 service workflow，不复制业务逻辑。
|
||
3. 旧接口响应增加迁移提示 header：
|
||
- `Deprecation: true`
|
||
- `X-DreamWeaver-Successor-Endpoint: <target>`
|
||
- `Link: <target>; rel="successor-version"`
|
||
4. 新前端不再新增对旧生成接口的依赖。
|
||
|
||
## 删除条件
|
||
|
||
旧接口可以在同时满足以下条件后删除：
|
||
|
||
- 用户端和管理端都已切到 `/api/generations`。
|
||
- smoke 脚本只依赖统一入口。
|
||
- 后端测试覆盖统一入口的故事、绘本、资产重试和失败降级。
|
||
- 至少一个迭代周期没有发现旧接口新增调用。
|
||
|
||
## 面试表达
|
||
|
||
我不会为了“代码看起来干净”直接删掉旧接口，因为这会引入不可见风险。更稳妥的做法是先定义目标 API，再把旧入口降级为带迁移信号的兼容层，最后通过测试和调用方收敛来决定删除时机。
|