# benruSdk

**Repository Path**: liuxia8/benru-sdk

## Basic Information

- **Project Name**: benruSdk
- **Description**: 本如数据核验 API 聚合服务 是一个开箱即用的数据核验与综合信息查询 API 聚合平台，将杭州本如网络科技有限公司提供的各类 API 服务（身份证二要素核验、IP 归属地查询、敏感词过滤、AI 聊天对话、手机号归属查询、商品条码查询、邮箱校验、人脸身份证比对、情绪识别等）封装为标准化、可扩展的开源工具，帮助开发者快速集成数据核验能力到自己的应用中。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 本如数据核验 API 聚合服务 —— 开源工程介绍

## 📖 项目简介

**本如数据核验 API 聚合服务** 是一个开箱即用的数据核验与综合信息查询 API 聚合平台，将杭州本如网络科技有限公司提供的各类 API 服务（身份证二要素核验、IP 归属地查询、敏感词过滤、AI 聊天对话、手机号归属查询、商品条码查询、邮箱校验、人脸身份证比对、情绪识别等）封装为**标准化、可扩展的开源工具**，帮助开发者快速集成数据核验能力到自己的应用中。  
公司介绍：https://www.liuxia8.cn/   
联系电话： 15968861337   
email: admin@liuxia8.com  

> **项目定位**：做一个**真正方便别人使用**的开源项目，让开发者能以最低成本、最快速度接入身份认证、信息核验、内容审核等能力。

---

## 🎯 为什么做这个项目？

在业务开发中，我们经常遇到以下痛点：
- 需要对接多个 API 服务商，每个接口的签名方式、返回格式、错误码都不统一
- 缺少好用的 SDK，每次都要重复编写 HTTP 请求、签名、异常处理等“脏活累活”
- 没有现成的开源参考实现，对接成本高

本项目的目标就是**解决这些问题**——提供一个开源的、多语言适配的 API 聚合客户端，让开发者像使用本地函数一样调用各类核验服务。

---

## ✨ 核心功能

本项目整合了杭州本如网络科技有限公司提供的以下 API 服务 ：

### 🔐 身份核验类
| 能力 | 说明 |
|------|------|
| **身份证二要素核验** | 通过姓名+身份证号校验是否一致，返回性别、生日、省份、城市等信息 |
| **人脸身份证比对** | 现场人脸照片与身份证照片进行 1:1 比对，返回相似度 |
| **手机号归属查询** | 查询手机号运营商、归属地（省份/城市）等信息 |

### 🛡️ 内容安全类
| 能力 | 说明 |
|------|------|
| **敏感词过滤/文本审核** | 基于 DFA 算法，支持敏感词检测、替换、违规内容识别  |
| **对话情绪识别** | 分析文本中的情绪波动，识别喜、怒、哀、惧等情绪 |

### 🌐 信息查询类
| 能力 | 说明 |
|------|------|
| **IP 归属地查询** | 支持批量查询，返回地理位置与运营商信息  |
| **商品条码查询** | 传入商品条码，查询名称、品牌、厂家、规格、参考价格 |
| **邮箱地址校验** | 验证邮箱格式、域名有效性及 MX 记录 |

### 🤖 AI 能力类
| 能力 | 说明 |
|------|------|
| **AI 聊天对话** | 接入大模型，支持情感陪护、工作问题解答、闲聊等 |

---

## 🏗️ 技术架构

```mermaid
flowchart LR
    A[应用层] --> B[API Gateway / SDK]
    B --> C[身份核验]
    B --> D[内容安全]
    B --> E[信息查询]
    B --> F[AI 能力]
    C --> G[本如 API 服务]
    D --> G
    E --> G
    F --> G
```

### 设计原则

1. **统一接口规范**：所有 API 使用统一的认证方式（Access Token / API Key）、统一的请求/响应格式 
2. **多语言支持**：提供 PHP、Python、Go、JavaScript/Node.js 等多语言 SDK 
3. **开箱即用**：支持 Composer、pip、npm 等主流包管理器安装
4. **模块化设计**：各功能模块独立，可按需引入

---

## 🚀 快速开始

### 安装

**PHP (Composer)**
```bash
composer require benru/api-client
```
要求 PHP >= 8.2 

**Python (pip)**
```bash
pip install benru-api-client
```

**Node.js (npm)**
```bash
npm install benru-api-client
```

### 基本用法

#### 身份证二要素核验

```php
<?php
use Benru\BenruClient;

$client = new BenruClient('your_access_token');

try {
    $result = $client->idcard->verify('张三', '110101199001011234');
    // $result->match: true/false
    // $result->province: 省份
    // $result->city: 城市
    // $result->gender: 性别
    // $result->birthday: 生日
} catch (Exception $e) {
    // 处理异常
}
?>
```

```python
from benru import BenruClient

client = BenruClient(access_token='your_access_token')

# 身份证二要素核验
result = client.idcard.verify(name='张三', id_card='110101199001011234')
print(result.match)       # True/False
print(result.province)    # 北京市
print(result.gender)      # 男
```

#### IP 归属地查询

```javascript
import { BenruClient } from 'benru-api-client';

const client = new BenruClient({ accessToken: 'your_access_token' });

// 查询指定 IP
const result = await client.ip.lookup('8.8.8.8');
console.log(result.country);  // 美国
console.log(result.city);     // 加利福尼亚
```

#### 敏感词过滤

```python
from benru import BenruClient

client = BenruClient(access_token='your_access_token')

# 检测文本是否包含敏感词
result = client.sensitive.filter('用户输入的文本内容')
print(result.has_sensitive)   # True/False
print(result.matched_words)   # 命中的敏感词列表
print(result.filtered_text)   # 过滤后的文本
```

---

## 📦 已支持的接口列表

| 分类 | 方法 | 说明 |
|------|------|------|
| 身份核验 | `idcard.verify()` | 身份证二要素核验（姓名+身份证号） |
| 身份核验 | `idcard.ocr()` | 身份证 OCR 识别 |
| 身份核验 | `face.compare()` | 人脸比对（两张照片比对） |
| 身份核验 | `phone.lookup()` | 手机号归属查询 |
| 内容安全 | `sensitive.filter()` | 敏感词过滤/文本审核  |
| 内容安全 | `emotion.analyze()` | 对话情绪识别 |
| 信息查询 | `ip.lookup()` | IP 归属地查询  |
| 信息查询 | `barcode.query()` | 商品条码查询 |
| 信息查询 | `email.validate()` | 邮箱地址校验 |
| AI 能力 | `chat.complete()` | AI 聊天对话 |

---

## 🔧 配置与部署

### 环境变量配置

推荐通过环境变量配置 Access Token：

```bash
export BENRU_ACCESS_TOKEN=your_access_token_here
export BENRU_API_BASE=https://api.benru.com/v1  # 可选，默认
```

### Docker 部署（可选）

```dockerfile
FROM php:8.2-cli
COPY . /app
WORKDIR /app
RUN composer install
CMD ["php", "examples/demo.php"]
```

### 反向代理集成

若部署于 Nginx 等反向代理之后，需确保正确传递 `X-Forwarded-For` 等头部以准确获取客户端信息 。

---

## 📚 应用场景

| 场景 | 使用的 API |
|------|-----------|
| **金融行业 KYC 合规** | 身份证二要素核验、人脸比对  |
| **游戏防沉迷** | 身份证实名认证 |
| **物流行业** | 手机号归属查询、IP 归属地查询 |
| **社交/社区平台** | 敏感词过滤、文本审核  |
| **电商平台** | 商品条码查询、邮箱校验 |
| **客服系统** | AI 聊天对话、情绪识别 |

---

## 🤝 贡献指南

欢迎参与开源贡献！你可以通过以下方式参与：

1. **提交 Issue**：报告 Bug 或提出新功能建议
2. **提交 Pull Request**：修复问题或增加新特性
3. **完善文档**：补充使用示例或翻译多语言文档
4. **增加语言支持**：为项目贡献其他编程语言的 SDK

### 本地开发

```bash
# 克隆项目
git clone https://github.com/benru/api-client.git
cd api-client

# 安装依赖
composer install   # PHP
pip install -e .   # Python
npm install        # Node.js

# 运行测试
composer test
pytest
npm test
```

---

## 📄 许可证

本项目采用 **MIT License** 开源协议，可自由使用、修改、分发 。

---

## 🔗 相关链接

- **官方 API 文档**：https://www.benru.com/docs
- **GitHub 仓库**：https://github.com/benru/api-client
- **Packagist**：https://packagist.org/packages/benru/api-client
- **PyPI**：https://pypi.org/project/benru-api-client
- **npm**：https://www.npmjs.com/package/benru-api-client

---

> 💡 **提示**：本项目为开源聚合客户端，所有 API 能力由杭州本如网络科技有限公司提供服务支撑 ，使用前请前往官网申请 Access Token。