网站安全综合评分API全参数拆解：请求、响应与工程落地方案
适用场景与接口能力边界
网站安全综合评分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参数
| 参数名 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
domain | 是 | string | 待检测的域名，不含http/https，不含路径。 | baidu.com |
Header参数
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
Authorization | 是 | string | API鉴权密钥，需替换为实际申请的Key。 |
注意：实际调用时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对象包含以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
domain | string | 请求的域名 |
overall_score | int | 综合评分（0-100） |
grade | string | 等级，A/B/C/D/F |
detection_time | string | 本次检测耗时，单位毫秒，如4521ms |
ssl | object | SSL证书详情（详见下方） |
domain_security | object | 域名安全详情 |
icp | object | ICP备案详情 |
blocked | object | 微信/QQ拦截详情 |
performance | object | 网站性能评分详情 |
子对象字段详解
ssl对象
| 字段 | 类型 | 说明 |
|---|---|---|
score | int | SSL维度得分（0-100） |
https_enabled | boolean | 是否启用HTTPS |
certificate_issuer | string | 证书颁发机构（可能不存在） |
days_until_expiry | int | 证书剩余有效天数 |
protocol | string | 支持的TLS协议版本，如TLSv1.2 |
domain_security对象
| 字段 | 类型 | 说明 |
|---|---|---|
score | int | 域名安全得分 |
expiration_date | string | 域名到期日期（ISO 8601格式） |
registrant_org | string | 准备组织（可能为空） |
dnssec_enabled | boolean | 是否启用DNSSEC |
icp对象
| 字段 | 类型 | 说明 |
|---|---|---|
score | int | ICP备案得分 |
icp_number | string | 备案号，如京ICP证030173号 |
organization | string | 备案主体名称 |
status | string | 备案状态，如正常 |
blocked对象
| 字段 | 类型 | 说明 |
|---|---|---|
score | int | 拦截检测得分（越高表示越安全） |
wechat_blocked | boolean | 是否被微信拦截 |
qq_blocked | boolean | 是否被QQ拦截 |
details | string | 拦截原因说明（如有） |
performance对象
| 字段 | 类型 | 说明 |
|---|---|---|
score | int | 性能得分 |
response_time_ms | int | 响应时间毫秒数 |
tls_handshake_time_ms | int | TLS握手耗时 |
compression_enabled | boolean | 是否启用Gzip/Brotli压缩 |
完整示例响应（美化后）
{ "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 } } }常见错误与排查指南
| HTTP状态码 | 响应code | msg含义 | 处理建议 |
|---|---|---|---|
| 200 | 0 | 成功 | 正常处理data |
| 400 | 1001 | 缺少必填参数domain | 检查请求URL是否包含?domain= |
| 401 | 1002 | 鉴权失败，API Key无效或未提供 | 确认Header名称和Key值，查看文档是否要求Bearer前缀 |
| 403 | 1003 | 权限不足，Key无该接口调用权限 | 联系管理员确认API订阅范围 |
| 429 | 1020 | 请求频率超过QPS限制（2次/秒） | 添加本地限流或退避重试 |
| 500 | 9999 | 服务内部错误 | 稍后重试，若持续失败反馈技术支持 |
关键排查点
- 域名格式：输入
baidu.com而不是https://baidu.com或www.baidu.com（后者也会被处理但可能影响备案查证）。 - Header名称：部分客户端默认将
Authorization转换为小写，但HTTP头部不区分大小写，通常无影响。若使用curl，请确保-H中的引号正确。 - 超时设置：接口检测耗时可能超过5秒，建议客户端超时设为10秒以上。
- 空字段处理：某些子对象字段（如
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
- 以上文档包含最新的请求示例、错误码枚举和更新日志。