「HTML 处理」是数据鱼API平台提供的 HTML 文本规范化接口,Base 路径 /api/html-tool,共 2 个端点。它接收一段 HTML 字符串,按指定动作返回重新排版或压缩后的 HTML,并附带处理前后的字节数对比。
接口面向的是后端模板渲染、富文本编辑器、邮件模板这类「HTML 由程序生成」的场景。这类产物经常出现缩进丢失、标签挤在一行、残留注释等问题,人工整理成本高,而该接口把格式化和压缩做成一次请求即可完成的操作。
能力上分为两部分:一个免鉴权的健康检查端点,用于探活与版本确认;一个处理端点,支持 format(美化)与 minify(压缩)两种动作,返回值同时给出结果长度、原始长度与两者比值,便于在流水线里直接判断压缩收益。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/html-tool/ping | 健康检查,返回服务版本 | 免鉴权 |
POST | /api/html-tool/process | 对 HTML 执行格式化或压缩 | 需要 API Key |
鉴权采用数据鱼API全站统一 Key,通过请求头 X-API-Key 或查询参数 api_key 传递;未携带返回 4011,无效返回 4013。健康检查端点豁免鉴权,可用作上线前的连通性探测。
响应统一为 code、msg、data 三段结构,code 为 0 表示成功。参数类错误使用 4001(缺参)、4002(格式或取值非法)、4003(取值不在支持列表)、4004(目标未收录);服务侧错误为 5000/5001,上游不可用为 5031/5032,后者不会以伪造数据兜底。本接口不依赖第三方数据源,正常情况下只会出现参数类与内部错误。
GET 与 POST 均可调用,POST 支持 JSON body 与表单提交,参数名与查询参数完全一致,迁移时无需改动字段。
用于确认服务存活并读取版本号,无请求参数。成功时 data.version 返回当前版本字符串,文档示例为 1.0.0。
GET /api/html-tool/ping对传入的 HTML 执行一次处理,返回结果串与体积统计。
参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
html | string | 是 | — | 待处理的 HTML 源串,为空时报参数错误 |
action | string | 否 | format | 处理动作,minify 执行压缩,其余取值按格式化处理 |
返回字段要点:data.result 为处理后的 HTML;data.action 原样回显请求动作;data.size 内含 original(原始字节数)、result(结果字节数)、ratio(结果与原始之比,保留四位小数)。
POST /api/html-tool/process
Content-Type: application/json
{"html": "<p>hello world</p>", "action": "minify"}ratio 同样按字节计算。format 走 DOM 解析后重新输出,会规整缩进与换行,输出末尾通常带一个换行。minify 为规则替换:去掉标签前后的空白、合并连续空白、移除 HTML 注释,不解析 DOM 结构。5000/5001。format 得到可读版本后直接比对结构。minify,用 size.ratio 评估压缩收益,决定是否写入构建产物。action 只有 minify 一个有效分支,其余取值(包括文档示例中的 "1")都会走格式化逻辑,并且回显为请求传入的原值。若依赖回显判断动作类型,需要在客户端自行校验。html 在实现中返回 code: 400 与固定中文提示,而通用错误码表以 4001 表示缺参;客户端应同时兼容两种写法,统一按「参数缺失」处理即可。minify 是正则级压缩,不区分上下文,pre、textarea 内的空白也会被合并。含预格式文本的内容应改用 format,或在调用前单独保护这类区块。format 依赖服务端 DOM 扩展解析,畸形 HTML 会被容错修正,标签闭合方式可能与原文不同,不要用它做逐字节等价校验。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。