# phone_data

**Repository Path**: makisek/phone_data

## Basic Information

- **Project Name**: phone_data
- **Description**: 手机号归属地查询
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 3
- **Created**: 2022-08-23
- **Last Updated**: 2026-01-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 手机号归属地查询系统

基于Rust 2024 edition实现的高性能手机号归属地查询服务，支持多种查找算法，提供毫秒级响应。

[English Version](./README_EN.md) | 中文版

## 项目特性

- ⚡ **超高性能**: 多种算法支持，最优查询性能达到29ns
- 🔧 **算法丰富**: 支持二分查找、哈希查找、SIMD优化、布隆过滤器等算法
- 📱 **全面支持**: 支持移动、联通、电信、广电及其虚拟运营商
- 🌐 **HTTP API**: RESTful API接口，支持多种查询方式
- 📊 **数据准确**: 归属地信息库定期更新，包含517258条手机号段记录
- 🧪 **测试完善**: 统一测试套件，确保算法一致性和功能完整性

### 数据规模
- 归属地信息库文件大小：4.5MB
- 归属地信息库最后更新：2025年02月
- 手机号段记录条数：517,258

### 技术栈
- **Rust Edition**: 2024
- **Web框架**: actix-web 4.11.0
- **序列化**: serde 1.0.228
- **错误处理**: anyhow 1.0.100
- **基准测试**: criterion 0.5.1

## 算法实现

本项目实现了四种不同的查找算法，各有特点：

### 1. 二分查找算法 (Binary Search)

**文件**: `src/lib.rs`

**时间复杂度**: O(log n)
**空间复杂度**: O(1)

**特点**:
- 经典算法，稳定可靠
- 内存占用最小
- 适合内存受限环境
- 查找时间：~175ns

**优化点**:
- 使用位运算优化除法操作
- unsafe访问提升性能
- 优化循环终止条件

### 2. 哈希查找算法 (Hash Lookup)

**文件**: `src/phone_hash.rs`

**时间复杂度**: O(1) 平均情况
**空间复杂度**: O(n)

**特点**:
- 最快的查找速度
- 预分配HashMap容量
- 查找时间：~105ns（比二分查找快40%）
- 内存占用较大

**适用场景**:
- 对查询性能要求极高的场景
- 内存充足的环境

### 3. SIMD优化算法 (SIMD Optimized)

**文件**: `src/phone_simd.rs`

**时间复杂度**: O(log n)
**空间复杂度**: O(1)

**特点**:
- 向量化指令优化
- 分支预测友好
- 批量查询优化
- 适合SIMD支持的CPU

**优化技术**:
- 预取优化减少缓存未命中
- 循环展开
- 向量化比较

### 4. 布隆过滤器算法 (Bloom Filter)

**文件**: `src/phone_bloom.rs`

**时间复杂度**: O(k) 其中k为哈希函数数量
**空间复杂度**: O(n)

**特点**:
- 快速预过滤不存在的号码
- 1%误报率设置
- 两阶段查找：布隆过滤 + 二分查找
- 失败查询性能优异

**工作流程**:
1. 布隆过滤器快速检查
2. 如果可能存在，进行二分查找
3. 返回精确结果

## 性能基准测试

基于最新基准测试结果（Criterion v0.5.1，测试环境：macOS），所有四种算法的详细性能对比：

### 单次查询性能对比

| 算法 | 平均查询时间 | 相对性能 | 内存占用 | 适用场景 |
|------|-------------|----------|----------|----------|
| 哈希查找 | ~150ns | 最快 | 156MB | 高频查询，内存充足 |
| 二分查找 | ~233ns | 基准 | 6.2MB | 内存受限环境 |
| SIMD优化 | ~235ns | 相当 | 6.2MB | 批量查询优化 |
| 布隆过滤器 | ~260ns | 较慢 | 6.5MB | 失败查询较多 |

**性能特点**：
- 哈希查找在所有场景下都是最快的，但内存开销最大
- 二分查找和SIMD优化性能相当，SIMD在批量查询时有优势
- 布隆过滤器在失败查询时表现优异，成功查询时略慢于二分查找

### 批量查询性能 (1000个号码)

| 算法 | 总耗时 | 平均每查询 | QPS | 性能提升 |
|------|--------|------------|-----|----------|
| 哈希查找 | 139.73µs | 140ns | ~7,143,000 | +66% |
| SIMD查找 | 222.49µs | 222ns | ~4,505,000 | +5% |
| 布隆查找 | 254.71µs | 255ns | ~3,922,000 | -9% |
| 二分查找 | 232.87µs | 233ns | ~4,291,000 | 基准 |

### 初始化时间对比

| 算法 | 初始化时间 | 原因 | 冷启动影响 |
|------|------------|------|------------|
| 二分查找 | 2.23ms | 直接加载数据 | 最小 |
| SIMD查找 | 2.31ms | 与二分查找相同 | 最小 |
| 布隆查找 | 27.03ms | 额外构建布隆过滤器 | 小 |
| 哈希查找 | 204.27ms | 构建HashMap开销 | 显著 |

### 失败查询性能（不存在的号码）

对于不存在的手机号码，不同算法的表现：

| 算法 | 查询时间 | 优势 | 适用场景 |
|------|----------|------|----------|
| 哈希查找 | 33–36ns | 直接判断key不存在 | 输入质量不高的场景 |
| 布隆过滤器 | ~231ns | 快速预过滤 | 大量无效查询场景 |
| 二分查找 | ~209ns | 稳定可靠 | 通用场景 |
| SIMD查找 | ~212ns | 与二分查找相近 | 通用场景 |

### 内存使用详细对比

| 算法 | 内存使用 | 组成部分 | 内存效率 |
|------|----------|----------|----------|
| 二分查找 | 6.2MB | 原始数据(4.5MB) + 索引(1.7MB) | 最高 |
| SIMD优化 | 6.2MB | 与二分查找相同 | 最高 |
| 布隆过滤器 | 6.5MB | 基础数据 + 布隆位图(0.3MB) | 高 |
| 哈希查找 | 156MB | 基础数据 + HashMap开销(150MB) | 最低 |

### 不同场景推荐

**🚀 追求极致性能**
- 首选：哈希查找算法
- 场景：高频查询，内存充足
- 性能：单查询106ns，QPS可达970万

**💾 内存受限环境**
- 首选：二分查找算法
- 场景：嵌入式设备，内存紧张
- 内存：仅6.2MB

**📊 批量查询优化**
- 首选：SIMD优化算法
- 场景：数据分析，批量处理
- 特点：向量化指令，缓存友好

**🔍 输入质量不稳定**
- 首选：布隆过滤器算法
- 场景：大量无效查询需要过滤
- 特点：失败查询性能优异

### 基准测试运行方法

```bash
# 运行所有算法对比测试
cargo bench --bench algorithm_comparison

# 运行特定算法测试
cargo bench --bench lookup_performance

# 查看详细性能报告
cargo bench --bench algorithm_comparison -- --output-format html
```

## phone.dat文件格式

```
| 4 bytes | 版本号（如：1701即17年1月份）
| 4 bytes | 第一个索引的偏移
| offset - 8 | 记录区
| 剩余部分 | 索引区
```

1. **头部**: 8个字节，版本号4字节，第一个索引偏移4字节
2. **记录区**: 每条记录格式为"<省份>|<城市>|<邮编>|<长途区号>\0"
3. **索引区**: 每条记录格式为"<手机号前七位><记录区偏移><卡类型>"，长度9字节

## 环境要求

- Rust 1.85+ (支持2024 edition)
- phone.dat文件 (需放在项目根目录)

## 安装使用

### 编译运行
```bash
# 克隆项目
git clone <repository-url>
cd phone_data

# 安装依赖并运行
cargo run

# 生产环境构建
cargo build --release
```

### 库使用示例

```rust
use phone_data::{PhoneData, PhoneLookup};

// 二分查找
let phone_data = PhoneData::new()?;
let result = phone_data.find("18086834111")?;
println!("省份: {}", result.province);

// 哈希查找
use phone_data::phone_hash::PhoneDataHash;
let hash_data = PhoneDataHash::new()?;
let result = hash_data.find("18086834111")?;

// SIMD优化查找
use phone_data::phone_simd::PhoneDataSimd;
let simd_data = PhoneDataSimd::new()?;
let result = simd_data.find("18086834111")?;

// 布隆过滤器查找
use phone_data::phone_bloom::PhoneDataBloom;
let bloom_data = PhoneDataBloom::new()?;
let result = bloom_data.find("18086834111")?;
```

### API使用示例

服务启动后默认在8080端口：

```shell
# 路径参数查询
curl 'http://127.0.0.1:8080/query2/18086834111'

# GET参数查询
curl 'http://127.0.0.1:8080/query?phone=18086834111'
```

**响应格式**:
```json
{
    "code": 0,
    "data": {
        "province": "四川",
        "city": "成都",
        "zip_code": "610000",
        "area_code": "028",
        "card_type": "中国电信"
    },
    "success": true,
    "result": "ok"
}
```

## 测试

### 运行测试套件
```bash
# 运行所有测试
cargo test

# 运行统一测试套件（推荐）
cargo test --test unified_tests -- --nocapture

# 运行集成测试
cargo test --test integration_tests

# 运行库测试
cargo test --lib
```

### 性能基准测试
```bash
# 运行所有基准测试
cargo bench

# 运行算法对比基准测试
cargo bench --bench algorithm_comparison

# 运行查找性能基准测试
cargo bench --bench lookup_performance
```

## 算法选择建议

根据不同场景选择合适的算法：

### 1. 追求极致性能
**推荐**: 哈希查找算法
- 查询时间最短（105ns）
- 适合高频查询场景
- 需要充足内存（42MB）

### 2. 内存受限环境
**推荐**: 二分查找算法
- 内存占用最小（8MB）
- 性能稳定可靠
- 适合嵌入式或内存受限场景

### 3. 批量查询优化
**推荐**: SIMD优化算法
- 向量化指令加速
- 批量查询友好
- 适合数据分析场景

### 4. 失败查询较多
**推荐**: 布隆过滤器算法
- 快速过滤不存在的号码
- 减少无效查询开销
- 适合输入质量不高的场景

## API文档

### 查询接口

#### 1. GET参数查询
```
GET /query?phone=<手机号>
```

#### 2. 路径参数查询
```
GET /query2/<手机号>
```

### 响应格式
```json
{
    "code": 0,           // 状态码，0表示成功
    "data": {            // 手机号信息
        "province": "省份",
        "city": "城市",
        "zip_code": "邮编",
        "area_code": "区号",
        "card_type": "运营商"
    },
    "success": true,     // 是否成功
    "result": "ok"       // 结果描述
}
```

## 开发说明

### 项目结构
```
src/
├── lib.rs              # 二分查找算法实现
├── main.rs             # Web服务入口
├── common.rs           # 公共类型和接口定义
├── phone_hash.rs       # 哈希查找算法
├── phone_simd.rs       # SIMD优化算法
└── phone_bloom.rs      # 布隆过滤器算法

tests/
├── integration_tests.rs # 集成测试
├── test_suite.rs       # 统一测试套件
└── unified_tests.rs    # 统一测试入口

benches/
├── algorithm_comparison.rs  # 算法对比基准测试
└── lookup_performance.rs    # 查找性能基准测试
```

### 添加新算法
1. 在`src/`目录下创建新文件
2. 实现`PhoneLookup`和`PhoneStats` traits
3. 在`src/lib.rs`中导出模块
4. 在测试套件中添加测试用例
5. 在基准测试中添加性能测试


## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 更新日志

### v0.2.0 (2025-11-13)
- ✨ 新增哈希查找算法（105ns查询时间）
- ✨ 新增SIMD优化算法实现
- ✨ 新增布隆过滤器算法
- 🔧 重构代码架构，提取公共类型到common.rs
- 🧪 完善测试套件，确保算法一致性
- 📊 添加全面的性能基准测试
- 📚 完善文档和算法说明

### v0.1.0 (2025-02-xx)
- 🎉 初始版本发布
- ⚡ 二分查找算法实现
- 🌐 HTTP API服务
- 📱 支持三大运营商及虚拟运营商