336 lines
13 KiB
Markdown
336 lines
13 KiB
Markdown
# xiaozhaoya.com 招聘接口说明
|
||
|
||
> 基础域名：`https://api.xiaozhaoya.com`
|
||
> 所有接口的响应体结构统一为 `{ "code": <int>, "message": <string>, "data": <string|null> }`。
|
||
> `data` 字段在成功时是一段 **AES 加密后再 Base64 编码的密文**，需解密后才能得到明文 JSON（解密方案与完整代码见文末第三节）。
|
||
|
||
## 一、接口总览
|
||
|
||
| # | 接口 | 方法 | 功能 | 是否需要授权 |
|
||
|---|------|------|------|-------------|
|
||
| 1 | `/api/recruitment/list` | GET | 招聘列表：分页返回岗位概要（含公司、行业、城市、投递方式等） | **部分**：未登录只能访问第 1 页；翻页（page ≥ 2）返回 401 |
|
||
| 2 | `/api/recruitment/detail?id={id}` | GET | 招聘详情：返回单条岗位的完整信息（含岗位职责、工作地址、薪资等） | **否**：可裸调。仅"招聘公告地址、投递方式"两个字段脱敏为"登陆后可查看" |
|
||
| 3 | `/api/recruitment/{id}/getUrl` | POST | 获取该岗位的**招聘公告原文地址**（`announcementLink`） | **是**：必须携带有效登录态，否则返回 401「请先登录」 |
|
||
|
||
### 关于 id 的重要说明
|
||
|
||
- **`id` 是自增 ID**：`recruitmentId` 随发布顺序连续递增（例如 41785、41786 … 41796），越大越新。可据此推断数据总量与遍历范围。
|
||
- **详情接口查询不存在的 id**：`/api/recruitment/detail?id={不存在的id}` 时，服务端返回 `code:500, message:"ok"`，且 **`data` 为 `null`**（没有可解密内容）。调用方应先判断 `data` 是否为 null，再进行解密。
|
||
- 特例：`id` 为负数时会返回 `401 请登录后继续浏览`。
|
||
|
||
---
|
||
|
||
## 二、请求示例、参数与返回值
|
||
|
||
### 接口 1：招聘列表 `GET /api/recruitment/list`
|
||
|
||
**请求参数（Query）**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `page` | int | 是 | 页码，从 1 开始。未登录时仅 `page=1` 可用 |
|
||
| `size` | int | 是 | 每页条数。**未登录时服务端强制为 12**，传更大值（如 200）也只返回 12 条 |
|
||
| `sortRule` | string | 否 | 排序规则，如 `updateDate`（按更新时间倒序）。为默认值，去掉不影响结果 |
|
||
| `userId` | string | 否 | 登录用户 ID。登录态下随请求携带 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl 'https://api.xiaozhaoya.com/api/recruitment/list?page=1&size=12&sortRule=updateDate' \
|
||
-H 'accept: application/json' \
|
||
-H 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/150.0.0.0 Safari/537.36'
|
||
```
|
||
|
||
**返回值（`data` 解密后）**
|
||
|
||
```json
|
||
{
|
||
"total": "33872",
|
||
"data": [
|
||
{
|
||
"recruitmentId": 41796,
|
||
"updateDate": "2026-07-21",
|
||
"companyName": "同花顺-AIME顶尖人才计划",
|
||
"companyTypeName": "民企",
|
||
"fullName": "浙江核新同花顺网络信息股份有限公司",
|
||
"shortName": "同花顺",
|
||
"logoUrl": "https://xiaozhaoya.oss-cn-shanghai.aliyuncs.com/company/logo/....jpg",
|
||
"batchNameList": "秋招专场",
|
||
"industryName": "IT/互联网/游戏",
|
||
"jobCategoryNameList": "设计, 人工智能, 工程师",
|
||
"jobTitle": "多模态算法工程师;大模型算法工程师;...",
|
||
"educationLevelNameList": "硕士, 博士",
|
||
"graduationYearList": "2026, 2027",
|
||
"majorRequirements": "未明确",
|
||
"cityNameList": "杭州市",
|
||
"applicationDeadline": "尽快投递",
|
||
"sourceName": "offer雷达",
|
||
"announcementTitle": "同花顺AIME顶尖人才计划｜全球招募",
|
||
"announcementLink": "/",
|
||
"applicationMethod": "https://campus.10jqka.com.cn/job/list?type=school",
|
||
"hasWrittenTest": "未明确",
|
||
"companyProfile": "国内领先的互联网金融信息服务商，...",
|
||
"isShow": true
|
||
}
|
||
// ... 共 12 条；jobContent、workAddress、salary、viewAmount 等字段在列表中为 null
|
||
],
|
||
"isMembershipValid": false,
|
||
"isLoggedIn": false
|
||
}
|
||
```
|
||
|
||
**说明**
|
||
|
||
- 列表中的 `applicationMethod`（投递方式）为**明文真实链接**；`announcementLink` 为 `/`（占位）。
|
||
- `jobContent`、`workAddress`、`salary`、`viewAmount`、`likeAmount`、`recruitmentCount` 等字段在列表接口中均为 `null`，需调用详情接口获取。
|
||
- 翻页未授权时的返回：`{ "code": 401, "message": "请登录后查看更多信息", "data": null }`。
|
||
|
||
---
|
||
|
||
### 接口 2：招聘详情 `GET /api/recruitment/detail`
|
||
|
||
**请求参数（Query）**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | int | 是 | 招聘 ID（自增）。不存在时 `data` 返回 null |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl 'https://api.xiaozhaoya.com/api/recruitment/detail?id=41794' \
|
||
-H 'accept: application/json' \
|
||
-H 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/150.0.0.0 Safari/537.36'
|
||
```
|
||
|
||
**返回值（`data` 解密后）**
|
||
|
||
```json
|
||
{
|
||
"recruitmentId": 41794,
|
||
"updateDate": "2026-07-21",
|
||
"companyName": "网易游戏-互娱",
|
||
"companyTypeName": "民企",
|
||
"logoUrl": "https://xiaozhaoya.oss-cn-shanghai.aliyuncs.com/company/logo/....jpg",
|
||
"batchNameList": "秋招专场",
|
||
"industryName": "IT/互联网/游戏",
|
||
"jobCategoryNameList": "运营, 设计, IT技术, 人工智能, ...",
|
||
"jobTitle": "游戏策划类;游戏程序类;游戏艺术类;...",
|
||
"educationLevelNameList": "本科, 硕士, 博士",
|
||
"graduationYearList": "2027",
|
||
"cityNameList": "上海市, 杭州市, 广州市",
|
||
"announcementDate": "2026-07-21",
|
||
"applicationDeadline": "尽快投递",
|
||
"sourceName": "网易游戏互娱招聘",
|
||
"announcementTitle": "网易游戏（互娱）2027届校园招聘正式启动！",
|
||
"announcementLink": "登陆后可查看",
|
||
"applicationMethod": "登陆后可查看",
|
||
"hasWrittenTest": "有笔试",
|
||
"companyProfile": "网易游戏（互娱）是国内领先的游戏厂商，...",
|
||
"tip": "每位同学最多投递2个岗位，表现优秀可转正",
|
||
"tags": "大厂校招,多岗热招,福利丰厚",
|
||
"viewAmount": "10",
|
||
"likeAmount": "1",
|
||
"recruitmentCount": "若干",
|
||
"jobContent": "#### 游戏策划类\n- 负责游戏玩法规则设计...（Markdown 格式的完整岗位职责）",
|
||
"workAddress": "广州市天河区思成路1号,杭州市滨江区网商路399号,上海市静安区江场路1228弄",
|
||
"salary": "面议",
|
||
"isMembershipValid": false,
|
||
"isLoggedIn": false
|
||
}
|
||
```
|
||
|
||
**说明**
|
||
|
||
- 详情接口未登录也可获取几乎全部字段（岗位职责、工作地址、薪资等）。
|
||
- 仅 `announcementLink`（招聘公告地址）与 `applicationMethod`（投递方式）两个字段被脱敏为 `"登陆后可查看"`。
|
||
- **不存在的 id** 的返回：`{ "code": 500, "message": "ok", "data": null }`。
|
||
|
||
---
|
||
|
||
### 接口 3：获取招聘公告地址 `POST /api/recruitment/{id}/getUrl`
|
||
|
||
功能：返回该岗位的**招聘公告原文地址**（即详情中被脱敏的 `announcementLink`）。
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | int | 是 | 招聘 ID，写在 URL 路径中 |
|
||
|
||
**请求体**：空对象 `{}`（`Content-Type: application/json`）。
|
||
|
||
**请求示例（需登录态）**
|
||
|
||
```bash
|
||
curl -X POST 'https://api.xiaozhaoya.com/api/recruitment/41794/getUrl' \
|
||
-H 'accept: application/json' \
|
||
-H 'content-type: application/json' \
|
||
-H 'authorization: <有效的登录 token>' \
|
||
-H 'origin: https://www.xiaozhaoya.com' \
|
||
-H 'referer: https://www.xiaozhaoya.com/' \
|
||
-H 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/150.0.0.0 Safari/537.36' \
|
||
--data '{}'
|
||
```
|
||
|
||
**返回值**
|
||
|
||
- 未授权（无有效登录态）：
|
||
|
||
```json
|
||
{ "code": 401, "message": "请先登录", "data": null }
|
||
```
|
||
|
||
- 授权成功：`data` 为加密字符串，解密后为招聘公告地址（结构以实际返回为准）。
|
||
|
||
**授权说明**：登录 token 通过 `authorization` 请求头传递（站点使用 Sa-Token 框架，响应头 `access-control-expose-headers: satoken`）。token 存在有效期，失效后即便请求头格式正确，服务端仍判定为未登录（列表接口返回中 `isLoggedIn` 为 `false`）。
|
||
|
||
---
|
||
|
||
## 三、`data` 字段解密方法
|
||
|
||
站点对响应体的 `data` 字段做了对称加密，须解密后才能得到明文 JSON。
|
||
|
||
**加密方案**
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 算法 | AES-128 |
|
||
| 模式 | CBC |
|
||
| 填充 | PKCS#7（CryptoJS 兼容） |
|
||
| Key | `version 2.2.1bak`（UTF-8，16 字节） |
|
||
| IV | `version 2.2.1bak`（UTF-8，16 字节，与 Key 相同） |
|
||
| 传输编码 | Base64 |
|
||
|
||
**解密流程**：Base64 解码 → AES-128-CBC 解密 → 去除 PKCS#7 填充 → UTF-8 解码 → JSON 解析。
|
||
|
||
**依赖**
|
||
|
||
```
|
||
cryptography>=41
|
||
```
|
||
|
||
**解密代码（完整源码）**
|
||
|
||
```python
|
||
"""Decode the encrypted payload returned by xiaozhaoya.com APIs.
|
||
|
||
The site currently uses AES-128-CBC with PKCS#7 padding. The key and IV are
|
||
part of the public frontend bundle, so keep them configurable in case the site
|
||
rotates them later.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import base64
|
||
import json
|
||
from collections.abc import Mapping
|
||
from typing import Any
|
||
|
||
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
|
||
|
||
|
||
DEFAULT_KEY = "version 2.2.1bak"
|
||
DEFAULT_IV = "version 2.2.1bak"
|
||
|
||
|
||
def decode_ciphertext(
|
||
ciphertext: str,
|
||
*,
|
||
key: str = DEFAULT_KEY,
|
||
iv: str = DEFAULT_IV,
|
||
parse_json: bool = True,
|
||
) -> Any:
|
||
"""Decrypt one Base64 payload and optionally parse its UTF-8 JSON.
|
||
|
||
Args:
|
||
ciphertext: The API's Base64-encoded ``data`` value.
|
||
key: AES key encoded as UTF-8 (16 bytes by default).
|
||
iv: CBC initialization vector encoded as UTF-8 (16 bytes by default).
|
||
parse_json: Return the decoded JSON value when true; otherwise return
|
||
the decoded UTF-8 string.
|
||
"""
|
||
|
||
if not isinstance(ciphertext, str) or not ciphertext.strip():
|
||
raise ValueError("ciphertext must be a non-empty Base64 string")
|
||
|
||
key_bytes = key.encode("utf-8")
|
||
iv_bytes = iv.encode("utf-8")
|
||
if len(key_bytes) not in (16, 24, 32):
|
||
raise ValueError("AES key must be 16, 24, or 32 UTF-8 bytes")
|
||
if len(iv_bytes) != 16:
|
||
raise ValueError("AES-CBC IV must be 16 UTF-8 bytes")
|
||
|
||
try:
|
||
encrypted = base64.b64decode(ciphertext, validate=True)
|
||
except ValueError as exc:
|
||
raise ValueError("ciphertext is not valid Base64") from exc
|
||
|
||
if not encrypted or len(encrypted) % 16:
|
||
raise ValueError("decoded ciphertext length must be a non-zero AES block multiple")
|
||
|
||
decryptor = Cipher(
|
||
algorithms.AES(key_bytes),
|
||
modes.CBC(iv_bytes),
|
||
).decryptor()
|
||
padded = decryptor.update(encrypted) + decryptor.finalize()
|
||
|
||
# CryptoJS.pad.Pkcs7 compatibility.
|
||
padding_length = padded[-1]
|
||
if not 1 <= padding_length <= 16 or padded[-padding_length:] != bytes([padding_length]) * padding_length:
|
||
raise ValueError("invalid PKCS#7 padding")
|
||
plaintext = padded[:-padding_length].decode("utf-8")
|
||
return json.loads(plaintext) if parse_json else plaintext
|
||
|
||
|
||
def decode_api_data(
|
||
response: Mapping[str, Any],
|
||
*,
|
||
key: str = DEFAULT_KEY,
|
||
iv: str = DEFAULT_IV,
|
||
) -> Any:
|
||
"""Extract and decode an API response's encrypted ``data`` field."""
|
||
|
||
try:
|
||
ciphertext = response["data"]
|
||
except (KeyError, TypeError) as exc:
|
||
raise ValueError("API response does not contain a data field") from exc
|
||
return decode_ciphertext(ciphertext, key=key, iv=iv)
|
||
```
|
||
|
||
上面提供两个函数：
|
||
|
||
- `decode_ciphertext(ciphertext, *, key=..., iv=..., parse_json=True)`：解密单个 Base64 密文字符串。
|
||
- `decode_api_data(response, *, key=..., iv=...)`：从完整响应对象中取出 `data` 字段并解密。
|
||
|
||
**调用示例**
|
||
|
||
```python
|
||
import json
|
||
import urllib.request
|
||
import gzip
|
||
# 将上面的解密函数保存为 decoder.py 后即可导入
|
||
from decoder import decode_api_data
|
||
|
||
url = "https://api.xiaozhaoya.com/api/recruitment/detail?id=41794"
|
||
headers = {
|
||
"accept": "application/json",
|
||
"user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/150.0.0.0 Safari/537.36",
|
||
}
|
||
|
||
resp = urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=30)
|
||
raw = resp.read()
|
||
if resp.headers.get("content-encoding") == "gzip":
|
||
raw = gzip.decompress(raw)
|
||
|
||
payload = json.loads(raw.decode("utf-8"))
|
||
# 注意：先判断 data 是否为 null（如 id 不存在、未授权等场景）
|
||
if isinstance(payload.get("data"), str):
|
||
data = decode_api_data(payload)
|
||
print(json.dumps(data, ensure_ascii=False, indent=2))
|
||
else:
|
||
print("无数据：", payload.get("code"), payload.get("message"))
|
||
```
|
||
|
||
> 备注：Key/IV 硬编码在前端 JS 中且公开，此加密本质是轻量混淆/反爬，并非真正的机密性保护。若站点后续轮换密钥，`decode_ciphertext` 支持通过 `key`/`iv` 参数覆盖默认值。
|