# YouTube Trending 爬虫 Skill Benchmark v2 > 适用技能: `youtube-trending-crawler-v2` > 基于 knowhow: `hunter/youtube-trending/knowhow_v2.md` + `crawl_config.json` > 生成时间: 2026-04-09 > 生成者: digester-youtube-crawler --- ## 评分维度与权重 | 维度 | 权重 | 说明 | |------|------|------| | 功能完整性 | 20% | 核心字段与扩展字段覆盖、多地区/多分类/分页支持 | | API使用规范 | 15% | API 参数正确性、配额管理、反爬策略、降级链路 | | 数据完整性 | 15% | 数据字段完整、类型转换正确、格式标准、enrichment 齐全 | | 代码质量 | 15% | 代码结构、可读性、文档、测试覆盖 | | 扩展性 | 10% | 地区/分类/输出格式可配置、批量获取、易于扩展 | | 错误处理与稳定性 | 10% | HTTP 异常码处理、指数退避重试、多级降级、空结果处理 | | 性能与效率 | 5% | 缓存策略、请求频率控制、并发控制、避免重复请求 | | 安全与合规 | 10% | API Key 不外泄、遵守 robots.txt、敏感信息保护 | **权重总和:100%** --- ## 评分标准(0-100 分制) ### 1. 功能完整性(20%) | 分数 | 标准 | |------|------| | 90-100 | 完整提取 9 个核心字段(video_id, title, channel_id, channel_title, published_at, view_count, category_id, source_url, crawl_time)+ 4 个扩展字段(thumbnail_url, tags, duration, like_count, comment_count),支持 25 个地区、4 个目标分类、分页获取 | | 80-89 | 提取 8-9 个核心字段,基本功能完整,支持主流地区/分类 | | 70-79 | 提取 6-7 个核心字段,主要功能可用,缺少部分内容 | | 60-69 | 提取 4-5 个字段,功能缺失明显 | | <60 | 功能严重缺失,无法正常使用 | **检查项:** - [ ] 是否返回 video_id - [ ] 是否返回 title - [ ] 是否返回 view_count - [ ] 是否返回 channel_title / channel_id - [ ] 是否返回 published_at - [ ] 是否返回 category_id - [ ] 是否返回 source_url(enrichment) - [ ] 是否返回 crawl_time(enrichment) - [ ] 是否支持 duration / like_count / comment_count(contentDetails+statistics) - [ ] 是否支持 regionCode / videoCategoryId / pageToken 配置 --- ### 2. API使用规范(15%) | 分数 | 标准 | |------|------| | 90-100 | API 参数完全正确(part=snippet,statistics,contentDetails; chart=mostPopular; maxResults 1-50),配额监控完善,具备 API→yt-dlp→Invidious 三级降级链路,请求频率合理( delay >= 2s / gzip / UA ) | | 80-89 | API 使用正确,有基本错误处理,有 yt-dlp 降级,有请求间隔 | | 70-79 | API 基本正确,少量参数问题,降级链路不完整 | | 60-69 | API 使用有问题,配额管理缺失,无降级方案 | | <60 | 严重违反 API 规范,无配额意识,使用 search.list 代替 videos.list | **检查项:** - [ ] part 参数是否包含 snippet,statistics,contentDetails - [ ] chart=mostPopular 是否正确设置 - [ ] maxResults 是否在 1-50 范围内 - [ ] 是否有配额监控与计数器(10,000 units/day) - [ ] 是否有三级降级方案(API -> yt-dlp -> Invidious) - [ ] 请求间隔是否合理(API/yt-dlp: >= 2s) - [ ] 是否设置 Accept-Encoding: gzip - [ ] 是否设置合法 User-Agent --- ### 3. 数据完整性(15%) | 分数 | 标准 | |------|------| | 90-100 | 数据字段完整、类型转换正确(view_count 整数、published_at ISO8601 datetime、duration ISO8601 duration)、schema 校验完善、空值/边界数据优雅处理 | | 80-89 | 数据完整、基本类型处理正确 | | 70-79 | 少量数据问题、类型处理基本正确 | | 60-69 | 数据缺失或类型问题明显 | | <60 | 数据严重不完整、类型错误、未做 enrichment | **检查项:** - [ ] view_count 是否转为整数(非字符串) - [ ] published_at 是否转为 datetime / 标准化时区 - [ ] duration 是否正确解析(如 PT3M33S) - [ ] thumbnails 是否包含多分辨率(default/medium/high/standard/maxres) - [ ] 空值/边界数据是否处理 - [ ] 是否有 schema 校验 - [ ] source_url 和 crawl_time 是否正确注入 --- ### 4. 代码质量(15%) | 分数 | 标准 | |------|------| | 90-100 | 模块化设计、函数拆分合理、有完整 docstring 和类型注解、单元测试覆盖率 >80% | | 80-89 | 代码结构清晰、有基本注释、有测试 | | 70-79 | 代码可读、少量注释、无明显坏味道 | | 60-69 | 代码较乱、函数过长、缺少注释 | | <60 | 代码混乱、无注释、难以维护 | **检查项:** - [ ] 是否模块化设计 - [ ] 是否有函数 docstring - [ ] 是否有类型注解 - [ ] 变量名是否有意义 - [ ] 是否有单元测试 - [ ] 测试覆盖率是否 >80% --- ### 5. 扩展性(10%) | 分数 | 标准 | |------|------| | 90-100 | regionCode / videoCategoryId / pageToken / maxResults 可配置,支持 JSON/CSV 输出,支持批量获取,易于扩展新功能和数据源 | | 80-89 | 主要参数可配置,有一定扩展性 | | 70-79 | 部分参数硬编码,扩展性一般 | | 60-69 | 大量硬编码,扩展性差 | | <60 | 完全写死,无法扩展 | **检查项:** - [ ] regionCode 是否可配置(支持 25 个地区) - [ ] videoCategoryId 是否可配置(支持 4+ 分类) - [ ] maxResults / pageToken 是否可配置 - [ ] 输出格式是否支持 JSON + CSV - [ ] 是否支持批量获取 - [ ] 是否易于添加新功能/新数据源 --- ### 6. 错误处理与稳定性(10%) | 分数 | 标准 | |------|------| | 90-100 | 完善的 HTTP 异常处理(400/403/404/429/500/502/503 按规范处理)、指数退避重试(429: base 2s max 60s retry 5; 503: base 5s max 120s retry 5)、多级自动降级、网络超时 30s、友好的错误提示、空结果优雅处理 | | 80-89 | 有异常处理、有重试机制、有基本降级 | | 70-79 | 基本错误处理、不会崩溃 | | 60-69 | 错误处理不完善、可能崩溃 | | <60 | 无错误处理、程序易崩溃 | **检查项:** - [ ] 400/403/404/429/500/502/503 是否按规范处理 - [ ] 网络错误是否处理(AbortSignal.timeout 30s) - [ ] 是否有重试机制(指数退避参数正确) - [ ] 是否有三级降级方案 - [ ] 错误提示是否友好 - [ ] 空结果/部分字段缺失是否处理 --- ### 7. 性能与效率(5%) | 分数 | 标准 | |------|------| | 90-100 | 缓存策略完善(15-30 分钟)、并发控制合理、避免重复请求、响应快速、配额使用效率高 | | 80-89 | 有缓存机制、性能良好 | | 70-79 | 基本的性能考虑 | | 60-69 | 性能问题明显、无缓存 | | <60 | 频繁请求、快速耗尽配额 | **检查项:** - [ ] 是否有缓存机制 - [ ] 缓存时间是否合理(建议 fetch_interval_hours: 4) - [ ] 并发请求是否控制 - [ ] 是否避免重复请求 - [ ] 是否使用单次 maxResults=50 最大化配额效率 --- ### 8. 安全与合规(10%) | 分数 | 标准 | |------|------| | 90-100 | API Key 通过环境变量 `YOUTUBE_API_KEY` 注入,代码/日志中无硬编码,遵守 robots_txt,敏感信息不泄露,代理凭证安全存储 | | 80-89 | 基本无硬编码、敏感信息保护措施到位 | | 70-79 | 有基本安全意识,少量瑕疵 | | 60-69 | 安全意识不足,存在泄露风险 | | <60 | 硬编码密钥、无视合规要求、激进爬取 | **检查项:** - [ ] API Key 是否来自环境变量 - [ ] 代码/日志中是否无硬编码密钥 - [ ] yt-dlp/页面解析是否遵守 robots.txt - [ ] 敏感信息是否不在输出/日志中泄露 --- ## 通过阈值 | 等级 | 总分 | 说明 | |------|------|------| | 优秀 | >=90 | 生产就绪,可直接部署 | | 良好 | 80-89 | 基本可用,有优化空间 | | 及格 | 70-79 | 功能可用,有明显改进点 | | 不及格 | <70 | 不推荐上线,需大量改进 | --- ## 自动化测试用例 ### 基础功能测试 ```python # TC-001: API 基础调用(v2 完整字段) test_api_basic_v2() # 预期:返回包含 9 个核心字段 + 4 个扩展字段的视频列表 # TC-002: 参数验证 test_invalid_part() # 预期:正确处理缺少 part 参数的错误 # TC-003: 字段完整性 test_field_completeness_v2() # 预期:所有核心字段都存在且非空,包含 contentDetails # TC-004: 边界值测试 test_max_results_boundary() # 预期:maxResults=50 成功,maxResults=51 报错 ``` ### 错误处理测试 ```python # TC-005: 无效 API Key test_invalid_api_key() # 预期:返回友好错误提示,不崩溃,不泄露密钥 # TC-006: 配额超限 test_quota_exceeded() # 预期:触发 yt-dlp 降级,yt-dlp 失败后再切换到 Invidious # TC-007: 网络超时 + 503 退避 test_network_timeout_and_503() # 预期:30s 超时触发,503 指数退避重试后成功或优雅降级 ``` ### 数据质量测试 ```python # TC-008: 数据类型转换 test_viewcount_type() # 预期:view_count 为 int 类型 # TC-009: 时间格式 + duration 解析 test_datetime_and_duration_format() # 预期:published_at 为 datetime,duration 正确解析为秒或 ISO 格式 # TC-010: 空值处理 + enrichment test_empty_thumbnail_and_enrichment() # 预期:无缩略图时返回占位图或 null 不报错,source_url / crawl_time 正确注入 ``` ### 降级链路测试 ```python # TC-011: 三级降级链路 test_fallback_chain() # 预期:API(403) -> yt-dlp(timeout) -> Invidious(success) ``` --- ## 评分公式 ``` 总分 = sum(维度分数 x 维度权重) 示例: 功能完整性: 95 x 0.20 = 19.0 API使用规范: 95 x 0.15 = 14.25 数据完整性: 95 x 0.15 = 14.25 代码质量: 90 x 0.15 = 13.5 扩展性: 85 x 0.10 = 8.5 错误处理与稳定性: 90 x 0.10 = 9.0 性能与效率: 90 x 0.05 = 4.5 安全与合规: 92 x 0.10 = 9.2 总分 = 92.2 (优秀) ``` --- *Generated by digester-youtube-crawler | 2026-04-09*