首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API接口详解:HTML 格式化与压缩工具

数据鱼API接口详解:HTML 格式化与压缩工具

原创
作者头像
用户12862874
发布于 2026-11-21 21:32:28
发布于 2026-11-21 21:32:28
120
举报

接口简介

「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。

代码语言:javascript
复制
GET /api/html-tool/ping

HTML 处理

对传入的 HTML 执行一次处理,返回结果串与体积统计。

参数

类型

必填

默认值

说明

html

string

是

—

待处理的 HTML 源串,为空时报参数错误

action

string

否

format

处理动作,minify 执行压缩,其余取值按格式化处理

返回字段要点:data.result 为处理后的 HTML;data.action 原样回显请求动作;data.size 内含 original(原始字节数)、result(结果字节数)、ratio(结果与原始之比,保留四位小数)。

代码语言:javascript
复制
POST /api/html-tool/process
Content-Type: application/json

{"html": "<p>hello  world</p>", "action": "minify"}

数据与限制

  • 体积统计基于字节长度而非字符数,UTF-8 下中文占 3 字节,ratio 同样按字节计算。
  • format 走 DOM 解析后重新输出,会规整缩进与换行,输出末尾通常带一个换行。
  • minify 为规则替换:去掉标签前后的空白、合并连续空白、移除 HTML 注释,不解析 DOM 结构。
  • 文档未给出单次请求的 HTML 长度上限,实际受请求体大小与服务端内存限制约束,超大文档建议分段处理。
  • 接口无结果缓存,相同输入每次都会重新计算。
  • 处理失败时不返回部分结果,直接给出 5000/5001。

典型使用场景

  • 后端模板或组件库渲染出的 HTML 在调试时需要缩进对齐,调用 format 得到可读版本后直接比对结构。
  • 发布前对页面片段执行 minify,用 size.ratio 评估压缩收益,决定是否写入构建产物。
  • 在内容审核或版本对比流程中先统一格式化再做逐行 diff,避免空白差异造成噪声。
  • 富文本编辑器粘贴进来的 HTML 结构混乱,提交前先做一次规范化再入库。

注意事项

  • action 只有 minify 一个有效分支,其余取值(包括文档示例中的 "1")都会走格式化逻辑,并且回显为请求传入的原值。若依赖回显判断动作类型,需要在客户端自行校验。
  • 空 html 在实现中返回 code: 400 与固定中文提示,而通用错误码表以 4001 表示缺参;客户端应同时兼容两种写法,统一按「参数缺失」处理即可。
  • minify 是正则级压缩,不区分上下文,pre、textarea 内的空白也会被合并。含预格式文本的内容应改用 format,或在调用前单独保护这类区块。
  • format 依赖服务端 DOM 扩展解析,畸形 HTML 会被容错修正,标签闭合方式可能与原文不同,不要用它做逐字节等价校验。
  • 本文行为描述以数据鱼API接口文档与当前实现为准,字节数、版本号等返回值随运行环境变化,接入时以实际响应为准。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 健康检查
    • HTML 处理
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档