本文介绍一种健壮、可重试的分页遍历策略，适用于基于页码参数（如 pn）的 api 分页场景，通过检测 recordcount 判断是否还有下一页，并结合请求重试机制提升稳定性。
本文介绍一种健壮、可重试的分页遍历策略，适用于基于页码参数（如 pn）的 api 分页场景，通过检测 recordcount 判断是否还有下一页，并结合请求重试机制提升稳定性。
在开发类似“人名查找”这类数据聚合应用时，正确、可靠地遍历所有分页结果是关键一步。许多政务或公开数据库 API（例如德州威廉森县评估办 WCAD 的房产查询接口）采用基于页码（pn=1,2,3...）的分页方式，但不提供总页数字段（如 TotalPageCount），因此不能依赖预知页数循环——而应以每页实际返回的记录数为终止依据。
核心原则是：当某页响应中 RecordCount 为 0 时，即表示无更多数据，应立即停止翻页。 这比依赖 TotalPageCount（若存在且准确）更可靠，也避免了因服务端动态分页逻辑变更导致的漏页或死循环。
以下是推荐的实现方案，已优化可维护性与鲁棒性：
import requests
from requests.adapters import HTTPAdapter, Retry
URL = "https://search.wcad.org/ProxyT/Search/Properties/quick/"
# 配置重试策略：自动重试 5 次，对 429（Too Many Requests）等状态码强制重试
RETRIES = Retry(
total=5,
status_forcelist=[429, 500, 502, 503, 504],
backoff_factor=1.0 # 指数退避：1s, 2s, 4s, 8s, 16s
)
def search_by_name(name: str) -> list:
"""
根据姓名搜索全部分页结果，返回所有非空记录的原始数据列表
"""
params = {
"f": name,
"pn": 1,
"st": 4,
"so": "desc",
"pt": "RP;PP;MH;NR",
"ty": "2024"
}
results = []
with requests.Session() as session:
session.mount(URL, HTTPAdapter(max_retries=RETRIES))
while True:
try:
response = session.get(URL, params=params, timeout=10)
response.raise_for_status()
data = response.json()
record_count = data.get("RecordCount", 0)
if record_count == 0:
print(f"✅ 遍历完成：共获取 {len(results)} 条有效记录")
break
# 提取当前页结果（假设 ResultList 存在且为列表）
page_results = data.get("ResultList", [])
results.extend(page_results)
print(f"? 第 {params['pn']} 页：{record_count} 条记录（累计 {len(results)}）")
params["pn"] += 1 # 准备下一页
# 建议添加合理延时（如 1–2 秒），遵守 robots.txt 及服务端限流策略
import time
time.sleep(1.2)
except requests.exceptions.RequestException as e:
print(f"⚠️ 请求失败（第 {params['pn']} 页）：{e}")
raise # 或按需降级处理（如跳过该页）
except ValueError as e:
print(f"⚠️ JSON 解析失败：{e}")
raise
return results
# 使用示例
if __name__ == "__main__":
name = input("请输入姓名（如 Kennedy）：").strip()
if name:
all_data = search_by_name(name)
# 后续可对 all_data 进行清洗、去重、提取地址等操作
for item in all_data[:3]: # 仅打印前3条示例
print(f"{item.get('OwnerName', 'N/A')} → {item.get('SitusAddress', 'N/A')}")? 重要注意事项：
- 法律与合规性优先：WCAD 等政府网站数据虽公开，但其 robots.txt 和服务条款可能限制自动化抓取频率与用途。本教程仅用于学习与合法合规场景（如个人非商业研究），严禁用于骚扰、营销或绕过访问控制。
- 去重逻辑需前置：示例中未内置去重（因 OwnerName + SitusAddress 组合可能重复），建议在 results.extend(...) 后使用 dict 键去重或 pandas.DataFrame.drop_duplicates() 处理。
- 异常需显式捕获：生产环境务必捕获网络超时、JSON 解析错误、字段缺失等异常，并记录日志而非静默失败。
- 避免硬编码 URL/参数：实际项目中应将 API 地址、默认参数、超时值等提取为配置项，便于维护与测试。
掌握这种“以 RecordCount 驱动循环 + 会话级重试 + 清晰错误反馈”的模式，可稳定适配绝大多数基于页码的 RESTful 分页接口，是构建可靠数据采集管道的基础能力。
