适用场景与接口能力边界

网站安全综合评分API（/api/site-security）提供了一站式的域名安全检测能力，通过SSL证书、域名安全、ICP备案、微信/QQ拦截和网站性能五个维度加权计算，输出0-100的综合分数及A/B/C/D/F等级。一次请求即可获得全面的诊断报告，适用于以下场景：

• 安全巡检自动化：定期对管理的大量域名进行安全态势扫描，生成趋势报告。
• CDN或云服务商：在用户接入域名时自动校验其安全合规状态。
• 运维监控看板：将评分数据嵌入实时监控系统，快速定位安全短板。

能力边界

• 支持的输入：纯域名（如example.com），不能包含协议头或路径。
• 输出范围：每项子维度评分0-100，总分0-100，等级A（≥90）、B（80-89）、C（70-79）、D（60-69）、F（<60）。
• QPS限制：2次/秒，超出返回429状态码。
• 检测时间：通常2-5秒，受目标服务器响应速度影响。

请求参数详解：Query与Header

Query参数

Header参数

注意：实际调用时Header名称为Authorization，值为Bearer YOUR_API_KEY或直接填入Key（以文档为准）。在curl示例中可能使用X-API-Key，请以最新文档为准。

鉴权方式

该API采用请求头鉴权，需在每次请求中携带有效的API Key。申请方式请参考官方文档（参考文档）。建议将Key存储在环境变量或密钥管理服务中，避免硬编码。

请求示例：curl与Java代码

curl示例（可复制运行）

# 替换 YOUR_API_KEY 为实际密钥 export API_KEY="YOUR_API_KEY" curl -sS \ -X GET \ -H "Authorization: Bearer $API_KEY" \ "https://v1.apizero.cn/api/site-security?domain=baidu.com" | jq .

如果使用jq格式化输出，建议先检查是否安装。若不安装，直接去掉| jq .即可。

Java（Spring Boot + RestTemplate）接入示例

import org.springframework.http.*; import org.springframework.web.client.RestTemplate; import java.util.Collections; public class SiteSecurityChecker { private static final String API_URL = "https://v1.apizero.cn/api/site-security"; private static final String API_KEY = System.getenv("API_KEY"); // 从环境变量读取 public static void main(String[] args) { String domain = "baidu.com"; RestTemplate rest = new RestTemplate(); HttpHeaders headers = new HttpHeaders(); headers.setBearerAuth(API_KEY); // 自动添加 Bearer 前缀 headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON)); String url = API_URL + "?domain=" + domain; HttpEntity<String> entity = new HttpEntity<>(headers); try { ResponseEntity<String> response = rest.exchange(url, HttpMethod.GET, entity, String.class); System.out.println("状态码: " + response.getStatusCode()); System.out.println("响应体: " + response.getBody()); } catch (Exception e) { System.err.println("请求失败: " + e.getMessage()); } } }

注意：Maven项目需引入spring-boot-starter-web依赖，或单独使用RestTemplate（非Spring Boot项目需手动添加）。

响应字段全解析（五维评分）

响应JSON结构层次分明，顶层包含code、msg和data。成功时code为0。data对象包含以下字段：

子对象字段详解

ssl对象

domain_security对象

icp对象

blocked对象

performance对象

完整示例响应（美化后）

{ "code": 0, "msg": "成功", "data": { "domain": "baidu.com", "overall_score": 92, "grade": "A", "detection_time": "4521ms", "ssl": { "score": 100, "https_enabled": true, "days_until_expiry": 365 }, "domain_security": { "score": 85, "expiration_date": "2026-09-01T00:00:00Z" }, "icp": { "score": 100, "icp_number": "京ICP证030173号", "organization": "北京百度网讯科技有限公司" }, "blocked": { "score": 80, "wechat_blocked": false, "qq_blocked": false }, "performance": { "score": 90, "response_time_ms": 180 } } }

常见错误与排查指南

关键排查点

1. 域名格式：输入baidu.com而不是https://baidu.com或www.baidu.com（后者也会被处理但可能影响备案查证）。
2. Header名称：部分客户端默认将Authorization转换为小写，但HTTP头部不区分大小写，通常无影响。若使用curl，请确保-H中的引号正确。
3. 超时设置：接口检测耗时可能超过5秒，建议客户端超时设为10秒以上。
4. 空字段处理：某些子对象字段（如certificate_issuer）可能因域名不支持而缺失，代码应做null安全检查。

工程化注意事项

1. 缓存策略

评分结果在短时间内（如1小时内）通常不会剧烈变化，可考虑使用Redis或本地缓存，减少API调用次数。缓存key可设计为site-security:{domain}，过期时间设为3600秒。

2. 限流与重试

由于QPS仅2次/秒，建议在客户端做令牌桶限流。若遇到429错误，应采用指数退避（如等待1秒、2秒、4秒后重试，最多3次）。

3. 容错处理

• 网络超时：捕获SocketTimeoutException，记录日志后跳过或降级。
• 解析失败：使用try-catch处理JSON解析异常，避免任务中断。
• 部分字段缺失：使用has()或可选字段占位符，防止NPE。

4. 日志与监控

• 记录每次请求的域名、响应时间、评分等级，用于后期分析。
• 对评分低于60（F级）的域名自动触发告警（邮件/钉钉/Webhook）。
• 监控接口调用成功率，若连续失败超过阈值，暂停调用并人工介入。

5. 测试与验证

建议在沙箱环境先用example.com或自己的测试域名验证功能。注意：example.com可能检测结果不全（如无ICP备案）。正式接入前应覆盖不同等级域名的场景。

参考文档

• 接口官方文档：https://apizero.cn/aidocs/site-security
• 原始Markdown文档：https://apizero.cn/aidocs/site-security/raw.md
• 以上文档包含最新的请求示例、错误码枚举和更新日志。