# Backend API Contract

> 从 Java/Spring 等后端项目的 Controller 或等价路由层快速导出无状态接口索引，只记录 HTTP 方法、完整路径、处理方法、参数/返回类型名称、明确权限注解和源码位置。用于生成精简 JSON、YAML 或 Markdown 接口资料供其他项目导入；不展开 DTO、不追踪 Service、不判断业务是否完成、不推断未声明接口，也不判断前端实现状态。

- Skill: `rayekry777/backend-api-contract` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add rayekry777/backend-api-contract`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rayekry777/backend-api-contract/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Rayekry777 (https://skillmd.com/u/rayekry777)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rayekry777/backend-api-contract

---


# 后端 Controller 接口索引

只提取路由层的客观声明。默认只读展示；用户要求导出时再写 JSON、YAML 或 Markdown。

## 扫描

- 只扫描 Controller 或框架等价路由文件，不读取 DTO 内容、Service、Repository 和数据库。
- 合并类级与方法级路径，记录 HTTP 方法、处理方法、参数类型名称、返回类型名称、明确权限注解和 `文件:行号`。
- 类型只保留源码中出现的名称，不展开字段，不从命名猜业务含义。
- Controller 没写的接口无法发现；不得把“未扫描到”解释为未实现、计划新增或不存在。

Java/Spring 按 [Spring Controller 扫描](references/spring.md) 执行。其他框架使用等价路由声明。

## 输出

用户未指定格式时使用紧凑 JSON：

```json
{"endpoints":[{"method":"GET","path":"/api/items","handler":"ItemController.list","requestType":"ItemQuery","responseType":"PageResult<ItemVO>","auth":"LoginRequired","source":"ItemController.java:42"}]}
```

也可输出 YAML 或 Markdown：

| Method | Path | Handler | Request type | Response type | Auth | Source |
|---|---|---|---|---|---|---|

不添加 `implemented`、`missing`、`unknown` 等状态，不输出前端建议，不补写 Controller 中没有的信息。