koa3-demo/src/controllers/Page/README.md

BookmarkController 使用说明

概述

BookmarkController 是收藏网站的后端API控制器，提供了完整的收藏管理功能，包括CRUD操作、搜索、筛选、统计等。

API 接口

1. 收藏管理

获取收藏列表

GET /api/bookmarks?page=1&limit=12&category_id=1&tag_id=2&search=关键词&orderBy=created_at&orderDirection=desc

查询参数：

• page: 页码（默认1）
• limit: 每页数量（默认12）
• category_id: 分类ID（可选）
• tag_id: 标签ID（可选）
• search: 搜索关键词（可选）
• orderBy: 排序字段（默认created_at）
• orderDirection: 排序方向（默认desc）

响应示例：

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 12,
    "total": 50,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  },
  "total": 50
}

获取单个收藏

GET /api/bookmarks/:id

创建收藏

POST /api/bookmarks
Content-Type: application/json

{
  "title": "网站标题",
  "url": "https://example.com",
  "description": "网站描述",
  "category_id": 1,
  "tags": ["JavaScript", "React"],
  "links": [
    {
      "title": "链接标题",
      "url": "https://example.com/link",
      "type": "tutorial"
    }
  ]
}

更新收藏

PUT /api/bookmarks/:id
Content-Type: application/json

{
  "title": "更新后的标题",
  "description": "更新后的描述"
}

删除收藏

DELETE /api/bookmarks/:id

2. 搜索和筛选

搜索收藏

GET /api/bookmarks/search?query=关键词&limit=50&includeTags=true

按分类获取收藏

GET /api/bookmarks/category/:categoryId?limit=20

按标签获取收藏

GET /api/bookmarks/tag/:tagId?limit=20

3. 统计和快捷访问

获取统计信息

GET /api/bookmarks/stats

响应示例：

{
  "success": true,
  "data": {
    "total": 50,
    "favorites": 10,
    "totalClicks": 150,
    "categories": [...],
    "popularTags": [...]
  }
}

获取快捷访问数据

GET /api/bookmarks/quick-access

响应示例：

{
  "success": true,
  "data": {
    "favorites": [...],
    "recent": [...],
    "popular": [...]
  }
}

4. 收藏操作

增加点击次数

POST /api/bookmarks/:id/click

切换收藏状态

POST /api/bookmarks/:id/favorite

5. 批量操作

批量操作

POST /api/bookmarks/batch
Content-Type: application/json

{
  "operation": "delete",
  "bookmarkIds": [1, 2, 3],
  "data": {}
}

支持的操作类型：

• delete: 批量删除
• move: 批量移动分类
• tag: 批量更新标签

6. 分类和标签

获取所有分类

GET /api/categories

获取所有标签

GET /api/tags

获取热门标签

GET /api/tags/popular?limit=20

认证要求

所有API接口都需要用户登录认证。系统会自动从session中获取用户ID：

const userId = ctx.state.user?.id
if (!userId) {
    throw new CommonError("用户未登录")
}

错误处理

所有API都使用统一的错误处理格式：

{
  "success": false,
  "message": "错误描述信息"
}

常见HTTP状态码：

• 200: 请求成功
• 400: 请求参数错误或业务逻辑错误
• 401: 未认证（用户未登录）
• 500: 服务器内部错误

前端集成

前端JavaScript代码已经更新为使用这些API接口。主要变化：

1. 数据加载: 从模拟数据改为API调用
2. 分页处理: 使用后端返回的分页信息
3. 错误处理: 统一的错误处理和用户提示
4. 认证支持: 自动包含用户认证信息

使用示例

启动服务器

npm start

测试API

# 获取收藏列表
curl -X GET "http://localhost:3000/api/bookmarks" \
  -H "Cookie: your-session-cookie"

# 创建收藏
curl -X POST "http://localhost:3000/api/bookmarks" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"title":"测试收藏","url":"https://example.com"}'

注意事项

1. 用户认证: 确保用户已登录才能访问API
2. 数据验证: 所有输入数据都会进行验证
3. 错误处理: 前端需要处理API调用失败的情况
4. 分页: 大量数据使用分页加载，避免性能问题
5. 缓存: 考虑对分类和标签等静态数据进行缓存

扩展建议

1. API版本控制: 添加版本号支持（如 /api/v1/bookmarks）
2. 速率限制: 添加API调用频率限制
3. 缓存策略: 实现Redis缓存提升性能
4. 日志记录: 记录API调用日志用于监控
5. API文档: 使用Swagger等工具生成API文档