---
type: template
template_id: API-Doc
tags:
  - 文档/API
status: design
created: {{date}}
updated: {{date}}
phase: 2025
attribute: 工程态
---

# 00.3｜API 文档母版

> [!summary] 接口基础信息
> * **时间阶段**：`2025` / `2026` (必填)
> * **文档属性**：`工程态` / `注册态` (必填)
> * **接口编号**：`API-XXXX`
> * **接口名称**：
> * **所属服务**：`前端` / `后端` / `算法服务`
> * **接口版本**：`Vx.x`
> * **维护人**：

---

## 1. 请求说明 (Request)

* **URL**: `/api/v1/resource/...`
* **Method**: `GET` / `POST` / `PUT` / `DELETE`
* **Content-Type**: `application/json`

### 1.1 Header 说明
| Key | Value | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| Authorization | Bearer token | 是 | 用户凭证 |

### 1.2 请求参数 (Body / Query)

| 参数名 | 类型 | 必填 | 示例值 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | String | 是 | "12345" | 资源 ID |
| `name` | String | 否 | "Test" | 名称 |

---

## 2. 返回说明 (Response)

### 2.1 成功响应示例 (HTTP 200)

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "12345",
    "status": "active"
  }
}
```

### 2.2 字段说明

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `code` | Number | 业务状态码 |
| `data` | Object | 业务数据 |

---

## 3. 错误码定义 (Error Codes)

| 错误码 (code) | 含义 | HTTP Status | 处理建议 |
| :--- | :--- | :--- | :--- |
| 40001 | 参数错误 | 400 | 检查参数格式 |
| 40100 | 未授权 | 401 | 跳转登录 |
| 50000 | 系统内部错误 | 500 | 联系管理员 |

---

## 4. 权限与安全

* **鉴权方式**：`Token` / `Cookie` / `API Key`
* **权限控制**：仅 `Admin` 角色可调用

---

## 5. 版本变更记录

| 版本 | 日期 | 变更人 | 变更内容 |
| :--- | :--- | :--- | :--- |
| V1.0 | {{date}} | | 初始版本创建 |