接口简介
「HTML 差异对比」是数据鱼API平台提供的页面片段比对接口,Base 路径 /api/diffhtml,共 4 个端点。它接收两份 HTML 字符串,按行逐一对照,返回是否存在差异、差异行数以及每一处差异所在的行号与新旧内容,用于改版前后核对页面输出、监控邮件模板变化或检查爬虫抓取的页面是否被调整。
接口的比较策略是逐行对位匹配,stats 端点返回的 method 字段直接写明为 line-based-diff。第一份 HTML 的第 n 行只与第二份的第 n 行比较,行内任何字符差别都会记为一处变更,包括缩进、属性顺序与空白。这种做法实现简单、结果直观,但不会像 LCS 那样识别「插入了一行、其余内容整体下移」,插入位置之后的所有行都会被标记为差异。
因此这个接口的定位是「快速定位哪些行变了」,而不是「精确计算最小编辑集」。做模板回归、页面快照巡检时,它能把差异缩小到具体行号,交给人工判断;需要最小差异集或统一 diff 文本时,应改用文本差异对比接口;需要按 JSON 结构比较时,则用页面版本差异对比接口。
端点总览
方法 路径 说明 鉴权
GET /api/diffhtml/ping 健康检查,返回版本号 免鉴权
GET /api/diffhtml/stats 返回比对方法标识 需要
POST /api/diffhtml/diff 比对两份 HTML,返回差异行列表 需要
GET /api/diffhtml/diff 同上,参数走查询串 需要
通用约定
鉴权使用数据鱼API 全站统一 Key,通过 X-API-Key 请求头或 ?api_key= 查询参数传递,缺失返回 4011,无效返回 4013。响应统一为 {code, msg, data}。
本接口的 GET 与 POST 行为一致,html1 与 html2 放在查询串、表单或 JSON 请求体中都能被读取。参数表把它们标注为「视业务」而非明确的必填,这是文档层面的宽松表述;实际调用时两者缺一即返回 4001,并提示缺少 html1 或 html2,调用方应按必填处理。
核心端点详解
健康检查 ping
探活端点,无参数、不校验 Key,返回固定的版本字符串 1.0,可用于部署后的连通性检查。
GET /api/diffhtml/ping
方法说明 stats
该端点不返回题库或数据量统计,只有一个 method 字段,值为 line-based-diff,用来说明当前实现采用的比对策略。调用方可以据此判断结果语义,不必把它当作业务指标接口。
参数 类型 必填 默认 说明
无 - - - 不接受参数
差异比对 diff
核心端点,接收两份 HTML 并按行对位比较。两份内容都按换行符切分成行数组,逐下标比对,长度不等时较短一侧缺失的行按空值处理。
参数 类型 必填 默认 说明
html1 string 是 - 原始 HTML,缺失返回 4001
html2 string 是 - 对比 HTML,缺失返回 4001
响应 data 含三个字段:has_diff 为布尔值,表示是否存在差异;diff_count 为差异行数,等于 changes 数组长度;changes 为差异明细,每个元素含 line、old、new。line 是从 1 开始的行号,old 与 new 分别是该行在两份 HTML 中的内容,一侧缺少对应行时该字段为 null。
POST /api/diffhtml/diff
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{"html1": "
标题
\n标题
\n上述请求只有第一行属性不同,返回的 diff_count 为 1,changes 中只有一条记录,line 为 1,old 与 new 分别是两个 div 起始标签。若在 html2 开头插入一行注释,则从第 1 行起后续所有行都会进入 changes,这是逐行对位的必然结果。
数据与限制
端点数量固定为 4 个,其中 diff 同时提供 GET 与 POST,两者参数与返回完全一致。
比较粒度为整行,不支持词级或字符级内联差异,也不返回统一 diff 文本。
行号从 1 开始,以 html1 的行序为基准;两份额外行数差会体现为 old 或 new 为 null 的记录。
接口不解析 DOM,不做标签闭合校验、属性排序或空白归一,任何字符级差异都会被计入。
文档未标注输入长度上限,实际受服务端请求体大小限制约束;超大页面建议先抽取关键区块再比较。
接口为无状态计算,不保存提交的 HTML 内容,也不提供历史比对记录。
典型使用场景
模板改版核对:把新旧两版渲染结果提交比对,按行号快速定位被改动的标签。
邮件模板巡检:定期抓取发送前的 HTML 与基线版本比较,has_diff 为 true 时告警。
页面监控:对同一 URL 两次抓取的内容做行级对照,发现内容被替换或注入。
组件输出验证:单元测试中把组件渲染结果与快照文件比较,差异行直接进入报告。
注意事项
html1 与 html2 实际为必填,缺失返回 4001 且提示为英文,接入层应把该错误映射为可读提示。
逐行对位比较不是最小差异算法:中间插入或删除一行会导致后续所有行被判为变更,diff_count 会被显著放大,不要用它推断改动规模。
比较对象是原始字符串,缩进调整、属性换序、自闭合写法差异都会被算作变更;需要容忍格式差异时应先做规范化。
JSON 请求体中的 HTML 需要正确转义换行与引号,否则解析失败会得到 4002 而不是差异结果。
stats 端点只返回方法标识,不含任何计数,不要把它当作数据统计接口排进监控指标。
接口不校验 HTML 合法性,传入纯文本同样按行比较;结果只说明文本差异,不代表页面渲染效果不同。
数据鱼API 不对比对内容的业务正确性做判断,改版是否可发布仍需人工确认。