客户端 HTTP API 指南

本文描述 HCIP 客户端运行时对外提供的 HTTP API 接口契约，适用于私有化部署后的业务系统集成。

1. 基础信息

默认服务地址由 config.yaml 中的 server.listen 决定。示例：

server:
  listen: "0.0.0.0:8080"

本指南中的示例以以下地址为准：

http://127.0.0.1:8080

所有接口当前均为 GET 方法。除 /health、/version、/license 外，查询接口会根据对应产品 license 状态决定是否可用。

2. 访问控制

HCIP 客户端 HTTP API 不内置 API Key、Token、签名或账号鉴权。私有化部署时应由部署环境控制访问边界：

仅监听内网地址或本机地址。
使用防火墙或安全组限制访问来源。
通过 Nginx、API Gateway、Ingress 等反向代理增加鉴权。
对外暴露时启用 HTTPS，必要时使用 mTLS。

3. 响应格式

3.1 默认 JSON 响应

默认配置：

response:
  format: "json"
  style: "snake"

成功响应基本结构：

{
  "code": 200,
  "message": "处理成功",
  "data": {},
  "request_id": "e14de18265c544fcaed2d1243d5f037c"
}

错误响应基本结构：

{
  "code": 400,
  "message": "IP地址格式错误",
  "data": null,
  "request_id": "64c55c1039454f7eba2fa885a28ca837"
}

response.style 控制字段命名：

snake：返回 request_id、long_ip、region_id、city_id 等字段。
camel：返回 requestId、longIp、regionId、cityId 等字段。

3.2 旧客户端兼容响应

请求头 X-HCIP-Response-Version 优先级最高，会覆盖 response.format 和 response.style。

curl -H 'X-HCIP-Response-Version: v1' \
  'http://127.0.0.1:8080/ip?ip=113.116.36.105'

支持值：

v1：返回 ret、msg、data、log_id。
v2：返回 code、message、data、request_id。

兼容响应使用旧业务码，例如 40001、40002、40003。

4. 公共状态码

HTTP 状态码	典型含义
`200`	请求成功
`400`	参数缺失、参数格式错误或数据未找到
`403`	对应产品 license 不可用、过期或未授权
`405`	请求方法不支持
`503`	对应产品数据库未加载
`500`	服务端解析数据失败

默认 JSON 响应中的 code 通常与 HTTP 状态码一致。旧兼容模式下业务码可能为 40001、40002、40003。

5. GET /health

健康检查接口。只要至少一个已启用产品 license 有效，接口返回 HTTP 200；否则返回 HTTP 403。

请求

curl 'http://127.0.0.1:8080/health'

成功响应

{
  "ok": true,
  "status": "running",
  "products": {
    "hcip": {
      "status": "valid",
      "valid": true,
      "message": "license valid"
    },
    "mobile": {
      "status": "valid",
      "valid": true,
      "message": "license valid"
    }
  }
}

失败响应

{
  "ok": false,
  "status": "license_invalid",
  "products": {
    "hcip": {
      "status": "expired",
      "valid": false,
      "message": "license expired"
    },
    "mobile": {
      "status": "disabled",
      "valid": false,
      "message": "手机号归属地授权未找到，手机号查询服务启动失败，已跳过"
    }
  }
}

产品状态

状态	含义
`valid`	license 有效，产品可用
`expired`	license 已过期
`invalid`	license 无效
`load_failed`	license 加载失败
`disabled`	产品未启用或被跳过

6. GET /version

返回程序版本和当前加载的 DBX 信息。

请求

curl 'http://127.0.0.1:8080/version'

响应

{
  "name": "hcip",
  "version": "0.1.0",
  "products": {
    "hcip": {
      "db_path": "/opt/hcip/ip.dbx",
      "db_source_name": "hcip-20260601.db",
      "db_source_sha256": "..."
    },
    "mobile": {
      "db_path": "/opt/hcip/mobile.dbx",
      "db_source_name": "mobile-20260601.db",
      "db_source_sha256": "..."
    }
  },
  "db_loaded_at": "2026-06-09T08:00:00Z"
}

字段说明：

字段	说明
`name`	服务名称，固定为 `hcip`
`version`	程序版本，构建时注入
`products.*.db_path`	当前产品 DBX 文件路径
`products.*.db_source_name`	DBX header 中记录的源数据名称
`products.*.db_source_sha256`	DBX header 中记录的源数据 SHA-256
`db_loaded_at`	当前内存数据库加载时间

7. GET /license

返回两个产品的 license 状态。

请求

curl 'http://127.0.0.1:8080/license'

响应

{
  "products": {
    "hcip": {
      "valid": true,
      "subject": "customer-a",
      "not_before": "2026-01-01T00:00:00Z",
      "not_after": "2027-01-01T00:00:00Z",
      "days_left": 205,
      "license_status": "valid",
      "message": "license valid"
    },
    "mobile": {
      "valid": false,
      "days_left": 0,
      "license_status": "disabled",
      "message": "手机号归属地授权未找到，手机号查询服务启动失败，已跳过"
    }
  }
}

字段说明：

字段	说明
`valid`	当前是否可用
`subject`	license 主体，通常对应客户标识
`not_before`	license 生效时间
`not_after`	license 过期时间
`days_left`	剩余天数，过期后为 0
`license_status`	当前状态
`message`	状态说明
`error`	加载失败时的错误信息

8. GET /ip

IP 归属地查询接口。

请求

curl 'http://127.0.0.1:8080/ip?ip=113.116.36.105'

Query 参数

参数	必填	说明
`ip`	是	IPv4 或 IPv6 地址。特殊值 `localhost` 会按请求来源解析为请求发起者 IP 地址。

成功响应

默认 snake 风格：

{
  "code": 200,
  "message": "处理成功",
  "data": {
    "ip": "113.116.242.237",
    "long_ip": "1903489773",
    "isp": "中国电信",
    "area": "华南",
    "region_id": "440000",
    "region": "广东",
    "city_id": "440300",
    "city": "深圳",
    "district": "光明区",
    "district_id": "440311",
    "country_id": "CN",
    "country": "中国",
    "lat": "22.748750",
    "lng": "113.936059"
  },
  "request_id": "e14de18265c544fcaed2d1243d5f037c"
}

camel 风格会将部分字段改为 longIp、regionId、cityId、districtId、countryId、requestId。

字段说明

字段	说明
`ip`	查询 IP
`long_ip`	IPv4 长整型字符串；IPv6 场景可能按数据源返回
`isp`	运营商
`area`	大区
`region_id`	省级行政区划代码
`region`	省份/地区
`city_id`	城市行政区划代码
`city`	城市
`district`	区县
`district_id`	区县行政区划代码
`country_id`	国家/地区代码
`country`	国家/地区名称
`lat`	纬度
`lng`	经度

错误响应

缺少 IP：

{
  "code": 400,
  "message": "IP地址参数不能为空",
  "data": null,
  "request_id": "64c55c1039454f7eba2fa885a28ca837"
}

IP 格式错误：

{
  "code": 400,
  "message": "IP地址格式错误",
  "data": null,
  "request_id": "64c55c1039454f7eba2fa885a28ca837"
}

IP 未找到：

{
  "code": 400,
  "message": "IP地址未找到",
  "data": null,
  "request_id": "64c55c1039454f7eba2fa885a28ca837"
}

license 不可用：

{
  "code": 403,
  "message": "license expired",
  "data": null,
  "request_id": "64c55c1039454f7eba2fa885a28ca837"
}

9. GET /query

/query 是 /ip 的别名，参数、响应、错误码与 /ip 一致。

请求

curl 'http://127.0.0.1:8080/query?ip=113.116.36.105'

建议新接入系统优先使用 /ip，仅在兼容旧调用方时保留 /query。

10. GET /mobile

手机号归属地查询接口。

请求

curl 'http://127.0.0.1:8080/mobile?mobile=18138434699'

Query 参数

参数	必填	说明
`mobile`	是	中国大陆手机号。

成功响应

默认 snake 风格：

{
  "code": 200,
  "message": "处理成功",
  "data": {
    "types": "中国电信",
    "city": "深圳",
    "zip_code": "518000",
    "isp": "中国电信",
    "prov": "广东",
    "num": "1813843",
    "city_code": "0755",
    "lat": "22.543099",
    "area_code": "440300",
    "lng": "114.057868"
  },
  "request_id": "02e083adc869472fbd1b7f322e0e4489"
}

camel 风格会将 zip_code、city_code、area_code、request_id 改为 zipCode、cityCode、areaCode、requestId。

字段说明

字段	说明
`types`	号段类型或运营商类型
`city`	城市
`zip_code`	邮政编码
`isp`	运营商名称
`prov`	省份
`num`	号段
`city_code`	电话区号
`lat`	纬度
`area_code`	行政区划代码
`lng`	经度

错误响应

缺少手机号：

{
  "code": 400,
  "message": "手机号参数不能为空",
  "data": null,
  "request_id": "02e083adc869472fbd1b7f322e0e4489"
}

手机号格式错误：

{
  "code": 400,
  "message": "手机号格式错误",
  "data": null,
  "request_id": "02e083adc869472fbd1b7f322e0e4489"
}

手机号未找到：

{
  "code": 400,
  "message": "手机号未找到",
  "data": null,
  "request_id": "02e083adc869472fbd1b7f322e0e4489"
}

mobile license 不可用：

{
  "code": 403,
  "message": "license expired",
  "data": null,
  "request_id": "02e083adc869472fbd1b7f322e0e4489"
}

11. 接口可用性与 license 状态

产品与接口对应关系：

产品	配置块	接口
`hcip`	`products.hcip`	`/ip`
`mobile`	`products.mobile`	`/mobile`

当某个产品 license 失效、过期、加载失败或权限不匹配时：

/health 会反映该产品状态。
/license 会返回该产品状态和错误说明。
该产品对应查询接口返回 HTTP 403。
其他产品如果 license 有效，仍可继续服务。

12. 调用建议

业务系统接入时建议：

启动后先调用 /health 做健康检查。
通过 /version 记录当前 DBX source，用于排查数据版本问题。
通过 /license 监控授权到期时间。
查询接口按 HTTP 状态码和响应体 code 同时判断结果。
如果需要兼容旧字段，优先通过配置 response.style 或请求头 X-HCIP-Response-Version 固定响应格式。
不要假设 request_id 可重复或有业务含义，它仅用于单次请求追踪。