461 lines
8.8 KiB
Markdown
461 lines
8.8 KiB
Markdown
# 📡 微信公众号文章爬虫 - API 接口文档
|
||
|
||
## 服务器信息
|
||
|
||
- **服务地址**: http://localhost:8080
|
||
- **协议**: HTTP/1.1
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
- **CORS**: 已启用（允许所有来源）
|
||
|
||
## 统一响应格式
|
||
|
||
所有API接口返回格式统一为：
|
||
|
||
```json
|
||
{
|
||
"success": true, // 请求是否成功
|
||
"message": "操作成功", // 提示信息
|
||
"data": {} // 数据内容（可选）
|
||
}
|
||
```
|
||
|
||
## 接口列表
|
||
|
||
### 1. 提取公众号主页
|
||
|
||
**接口地址**: `/api/homepage/extract`
|
||
**请求方法**: POST
|
||
**功能说明**: 从文章链接中提取公众号主页链接
|
||
|
||
#### 请求参数
|
||
|
||
```json
|
||
{
|
||
"url": "https://mp.weixin.qq.com/s?__biz=xxx&mid=xxx"
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| url | string | 是 | 公众号文章链接 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "提取成功",
|
||
"data": {
|
||
"homepage": "https://mp.weixin.qq.com/mp/profile_ext?action=home&__biz=xxx&scene=124",
|
||
"output": "完整的命令行输出信息"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应**:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "未能提取到主页链接"
|
||
}
|
||
```
|
||
|
||
#### 调用示例
|
||
|
||
**jQuery**:
|
||
```javascript
|
||
$.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**:
|
||
```bash
|
||
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
|
||
**功能说明**: 下载指定的单篇文章
|
||
|
||
#### 请求参数
|
||
|
||
```json
|
||
{
|
||
"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） |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "下载任务已启动",
|
||
"data": {
|
||
"url": "https://mp.weixin.qq.com/s?__biz=xxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取文章列表
|
||
|
||
**接口地址**: `/api/article/list`
|
||
**请求方法**: POST
|
||
**功能说明**: 批量获取公众号的文章列表
|
||
|
||
#### 请求参数
|
||
|
||
```json
|
||
{
|
||
"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） |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "任务已启动"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 批量下载文章
|
||
|
||
**接口地址**: `/api/article/batch`
|
||
**请求方法**: POST
|
||
**功能说明**: 批量下载公众号的所有文章
|
||
|
||
#### 请求参数
|
||
|
||
```json
|
||
{
|
||
"official_account": "公众号名称或文章链接",
|
||
"save_image": true,
|
||
"save_content": true
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| official_account | string | 是 | 公众号名称或任意文章链接 |
|
||
| save_image | boolean | 否 | 是否保存图片（默认false） |
|
||
| save_content | boolean | 否 | 是否保存内容（默认true） |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "任务已启动"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 获取数据列表
|
||
|
||
**接口地址**: `/api/data/list`
|
||
**请求方法**: GET
|
||
**功能说明**: 获取已下载的公众号数据列表
|
||
|
||
#### 请求参数
|
||
|
||
无
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"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**:
|
||
```javascript
|
||
$.get('http://localhost:8080/api/data/list', function(response) {
|
||
if (response.success) {
|
||
console.log('数据列表:', response.data);
|
||
}
|
||
});
|
||
```
|
||
|
||
**curl**:
|
||
```bash
|
||
curl http://localhost:8080/api/data/list
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 获取任务状态
|
||
|
||
**接口地址**: `/api/task/status`
|
||
**请求方法**: GET
|
||
**功能说明**: 获取当前任务的执行状态
|
||
|
||
#### 请求参数
|
||
|
||
无
|
||
|
||
#### 响应示例
|
||
|
||
**任务运行中**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"running": true,
|
||
"progress": 45,
|
||
"message": "正在下载第10篇文章..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**无任务运行**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"running": false,
|
||
"progress": 0,
|
||
"message": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| running | boolean | 是否有任务运行中 |
|
||
| progress | integer | 任务进度（0-100） |
|
||
| message | string | 任务状态描述 |
|
||
| error | string | 错误信息（可选） |
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
### HTTP状态码
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 业务错误码
|
||
|
||
所有业务错误通过响应中的 `success` 字段和 `message` 字段返回：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "具体的错误信息"
|
||
}
|
||
```
|
||
|
||
常见错误信息：
|
||
|
||
| 错误信息 | 说明 | 解决方法 |
|
||
|----------|------|----------|
|
||
| 请求参数错误 | JSON格式不正确或缺少必填参数 | 检查请求参数格式 |
|
||
| 执行失败 | 后端程序执行出错 | 查看详细错误信息 |
|
||
| 未能提取到主页链接 | 文章链接格式错误或解析失败 | 使用有效的文章链接 |
|
||
| 读取数据目录失败 | data目录不存在或无权限 | 检查目录权限 |
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 本地测试
|
||
|
||
1. **启动API服务器**:
|
||
```bash
|
||
cd backend\api
|
||
start_api.bat
|
||
```
|
||
|
||
2. **测试接口**:
|
||
```bash
|
||
# 测试提取主页
|
||
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，允许所有来源访问：
|
||
|
||
```go
|
||
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` 中添加：
|
||
|
||
```go
|
||
server := &http.Server{
|
||
Addr: ":8080",
|
||
ReadTimeout: 30 * time.Second,
|
||
WriteTimeout: 30 * time.Second,
|
||
}
|
||
```
|
||
|
||
### 日志记录
|
||
|
||
API服务器使用标准输出记录日志：
|
||
|
||
```go
|
||
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
|