首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >Git 仓库地址校验接口接入说明|数据鱼API

Git 仓库地址校验接口接入说明|数据鱼API

原创
作者头像
用户12862874
发布于 2026-11-21 21:30:17
发布于 2026-11-21 21:30:17
130
举报

接口简介

「Git 仓库地址校验」是数据鱼API平台提供的仓库地址格式检查接口,Base 路径 /api/gitcheck,共 3 个端点:健康检查,以及 GET 与 POST 两种形态的校验端点。

数据鱼API 的这个接口做两件事:先按正则判断传入字符串是否符合 Git 仓库地址的书写规则,再对公开托管平台的 HTTP 地址发一次 HEAD 请求探测可达性。返回里有四个字段:是否合法、规范化后的地址、托管平台类型、可达状态。

格式判定接受两类写法:带 http、https、git、ssh 协议前缀且以 .git 结尾的地址,或者 git@主机:路径.git 这种 SCP 简写。协议前缀大小写不敏感,但 .git 后缀是硬性要求,缺了就直接判为非法,这正是很多人把浏览器地址栏里的仓库页地址贴进来时报错的原因。

平台识别用子串匹配:地址中出现 GitHub、GitLab、Gitee 对应的平台名就归入相应类型,三者都不含则归 Other。可达性探测只对「平台为 GitHub 或 GitLab」且「带 http 前缀」的地址执行,其余地址的 status 固定为 unknown,不会因为不可达而判非法。

端点总览

方法

路径

说明

鉴权

GET

/api/gitcheck/ping

健康检查

需要

POST

/api/gitcheck/check

校验地址(请求体)

需要

GET

/api/gitcheck/check

校验地址(查询串)

需要

通用约定

鉴权沿用数据鱼API 全站规则:X-API-Key 请求头或 ?api_key= 查询参数,缺失 4011、无效 4013。响应统一为 {code, msg, data}。

参数层面的错误与结果层面的「不合法」是两件事:完全没传 url 时返回 4001、msg 为「缺少 url 参数」;传了但格式不对时仍是 code: 0,在 data.valid 里给 false 并附中文原因。客户端判断成败要看 data.valid,不能只看 HTTP 状态码。

ping 只返回 msg: pong,不带 data,也不带版本号;做探活时不要按其它接口的结构去取 data.version。

核心端点详解

校验地址(check)

对传入的仓库地址做格式判定与可达性探测。

参数

类型

必填

默认

说明

url

string

是

—

仓库地址,首尾空白会被裁掉

返回字段:valid 布尔值,url 为裁剪后的地址,type 取 GitHub / GitLab / Gitee / Other,status 取 accessible / inaccessible / unknown。格式非法时只返回 valid: false 与 msg,不带 type 与 status。

可达性探测是同步的 HEAD 请求,跟随重定向,超时 5 秒。也就是说一个不可达的公开仓库地址会让这次调用最长多等 5 秒;批量校验时应控制并发,避免请求堆积。

代码语言:javascript
复制
POST /api/gitcheck/check
Content-Type: application/json

{"url": "REPO_URL.git"}

上例返回 valid: true、type 取决于地址中的托管平台,status 取决于探测结果。把地址末尾的 .git 去掉会得到 valid: false,msg 为「非法的 Git 仓库地址格式」。

数据与限制

  • 格式规则:带 http、https、git、ssh 协议前缀且以 .git 结尾,或 git@主机:路径.git 形式的 SCP 简写;前缀不区分大小写。
  • .git 后缀为必需项,结尾带斜杠、带查询串、带锚点的地址都会被判非法。
  • 平台识别为子串匹配,只区分 GitHub、GitLab、Gitee 与 Other 四种结果。
  • 可达性探测仅对 GitHub 与 GitLab 平台且带 http 前缀的地址执行,超时 5 秒,只看响应状态码是否为 200。
  • 地址长度未做限制,也没有批量参数,一次只能校验一个地址。
  • 接口不解析仓库内容、不校验权限、不返回默认分支与提交信息。

典型使用场景

  • 项目登记表单在提交前校验仓库地址,把「缺少 .git 后缀」这类错误挡在前端。
  • 代码托管迁移工具先跑一遍地址清单,把非法与不可达的条目分两列导出。
  • CI 配置生成器按 type 选择不同的克隆协议与凭据模板。
  • 资产管理后台定期抽查公开仓库的可达性,inaccessible 的条目进入人工复核队列。

注意事项

  • 文档只给了一条 valid: false 的响应示例,没有列出 url、type、status 三个字段,也没有说明 status 的三个取值,实际返回比文档更丰富。
  • .git 后缀是硬性要求,仓库页地址以及以斜杠结尾的克隆地址都会被判非法,这是最常见的误报来源。
  • status 为 unknown 不等于不可达:SSH 地址、Gitee 地址与自建 Git 服务都只做格式校验,不做探测。
  • 探测只认状态码 200,GitHub 对私有仓库返回 404,会被标成 inaccessible,但这只说明匿名访问不到,不代表地址写错。
  • 平台识别是子串匹配,平台名出现在更长的域名或路径里也会被判为对应平台并触发服务端请求,接入时不要把完全不可信的地址直接透传。
  • 本接口只做格式与可达性初筛,不保证地址指向的仓库存在、可克隆或有权访问;克隆与鉴权请以 Git 客户端与托管平台的返回为准。

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

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

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 校验地址(check)
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档