297 lines
6.9 KiB
Markdown
297 lines
6.9 KiB
Markdown
# 通用数据路由API使用指南
|
||
|
||
## 概述
|
||
|
||
通用数据路由系统提供了一个统一的API接口，可以根据数据类型和平台自动将数据路由到对应的ClickHouse表中进行存储。这个系统支持所有主要的招聘平台（Boss直聘、前程无忧、智联招聘）和数据类型（职位、公司）。
|
||
|
||
## 核心特性
|
||
|
||
- **统一接口**: 所有平台的数据都通过相同的API接口处理
|
||
- **自动路由**: 根据数据类型和平台自动选择对应的存储表
|
||
- **重复检查**: 支持自动重复数据检查，避免数据冗余
|
||
- **批量处理**: 支持单条和批量数据处理
|
||
- **异步处理**: 支持异步后台任务处理大量数据
|
||
- **数据预处理**: 自动进行字段映射和数据转换
|
||
|
||
## API端点
|
||
|
||
### 基础路径
|
||
```
|
||
/api/v1/universal
|
||
```
|
||
|
||
### 主要端点
|
||
|
||
1. **存储单条数据**: `POST /data/store`
|
||
2. **批量存储数据**: `POST /data/batch-store`
|
||
3. **异步存储单条数据**: `POST /data/store-async`
|
||
4. **异步批量存储数据**: `POST /data/batch-store-async`
|
||
5. **获取支持的平台**: `GET /platforms`
|
||
|
||
### 平台特定便捷端点
|
||
|
||
- `POST /boss/job` - Boss直聘职位数据
|
||
- `POST /boss/company` - Boss直聘公司数据
|
||
- `POST /qcwy/job` - 前程无忧职位数据
|
||
- `POST /qcwy/company` - 前程无忧公司数据
|
||
- `POST /zhilian/job` - 智联招聘职位数据
|
||
- `POST /zhilian/company` - 智联招聘公司数据
|
||
|
||
## 数据类型和平台
|
||
|
||
### 支持的平台
|
||
- `boss` - Boss直聘
|
||
- `qcwy` - 前程无忧
|
||
- `zhilian` - 智联招聘
|
||
|
||
### 支持的数据类型
|
||
- `job` - 职位数据
|
||
- `company` - 公司数据
|
||
|
||
### 默认重复检查字段
|
||
|
||
| 平台 | 职位数据 | 公司数据 |
|
||
|------|----------|----------|
|
||
| boss | encrypt_job_id | encrypt_id |
|
||
| qcwy | job_id | company_id |
|
||
| zhilian | job_id | company_id |
|
||
|
||
## 使用示例
|
||
|
||
### 1. 存储Boss直聘职位数据
|
||
|
||
```json
|
||
POST /api/v1/universal/data/store
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"data": {
|
||
"securityId": "abc123",
|
||
"jobBaseInfoVO": {
|
||
"encryptJobId": "job_encrypt_123",
|
||
"jobId": 12345,
|
||
"positionName": "Python开发工程师",
|
||
"locationName": "北京",
|
||
"lowSalary": 15000,
|
||
"highSalary": 25000,
|
||
"jobDesc": "负责后端开发工作..."
|
||
},
|
||
"bossBaseInfoVO": {
|
||
"encryptBossId": "boss_encrypt_456",
|
||
"bossId": 67890,
|
||
"bossName": "张经理"
|
||
},
|
||
"brandComInfoVO": {
|
||
"brandName": "某科技公司",
|
||
"industryName": "互联网",
|
||
"scaleName": "100-499人"
|
||
}
|
||
},
|
||
"data_type": "job",
|
||
"platform": "boss",
|
||
"check_duplicate": true,
|
||
"duplicate_key": "encrypt_job_id"
|
||
}
|
||
```
|
||
|
||
### 2. 批量存储前程无忧职位数据
|
||
|
||
```json
|
||
POST /api/v1/universal/data/batch-store
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"data_list": [
|
||
{
|
||
"job_name": "Java开发工程师",
|
||
"brand_name": "某互联网公司",
|
||
"job_addr": "上海",
|
||
"salary_desc": "15k-25k",
|
||
"job_desc": "负责Java后端开发..."
|
||
},
|
||
{
|
||
"job_name": "前端开发工程师",
|
||
"brand_name": "某科技公司",
|
||
"job_addr": "深圳",
|
||
"salary_desc": "12k-20k",
|
||
"job_desc": "负责前端页面开发..."
|
||
}
|
||
],
|
||
"data_type": "job",
|
||
"platform": "qcwy",
|
||
"check_duplicate": true
|
||
}
|
||
```
|
||
|
||
### 3. 使用便捷端点存储数据
|
||
|
||
```json
|
||
POST /api/v1/universal/boss/job
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"securityId": "abc123",
|
||
"jobBaseInfoVO": {
|
||
"encryptJobId": "job_encrypt_789",
|
||
"positionName": "产品经理",
|
||
"locationName": "杭州"
|
||
},
|
||
"brandComInfoVO": {
|
||
"brandName": "某电商公司",
|
||
"industryName": "电子商务"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 异步批量处理大量数据
|
||
|
||
```json
|
||
POST /api/v1/universal/data/batch-store-async
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"data_list": [
|
||
// ... 大量数据
|
||
],
|
||
"data_type": "job",
|
||
"platform": "zhilian",
|
||
"check_duplicate": true
|
||
}
|
||
```
|
||
|
||
## 响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "数据存储成功",
|
||
"data": {
|
||
"success": true,
|
||
"message": "数据存储成功",
|
||
"duplicate": false,
|
||
"result": true
|
||
},
|
||
"platform": "boss",
|
||
"data_type": "job"
|
||
}
|
||
```
|
||
|
||
### 重复数据响应
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "数据已存在",
|
||
"data": {
|
||
"success": false,
|
||
"message": "数据已存在",
|
||
"duplicate": true,
|
||
"existing_id": 12345
|
||
},
|
||
"platform": "boss",
|
||
"data_type": "job"
|
||
}
|
||
```
|
||
|
||
### 批量处理响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "批量处理完成: 成功 8 条，失败 1 条，重复 1 条",
|
||
"data": {
|
||
"total": 10,
|
||
"success": 8,
|
||
"failed": 1,
|
||
"duplicate": 1,
|
||
"errors": [
|
||
{
|
||
"index": 5,
|
||
"error": "缺少必要字段"
|
||
}
|
||
]
|
||
},
|
||
"platform": "qcwy",
|
||
"data_type": "job"
|
||
}
|
||
```
|
||
|
||
### 异步处理响应
|
||
|
||
```json
|
||
{
|
||
"code": 202,
|
||
"message": "数据已加入异步处理队列",
|
||
"platform": "zhilian",
|
||
"data_type": "job"
|
||
}
|
||
```
|
||
|
||
## 数据预处理
|
||
|
||
系统会根据不同平台自动进行数据预处理：
|
||
|
||
### Boss直聘数据预处理
|
||
- 从嵌套的VO对象中提取字段
|
||
- 映射到标准的数据库字段
|
||
- 保留原始数据在`raw_data`字段中
|
||
|
||
### 前程无忧数据预处理
|
||
- 直接映射字段名
|
||
- 处理数组类型字段
|
||
- 标准化日期格式
|
||
|
||
### 智联招聘数据预处理
|
||
- 处理复杂的嵌套结构
|
||
- 提取关键信息字段
|
||
- 转换数据类型
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误码
|
||
|
||
- `400` - 请求参数错误或数据已存在
|
||
- `500` - 服务器内部错误
|
||
- `202` - 异步处理已接受
|
||
|
||
### 错误响应示例
|
||
|
||
```json
|
||
{
|
||
"detail": "数据存储失败: 缺少必要字段 'encrypt_job_id'"
|
||
}
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **使用重复检查**: 始终启用重复检查以避免数据冗余
|
||
2. **批量处理**: 对于大量数据，使用批量接口提高效率
|
||
3. **异步处理**: 对于非实时需求，使用异步接口避免超时
|
||
4. **错误处理**: 妥善处理API返回的错误信息
|
||
5. **数据验证**: 在发送前验证数据的完整性
|
||
|
||
## 监控和日志
|
||
|
||
系统会自动记录以下信息：
|
||
- 数据处理成功/失败统计
|
||
- 重复数据检测结果
|
||
- 处理时间和性能指标
|
||
- 错误详情和堆栈信息
|
||
|
||
可以通过应用日志查看详细的处理信息。
|
||
|
||
## 迁移指南
|
||
|
||
### 从平台特定API迁移
|
||
|
||
如果你之前使用平台特定的API（如`/api/v1/boss/job`），可以：
|
||
|
||
1. **继续使用便捷端点**: 使用`/api/v1/universal/boss/job`等便捷端点
|
||
2. **迁移到通用端点**: 使用`/api/v1/universal/data/store`通用端点
|
||
3. **逐步迁移**: 先测试新接口，确认无误后再完全迁移
|
||
|
||
### 数据格式兼容性
|
||
|
||
新的通用API完全兼容现有的数据格式，无需修改数据结构。 |