# To API

> 将当前需求上下文规划为接口清单：公开路由、内部入口、停用入口、对象图与跨接口 ID。适用于用户要求 to-api、出 API 清单或规划接口；不用于已实现功能的前端联调文档。

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

---


# To API

将当前可用的需求材料整理成接口规划契约 `API清单.md`。只整理需求材料、用户确认和当前适用 RULE 中已有的规则，不把经验、惯例、模板占位或代码现状补写成新规则。按模板成稿；对象图深度、接口数量、内部入口和停用入口以本次需求为准，没有的章节整节省略。

## 流程

### 1. 加载项目上下文

按项目知识协议使用相关 CONTEXT 与适用 RULE；已有知识足够时复用，知识不可用时说明缺口并继续。

### 2. 汇总需求来源

使用用户指定的需求来源；没有指定时，从当前对话和仓库中识别与接口规划直接相关的材料。来源可以是 PRD、其他需求文档、截图或当前对话。

根据需求目标确定本次规划的系统或服务范围；需求不涉及接口时停止并说明。

### 3. 收口接口形状

读取需求材料，对照规划范围内现有公开路由和内部调用，标成改造、新增、内部或停用：

- **改造 / 新增**：本期前端或其他外部调用方要打的业务路由
- **内部**：改变业务状态，但不对前端新增路由
- **停用**：现有公开路由本期下线

根据实际调用需要和项目约定选择路由、HTTP 方法与对象边界，优先复用语义一致的现有能力。业务操作和资源访问需求决定路由边界。

现有入口语义与需求不一致时说明差异，再确定改造或新增；只有需求或用户确认要求下线时才列为停用。平台已有且本期无需改造的能力记录为复用项。

已确认由现有返回数据支撑的页面内操作不增设路由；在场景调用中写清哪些 ID 来自已有响应，以及后续如何使用。

常规接口设计依据已确认需求和项目惯用法自行完成。缺失的业务取舍会改变对象边界、覆盖语义、失败结果或交付范围时定向提问；关键取舍相互依赖时围绕这些问题调用 `ask-me`。代码用于查证现状，不能据此新增需求规则。

**完成标准：** 每个拟写接口都有状态、调用方、主标识和对象图边界；每个前端场景都有接口顺序和跨接口 ID；未决的接口形状决策已关闭。

### 4. 拟稿并写入

用户指定输出路径时直接使用；已有对应需求目录时写入该目录的 `API清单.md`。否则写入 `docs/scratch/<下一个两位序号>-<中文需求名称>/API清单.md`。覆盖已有同名文件，无需询问是否发布。

按写法填入模板。公开接口按实际调用顺序编号，全部写在 `接口规划` 下；每个接口只选查询或命令一种小节集。

**完成标准：** 文件已写入目标位置；接口总表覆盖全部拟交付的公开、内部和停用入口；每个公开接口出现在至少一个场景；每条跨接口 ID 能在标识表中找到「谁产生 / 后续谁用」；写法每条均已落实。

## 写法

- **契约层**：写路由、业务对象、状态变化和跨接口 ID。代码只用来查证。分页外壳、鉴权参数、快照全字段和页面显隐不进正文。
- **结构对形状**：扁平且有规则的字段用两列表；嵌套用对象图，节点右侧标标识；列表响应按定位 / 展示 / 跳转分行，详情响应换对象图。请求只剩一个 ID 时写一句话。已确认的服务端判断写入「执行条件」。结构装不下的绑定规则紧跟其后，一句一条。
- **短语入格**：总表、标识表、场景表每格一个短语。场景顺序用 `→`。
- **副作用写全**：同一操作必须连续完成的多件事用有序列表，标题改为「成功副作用，同一业务操作内完成」。失败写触发条件、整批还是单条、留下什么，以及面向办理人的业务文案。成功是否返回业务对象必须写明。
- **不做打误读**：只列读者会以为本接口会做、实际不会做的事；已经写进请求、执行条件或副作用的不再单列，没有误读则整节省略。
- **标识一处定义**：对外资源与聚合边界写在资源与标识。标识表只收跨接口流转或易混的 ID。接口正文引用 ID，不重复定义。

## 模板

````markdown
# <功能名称> API 清单

## 文档用途

本文是接口规划契约，只回答三件事：

1. 本次对外暴露哪些接口、停用哪些接口、哪些能力根本不进 Controller。
2. 每个接口的调用方、标识、对象图边界、副作用和失败语义。
3. 接口之间传递哪些 ID，以及一次用户动作会打到哪些接口。

本文不是 Swagger / OpenAPI，不枚举快照字段、分页外壳和平台通用参数。字段级契约留给实现后的 API 文档；页面显隐、二次确认和节点裁剪留给前端与联调说明。

需求来源：<链接本次使用的需求材料；没有文档时简述需求来自当前对话>。本清单规划 <系统或服务范围>；<其他系统或角色> 是调用方。

## 资源与标识

<对外资源是什么。聚合是详情内部结构时，写明不按表拆 Controller。>

```text
<资源>                             <主标识>
├── <子资源>                       <id>
```

| 标识 | 含义 | 谁产生 | 后续谁用 |
| --- | --- | --- | --- |
| `<id>` | | | |

## 接口总表

| 状态 | 接口 | 调用方 | 用途 |
| --- | --- | --- | --- |
| 改造 / 新增 / 内部 / 停用 | `<METHOD> /...` 或内部能力名 | | |

平台通用能力继续复用，不写入本清单的交付接口：<实际复用项>。

## 场景调用

| 场景 | 接口顺序 | 跨接口数据 |
| --- | --- | --- |
| <角色 + 动作> | <入口> → <接口> | `<id>` |

<仅当页面内操作不发新请求时，补一句 ID 在首次详情结果中流转。>

## 接口规划

### 1. <查询接口业务名>

**`<METHOD> /path`**

<一句话：谁在什么入口调用，粒度是什么。>

#### 请求

| 字段 | 规则 |
| --- | --- |
| `<field>` | <必填或选填、匹配方式、与其他字段的约束> |

<仅当有请求里没有的默认过滤时，补一句固定范围。>

#### 响应

<开场一句：返回粒度和不含什么。>

- 定位：<后续请求或跳转要用的 ID>
- 展示：<列表可见字段，短语罗列>
- 跳转：<带哪个 ID 打开哪>

<!-- 详情把本节换成对象图，再补树装不下的绑定规则。 -->

#### 不做

- <读者可能以为在本接口里发生、实际没有的事。没有误读时删除本节。>

### 2. <命令接口业务名>

**`<METHOD> /path`**

<一句话：谁在什么入口调用。>

#### 请求

```text
<field>                    <规则>
<field>[]
├── <child>                <规则>
```

<!-- 扁平请求改用两列表。只剩一个 ID 时改成一句话，不要空表。 -->

#### 执行条件

<已确认且应由服务端判断的条件。没有独立条件时省略。>

#### 成功副作用

<状态迁移与同一操作内必须完成的事。成功是否返回业务对象。>

#### 失败

<触发条件、整批或单条、留下什么、面向办理人的业务文案。>

#### 不做

- <读者可能以为在本接口里发生、实际没有的事。没有误读时删除本节。>

## 内部入口

这些能力改变业务状态，但不对前端新增路由。

### <入口名>

<触发方、生成或迁移什么、不走哪条公开路由。>

<!-- 没有内部入口时删除本章。 -->

## 停用公开入口

| 现有路由 | 原因 |
| --- | --- |
| `<METHOD> /...` | <已确认的停用原因> |

<!-- 没有停用入口时删除本章。 -->
````