shengyudong/yixiaogao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4fef65bd930b6ac88619d983c9539981db317a54
yixiaogao/backend/api/API接口文档.md
shengyudong 4fef65bd93 新版可用
2025-11-27 18:40:08 +08:00

8.8 KiB
Raw Blame History

📡 微信公众号文章爬虫 - API 接口文档

服务器信息

  • 服务地址: http://localhost:8080
  • 协议: HTTP/1.1
  • 数据格式: JSON
  • 字符编码: UTF-8
  • CORS: 已启用（允许所有来源）

统一响应格式

所有API接口返回格式统一为：

{
  "success": true,           // 请求是否成功
  "message": "操作成功",     // 提示信息
  "data": {}                 // 数据内容（可选）
}

接口列表

1. 提取公众号主页

接口地址: /api/homepage/extract
请求方法: POST
功能说明: 从文章链接中提取公众号主页链接

请求参数

{
  "url": "https://mp.weixin.qq.com/s?__biz=xxx&mid=xxx"
}
参数 类型 必填 说明
url string 是 公众号文章链接

响应示例

成功响应:

{
  "success": true,
  "message": "提取成功",
  "data": {
    "homepage": "https://mp.weixin.qq.com/mp/profile_ext?action=home&__biz=xxx&scene=124",
    "output": "完整的命令行输出信息"
  }
}

失败响应:

{
  "success": false,
  "message": "未能提取到主页链接"
}

调用示例

jQuery:

$.ajax({
    url: 'http://localhost:8080/api/homepage/extract',
    method: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        url: 'https://mp.weixin.qq.com/s?__biz=xxx&mid=xxx'
    }),
    success: function(response) {
        if (response.success) {
            console.log('主页链接:', response.data.homepage);
        }
    }
});

curl:

curl -X POST http://localhost:8080/api/homepage/extract \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mp.weixin.qq.com/s?__biz=xxx&mid=xxx"}'

2. 下载单篇文章

接口地址: /api/article/download
请求方法: POST
功能说明: 下载指定的单篇文章

请求参数

{
  "url": "https://mp.weixin.qq.com/s?__biz=xxx",
  "save_image": true,
  "save_content": true
}
参数 类型 必填 说明
url string 是 文章链接
save_image boolean 否 是否保存图片（默认false）
save_content boolean 否 是否保存内容（默认true）

响应示例

{
  "success": true,
  "message": "下载任务已启动",
  "data": {
    "url": "https://mp.weixin.qq.com/s?__biz=xxx"
  }
}

3. 获取文章列表

接口地址: /api/article/list
请求方法: POST
功能说明: 批量获取公众号的文章列表

请求参数

{
  "access_token": "https://mp.weixin.qq.com/mp/profile_ext?action=xxx&appmsg_token=xxx",
  "pages": 0
}
参数 类型 必填 说明
access_token string 是 包含appmsg_token的URL
pages integer 否 获取页数，0表示全部（默认0）

响应示例

{
  "success": true,
  "message": "任务已启动"
}

4. 批量下载文章

接口地址: /api/article/batch
请求方法: POST
功能说明: 批量下载公众号的所有文章

请求参数

{
  "official_account": "公众号名称或文章链接",
  "save_image": true,
  "save_content": true
}
参数 类型 必填 说明
official_account string 是 公众号名称或任意文章链接
save_image boolean 否 是否保存图片（默认false）
save_content boolean 否 是否保存内容（默认true）

响应示例

{
  "success": true,
  "message": "任务已启动"
}

5. 获取数据列表

接口地址: /api/data/list
请求方法: GET
功能说明: 获取已下载的公众号数据列表

请求参数

无

响应示例

{
  "success": true,
  "data": [
    {
      "name": "研招网资讯",
      "article_count": 125,
      "path": "D:\\workspace\\Access_wechat_article\\backend\\data\\研招网资讯",
      "last_update": "2025-11-27"
    }
  ]
}
字段 类型 说明
name string 公众号名称
article_count integer 文章数量
path string 存储路径
last_update string 最后更新时间

调用示例

jQuery:

$.get('http://localhost:8080/api/data/list', function(response) {
    if (response.success) {
        console.log('数据列表:', response.data);
    }
});

curl:

curl http://localhost:8080/api/data/list

6. 获取任务状态

接口地址: /api/task/status
请求方法: GET
功能说明: 获取当前任务的执行状态

请求参数

无

响应示例

任务运行中:

{
  "success": true,
  "data": {
    "running": true,
    "progress": 45,
    "message": "正在下载第10篇文章..."
  }
}

无任务运行:

{
  "success": true,
  "data": {
    "running": false,
    "progress": 0,
    "message": ""
  }
}
字段 类型 说明
running boolean 是否有任务运行中
progress integer 任务进度（0-100）
message string 任务状态描述
error string 错误信息（可选）

错误码说明

HTTP状态码

状态码 说明
200 请求成功
400 请求参数错误
500 服务器内部错误

业务错误码

所有业务错误通过响应中的 success 字段和 message 字段返回：

{
  "success": false,
  "message": "具体的错误信息"
}

常见错误信息：

错误信息 说明 解决方法
请求参数错误 JSON格式不正确或缺少必填参数 检查请求参数格式
执行失败 后端程序执行出错 查看详细错误信息
未能提取到主页链接 文章链接格式错误或解析失败 使用有效的文章链接
读取数据目录失败 data目录不存在或无权限 检查目录权限

开发指南

本地测试

  1. 启动API服务器:
cd backend\api
start_api.bat
  1. 测试接口:
# 测试提取主页
curl -X POST http://localhost:8080/api/homepage/extract \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"文章链接\"}"

# 测试获取数据列表
curl http://localhost:8080/api/data/list

跨域配置

API服务器已启用CORS，允许所有来源访问：

w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type")

如需限制特定域名，修改 server.go 中的 corsMiddleware 函数。

超时设置

默认HTTP超时时间：30秒

如需修改，在 server.go 中添加：

server := &http.Server{
    Addr:         ":8080",
    ReadTimeout:  30 * time.Second,
    WriteTimeout: 30 * time.Second,
}

日志记录

API服务器使用标准输出记录日志：

log.Printf("[%s] %s - %s", r.Method, r.URL.Path, message)

接口更新计划

v1.1.0（计划中）

  • 添加用户认证机制
  • 支持任务队列管理
  • 增加下载进度推送（WebSocket）
  • 提供文章搜索接口

v1.2.0（计划中）

  • 数据统计分析接口
  • 导出功能（PDF/Word）
  • 批量任务管理
  • 定时任务支持

技术栈

  • 语言: Go 1.20+
  • Web框架: net/http (标准库)
  • 数据格式: JSON
  • 并发模型: Goroutine

性能说明

并发能力

  • 支持多客户端同时访问
  • 但同一时间只能执行一个爬虫任务（currentTask）

资源占用

  • CPU: 低（主要I/O操作）
  • 内存: <50MB
  • 磁盘: 取决于下载的文章数量

性能优化建议

  1. 使用连接池管理HTTP请求
  2. 实现任务队列机制
  3. 添加结果缓存
  4. 启用gzip压缩

安全建议

1. 生产环境部署

  • 添加HTTPS支持
  • 实现API认证（JWT/OAuth）
  • 限制跨域来源
  • 添加请求频率限制

2. 数据安全

  • 不要暴露敏感信息（Cookie）
  • 定期清理临时文件
  • 备份重要数据

3. 访问控制

  • 添加IP白名单
  • 实现用户权限管理
  • 记录操作日志

常见问题

Q1: 为什么任务启动后没有响应？

A: 检查后端 wechat-crawler.exe 是否存在并有执行权限。

Q2: 如何查看详细的错误信息？

A: 查看API服务器窗口的控制台输出。

Q3: 能同时执行多个下载任务吗？

A: 当前版本不支持，同时只能执行一个任务。

Q4: 如何停止正在运行的任务？

A: 关闭API服务器窗口或重启服务器。

文档版本: v1.0.0
最后更新: 2025-11-27
维护者: AI Assistant