yixiaogao/backend/api/API接口文档.md

# 📡 微信公众号文章爬虫 - 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