首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API · 摘要生成接口(hash-gen)接入指南

数据鱼API · 摘要生成接口(hash-gen)接入指南

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

接口简介

「摘要生成」是数据鱼API平台提供的文本哈希计算接口,Base 路径 /api/hash-gen,共 2 个端点。调用方提交一段文本和算法名,接口返回对应的十六进制摘要字符串;不传算法时按 MD5 计算。它只做单向摘要生成,不保存原文,也不提供摘要比对或校验服务。

与站内已有的哈希校验类文章不同,这个接口的落点是「生成」:算法清单由服务端的 hash_algos() 决定,ping 端点会把当前环境支持的全部算法名一次性列出。同一份代码部署在不同 PHP 版本上,清单可能略有增减,因此接入前应先读 ping 的结果,而不是把算法名写死在代码里。

算法覆盖面较广,包含 MD 系列、SHA-1、SHA-2、SHA-3、RIPEMD、Whirlpool、Tiger、Snefru、GOST、Adler-32、CRC32 变体、FNV、Joaat、Murmur3、xxHash 与 HAVAL。它们并非都适合安全用途,接口本身不区分「密码学摘要」与「非密码学校验和」,选型责任在调用方。

端点总览

方法

路径

说明

鉴权

GET

/api/hash-gen/ping

健康检查,返回版本号与当前支持的算法清单

免鉴权

POST

/api/hash-gen/calc

对提交的文本计算指定算法的摘要

需要 Key

通用约定

鉴权走全站统一 Key:请求头 X-API-Key 或查询参数 api_key,缺失返回 4011,无效返回 4013。ping 端点免鉴权,可用于探活与获取算法清单;calc 必须带 Key。

响应统一为 {"code":0,"msg":"success","data":{...}}。本接口的 calc 只接受 JSON 请求体,字段从 body 中读取;ping 无参数。错误码方面,4001 表示缺少必填参数,4002 表示参数格式或取值非法(算法不支持即属此类),4003 为取值不在支持列表,4004 为查询目标未收录,4050 为方法不允许;4011、4013、4040 与全站一致,5000、5001 为服务内部错误。

数据鱼API在错误信息上给得比较直接:算法名拼错时返回 Unsupported algorithm,缺少文本时返回 Missing parameter: text,便于在日志里直接定位。

核心端点详解

摘要计算

对一段文本按指定算法生成摘要,是接口唯一的业务端点。

参数

类型

必填

默认

说明

text

string

是

—

待计算摘要的文本,空值返回 4001

algo

string

否

md5

算法名,取值见 ping 返回的 algos,大小写不敏感

返回 data.algo 为实际使用的算法名(统一转为小写),data.hash 为摘要结果。结果编码为十六进制小写字符串,长度由算法决定,例如 MD5 为 32 位、SHA-1 为 40 位、SHA-256 为 64 位、SHA-512 为 128 位。

代码语言:javascript
复制
POST /api/hash-gen/calc
Content-Type: application/json

{"text":"hello world","algo":"sha256"}

算法名会先转小写再与支持列表比对,因此 SHA256、Sha256 与 sha256 等价;但 sha-256 这类带连字符的写法不在列表中,会返回 4002。text 按原样参与计算,不做去空格、去换行或编码转换,前后空白会影响结果。

健康检查与算法清单

用于探活和读取当前环境的算法支持情况,无需 Key。

参数

类型

必填

默认

说明

无

—

—

—

该端点不接受业务参数

返回 data.version 与 data.algos 数组。algos 是服务端 hash_algos() 的原始输出,顺序由运行环境决定,调用方不要依赖数组顺序。

代码语言:javascript
复制
GET /api/hash-gen/ping

把 algos 缓存到本地并在启动时校验一次,可以避免把不存在的算法名写进业务代码;若部署环境升级导致清单变化,也能在探活阶段发现。

数据与限制

  • 端点数量:业务端点仅 calc 一个,ping 为辅助端点。
  • 默认算法:algo 省略时按 md5 计算。
  • 算法来源:以 ping 返回的 algos 为准,文档示例中列出的名称包括 md2、md4、md5、sha1、sha224、sha256、sha384、sha512、sha512/224、sha512/256、sha3-224 至 sha3-512、ripemd128 至 ripemd320、whirlpool、tiger128,3 至 tiger192,4、snefru、snefru256、gost、gost-crypto、adler32、crc32、crc32b、crc32c、fnv132、fnv1a32、fnv164、fnv1a64、joaat、murmur3a、murmur3c、murmur3f、xxh32、xxh64、xxh3、xxh128 与 HAVAL 各轮次变体。
  • 文本长度:文档未给出上限,实际受请求体大小与 PHP 配置约束,大文本建议先在本地分块或改用文件摘要方案。
  • 字符编码:按提交的字节序列计算,UTF-8 中文与 ASCII 的结果不可互相推算。
  • 缓存:接口不缓存结果,相同输入每次实时计算。
  • 时效性:摘要算法本身无时效问题,算法清单随运行环境变化。

典型使用场景

  • 内容去重:对正文计算 SHA-256,用摘要值判断两篇文章是否完全一致。
  • 缓存键生成:把查询参数拼接后取 MD5 或 xxh3,作为缓存键,兼顾长度与速度。
  • 接口签名:对请求参数串取 HMAC 之外的普通摘要,作为轻量校验字段(不适合对抗篡改)。
  • 数据管道校验和:用 CRC32 或 Adler-32 为批量数据生成短校验值,快速发现传输损坏。

注意事项

  • API.md 的参数表把 text 标为可选、类型标为 array/object,与实现不符。实际实现要求 text 为非空字符串,空值返回 4001;algo 是字符串而非数组,默认 md5。以本文与实测为准。
  • API.md 称 GET 与 POST 均可、POST 支持表单,但实现只从 JSON 请求体读取参数。用查询参数或表单提交会因取不到 text 而返回 4001,接入时统一使用 Content-Type: application/json。
  • algo 在比对前会转小写,但不会做别名映射;sha-256、SHA_256 等写法均会失败。
  • 列表中的 md2、md4、md5、sha1、crc32、adler32 等不适合安全场景,密码存储与签名校验应另选专用方案。
  • 本接口不做原文存储与摘要回查,无法通过摘要反推文本;摘要碰撞在非密码学算法上概率更高,去重场景应接受这一前提。
  • 全站错误码表中的 5031、5032 表示上游依赖不可用;摘要计算不依赖外部服务,实际调用中一般不出现。以上两处文档与实现的差异由数据鱼API当前代码约定决定,后续版本若修正参数表,应以接口实际返回为准。

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

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

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