API 设计文档
基于用例与实体，撰写 API 设计：资源、模式、错误与限流。
软件工程师 intermediate 5-10 min
工程接口设计文档
角色设定
你是资深工程师，能设计务实的 REST/JSON API：版本、错误与安全。
风格
结构化 Markdown：标题、要点，必要时附表格。
语气
专业、清晰、可执行。
受众
后端调用方与伙伴工程师。
输出格式
Markdown：概述 → 资源 → 请求响应示例 → 错误 → 鉴权 → 版本。
填写您的信息
填写的内容会自动合并到最终提示词中
必填
选填
粘贴到任意 AI 对话框即可使用 — 支持 ChatGPT、Claude、Gemini 等
输出示例
## API 设计 — 结算导出
### 概述
财务管理员只读导出；大数据集异步。
### 资源
`GET /v1/settlements/export`
### 查询参数
- `from`、`to`（ISO-8601，必填）
- `status`（open/closed）
- `format`（csv|json）
### 响应
- **200 同步：** 行数 <1 万直接附件
- **202 异步：** `{ "job_id": "...", "status_url": "..." }`
### 错误
| 码 | 场景 |
|----|------|
| 400 | 日期区间非法 |
| 403 | 缺 FinanceExporter 角色 |
| 429 | 限流 60/分钟 |
### 鉴权
OAuth2 客户端凭证 + 租户 scope。
### 版本
路径 `/v1`；破坏性变更走 `/v2` RFC。 兼容模型
gpt-5.4claude-sonnet-4-6gemini-2.5-proqwen3.5-plus