Python 实现网站 SEO 巡检：正确处理 PageSpeed 与域名接口状态

把 PageSpeed、DNS、SSL 和 WHOIS 放进同一个 Python 任务时，难点不在发出四个 HTTP 请求，而在于正确处理不同返回契约、缓存信息和失败边界。

本文以 网页性能与 SEO 评分 API 为主，给出一套可复用的 Python 封装思路。示例使用标准库，AppKey 通过服务端环境变量读取。

先定义统一结果，而不是统一原始响应

PageSpeed 的业务状态位于 DataStatus.StatusCode，成功值为 100；DNS、SSL、WHOIS v2 接口则返回 dataStatus.statusCode=200。强行用一套字段解析所有响应，会把正常结果误判为失败。

更合适的方法是分别验证原始契约，再映射到统一结果：

from dataclasses import dataclass, field
from typing import Any


@dataclass
class CheckResult:
    check_name: str
    target: str
    ok: bool
    collected_at: str
    raw_status: int
    data: dict[str, Any] = field(default_factory=dict)
    error: str | None = None

统一结果用于报告和存储，原始响应仍可在受控日志或对象存储中按合规要求保留。

封装 GET 请求

import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen


API_ROOT = "https://api.gugudata.com"


def get_json(path: str, params: dict[str, str], timeout: int = 60) -> dict:
    query = urlencode(params)
    request = Request(
        f"{API_ROOT}{path}?{query}",
        headers={"X-GUGUDATA-APPKEY": os.environ["GUGUDATA_APPKEY"]},
        method="GET",
    )
    with urlopen(request, timeout=timeout) as response:
        return json.load(response)

不要把 AppKey 放进 params，这样更容易避免密钥进入访问日志。生产实现还应限制读取大小，并分别处理超时、连接错误和非 2xx HTTP 状态。

PageSpeed 校验器

def fetch_pagespeed(page_url: str) -> dict:
    payload = get_json(
        "/websitetools/pagespeed-score",
        {
            "url": page_url,
            "strategy": "mobile",
            "locale": "zh-CN",
            "categories": "performance,accessibility,best-practices,seo",
            "forceRefresh": "false",
        },
    )
    status = payload.get("DataStatus", {})
    if int(status.get("StatusCode", 0)) != 100:
        raise RuntimeError(status.get("StatusDescription", "PageSpeed failed"))
    return payload.get("Data", {})

需要保存的不只是 Scores。FinalUrl 可以帮助发现重定向，FetchTime 与 Cached 用于解释数据时效，TopIssues 才能把分数转成具体优化项。

v2 域名接口校验器

def fetch_domain_check(path: str, domain: str) -> dict:
    payload = get_json(path, {"domain": domain}, timeout=30)
    status = payload.get("dataStatus", {})
    if int(status.get("statusCode", 0)) != 200:
        message = status.get("statusDescription", "Domain check failed")
        raise RuntimeError(message)
    return payload.get("data", {})


def fetch_dns(domain: str) -> dict:
    return fetch_domain_check("/v2/websitetools/dns-lookup", domain)


def fetch_ssl(domain: str) -> dict:
    return fetch_domain_check("/v2/websitetools/sslcertinfo", domain)


def fetch_whois(domain: str) -> dict:
    return fetch_domain_check("/v2/websitetools/whois", domain)

这里按当前 v2 契约判断 200，不要把 PageSpeed 的 100 复制过来。

从 URL 安全提取域名

from urllib.parse import urlsplit


def extract_domain(page_url: str) -> str:
    parsed = urlsplit(page_url)
    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
        raise ValueError("A valid HTTP or HTTPS URL is required")
    return parsed.hostname.encode("idna").decode("ascii")

不要通过字符串切割提取域名。真实 URL 可能包含端口、认证信息、IPv6、国际化域名或路径中的相似文本。

URL 与域名任务分别去重

假设一次巡检包含同一域名下的 20 个页面，PageSpeed 需要按 20 个 URL 执行；DNS、SSL、WHOIS 通常只需按域名执行一次。

def build_targets(page_urls: list[str]) -> tuple[list[str], list[str]]:
    urls = list(dict.fromkeys(page_urls))
    domains = list(dict.fromkeys(extract_domain(url) for url in urls))
    return urls, domains

这个小步骤能直接减少重复查询，也让缓存键和失败重试更清晰。

不要把所有失败都重试

建议按三层分类：

对参数错误、权限问题和稳定复现的业务失败不断重试，只会消耗额度并延迟真正需要处理的问题。

报告记录建议

每次检查至少保存：目标、检查类型、HTTP 状态、原始业务状态、采集时间、是否缓存、关键结果摘要、首次发现时间、连续出现次数和负责人。

PageSpeed 评分应在相同 strategy 下比较；WHOIS 字段缺失要标记为未知，因为隐私保护或注册局差异都可能造成空值。最终报告要告诉读者“下一步做什么”，而不是只打印 JSON。

接入前自测

• 使用无效 URL 验证参数失败路径。
• 使用可重定向 URL 验证 FinalUrl 保存逻辑。
• 确认 PageSpeed 成功码 100 与 v2 域名成功码 200 分开处理。
• 多个同域 URL 只生成一组域名任务。
• 日志中不出现 AppKey。
• 缓存结果保留 Cached 与 FetchTime。
• 重试次数有上限，业务异常不会被当成网络错误。

正确处理接口边界之后，SEO 巡检代码才有资格进入定时任务；否则再漂亮的报告，也可能建立在错误的成功判断上。