跳到主要内容

API 文档规范

本文档定义 api_docs 下各模块 API 文档的统一写作格式，便于前后端对接、排查与维护。新接口或修订时请按此规范编写。

1. 与《00-通用报错码》的关系​

文档职责关系
本规范（00-API文档规范.md）规定文档结构与写作格式：模块头部、接口条目、必选区块（描述、调用信息、请求参数、响应数据、错误码、示例）及用词约定。在「错误码」区块上，依赖《00-通用报错码》为唯一数据源。
00-通用报错码.md定义错误响应格式、报错码规则（RH + 5 位数字）及报错码对照表，是云函数返回 code / message 的唯一依据。被本规范及各模块 API 文档引用；模块文档不在本规范之外自造通用错误码。
  • 各模块文档的「错误码 (Error Codes)」区块：通用错误（鉴权、参数、权限、资源不存在、系统错误等）必须写「见 通用报错码」或等价引用，不得在模块内重复定义通用码。
  • 模块文档仅需列出该模块特有的报错码（若该码已在《00-通用报错码》中登记，可只写码+描述+解决方案，或直接写「见 通用报错码」）。
  • 新增报错时：在《00-通用报错码》对应区间内分配新编号并更新对照表，再在模块文档中引用或列出。

2. 文档整体结构​

每个模块对应一篇文档（如 01-用户.md），文档内按「模块说明 → 各接口详情」组织。

2.1 模块头部（必选）​

每个模块文档开头须包含：

# 模块名称：XXX (English Name)
> 此模块负责……（一句话说明模块职责）

---
  • 模块名称：中文名 + 英文名（括号内），与 README 中的「文档」列一致。
  • 引用块：用一句话概括该模块的职责，便于快速定位。

2.2 接口条目结构（每个接口一份）​

每个接口占一个二级标题，格式为：


---

## N. 接口简短名称 [GET|POST|PUT|DELETE]
  • N：该模块内的接口序号（1、2、3…）。
  • 接口名称：中文，能一眼看出用途（如「获取用户详情」「提交订单」）。
  • [HTTP 方法]：若云函数同时提供 HTTP 触发（如预拉取、回调），写实际方法；纯 callFunction 调用的可写 [GET] / [POST] 以区分读/写语义，或按项目约定省略。

3. 每个接口必须包含的区块​

以下区块建议全部保留，无内容时可写「无」或「见通用约定」。

3.1 接口描述（一段话）​

在标题下用一段话说明：谁在什么场景下调用、主要作用。

示例：

  • 「根据用户唯一 ID 获取其详细的公开资料。」
  • 「用户提交订单时调用，创建订单并返回订单号与支付参数。」

3.2 调用信息表（云函数 + 路由 + Action）​

项目说明示例
云函数名小程序侧 wx.cloud.callFunction({ name: 'xxx', data }) 的 nameuser、order
HTTP 路由（如有）仅当该云函数存在 HTTP 触发时填写；无则写「-」或「不适用」/v1/user/profile、/preload
动作类型 (Action)event.data.action 的值getUserInfo、createOrder
  • 云函数名、Action 必填；HTTP 路由仅在有 HTTP 触发时填。

3.3 请求参数 (Parameters)​

使用表格，列：参数名、类型、必选、默认值、描述、示例。

参数名类型必选默认值描述示例
userIdString是-用户唯一识别符“U12345”
scopeString否“base”返回范围: base / full“full”
  • 必选：是 / 否。
  • 默认值：无则写「-」。
  • 若参数在 event.data 的嵌套对象里，可用「data.xxx」或单独表格说明层级。

3.4 响应数据 (Response)​

成功情况：注明 HTTP 状态或「成功时」；用表格列出返回体结构。

字段名类型描述示例
codeInteger业务状态码，200 为成功200
dataObject业务主体数据-
data.nicknameString用户昵称“Gemini”
  • 与项目统一出参一致：{ success, data?, message? } 或 { code, data?, message? } 等，以实际约定为准。
  • 若有分页，需说明 data.list、data.total 等。

失败情况：见「错误码」区块，不必在响应表重复。

3.5 错误码 (Error Codes)​

  • 数据源：错误码以 通用报错码 为唯一数据源（格式 RH + 5 位数字，与云函数返回的 code 一致）。本接口区块仅列出模块特有错误，或整段写「见 通用报错码」。
  • 表格列：错误码（如 RHxxxxx）、描述、解决方案。
错误码描述解决方案
RH00006用户 ID 对应资源不存在检查 userId 或见 通用报错码
RH00302仅创建者可编辑该物品使用物品所属账号操作
  • 通用错误（如 RH00001 鉴权失败、RH00002 参数错误、RH00006 资源不存在等）不必在每篇模块文档中重复，写「见 通用报错码」即可。

3.6 示例 (Examples)​

小程序调用（callFunction）示例（必选）：

{
  "action": "getUserInfo",
  "data": {
    "userId": "U12345",
    "scope": "full"
  }
}
  • 对应 wx.cloud.callFunction({ name: 'user', data: { action: "getUserInfo", data: { ... } } }) 中的 data 部分。

HTTP 请求示例（仅当该接口有 HTTP 触发时提供）： 可写 Request URL、Method、Headers、Body 示例。

4. 格式与用词约定​

  • 表格：表头用 :--- 左对齐；列名简洁（参数名、类型、必选、描述等）。
  • 代码块：标明语言，如 json、javascript。
  • 专有名词：云函数名、action、集合名等用行内代码，如 user、getProfile。
  • 中英混排：模块名、接口名以中文为主，英文仅括号内或术语（如 Action、GET）。

5. 与现有文档的对应关系​

  • 现有文档（如 01-用户.md）多为「按 action 列表 + 简要说明」的索引形式。
  • 新写或大改的接口建议按本规范写成「一个接口一块」的完整条目；历史接口可在不破坏现有表格的前提下，逐步补全「请求参数 / 响应 / 错误码 / 示例」。
  • 云函数调用方式以 README 2.2 通用约定 为准：入参 event = { action, data? }，出参统一形状见 README。
  • 错误码：与 00-通用报错码 的关系见本文档开头「与《00-通用报错码》的关系」；所有 code（RHxxxxx）以该文档为准，模块文档只引用或补充模块特有码。

6. 单接口模板（复制即用）​


---

## N. 接口名称 [GET/POST]

**接口描述**：（一句话说明用途与场景。）

- **云函数名**：`xxx`
- **HTTP 路由**：`/path` 或 不适用
- **动作类型 (Action)**：`actionName`

### 请求参数 (Parameters)

| 参数名 | 类型 | 必选 | 默认值 | 描述 | 示例 |
| :--- | :--- | :--- | :--- | :--- | :--- |
|   |   |   |   |   |   |

### 响应数据 (Response)

成功返回 (Status: 200 OK / 成功时):

| 字段名 | 类型 | 描述 | 示例 |
| :--- | :--- | :--- | :--- |
|   |   |   |   |

### 错误码 (Error Codes)

通用错误见 [通用报错码](common-error-codes.md)。本接口特有（若有）：

| 错误码 | 描述 | 解决方案 |
| :--- | :--- | :--- |
|   |   |   |

### 示例 (Examples)

**Request Body (Cloud Function):**

```json
{
  "action": "actionName",
  "data": {}
}