# search-api

**Repository Path**: vicoproplus/search-api

## Basic Information

- **Project Name**: search-api
- **Description**: 通过python/moonbit运行的search工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 免浏览器搜索引擎爬取

纯命令行 / HTTP API 方式爬取 百度、360、搜狗 三家搜索引擎的搜索结果，不依赖浏览器 / GUI / 第三方 Web 框架。

## 目录结构

```
search_cli.py    # 命令行版爬取脚本（原逻辑，无 GUI）
search_api.py    # HTTP API 服务版（基于 search_cli，零额外依赖）
```

---

## 一、命令行版 search_cli.py

用法（`-` 为关键词参数前缀，多个关键词用 `;` 分割）：

```bash
python search_cli.py -关键词
python search_cli.py -关键词1;关键词2;关键词3
```

> 注意：`;` 是 shell 命令分隔符，整段必须加引号，例如：
> ```bash
> python search_cli.py "-关键词1;关键词2;关键词3"
> ```

脚本会依次（轮询）向 百度、360、搜狗 发起查询，每个关键词在三家引擎各取第 1 页结果，并将结果打印到终端（嵌套 dict 形式，不输出 JSON）。

---

## 二、HTTP API 版 search_api.py

基于 `search_cli.py` 的爬取核心逻辑，包装成一个轻量 HTTP 服务，便于远程调用 / 程序集成。

### 安装依赖

原项目依赖（HTTP API 版不新增任何第三方依赖）：

```bash
pip install requests beautifulsoup4 lxml
```

### 启动

```bash
python search_api.py                # 默认监听 0.0.0.0:8000
python search_api.py --port 8080    # 指定端口
python search_api.py --host 127.0.0.1 --port 9000   # 指定监听地址与端口
```

启动成功后输出：

```
[search_api] 服务已启动：http://0.0.0.0:8000/
[search_api] 默认引擎：按关键词轮询（baidu → so360 → sogou → …）
[search_api] 示例：curl "http://127.0.0.1:8000/?keyword=Python"
```

### 接口

`GET /`

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `keyword` | 是 | — | 搜索关键词；支持 `;` 分隔多个（如 `keyword=Python;爬虫`） |
| `engine` | 否 | 按关键词轮询 | `baidu` / `so360` / `sogou`，指定则所有关键词都只查该家；不指定则每个关键词轮询一家（第 1 个→百度、第 2 个→360、第 3 个→搜狗、第 4 个→百度……） |
| `page` | 否 | 1 | 页码 |
| `cookie` | 否 | 空 | 透传给引擎（部分站点需要登录态） |
| `resolve` | 否 | false | 是否解析搜狗中转链接为真实地址（`true`/`false`，仅搜狗生效） |

### 请求示例

```bash
# 1. 主路径：每个关键词按关键词轮询一家引擎（如 Python→百度）
curl "http://127.0.0.1:8000/?keyword=Python"

# 2. 单引擎 + 解析搜狗中转链接
curl "http://127.0.0.1:8000/?engine=sogou&keyword=测试&resolve=true"

# 3. 多个关键词
curl "http://127.0.0.1:8000/?keyword=Python;爬虫"

# 4. 指定页码与 cookie
curl "http://127.0.0.1:8000/?keyword=Python&page=2&cookie=BAIDUID=xxx"
```

### 响应格式

成功（HTTP 200）返回 JSON，格式与命令行版一致——仅含「搜索关键词 + 结果摘要」，折叠掉引擎 / 标题 / 链接。每个关键词只取其所分配那家引擎解析到的摘要：

```json
{
  "Python": [
    "摘要内容 1……",
    "摘要内容 2……",
    "摘要内容 3……"
  ]
}
```

### 错误响应

| 场景 | HTTP 状态 | 响应 |
|------|-----------|------|
| 缺少 `keyword` | 400 | `{"error": "missing keyword"}` |
| 服务端内部异常 | 500 | `{"error": "..."}` |

> 单引擎爬取失败时，该引擎结果返回空列表 `[]`，不影响其他引擎与服务稳定性。

### Python 客户端示例

```python
import requests

resp = requests.get("http://127.0.0.1:8000/", params={
    "keyword": "Python",
    "resolve": "true",
})
data = resp.json()
for keyword, summaries in data.items():
    print(keyword, "->", len(summaries), "条摘要")
    for s in summaries:
        print("  -", s)
```

### Apifox 示例

可在 [Apifox](https://apifox.com/) 中新建接口或导入下方 OpenAPI 文档来调试本服务。

**方式一：手动新建接口**

1. 新建请求，方法选 `GET`，URL 填 `http://127.0.0.1:8000/`。
2. 在「Query 参数」中按接口表格添加参数：

   | 参数名 | 类型 | 示例值 | 说明 |
   |--------|------|--------|------|
   | `keyword` | string | `Python;爬虫` | 必填，多个用 `;` 分隔 |
   | `engine` | string | `sogou` | 可选，不填则按关键词轮询 |
   | `page` | string | `2` | 可选，默认 1 |
   | `cookie` | string | `BAIDUID=xxx` | 可选 |
   | `resolve` | string | `true` | 可选，仅搜狗生效 |

3. 保存并「发送」，响应区会以 JSON 展示 `{ "关键词": [ "摘要1", "摘要2", ... ] }`。

**方式二：导入 OpenAPI（推荐，可一键生成文档/ mock）**

复制以下 YAML 保存为 `openapi.yaml`，在 Apifox 项目内「导入」→ 选择该文件即可自动生成接口与参数说明：

```yaml
openapi: 3.0.3
info:
  title: 搜索引擎爬取 HTTP API
  version: 1.0.0
  description: 基于 search_cli 的轻量 HTTP 爬取服务（仅 stdlib http.server）
servers:
  - url: http://127.0.0.1:8000
paths:
  /:
    get:
      summary: 爬取搜索结果摘要
      description: 按关键词向搜索引擎发起爬取，返回 {关键词: [摘要,...]}。
      parameters:
        - name: keyword
          in: query
          required: true
          description: 搜索关键词，多个用 ";" 分隔
          schema:
            type: string
            example: Python;爬虫
        - name: engine
          in: query
          required: false
          description: baidu / so360 / sogou；不填则按关键词轮询
          schema:
            type: string
            example: sogou
        - name: page
          in: query
          required: false
          description: 页码，默认 1
          schema:
            type: integer
            default: 1
            example: 2
        - name: cookie
          in: query
          required: false
          description: 透传给引擎的 Cookie
          schema:
            type: string
            example: BAIDUID=xxx
        - name: resolve
          in: query
          required: false
          description: 是否解析搜狗中转链接，仅搜狗生效
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: 成功，返回 {关键词: [摘要,...]}
          content:
            application/json:
              example:
                Python:
                  - 摘要内容 1……
                  - 摘要内容 2……
        '400':
          description: 缺少 keyword
          content:
            application/json:
              example:
                error: missing keyword
        '500':
          description: 服务端内部异常
          content:
            application/json:
              example:
                error: "..."

```

---

## 三、依赖

- `requests`
- `beautifulsoup4`
- `lxml`

```bash
pip install requests beautifulsoup4 lxml
```

HTTP API 版（`search_api.py`）额外仅使用 Python 标准库 `http.server` / `argparse` / `urllib`，无需安装 Flask 等 Web 框架。

---

## 四、说明与限制

- 爬取逻辑基于各搜索引擎 PC 页面结构，页面改版可能需要同步更新 `search_cli.py` 中的选择器。
- 默认只爬取第 1 页，需要更多页请通过 `page` 参数指定。
- 仅用于学习 / 合规的数据采集场景，请遵守目标站点的 `robots.txt` 与使用条款，控制请求频率。