# ghostapi-client-sdk **Repository Path**: lzdghost/ghostapi-client-sdk ## Basic Information - **Project Name**: ghostapi-client-sdk - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-06-25 - **Last Updated**: 2024-10-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SDK开发者文档 # 指南 ## 简介智桥API 开发者文档是**智桥API**的一个接口调用工具包，通过[SDK]( https://gitee.com/lzdghost/ghostapi-client-sdk)即可将轻松、稳定、安全的集成接口到您的项目中，实现更高效的开发和调用。帮助您实现更快速、便捷的开发和调用体验。 ### 优势 + **去客户端SDK支持：** 为了方便开发者集成接口到自己的代码中，平台提供了客户端SDK，使调用接口变得更加简单和便捷。 + **简洁高效：** 稳定、安全、高效的接口调用服务，帮助您实现更快速、便捷的开发和调用体验。 + **开发者文档和技术支持：** 平台提供了详细的开发者文档和技术支持，帮助开发者快速接入和发布接口，解决遇到的问题和困难。 + **多样化的接口选择：** 丰富多样的接口供您选择，涵盖了各个领域的功能和服务，满足不同的需求。 + **在线调试功能：** 您可以在平台上进行接口在线调试，快速验证接口的功能和效果，节省了开发调试的时间和工作量。 ### 参与贡献欢迎各位道友一起来参与完善SDK，期待你的 PR！ + 贡献代码：代码地址 [SDK]( https://gitee.com/lzdghost/ghostapi-client-sdk)，欢迎提交 Issue 或者 Pull Requests + Demo示例：[sdk-demo](https://gitee.com/lzdghost/sdk-demo) ## 快速开始 ### 引入Maven依赖 + 注意：由于改SDK暂时还没有发布到Maven中央仓库，所以请下载jar包后，导入到你的本地maven仓库地址 ```xml cn.whut ghostapi-client-sdk 0.0.1 ``` ### 配置客户端 #### 获取开发者密钥 + 前往智桥API平台获取 #### 初始化客户端GhostClient对象 ##### 方法一：配置文件注入 + 配置密钥 - yml ```yaml ghost: client: access-key: 你的 accessKey secret-key: 你的 secretKey ``` - properties ```properties ghost.client.access-key=你的 accessKey ghost.client.secret-key=你的 secretKey ``` + 注入GhostClient ```java @Resource private GhostClient ghostClient; ``` ##### 方法二：主动注入 ```java GhostClient ghostClient = new GhostClient(你的 accessKey, 你的 secretKey); ``` #### 发起请求 ```java // 构建请求参数 InvokeQueryRequest invokeQueryRequest = new InvokeQueryRequest(); // 接口类型 invokeQueryRequest.setType("getWeather"); // 接口参数 List requestParam = new ArrayList<>(); InvokeQueryRequest.Param param = new InvokeQueryRequest.Param(); // 接口参数名字 param.setName("city"); param.setValue("武汉"); requestParam.add(param); invokeQueryRequest.setRequestParams(requestParam); // 请求 SDKResponse sdkResponse = ghostClient.doInvoke(invokeQueryRequest); ``` #### 返回响应码 | 响应码 | 参数名称 | 参数描述 | | :---: | :---: | :---: | | 0 | SUCCESS | ok | | 40000 | PARAMS_ERROR | 请求参数错误 | | 40101 | NO_AUTH_ERROR | 无权限 | | 40300 | FORBIDDEN_ERROR | 禁止访问 | | 40400 | NOT_FOUND_ERROR | 请求数据不存在 | | 50000 | SYSTEM_ERROR | 系统内部异常 | | 50001 | OPERATION_ERROR | 操作失败 | # API接口详情 ## 智能AI ### 接口信息 + 接口状态：正常 + 返回格式：`JSON` + 扣除积分数：`5` ### 请求地址 ```plain http://localhost:9001/api/ai/aigc ``` ### 请求参数 | 参数名称 | 必选 | 类型 | 描述 | | :---: | :---: | :---: | :---: | | userInput | 是 | string | 用户输入 | ### 响应参数 | 参数名称 | 类型 | 描述 | | :---: | :---: | :---: | | code | int | 响应码 | | data | string | 响应结果 | | message | string | 响应信息 | | description | string | 响应描述 | ### 代码示例示例一：推荐👍 + 通过yml配置开发者调用凭证 ```yaml ghost: client: access-key: ghost secret-key: ghostandfox ``` + 注入service ```java @Resource private GhostClient ghostClient; ``` + 发起调用 ```java @PostMapping("/getAIGC1") public SDKResponse getAIGC (@RequestBody AIGCQueryRequest aigcQueryRequest) { SDKResponse sdkResponse = ghostClient.getAIGC(aigcQueryRequest); return sdkResponse; } ``` + 或者 ```java /** * @return SDKResponse */ @GetMapping("/getAIGC2") public SDKResponse getAIGC () { // 构建请求参数 InvokeQueryRequest invokeQueryRequest = new InvokeQueryRequest(); // 接口类型 invokeQueryRequest.setType("getAIGC"); // 接口参数 List requestParam = new ArrayList<>(); InvokeQueryRequest.Param param = new InvokeQueryRequest.Param(); // 接口参数名字 param.setName("userInput"); param.setValue("什么是Java SDK"); requestParam.add(param); invokeQueryRequest.setRequestParams(requestParam); // 请求 SDKResponse sdkResponse = ghostClient.doInvoke(invokeQueryRequest); return sdkResponse; } ``` 响应示例： ```json { "code": 0, "message": "ok", "data": "您好！有什么我可以帮助您的吗？", "description": "aigc成功" } ``` 示例二： ```java @PostMapping("/getAIGC3") public SDKResponse getAIGC (@RequestBody AIGCQueryRequest aigcQueryRequest) { GhostClient ghostClient = new GhostClient("ghost", "ghostandfox"); SDKResponse sdkResponse = ghostClient.getAIGC(aigcQueryRequest); return sdkResponse; } ``` ## 天气信息 ### 接口信息 + 接口状态：正常 + 返回格式：`JSON` + 扣除积分数：`3` ### 请求地址 ```plain http://localhost:9001/api/interface/weather ``` ### 请求参数 | 参数名称 | 必选 | 类型 | 描述 | | :---: | :---: | :---: | :---: | | city | 否 | string | 城市 | | ip | 否 | string | ip地址 | ### 响应参数 | 参数名称 | 类型 | 描述 | | :---: | :---: | :---: | | code | int | 响应码 | | data.city | string | 城市名称 | | data.data.date | string | 日期 | | data.data.week | string | 星期几 | | data.data.type | string | 天气类型 | | data.data.low | string | 最低温度 | | data.data.high | string | 最高温度 | | data.data.fengxiang | string | 风向 | | data.data.fengli | string | 风力 | | data.data.night.type | string | 夜间天气类型 | | data.data.night.fengxiang | string | 夜间风向 | | data.data.night.fengli | string | 夜间风力 | | data.data.air.aqi | int | 空气质量指数 | | data.data.air.aqi_level | int | 空气质量指数级别 | | data.data.air.aqi_name | string | 空气质量指数名称 | | data.data.air.co | string | 一氧化碳浓度 | | data.data.air.no2 | string | 二氧化氮浓度 | | data.data.air.o3 | string | 臭氧浓度 | | data.data.air.pm10 | string | PM10浓度 | | data.data.air.pm2.5 | string | PM2.5浓度 | | data.data.air.so2 | string | 二氧化硫浓度 | | data.data.tip | string | 提示信息 | | message | string | 响应信息 | | description | string | 响应描述 | ### 代码示例示例一：推荐👍 + 通过yml配置开发者调用凭证 ```yaml ghost: client: access-key: ghost secret-key: ghostandfox ``` + 注入service ```java @Resource private GhostClient ghostClient; ``` + 发起调用 ```java @PostMapping("/getWeather1") public SDKResponse getWeather (@RequestBody WeatherQueryRequest weatherQueryRequest) { SDKResponse sdkResponse = ghostClient.getWeather(weatherQueryRequest); return sdkResponse; } ``` + 或者 ```java @GetMapping("/getWeather2") public SDKResponse getWeather () { // 构建请求参数 InvokeQueryRequest invokeQueryRequest = new InvokeQueryRequest(); // 接口类型 invokeQueryRequest.setType("getWeather"); // 接口参数 List requestParam = new ArrayList<>(); InvokeQueryRequest.Param param = new InvokeQueryRequest.Param(); // 接口参数名字 param.setName("city"); param.setValue("武汉"); requestParam.add(param); invokeQueryRequest.setRequestParams(requestParam); // 请求 SDKResponse sdkResponse = ghostClient.doInvoke(invokeQueryRequest); return sdkResponse; } ``` 响应示例： ```json { "code": 0, "message": "ok", "data": { "city": "武汉市", "weather": { "data": { "date": "2024-10-24", "week": "星期四", "type": "多云", "low": "11°C", "high": "23°C", "fengxiang": "微风", "fengli": "1-3级", "night": { "type": "多云", "fengxiang": "微风", "fengli": "1-3级" } }, "air": { "aqi": 47, "aqi_level": 1, "aqi_name": "优", "co": "0.8", "no2": "20", "o3": "148", "pm10": "37", "pm2.5": "27", "so2": "13" } }, "tip": "现在的温度比较舒适~" }, "description": "获取天气" } ``` 示例二： ```java @PostMapping("/getWeather3") public SDKResponse getWeather (@RequestBody WeatherQueryRequest weatherQueryRequest) { GhostClient ghostClient = new GhostClient("ghost", "ghostandfox"); SDKResponse sdkResponse = ghostClient.getWeather(weatherQueryRequest); return sdkResponse; } ``` ## IP信息归属地 ### 接口信息 + 接口状态：正常 + 返回格式：`JSON` + 扣除积分数：`3` ### 请求地址 ```plain http://localhost:9001/api/interface/ipInfo ``` ### 请求参数 | 参数名称 | 必选 | 类型 | 描述 | | :---: | :---: | :---: | :---: | | ip | 是 | string | ip地址 | ### 响应参数 | 参数名称 | 类型 | 描述 | | :---: | :---: | :---: | | code | int | 响应码 | | data.ip | string | ip地址 | | data.data.country | string | 国家 | | data.data.prov | string | 省份 | | data.data.city | string | 城市 | | data.data.lsp | string | 运营商 | | message | string | 响应信息 | | description | string | 响应描述 | ### 代码示例示例一：推荐👍 + 通过yml配置开发者调用凭证 ```yaml ghost: client: access-key: ghost secret-key: ghostandfox ``` + 注入service ```java @Resource private GhostClient ghostClient; ``` + 发起调用 ```java @PostMapping("/getIpInfo1") public SDKResponse getIpInfo (@RequestBody IpInfoQueryRequest ipInfoQueryRequest) { SDKResponse sdkResponse = ghostClient.getIpInfo(ipInfoQueryRequest); return sdkResponse; } ``` + 或者 ```java @GetMapping("/getIpInfo2") public SDKResponse getIpInfo () { // 构建请求参数 InvokeQueryRequest invokeQueryRequest = new InvokeQueryRequest(); // 接口类型 invokeQueryRequest.setType("getIpInfo"); // 接口参数 List requestParam = new ArrayList<>(); InvokeQueryRequest.Param param = new InvokeQueryRequest.Param(); // 接口参数名字 param.setName("ip"); param.setValue("58.154.0.0"); requestParam.add(param); invokeQueryRequest.setRequestParams(requestParam); // 请求 SDKResponse sdkResponse = ghostClient.doInvoke(invokeQueryRequest); return sdkResponse; } ``` 响应示例： ```json { "code": 0, "message": "ok", "data": { "city": "武汉市", "weather": { "data": { "date": "2024-10-24", "week": "星期四", "type": "多云", "low": "11°C", "high": "23°C", "fengxiang": "微风", "fengli": "1-3级", "night": { "type": "多云", "fengxiang": "微风", "fengli": "1-3级" } }, "air": { "aqi": 47, "aqi_level": 1, "aqi_name": "优", "co": "0.8", "no2": "20", "o3": "148", "pm10": "37", "pm2.5": "27", "so2": "13" } }, "tip": "现在的温度比较舒适~" }, "description": "获取天气" } ``` 示例二： ```java @PostMapping("/getWeather3") public SDKResponse getWeather (@RequestBody WeatherQueryRequest weatherQueryRequest) { GhostClient ghostClient = new GhostClient("ghost", "ghostandfox"); SDKResponse sdkResponse = ghostClient.getWeather(weatherQueryRequest); return sdkResponse; } ``` ## 你的名字 ### 接口信息 + 接口状态：正常 + 返回格式：`JSON` + 扣除积分数：`3` ### 请求地址 ```plain http://localhost:9001/api/interface/user ``` ### 请求参数 | 参数名称 | 必选 | 类型 | 描述 | | :---: | :---: | :---: | :---: | | username | 是 | string | 名字 | ### 响应参数 | 参数名称 | 类型 | 描述 | | :---: | :---: | :---: | | code | int | 响应码 | | data | string | 响应结果 | | message | string | 响应信息 | | description | string | 响应描述 | ### 代码示例示例一：推荐👍 + 通过yml配置开发者调用凭证 ```yaml ghost: client: access-key: ghost secret-key: ghostandfox ``` + 注入service ```java @Resource private GhostClient ghostClient; ``` + 发起调用 ```java @PostMapping("/getUserName1") public SDKResponse getUserName (@RequestBody NameQueryRequest nameQueryRequest) { SDKResponse sdkResponse = ghostClient.getName(nameQueryRequest); return sdkResponse; } ``` + 或者 ```java @GetMapping("/getUserName2") public SDKResponse getName () { // 构建请求参数 InvokeQueryRequest invokeQueryRequest = new InvokeQueryRequest(); // 接口类型 invokeQueryRequest.setType("getName"); // 接口参数 List requestParam = new ArrayList<>(); InvokeQueryRequest.Param param = new InvokeQueryRequest.Param(); // 接口参数名字 param.setName("username"); param.setValue("ghost"); requestParam.add(param); invokeQueryRequest.setRequestParams(requestParam); // 请求 SDKResponse sdkResponse = ghostClient.doInvoke(invokeQueryRequest); return sdkResponse; } ``` 响应示例： ```json { "code": 0, "message": "ok", "data": "发送POST请求 JSON中你的名字是：ghost", "description": "获取名字" } ``` 示例二： ```java @PostMapping("/getUserName3") public SDKResponse getUserName (@RequestBody NameQueryRequest nameQueryRequest) { GhostClient ghostClient = new GhostClient("ghost", "ghostandfox"); SDKResponse sdkResponse = ghostClient.getName(nameQueryRequest); return sdkResponse; } ``` # SDK接入其他接口 ## 添加接口服务 + 创建DemoService，并且继承ApiService + 构建接口访问地址和构造参数 + 无论是您的接口是get和post，都发起doPost ```java public class DemoService extends ApiService{ public static final String WEATHER_URL = GATEWAY_HOST + "/api/interface/weather"; public DemoService(String accessKey, String secretKey) { super(accessKey, secretKey); } public String getDemo(DemoQueryRequest demoQueryRequest) { return doPost(demoQueryRequest, WEATHER_URL); } } ``` ## 实现DataSource接口 ```java public interface DataSource { SDKResponse invoke(InvokeQueryRequest invokeQueryRequest); } ``` + 例如 ```java public class DemoSource implements DataSource { private final DemoService demofoService; public IpInfoSource(DemoService demofoService) { this.demofoService = demofoService; } @Override public SDKResponse invoke(InvokeQueryRequest invokeQueryRequest) { IpInfoQueryRequest ipInfoQueryRequest; List requestParams = invokeQueryRequest.getRequestParams(); // 参数为空 if (CollUtil.isEmpty(requestParams)) { ipInfoQueryRequest = null; } else { ipInfoQueryRequest = new IpInfoQueryRequest(); for (InvokeQueryRequest.Param requestParam : requestParams) { String name = requestParam.getName(); String value = requestParam.getValue(); if ("ip".equals(name)) { ipInfoQueryRequest.setIp(value); } else { throw new SDKException(ResCode.PARAMS_ERROR, "参数不符合规范"); } } } // 调用添加的接口服务 String ipInfo = demofoService.getDemo(ipInfoQueryRequest); // 条件成立则抛异常 ThrowUtils.throwIf(StringUtils.isEmpty(ipInfo),ResCode.NOT_FOUND_ERROR, "请求模拟接口失败"); // 也可以像下面这样解析，转为Map，全部传递 Map ipInfoMap = JSONUtil.toBean(ipInfo, Map.class); IpInfoVO ipInfoVO = new IpInfoVO(); ipInfoVO.setIpInfo(ipInfoMap); return Res.success(ResCode.SUCCESS, ipInfoVO, "获取ip"); } } ``` ## 注册数据源 ```java public class DataSourceRegister { private Map typeDataSourceMap; /** * 注册数据源 */ @PostConstruct public void registerDataSources(String accessKey, String secretKey) { typeDataSourceMap = new ConcurrentHashMap<>(); typeDataSourceMap.put(InvokeTypeEnum.GETNAMEE.getValue(), createNameSource(accessKey, secretKey)); typeDataSourceMap.put(InvokeTypeEnum.GETWEATHER.getValue(), createWeatherSource(accessKey, secretKey)); typeDataSourceMap.put(InvokeTypeEnum.GETIPINFO.getValue(), createIpInfoSource(accessKey, secretKey)); } private DataSource createNameSource(String accessKey, String secretKey) { NameService nameService = new NameService(accessKey, secretKey); return new NameSource(nameService); } /** * 获取数据源 */ public DataSource getDataSource(String type) { if (type == null || !typeDataSourceMap.containsKey(type)) { return null; } return typeDataSourceMap.get(type); } } ```