# API Doc Infer

> 根据产品说明、页面描述、模块功能、数据库表结构、字段清单、业务规则推理出 RESTful API 接口设计文档，包含接口名称、HTTP 方法、路径、入参、出参、校验规则和 Mermaid 流程图。当用户提到"推理接口"、"设计接口"、"API 文档"、"接口设计"、"推断接口"、"帮我设计接口"、"推导 API"、"根据表结构生成接口"时使用此技能。也适用于用户给出页面、模块、表结构或碎片化需求，需要产出接口文档的场景。

- Skill: `xiaoweidotnet/api-doc-infer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add xiaoweidotnet/api-doc-infer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaoweidotnet/api-doc-infer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: xiaoweidotnet (https://skillmd.com/u/xiaoweidotnet)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaoweidotnet/api-doc-infer

---


# API 接口推理技能


## 目标

将零散的产品信息、模块描述和数据库表结构整理成完整的 RESTful API 接口设计文档。发现不确定问题时，立即通过 `AskUserQuestion` 向用户提问确认，确保最终文档中的所有内容都是已确认的。

## 输出规则

- 每个模块一个文档，保存到 `docs/api/` 目录
- 文件命名：`api-{模块英文名}.md`，如 `api-property.md`、`api-rental-demand.md`
- RESTful 风格：资源名用复数名词，路径以 `/api/` 为前缀
- 金额字段以**分**为单位（INT），避免浮点精度问题

## 工作流

按顺序执行以下步骤。遇到不确定的问题时，**立即使用 `AskUserQuestion` 向用户提问**（每次最多 4 个问题），等用户确认后再继续。不要把问题攒到文档末尾，确保最终文档中没有任何未确认的内容。

### 提问规则

- 发现不确定的推断、有歧义的字段含义、模糊的模块边界时，立即提问
- 将同一步骤中发现的多个问题收集起来，用一次 `AskUserQuestion` 批量提问（最多 4 个）
- 如果问题超过 4 个，分批提问
- 对于每个问题，提供 2-4 个可选答案（基于你的推断），并允许用户选择"其他"自由输入
- 用户的回答记录到文档的"已确认事项"章节中

### Step 1: 收集信息源

读取用户提供的材料，识别：
- 页面和用户操作
- 模块功能和业务动作
- 数据库表、字段、关联关系、枚举值和状态字段

然后检查 `docs/api/` 目录：

1. **读取公共规范文件**：查找 `docs/api/api-common.md`，获取统一的响应结构、分页参数、错误码规范、金额约定等。这些是全局约定，每个接口文档都必须遵循。如果该文件不存在，先生成它（模板见下方"公共规范文件模板"），再继续。
2. **读取已有模块文档**：如果 `docs/api/` 下已有其他模块文档，识别其命名约定、响应结构风格、字段命名模式，保持一致。

**检查点**：如果用户没有提供表结构或模块描述中的任何一个，询问是否有相关文档可以补充。

#### 公共规范文件模板

如果 `docs/api/api-common.md` 不存在，生成它，包含以下章节：

```markdown
# API 公共规范

## 1. 统一响应结构
{ code, message, data } 的完整定义，包含成功/失败/无数据返回的示例

## 2. 分页查询
请求参数（page/pageSize/sortBy/sortOrder）和响应结构（{ list, total, page, pageSize }）

## 3. 错误码规范
通用错误码（200/400/401/403/404/409/500）和业务错误码区间划分

## 4. 认证方式
token 携带方式（Authorization: Bearer <token>）

## 5. 通用字段约定
id/createdAt/updatedAt/deletedAt/status/createdBy/updatedBy 的类型和格式

## 6. 金额字段
统一以分为单位（Integer），前端展示时除以 100
```

内容从现有模块文档中提取模式（响应格式、分页结构、错误码等）。如果项目已有类似规范文件但命名不同，优先读取现有文件而非重新生成。

### Step 2: 确认模块边界

从材料中提取：
- 哪些实体属于本模块（是 Owner）
- 哪些操作属于本模块，哪些应委托给其他模块
- 特别注意：支付、分账、消息通知等跨模块操作

将提取的边界简要列出，如果存在不明确的边界，使用 `AskUserQuestion` 向用户提问确认。

### Step 3: 推理接口列表

将以下操作视为候选接口：
- 页面加载 → GET 列表/详情
- 表单提交 → POST 创建 / PUT 更新
- 状态流转 → POST `/resources/:id/actions/{action}`
- 删除 → DELETE（软删除）
- 查询/筛选 → GET 带查询参数

**合并规则**：只有当事务边界和响应结构完全相同时，才合并为一个接口。
**拆分规则**：当流程涉及支付、审核、状态流转时，拆分为独立接口。

> **注意**：不要以权限差异作为接口拆分或合并的依据。权限是业务逻辑，由后端 RBAC 系统控制，不属于接口定义。接口文档只关注契约本身：方法、路径、入参、出参、校验规则。

**辅助接口检查**：除了核心 CRUD，检查是否遗漏：
- 审核记录查询（如果有审核流程）
- 图片/附件上传和删除（如果有 `images` 或文件字段）
- 导出功能（如果模块描述提及导出）
- 管理端独立列表/详情（如果管理端和用户端的数据结构或业务流程不同）

使用以下接口总览表格式：

```markdown
| 序号 | 接口名称 | 方法 | 路径 | 触发页面/动作 | 说明 |
```

**检查点**：接口列表产出后，对照模块描述中的"关键功能"逐项核对，确认每个功能都有对应接口。缺失的补充，多余的标注理由。

### Step 4: 推理接口参数

**请求参数来源**：筛选项、表单字段、路径 ID、分页、排序、当前用户上下文。

**响应参数来源**：页面展示字段、表字段、业务计算值、关联摘要。

规则：
- 列表接口：默认包含 `page`(1)、`pageSize`(20)，从表结构中提取可筛选字段。响应返回 `{ list, total, page, pageSize }`（参照 `api-common.md` 的分页规范）
- 创建接口：排除 `id`、`created_at`、`updated_at`、`deleted_at` 等自动字段
- 更新接口：同创建，但所有字段非必填
- 详情接口：返回完整对象，可包含关联子资源（如审核记录、跟进记录）
- 状态字段用枚举值，在说明中列出可选值
- 不确定的字段标记为 `推断`，使用 `AskUserQuestion` 向用户确认

**检查点**：对于金额字段，确认单位是分还是元。schema 中 `INT UNSIGNED` 且 COMMENT 含"分"的，统一为分。

### Step 5: 补充校验与异常

为每个接口补充校验与异常表：

```markdown
| 场景 | 返回/处理 |
| --- | --- |
| 资源不存在 | 404，"xxx不存在" |
| 参数校验失败 | 400，具体失败原因 |
| 状态冲突（如重复操作） | 409，具体冲突原因 |
```

### Step 6: 补充 Mermaid 流程

只为**有业务逻辑的接口**生成流程图：
- 涉及多步骤的操作（审核、付费查看、提现）
- 涉及状态变更的操作
- 涉及外部系统调用的操作（支付、微信）

简单 CRUD 不需要流程图。

图表类型选择：
- **flowchart TD** — 表达业务决策分支（审核通过/驳回、支付成功/失败）
- **sequenceDiagram** — 表达多角色交互（用户、服务端、第三方）

保持 Mermaid 语法可执行；包含标点或复杂文本的节点名称使用引号。

### Step 7: 自检与保存

保存前逐项核对产出完整性：

- [ ] 公共规范：`docs/api/api-common.md` 已存在（不存在则先生成），且本文档顶部有引用链接
- [ ] 模块范围：适用端、涉及页面、关键假设均已填写
- [ ] 数据表映射：本模块涉及的表都已列出，关联关系正确
- [ ] 接口总览表：每个接口有方法、路径、触发场景
- [ ] 接口详情：每个接口有入参表、出参表、JSON 示例、业务规则、校验与异常表
- [ ] 公共字段去重：响应结构中的 `code`/`message`/`data` 包裹层和分页参数 `page`/`pageSize` 不在出参表中重复列出，而是在 JSON 示例中体现；只有 `data` 内部的业务字段才写入出参表
- [ ] 重要流程：涉及状态变更/支付/审核的接口有 Mermaid 图
- [ ] 待确认问题：所有不确定的问题都已通过 `AskUserQuestion` 向用户确认，文档中不存在未确认的内容
- [ ] 已确认事项：用户确认的关键决策已记录到文档的"已确认事项"章节

保存到 `docs/api/<模块英文名>.md`。除非用户明确要求重新生成，否则保留已有人工编写内容。

## 文档模板

每个模块文档严格使用以下结构：

```markdown
# {模块中文名} API

> 本文档遵循 [公共规范](api-common.md)，响应结构、分页参数、错误码等均以公共规范为准，不在本文档重复定义。

## 1. 模块范围
- 适用端：
- 涉及页面：
- 核心目标：
- 信息来源：
- 关键假设：

## 2. 数据表映射
| 表名 | 用途 | 关键字段 | 关联关系 |

## 3. 接口总览
| 序号 | 接口名称 | 方法 | 路径 | 触发页面/动作 | 说明 |

## 4. 接口详情
（每个接口包含：方法、路径、请求参数表、响应参数表、出举示例 JSON、业务规则、校验与异常表。不要为接口标注"权限：xxx角色"，权限属于业务逻辑，不在接口文档中定义。）

## 5. 重要流程
（Mermaid flowchart TD 或 sequenceDiagram）

## 6. 已确认事项
| 问题 | 确认结果 | 确认依据 |
（记录推理过程中通过 `AskUserQuestion` 向用户确认的关键决策和推断，确保文档中所有内容都有据可查）
```

## 命名规范

- 路径用小写连字符：`/api/rental-demands`
- 分页列表接口：GET `/api/resources`，含 `page`、`pageSize`、排序和筛选字段
- 详情接口：GET `/api/resources/:id`
- 创建：POST `/api/resources`
- 更新：PUT `/api/resources/:id`
- 删除：DELETE `/api/resources/:id`（软删除）
- 业务操作：POST `/api/resources/:id/actions/{action}`，如 `/api/properties/1/actions/submit-audit`

## 边界条件

| 场景 | 处理方式 |
|------|---------|
| 用户只给了表结构，没有模块描述 | 基于表名和字段 COMMENT 推理业务含义，在"关键假设"中标注推断来源 |
| 已有 `docs/api/` 文档存在 | 先读取既有文档的风格和约定，保持一致。除非用户要求重新生成 |
| 字段类型推断有歧义（如 TEXT 类型存 ID） | 使用 `AskUserQuestion` 向用户确认字段含义和类型，不猜测 |
| 模块涉及跨系统交互（支付、微信） | 只定义本模块的接口，跨系统交互在 Mermaid 流程图中用虚线标注 |
| 简单模块（只有查询，无 CRUD） | 不要强行添加 CRUD，只产出必要的接口。避免过度设计 |
| 金额字段类型不一致（有的 INT 有的 DECIMAL） | 统一在"关键假设"中说明选择理由 |