3个案例图解原理：搞定香港手机号验证与报错

凌晨三点，IDE 界面一片血红。你盯着屏幕，手里攥着凉透的咖啡，心里只有一个念头：这堆 StackTrace 到底在说什么鬼话？java.lang.IllegalArgumentException: Invalid phone number format，下面跟着几十行调用栈，每一行都指向不同的内部方法。你试图搜索错误信息，跳到一个 Stack Overflow 帖子，里面有人贴了一长串代码，但版本和你用的不一致，复制过去直接编译失败。这种“报错一堆看不懂 StackTrace”的绝望感，是无数开发者在对接第三方服务时的共同噩梦。

今天我们要聊的，就是让无数人头秃的【香港手机号】验证问题。别被名字吓到，这不仅仅是一个地区号码问题，它是正则表达式、国际标准、以及业务逻辑三者碰撞的典型案例。我们将通过【图解原理】的方式，把这个问题拆解得明明白白，让你下次遇到类似场景，能像老手一样从容应对。

概念速懂：为什么香港号码这么“特殊”

在写代码之前，先搞清楚我们到底在验证什么。很多人以为手机号验证就是看长度，这是大错特错。

核心误区：长度≠合法性。

中国的手机号通常是 11 位，开头是 1。美国的号码是 10 位，前面加个 +1。那香港的号码呢？香港手机号（HK Phone Number）通常由 8 位数字 组成。

以 5 或 6 开头：通常是 2G/3G 移动号段。
以 9 开头：通常是 4G/5G 移动号段。
以 2 或 3 开头：通常是固定电话号码。

图解原理： 想象一下，手机号验证其实是一个“漏斗”模型。

第一层滤网（格式层）：字符是否都是数字？有没有空格、横线、加号？
第二层滤网（长度层）：位数对不对？香港必须是 8 位。
第三层滤网（号段层）：开头数字是否在合法范围内？（5, 6, 9, 2, 3）
第四层滤网（业务层）：这个号段是否已停用？是否属于虚拟运营商？

很多初级开发者卡在第二层和第三层之间。比如，用户输入 +852 9123 4567，如果你的正则只匹配纯数字，直接报错；如果你只去空格，又忘了处理 +852 这个国际区号，依然报错。这就是为什么 StackTrace 会指向 format 方法，而不是 validate 方法——因为你在数据清洗阶段就挂了。

关键点：

国际标准：遵循 E.164 标准，国际区号是 +852。
本地格式：8 位纯数字。
常见陷阱：用户习惯带区号输入，或者带分隔符（如 - 或）。

环境准备：构建一个“防坑”测试场景

在动手写正则之前，我们先搭建一个极简的 Java 测试环境。为什么选 Java？因为后端业务逻辑大多在 JVM 上跑，且 Java 的正则表达式（java.util.regex）行为非常稳定，便于复现那些诡异的报错。

准备工作：

创建一个 Maven 项目，引入 junit-jupiter 用于单元测试。
准备一组“脏数据”测试集，涵盖各种真实用户输入场景。

测试数据集设计（至关重要）： | 输入值 | 预期结果 | 原因分析 | | :--- | :--- | :--- | | "91234567" | 通过 | 标准 8 位，9 开头 | | "51234567" | 通过 | 标准 8 位，5 开头 | | "+85291234567" | 通过 | 带国际区号，需清洗 | | "9123456" | 失败 | 长度不足，7 位 | | "091234567" | 失败 | 0 开头，非香港号段 | | "9123456A" | 失败 | 包含非数字字符 | | " 9123 4567 " | 通过 | 含空格，需清洗 |

环境配置代码：

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;public class HKPhoneNumberValidatorTest {// 这里我们将放入我们的验证逻辑// 暂留空，下一步实现
}

很多人忽略这一步，直接写正则，结果发现正则对了，但业务逻辑错了。比如，你的系统允许用户输入带区号的号码，但你的数据库只存本地号码。这时候，验证器不仅要判断“是否合法”，还要决定“如何标准化”。这就是环境准备的核心：明确输入域和输出域。

核心语法：正则表达式的“手术刀”

现在进入硬核部分。如何用一行正则代码，精准地切开合法与非法的界限？

图解原理：正则拆解

我们要构建一个能处理多种情况的正则。让我们把它拆成几个部分：

可选的国际区号：(?:\+?852)?
- (?:...)：非捕获组，不占用匹配结果的索引，提升性能。
- \+?：加号是可选的。
- 852：固定数字。
可选的分隔符：[\s-]?
- \s：匹配空格、制表符等。
- -：匹配连字符。
- ?：可选。
核心号码：[569][0-9]{7}
- [569]：第一位必须是 5、6 或 9（移动号段）。注：若需包含固话，可扩展为 [23569]。
- [0-9]{7}：后续 7 位纯数字。

组合起来： ^(?:\+?852)?[\s-]?[569][0-9]{7}$

逐行讲解：

^：锚点，确保从字符串开头开始匹配，防止中间插入非法字符。
$：锚点，确保匹配到字符串结尾。
(?:\+?852)?：整个区号部分是可选的。如果用户输入 +852，则匹配；如果输入 91234567，则跳过。
[\s-]?：允许区号和号码之间有一个空格或横线。
[569]：严格限定首位。
[0-9]{7}：严格限定剩余 7 位。

进阶：处理“脏数据”的预处理

正则虽然强大，但不要让它做清洗工作。正则应该用于验证，而清洗应该在验证前完成。

推荐流程：

Trim：去除首尾空格。
Normalize：去除所有非数字字符（除了可能的 + 和 -，但最好全去，靠逻辑判断）。
Validate：使用正则验证标准化后的字符串。

Java 实现核心逻辑：

import java.util.regex.Pattern;
import java.util.regex.Matcher;public class HKPhoneNumberUtils {// 预编译正则，避免每次调用都重新编译，提升性能private static final Pattern HK_LOCAL_PATTERN = Pattern.compile("^([569]\\d{7})$");// 国际格式：+852 或 852 开头private static final Pattern HK_INTL_PATTERN = Pattern.compile("^(?:\\+?852)?([569]\\d{7})$");/*** 验证并标准化香港手机号* @param input 用户原始输入* @return 标准化后的 8 位本地号码，如果非法则抛出异常*/public static String validateAndNormalize(String input) {if (input == null || input.trim().isEmpty()) {throw new IllegalArgumentException("Phone number cannot be empty");}// 1. 清洗：只保留数字和加号（简化版，实际业务需更严谨）// 移除空格、横线、括号等String cleaned = input.replaceAll("[^\\d+]", "");// 2. 去除前缀if (cleaned.startsWith("+")) {cleaned = cleaned.substring(1);}// 3. 判断是否带区号String localNumber;if (cleaned.startsWith("852") && cleaned.length() == 11) {// 假设是 +852 91234567 或 85291234567localNumber = cleaned.substring(3);} else if (cleaned.length() == 8) {// 假设是本地号码 91234567localNumber = cleaned;} else {throw new IllegalArgumentException("Invalid length after cleaning: " + cleaned.length());}// 4. 正则验证核心号段if (!HK_LOCAL_PATTERN.matcher(localNumber).matches()) {throw new IllegalArgumentException("Invalid HK phone number format: " + localNumber);}return localNumber;}
}

代码解析：

预编译 Pattern：Pattern.compile 放在静态块中，是 Java 正则最佳实践。每次 new Pattern 都会消耗 CPU，在高并发下是性能杀手。
清洗逻辑：replaceAll("[^\\d+]", "") 移除了除数字和加号外的所有字符。这比正则直接匹配含空格的情况更健壮，因为它能处理 9 1 2 3 4 5 6 7 这种极端输入。
长度判断：先判断长度，再判断号段。这是“短路求值”思想，长度不对直接抛错，避免进入正则匹配，性能更好。

完整代码示例：从输入到落库的全链路

光有工具类还不够，我们来看一个完整的 Controller 层示例，模拟真实业务场景：用户注册时填写香港手机号。

场景：

前端传入 JSON：{"phone": "+852-9123-4567"}
后端接收、验证、标准化、存储。

Spring Boot 代码示例：

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.http.ResponseEntity;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;import java.util.Map;@Slf4j
@RestController
public class UserController {@PostMapping("/register")public ResponseEntity<Map<String, String>> register(@RequestBody UserDTO userDTO) {try {// 1. 调用工具类进行验证和标准化String standardPhone = HKPhoneNumberUtils.validateAndNormalize(userDTO.getPhone());log.info("Phone validated and normalized: {}", standardPhone);// 2. 业务逻辑：检查号码是否已注册// boolean exists = userRepository.existsByPhone(standardPhone);// if (exists) throw new BusinessException("Phone already registered");// 3. 存储标准化后的号码// user.setPhone(standardPhone);// userRepository.save(user);return ResponseEntity.ok(Map.of("message", "Registration successful", "phone", standardPhone));} catch (IllegalArgumentException e) {// 捕获参数异常，返回友好提示，而不是 500 错误log.warn("Invalid phone format: {}", userDTO.getPhone(), e);return ResponseEntity.badRequest().body(Map.of("error", e.getMessage()));}}
}@Data
class UserDTO {private String phone;// 其他字段...
}

关键点解析：

异常处理：不要让 IllegalArgumentException 冒泡到全局异常处理器变成 500。在 Controller 层捕获，返回 400 Bad Request，并附带具体的错误信息（如“Invalid HK phone number format”），这对前端调试和用户体验都至关重要。
日志记录：log.warn 记录了原始输入和异常，方便后续排查是用户输错了，还是逻辑有 Bug。注意：生产环境不要打印完整的敏感信息，但这里为了演示清晰，保留了关键部分。
标准化存储：无论用户输入 +852 9123 4567 还是 91234567，数据库中统一存 91234567。这是保证数据一致性的关键。

测试用例验证：

@Test
public void testValidateWithInternationalPrefix() {assertEquals("91234567", HKPhoneNumberUtils.validateAndNormalize("+852-91234567"));assertEquals("51234567", HKPhoneNumberUtils.validateAndNormalize("51234567"));
}@Test
public void testValidateInvalid() {assertThrows(IllegalArgumentException.class, () -> HKPhoneNumberUtils.validateAndNormalize("12345678")); // 1 开头非法assertThrows(IllegalArgumentException.class, () -> HKPhoneNumberUtils.validateAndNormalize("9123456")); // 长度不足assertThrows(IllegalArgumentException.class, () -> HKPhoneNumberUtils.validateAndNormalize("abc")); // 非数字
}

常见报错：Stack Trace 背后的真相

回到开头的那个噩梦：StackTrace。现在我们来看看，常见的几种报错背后，到底发生了什么。

案例 1：IllegalArgumentException: Invalid phone number format

现象：你传入了 91234567，但报错了。
原因：你的正则写成了 [569]\d{6}，少写了一位。或者，你在清洗阶段把数字里的某个字符误删了。
对策：打印出 cleaned 变量和 localNumber 变量，对比预期值。在 IDE 中打断点，一步步看字符串的变化。

案例 2：NullPointerException

现象：用户没填手机号，前端传了 null。
原因：input.replaceAll 在 input 为 null 时会抛出 NPE。
对策：在方法入口处加 if (input == null) 判断。这是防御性编程的基本要求。

案例 3：Stack Overflow 帖子里的“神正则”不生效

现象：你从 Stack Overflow 复制了一个复杂的正则，比如 ^(\+?852)?(\s|-)?[569]\d{7}$，但你的代码报错。
原因：
1. 版本差异：某些正则特性在不同 Java 版本中行为略有不同。
2. 字符集问题：[\s] 在某些编码环境下可能不匹配某些不可见字符。
3. 贪婪匹配：如果没有正确使用锚点 ^ 和 $，正则可能只匹配字符串的一部分。
对策：
- 使用 Regex101 或 RegExr 等在线工具，先单独测试正则。
- 简化正则：能用逻辑判断解决的，不要用正则。比如长度判断，直接 length() == 8 比正则 \d{8} 更直观、性能更高。
- 参考权威：Stack Overflow 上高赞回答通常会附带测试用例。如果你只复制了正则，没复制测试用例，那等于没用。务必运行他们的测试代码，确保在你的环境下也能通过。