使用 libphonenumber 验证电话号码

1. 概述

在这篇简短的文章中，我们将介绍如何使用 Google 开源的 libphonenumber 库来在 Java 中验证电话号码。

2. Maven 依赖

首先，我们需要在 pom.xml 中添加该库的依赖：

<dependency>
    <groupId>com.googlecode.libphonenumber</groupId>
    <artifactId>libphonenumber</artifactId>
    <version>8.12.10</version>
</dependency>

最新的版本信息可以在 Maven Central 上找到。

添加完依赖后，我们就可以愉快地使用这个库提供的所有功能了。

3. PhoneNumberUtil 工具类

该库提供了一个工具类 PhoneNumberUtil，里面封装了大量用于处理电话号码的方法。

我们来看几个使用该类进行验证的例子。

⚠️ 注意：所有示例中，我们都使用的是该类的单例对象来调用方法：

PhoneNumberUtil phoneNumberUtil = PhoneNumberUtil.getInstance();

3.1. isPossibleNumber

通过 PhoneNumberUtil#isPossibleNumber 方法，我们可以判断一个电话号码在特定国家或地区是否是可能存在的号码。

以美国为例（国家代码为 1），我们可以这样判断号码是否可能是美国的号码：

@Test
public void givenPhoneNumber_whenPossible_thenValid() {
    PhoneNumber number = new PhoneNumber();
    number.setCountryCode(1).setNationalNumber(123000L);
    assertFalse(phoneNumberUtil.isPossibleNumber(number));
    assertFalse(phoneNumberUtil.isPossibleNumber("+1 343 253 00000", "US"));
    assertFalse(phoneNumberUtil.isPossibleNumber("(343) 253-00000", "US"));
    assertFalse(phoneNumberUtil.isPossibleNumber("dial p for pizza", "US"));
    assertFalse(phoneNumberUtil.isPossibleNumber("123-000", "US"));
}

在这个例子中，我们还使用了另一个重载版本的方法，传入了号码所属的地区（region）作为参数。

3.2. isPossibleNumberForType

该库支持识别多种电话号码类型，例如：固定电话（fixed-line）、移动电话（mobile）、免费电话（toll-free）、语音信箱（voicemail）、VoIP、寻呼机（pager）等，更多类型见官方文档。

isPossibleNumberForType 方法用于判断某个号码在特定地区是否可能是某种类型的号码。

我们以阿根廷为例，因为该国对不同类型的号码有不同的长度要求：

@Test
public void givenPhoneNumber_whenPossibleForType_thenValid() {
    PhoneNumber number = new PhoneNumber();
    number.setCountryCode(54);

    number.setNationalNumber(123456);
    assertTrue(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.FIXED_LINE));
    assertFalse(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.TOLL_FREE));

    number.setNationalNumber(12345678901L);
    assertFalse(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.FIXED_LINE));
    assertTrue(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.MOBILE));
    assertFalse(phoneNumberUtil.isPossibleNumberForType(number, PhoneNumberType.TOLL_FREE));
}

从上面的例子可以看出，阿根廷允许 6 位的固定电话号码和 11 位的手机号码。

3.3. isAlphaNumber

该方法用于判断号码是否为有效的字母数字混合格式，比如：325-CARS：

@Test
public void givenPhoneNumber_whenAlphaNumber_thenValid() {
    assertTrue(phoneNumberUtil.isAlphaNumber("325-CARS"));
    assertTrue(phoneNumberUtil.isAlphaNumber("0800 REPAIR"));
    assertTrue(phoneNumberUtil.isAlphaNumber("1-800-MY-APPLE"));
    assertTrue(phoneNumberUtil.isAlphaNumber("1-800-MY-APPLE.."));
    assertFalse(phoneNumberUtil.isAlphaNumber("+876 1234-1234"));
}

⚠️ 说明：一个有效的字母数字号码必须以至少三位数字开头，后面跟着三个或更多字母。该方法会先去除格式符号，再判断是否符合规则。

3.4. isValidNumber

前面提到的 isPossibleNumber 是基于号码长度的快速判断。而 isValidNumber 则是完整验证，包括前缀和号码长度等信息：

@Test
public void givenPhoneNumber_whenValid_thenOK() throws Exception {

    PhoneNumber phone = phoneNumberUtil.parse("+911234567890", 
      CountryCodeSource.UNSPECIFIED.name());

    assertTrue(phoneNumberUtil.isValidNumber(phone));
    assertTrue(phoneNumberUtil.isValidNumberForRegion(phone, "IN"));
    assertFalse(phoneNumberUtil.isValidNumberForRegion(phone, "US"));
    assertTrue(phoneNumberUtil.isValidNumber(phoneNumberUtil.getExampleNumber("IN")));
}

上面的例子中，即使我们没有指定地区，号码也能被正确验证。

3.5. isNumberGeographical

该方法用于判断一个号码是否具有地理归属（即是否为本地号码）：

@Test
public void givenPhoneNumber_whenNumberGeographical_thenValid() throws NumberParseException {
    
    PhoneNumber phone = phoneNumberUtil.parse("+911234567890", "IN");
    assertTrue(phoneNumberUtil.isNumberGeographical(phone));

    phone = new PhoneNumber().setCountryCode(1).setNationalNumber(2530000L);
    assertFalse(phoneNumberUtil.isNumberGeographical(phone));

    phone = new PhoneNumber().setCountryCode(800).setNationalNumber(12345678L);
    assertFalse(phoneNumberUtil.isNumberGeographical(phone));
}

✅ 第一个号码是印度的国际格式，返回 true；
❌ 第二个是美国的本地号码，返回 false；
❌ 第三个是免费号码（toll-free），也返回 false。

4. 总结

在本文中，我们介绍了 libphonenumber 提供的部分功能，包括格式化、解析和验证电话号码。

✅ 这是一个功能强大的库，能满足大多数项目中对电话号码处理的需求。

一如既往，本文的源代码可以在 GitHub 上找到。

Persistence

REST

Security