Files

2026-04-08 16:02:19 +08:00

5.1 KiB

Raw Blame History

name, description

name	description
api-doc-maintainer	当用户修改、新增或删除任何 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 文档包含以下章节：

# 模块名称 API

## Changelog
- YYYY-MM-DD: 变更说明

## 概述
功能说明、前置依赖

## 认证方式
（如需要）说明鉴权方式

## 通用响应格式
（引用统一响应格式即可）

## 接口列表
### 1. 接口名称
（按下方模板）

## 错误码说明
| 错误码 | HTTP 状态码 | 说明 | 触发条件 |

## 接入流程
典型业务场景的调用顺序

## 客户端示例
Cocos Creator TypeScript 调用代码

接口文档模板

根据接口类型智能选择模板，不需要填写不适用的字段。

查询类接口（GET，无请求体）

### 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"
}

字段说明：

字段	类型	必填	说明

成功响应示例：

{ "success": true, "data": { ... }, "message": null, "timestamp": "..." }

失败响应示例（如有特殊错误场景）：

{ "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 时间戳
}

更新工作流

当接口代码发生变更时，按以下步骤操作：

新增接口

在对应模块文档中按模板添加接口章节
从 Controller 读取路由路径和方法，从 DTO 读取参数定义
补充业务逻辑说明（来自 Service）
添加 Cocos Creator 调用示例
更新 Changelog
在 docs/api/README.md 索引中确认已注册

修改接口

对比代码变更，确定文档中哪些内容需要更新
更新受影响的字段：路径、参数、响应结构、业务逻辑
更新示例响应（确保与实际代码一致）
在 Changelog 中记录变更

删除接口

在文档中标记为「已废弃」并注明替代方案，或直接移除
更新索引
在 Changelog 中记录

错误码变更

在错误码表中新增/修改/删除条目
注明触发条件

完成后输出

文档更新完成后，向用户简要报告：

哪些文档被修改了
具体变更了什么内容
是否有需要客户端配合调整的地方

5.1 KiB Raw Blame History Unescape Escape