ApiOne HTTP Client 使用指南

ApiOne 是数字海南的统一 API 网关平台，提供标准化的接口调用服务。

前置检查清单

调用 ApiOne 接口前，请确认：

• [ ] 项目已引入 apione-http-client 依赖
• [ ] 已从功能提供方获取 apiName、ak、sk
• [ ] 已确定接口所在区域（INTRA/INTER/PUBLIC）
• [ ] 已确定目标环境地址

环境信息

环境	接口地址
统一地址	https://api-one.digitalhainan.com.cn/apione

依赖配置

<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>apione-http-client</artifactId>
    <version>1.0.5-SNAPSHOT</version>
</dependency>

参考文档索引

文档	内容	链接
基础调用指南	通用工具类封装、Path/Query/Header 参数传递、调试排查	basic-usage.md
Content-Type 调用	JSON、XML、Form、Multipart 等不同格式的调用示例	content-types.md
文件处理	文件上传与二进制文件下载	file-handling.md
Spring Boot 集成	多客户端配置、Manager 层调用规范、ApiName 动态配置	spring-boot-integration.md

Step-by-step 调用流程

Step 1：准备调用参数

参数	说明	获取方式
apiName	接口名称	功能提供方提供
ak	Access Key	我的应用-我申请的功能-对应功能查看
sk	Secret Key	我的应用-我申请的功能-对应功能查看
region	接口所在区域	INTRA(政务外网), INTER(政务互联网), PUBLIC(公网)
requestUrl	请求地址	根据环境选择生产或测试地址

Step 2：构建参数并执行

使用 HttpParameters.builder() 构建参数，通过 HttpCaller.getInstance().call() 执行调用。详细代码示例参见 basic-usage.md。

接口类型速查

接口类型	MediaType	参考文档
JSON 接口（默认）	application/json	content-types.md
XML 接口	application/xml	content-types.md
Form 表单	application/x-www-form-urlencoded	content-types.md
文件上传	multipart/form-data	file-handling.md
含 Path 参数	-	basic-usage.md
含 Query 参数	-	basic-usage.md
含 Header 参数	-	basic-usage.md

常见状态码处理

状态码	错误信息	解决方案
401	Invalid signature	加签错误，请使用 apione-sdk 进行调用
401	Clock skew exceeded	请求已过期（默认5分钟有效），检查服务器时间与北京时间差值
401	Invalid apiname or ak unauthorized	凭证未授权该接口，检查 apiname 是否被授权/拼写是否正确
401	Api info not conf	凭证未授权任何接口，请联系功能提供方
401	access key or signature missing	鉴权参数缺失，请使用 apione-sdk
429	Limit xxx requests xxx	调用被限制，请联系功能提供方
403	Your IP address is not allowed	提供调用服务 IP 给功能提供方
500	timeout	网络不通或超时时间过短