# [模块名称] - API设计

> **基础路径：** `/api/v1/模块名`  
> **端点数量：** X个  
> **认证要求：** JWT Token  
> **最后更新：** YYYY-MM-DD

---

## 📋 API概览

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/xxx/resources` | GET | 获取资源列表 | ✅ |
| `/api/v1/xxx/resources/:id` | GET | 获取资源详情 | ✅ |
| `/api/v1/xxx/resources` | POST | 创建资源 | ✅ |
| `/api/v1/xxx/resources/:id` | PUT | 更新资源 | ✅ |
| `/api/v1/xxx/resources/:id` | DELETE | 删除资源 | ✅ |

---

## 📚 API详细设计

### 1. 获取资源列表

**端点：** `GET /api/v1/xxx/resources`

**用途：** 获取当前用户的资源列表（分页）

**请求参数：**

**Query参数：**
```typescript
{
  page?: number;        // 页码，默认1
  pageSize?: number;    // 每页数量，默认10，最大100
  status?: string;      // 筛选：状态（active/inactive）
  keyword?: string;     // 搜索关键词
  sortBy?: string;      // 排序字段（createdAt/updatedAt）
  sortOrder?: 'asc' | 'desc';  // 排序方向，默认desc
}
```

**请求示例：**
```bash
GET /api/v1/xxx/resources?page=1&pageSize=10&status=active
Authorization: Bearer <token>
```

**成功响应：** `200 OK`
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "userId": 123,
        "fieldName": "示例",
        "description": "描述",
        "status": "active",
        "createdAt": "2025-11-06T10:00:00.000Z",
        "updatedAt": "2025-11-06T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 100,
      "totalPages": 10
    }
  },
  "message": "获取成功"
}
```

**错误响应：**
```json
// 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "未授权，请先登录"
  }
}

// 400 Bad Request
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "参数错误",
    "details": [
      { "field": "pageSize", "message": "最大不能超过100" }
    ]
  }
}
```

---

### 2. 获取资源详情

**端点：** `GET /api/v1/xxx/resources/:id`

**用途：** 获取指定资源的详细信息

**路径参数：**
- `id` (必填): 资源ID

**请求示例：**
```bash
GET /api/v1/xxx/resources/123
Authorization: Bearer <token>
```

**成功响应：** `200 OK`
```json
{
  "success": true,
  "data": {
    "id": 123,
    "userId": 456,
    "fieldName": "示例",
    "description": "详细描述",
    "status": "active",
    "createdAt": "2025-11-06T10:00:00.000Z",
    "updatedAt": "2025-11-06T10:00:00.000Z",
    // 额外的关联数据
    "user": {
      "id": 456,
      "name": "用户名"
    }
  },
  "message": "获取成功"
}
```

**错误响应：**
```json
// 404 Not Found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "资源不存在"
  }
}

// 403 Forbidden
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "无权访问此资源"
  }
}
```

---

### 3. 创建资源

**端点：** `POST /api/v1/xxx/resources`

**用途：** 创建新资源

**请求体：**
```json
{
  "fieldName": "资源名称",      // 必填，长度2-200
  "description": "描述",        // 可选，最大5000字
  "status": "active"            // 可选，默认active
}
```

**验证规则：**
- `fieldName`: 必填，2-200字符，不能包含特殊字符
- `description`: 可选，最大5000字符
- `status`: 可选，有效值：active, inactive

**请求示例：**
```bash
POST /api/v1/xxx/resources
Authorization: Bearer <token>
Content-Type: application/json

{
  "fieldName": "新资源",
  "description": "这是一个新资源"
}
```

**成功响应：** `201 Created`
```json
{
  "success": true,
  "data": {
    "id": 124,
    "userId": 456,
    "fieldName": "新资源",
    "description": "这是一个新资源",
    "status": "active",
    "createdAt": "2025-11-06T10:00:00.000Z",
    "updatedAt": "2025-11-06T10:00:00.000Z"
  },
  "message": "创建成功"
}
```

**错误响应：**
```json
// 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": [
      { "field": "fieldName", "message": "字段名称不能为空" },
      { "field": "fieldName", "message": "字段名称长度必须在2-200之间" }
    ]
  }
}

// 409 Conflict
{
  "success": false,
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "该资源已存在"
  }
}
```

---

### 4. 更新资源

**端点：** `PUT /api/v1/xxx/resources/:id`

**用途：** 更新指定资源（完整更新）

**路径参数：**
- `id` (必填): 资源ID

**请求体：**
```json
{
  "fieldName": "更新后的名称",
  "description": "更新后的描述",
  "status": "inactive"
}
```

**请求示例：**
```bash
PUT /api/v1/xxx/resources/123
Authorization: Bearer <token>
Content-Type: application/json

{
  "fieldName": "更新后的名称",
  "description": "更新后的描述"
}
```

**成功响应：** `200 OK`
```json
{
  "success": true,
  "data": {
    "id": 123,
    "fieldName": "更新后的名称",
    "description": "更新后的描述",
    "updatedAt": "2025-11-06T11:00:00.000Z"
  },
  "message": "更新成功"
}
```

**错误响应：**
```json
// 404 Not Found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "资源不存在"
  }
}

// 403 Forbidden
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "无权修改此资源"
  }
}
```

---

### 5. 删除资源

**端点：** `DELETE /api/v1/xxx/resources/:id`

**用途：** 删除指定资源（软删除）

**路径参数：**
- `id` (必填): 资源ID

**请求示例：**
```bash
DELETE /api/v1/xxx/resources/123
Authorization: Bearer <token>
```

**成功响应：** `200 OK`
```json
{
  "success": true,
  "data": null,
  "message": "删除成功"
}
```

**错误响应：**
```json
// 404 Not Found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "资源不存在"
  }
}

// 403 Forbidden
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "无权删除此资源"
  }
}

// 409 Conflict
{
  "success": false,
  "error": {
    "code": "CANNOT_DELETE",
    "message": "该资源有关联数据，无法删除"
  }
}
```

---

## 🔐 认证与权限

### 认证方式
所有API都需要JWT Token认证：
```
Authorization: Bearer <token>
```

### 权限检查
- 用户只能访问自己的资源
- ADMIN角色可以访问所有资源

---

## 📊 错误码汇总

| 错误码 | HTTP状态 | 说明 |
|--------|---------|------|
| UNAUTHORIZED | 401 | 未授权 |
| FORBIDDEN | 403 | 无权限 |
| NOT_FOUND | 404 | 资源不存在 |
| VALIDATION_ERROR | 422 | 参数验证失败 |
| ALREADY_EXISTS | 409 | 资源已存在 |
| INTERNAL_ERROR | 500 | 服务器错误 |

---

## 🚀 使用示例

### JavaScript/TypeScript
```typescript
// 获取资源列表
const response = await fetch('/api/v1/xxx/resources?page=1&pageSize=10', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});
const data = await response.json();

// 创建资源
const response = await fetch('/api/v1/xxx/resources', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fieldName: '新资源',
    description: '描述',
  }),
});
```

### cURL
```bash
# 获取列表
curl -X GET "http://localhost:3001/api/v1/xxx/resources?page=1&pageSize=10" \
  -H "Authorization: Bearer <token>"

# 创建资源
curl -X POST "http://localhost:3001/api/v1/xxx/resources" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"fieldName":"新资源","description":"描述"}'
```

---

## ⚠️ 注意事项

**性能优化：**
- 列表接口必须支持分页，默认pageSize=10，最大100
- 避免返回过多关联数据，按需加载
- 大量数据导出使用异步任务

**安全性：**
- 所有接口必须验证JWT Token
- 必须检查资源归属（用户只能操作自己的资源）
- 敏感字段不要返回（如密码）

**向后兼容：**
- API变更使用版本号（/api/v2）
- 不要删除已有字段，只能标记为deprecated
- 新增字段必须有默认值

---

## 🔗 相关文档

**规范：**
- [API设计规范](../../04-开发规范/02-API设计规范.md)
- [API路由总览](../../04-开发规范/04-API路由总览.md)

**数据库：**
- [本模块数据库设计](./01-数据库设计.md)

---

**最后更新：** YYYY-MM-DD  
**维护人：** 技术架构师














