195 lines
5.1 KiB
Markdown
195 lines
5.1 KiB
Markdown
---
|
||
name: api-doc-maintainer
|
||
description: >
|
||
当用户修改、新增或删除任何 API 接口时，同步更新 docs/api/ 下的 Markdown 文档。
|
||
触发场景：修改 Controller、DTO、Service 中的接口逻辑或参数，新增/删除 endpoint，
|
||
变更响应结构，添加错误码。只要涉及 src/modules/*/ 下的接口代码改动，都应触发此技能。
|
||
---
|
||
|
||
# API 文档维护技能
|
||
|
||
## 为什么文档同步如此重要
|
||
|
||
MemeMind 的客户端是 Cocos Creator 小游戏，客户端开发者依赖 `docs/api/` 下的文档来接入后端接口。文档滞后意味着客户端开发者要去读源码才能对接，这会严重拖慢开发节奏。所以每次接口变更，文档必须同步更新。
|
||
|
||
## 代码结构索引
|
||
|
||
在更新文档前，先确认变更涉及哪些文件：
|
||
|
||
```
|
||
src/modules/
|
||
├── auth/ # 认证模块：wx-login、user assets、game-data
|
||
│ ├── auth.controller.ts
|
||
│ ├── dto/
|
||
│ └── auth.service.ts
|
||
├── wechat-game/ # 游戏模块：levels、configs
|
||
│ ├── wechat-game.controller.ts
|
||
│ ├── dto/
|
||
│ └── wechat-game.service.ts
|
||
└── share/ # 分享挑战模块：创建分享、加入、进度上报
|
||
├── share.controller.ts
|
||
├── dto/
|
||
└── share.service.ts
|
||
```
|
||
|
||
Controller 定义了路由和参数，DTO 定义了请求/响应的数据结构，Service 包含业务逻辑。三者共同决定文档内容。
|
||
|
||
## 文档存放与组织
|
||
|
||
文档统一放在 `docs/api/` 目录下，按功能模块分文件：
|
||
|
||
| 模块 | 文档文件 | 对应代码 |
|
||
|------|----------|----------|
|
||
| 用户认证 | `auth-api.md` | `src/modules/auth/` |
|
||
| 游戏关卡 | `game-api.md` | `src/modules/wechat-game/` |
|
||
| 分享挑战 | `share-challenge-api.md` | `src/modules/share/` |
|
||
| 排行榜 | `leaderboard-api.md` | （预留） |
|
||
|
||
新增模块时，创建对应的文档文件并在 `docs/api/README.md` 中注册索引。
|
||
|
||
## 文档结构
|
||
|
||
每个模块的 API 文档包含以下章节：
|
||
|
||
```markdown
|
||
# 模块名称 API
|
||
|
||
## Changelog
|
||
- YYYY-MM-DD: 变更说明
|
||
|
||
## 概述
|
||
功能说明、前置依赖
|
||
|
||
## 认证方式
|
||
（如需要）说明鉴权方式
|
||
|
||
## 通用响应格式
|
||
（引用统一响应格式即可）
|
||
|
||
## 接口列表
|
||
### 1. 接口名称
|
||
（按下方模板）
|
||
|
||
## 错误码说明
|
||
| 错误码 | HTTP 状态码 | 说明 | 触发条件 |
|
||
|
||
## 接入流程
|
||
典型业务场景的调用顺序
|
||
|
||
## 客户端示例
|
||
Cocos Creator TypeScript 调用代码
|
||
```
|
||
|
||
## 接口文档模板
|
||
|
||
根据接口类型智能选择模板，不需要填写不适用的字段。
|
||
|
||
### 查询类接口（GET，无请求体）
|
||
|
||
```markdown
|
||
### N. 接口名称
|
||
|
||
**接口地址**：`GET /api/v1/{module}/{endpoint}`
|
||
|
||
**是否需要认证**：是/否
|
||
|
||
**路径参数**（如有）：
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
|
||
**查询参数**（如有）：
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
|
||
**成功响应示例**：
|
||
```json
|
||
{ "success": true, "data": { ... }, "message": null, "timestamp": "..." }
|
||
```
|
||
|
||
**业务逻辑说明**：
|
||
- 规则 1
|
||
```
|
||
|
||
### 写入类接口（POST/PUT/PATCH/DELETE，有请求体）
|
||
|
||
```markdown
|
||
### N. 接口名称
|
||
|
||
**接口地址**：`POST /api/v1/{module}/{endpoint}`
|
||
|
||
**是否需要认证**：是/否
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"field": "value"
|
||
}
|
||
```
|
||
|
||
**字段说明**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
|
||
**成功响应示例**：
|
||
```json
|
||
{ "success": true, "data": { ... }, "message": null, "timestamp": "..." }
|
||
```
|
||
|
||
**失败响应示例**（如有特殊错误场景）：
|
||
```json
|
||
{ "success": false, "data": null, "message": "错误描述", "timestamp": "..." }
|
||
```
|
||
|
||
**业务逻辑说明**：
|
||
- 规则 1
|
||
```
|
||
|
||
如果某个字段（如路径参数、查询参数）不适用于当前接口，直接省略该小节。
|
||
|
||
## 统一响应格式
|
||
|
||
所有 API 响应使用统一包装：
|
||
|
||
```typescript
|
||
interface ApiResponse<T> {
|
||
success: boolean; // 请求是否成功
|
||
data: T | null; // 响应数据
|
||
message: string | null; // 错误信息（成功时为 null）
|
||
timestamp: string; // ISO 8601 时间戳
|
||
}
|
||
```
|
||
|
||
## 更新工作流
|
||
|
||
当接口代码发生变更时，按以下步骤操作：
|
||
|
||
### 新增接口
|
||
1. 在对应模块文档中按模板添加接口章节
|
||
2. 从 Controller 读取路由路径和方法，从 DTO 读取参数定义
|
||
3. 补充业务逻辑说明（来自 Service）
|
||
4. 添加 Cocos Creator 调用示例
|
||
5. 更新 Changelog
|
||
6. 在 `docs/api/README.md` 索引中确认已注册
|
||
|
||
### 修改接口
|
||
1. 对比代码变更，确定文档中哪些内容需要更新
|
||
2. 更新受影响的字段：路径、参数、响应结构、业务逻辑
|
||
3. 更新示例响应（确保与实际代码一致）
|
||
4. 在 Changelog 中记录变更
|
||
|
||
### 删除接口
|
||
1. 在文档中标记为「已废弃」并注明替代方案，或直接移除
|
||
2. 更新索引
|
||
3. 在 Changelog 中记录
|
||
|
||
### 错误码变更
|
||
1. 在错误码表中新增/修改/删除条目
|
||
2. 注明触发条件
|
||
|
||
## 完成后输出
|
||
|
||
文档更新完成后，向用户简要报告：
|
||
1. 哪些文档被修改了
|
||
2. 具体变更了什么内容
|
||
3. 是否有需要客户端配合调整的地方
|