环境准备

  • 环境要求使用Java 1.8及以上版本。
  • 查看Java版本执行命令 java -version

下载SDK

如已购买IP地理位置库(离线版)商品,可进入实例详情,下载以下三个文件

  • 离线数据库(数据文件)
  • 授权证书文件(license)
  • SDK(Java语言)
注意 续费、升级商品套餐一定要同步更新license证书文件,如果license证书过期,则SDK会直接不可用。

安装SDK

方式一:在 Intellij IDEA 项目中导入JAR包

  1. 下载SDK(Java语言)JAR。
  2. 将SDK JAR文件拷贝到您的项目中。
  3. 在 Intellij IDEA 中选择您的工程,选择File > Project Structure > Modules > Dependencies > + > JARs or directories
  4. 选中您在第2步拷贝的SDK JAR文件,导入到External Libraries中。

注意:

  1. SDK JAR包未发布到线上仓库,仅支持直接引入使用
  2. SDK JAR包内仅包含SDK 的开发代码,未包含需要的其他第三方JAR包代码,在使用时需要手动加入相应的第三方依赖如下(使用时可根据实际情况做调整,其中commons-codec的版本必须为1.11或以上版本):
        <dependency>
            <groupId>org.apache.commons</groupId> 
            <artifactId>commons-lang3</artifactId>
            <version>3.10</version>
        </dependency>

        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>28.2-jre</version>
        </dependency>

        <dependency>
            <groupId>commons-codec</groupId>
            <artifactId>commons-codec</artifactId>
            <version>1.11</version>
        </dependency>

        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.68</version>
        </dependency>

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.7.26</version>
        </dependency>

快速入门

重要类介绍

  • com.alibaba.sec.domain.FastGeoConf 目前有三个字段,分别是:
    • properties:用户自定加载的字段,不填写则加载所有字段,在使用时可选择性加载其中需要的属性,这样能显著降低内存的占用空间。具体字段含义参考下文附件
    • licenseFilePath:license路径
    • dataFilePath:data数据路径
  • com.alibaba.sec.client.FastIPGeoClient 是用户使用SDK的客户端对象,需要通过构造函数实例化

使用方法

  1. 将加载字段、license文件路径、数据文件路径封装成一个 com.alibaba.sec.domain.FastGeoConf
  2. 通过静态方法获取单例(能保证在数据文件和license文件路径一样的情况下的实例只会在内存里面生成一份)com.alibaba.sec.client.FastIPGeoClient.getSingleton(com.alibaba.sec.domain.FastGeoConf)
  3. 通过 FastIPGeoClient.search(String ip) 方法来检索ip的地址位置等相关信息,返回的数据为json格式,键值对都是 FastGeoConf.properties 里指定的字段(若未指定,则加载所有字段。在明确实际要用到字段的情况下,生产环境建议固定字段,避免因为新数据字段增加导致内存占用增加),值不在时用空字符串 "" 代替。
  4. 在使用时需要显式的捕获异常:LicenseException,FastIPGeoException,根据异常的编码做相应处理,具体异常列表参考下文附件。
调用实例
import com.alibaba.sec.client.FastIPGeoClient;
import com.alibaba.sec.domain.FastGeoConf;
import com.alibaba.sec.exception.FastIPGeoException;
import com.alibaba.sec.license.exception.LicenseException;

public class GeoClientTest {

    private static final String DATA_FILE_PATH = "${path}/ipv4.dex";
    private static final String LICENSE_FILE_PATH = "${path}/license.lic";

    public static void main(String[] args) throws Exception {
        FastGeoConf geoConf = new FastGeoConf();
        geoConf.setDataFilePath(DATA_FILE_PATH);
        geoConf.setLicenseFilePath(LICENSE_FILE_PATH);

        //通过构造方法初始化(非单例,旧版SDK中使用)
        //FastIPGeoClient fastIpGeoClient = new FastIPGeoClient(geoConf);

        //通过静态方法(单例), 推荐使用该方法,sdk需升级到最新版本
        FastIPGeoClient fastIpGeoClient = FastIPGeoClient.getSingleton(geoConf);
        String result = null;
        try {
            String result = fastIpGeoClient.search("1.1.1.1");
            System.out.println(result);
        } catch (LicenseException e) {
            e.printStackTrace();
        } catch (FastIPGeoException e) {
            e.printStackTrace();
        }
    }
}

附件

properties 字段含义:

字段 含义
country 国家
country_code 国家代码
country_en 国家英文
province 省/州
province_code 省/州数字代码
province_en 省/州英文
county 区/县
county_code 区/县数字代码
city 城市
city_code 城市数字代码
city_en 城市英文
isp 运营商
isp_code 运营商代码
routes 运营商线路
longitude 经度
latitude 纬度
LicenseException 错误码:
UNKNOWN(500, "未知异常"),
ALREADY_EXIST(100, "文件已经存在"),
NOT_ABS_PATH(101, "不是绝对路径"),
DIR_NOT_EXIST(102, "文件夹不存在"),  
LICENSE_INVALID(501, "证书异常"),   //证书不合法
SYSTEM_TIME_ERR(502, "系统时间异常"), 
LICENSE_WILL_EXPIRE(503, "证书即将过期,请提前申请,过期后将无法使用"),
LICENSE_EXPIRE(504, "证书过期, 请重新申请"), 
LICENSE_DELAY_ERR(505, "证书延期异常"),
LICENCE_ERR_ECHO(506, "非法回应"),  //证书不合法,证书内部校验返回值失败
LICENSE_ERR_RATELIMIT(507, "超过购买的qps阈值");
FastIPGeoException 错误编码:
UNKNOWN(1500, "未知异常"), 
INVALID_DAT(1501, "文件内容不合法"),
NOT_MATCH(1503, "文件不匹配"); //用户的license类型和文件类型不匹配