豆瓣电影信息API参数详解：从请求到响应字段的完整指南
适用场景
豆瓣电影信息 API 为开发者提供通过豆瓣电影 ID 或完整 URL 获取电影详情的接口。常见使用场景包括：
- 个人电影收藏/评分网站，需要展示影片的评分、导演、演员等基础信息。
- 电影推荐系统，根据用户喜好获取电影元数据用于内容过滤。
- 自动化影评分析工具，采集热门短评（部分接口可能返回）。
- 后台管理面板，快速查询电影信息进行数据校对。
接口能力边界
- 请求方法：GET
- 接口地址：
https://v1.apizero.cn/api/douban-movie - 频率限制：5 QPS（每秒查询次数），超出会返回 429 状态码。
- 鉴权方式：需在请求头中携带
X-API-Key。 - 输入参数：仅一个必填参数
id，可为纯数字豆瓣 ID 或完整豆瓣电影页面 URL。 - 返回格式：JSON 数组，外层数组通常只有一个元素，内层包含
code、msg、data字段。 - 数据覆盖：基于豆瓣公开 JSON API，返回字段包括评分、导演、演员、类型、地区、片长、集数（剧集）、热门短评等，具体以实际响应为准。
参数详解与鉴权
必填参数id
- 类型：
string（字符串） - 是否必填：是
- 说明：豆瓣电影的唯一标识。支持两种格式：
- 纯数字 ID，例如
1292052（《肖申克的救赎》） - 完整豆瓣电影页面 URL，例如
https://movie.douban.com/subject/1292052/，API 会自动解析出 ID。
- 纯数字 ID，例如
- 示例值：
1292052
注意：若传入无效 ID 或 URL 格式无法解析，API 会返回错误码 400。
鉴权方式
该 API 使用 HTTP 请求头X-API-Key进行身份认证。你需要在调用前在 apizero.cn/console 申请 API Key，并将其作为请求头传递。
安全建议：
- 不要将 API Key 硬编码在源代码中，应通过环境变量（如
$APIZERO_API_KEY）注入。 - 在客户端调用时，禁止在前端代码中暴露 API Key。
curl 请求示例
以下示例展示通过 curl 发送请求，其中$APIZERO_API_KEY为环境变量，请替换为实际密钥。
示例 1：使用纯数字 ID
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/douban-movie?id=1292052"示例 2：使用完整豆瓣 URL
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/douban-movie?id=https://movie.douban.com/subject/1292052/"注意：URL 中的
id参数值如果包含特殊字符（如:,/）, curl 会自动进行 URL 编码，通常无需手动处理。若在编程语言中构建请求，应使用URLEncoder.encode()进行转义。
返回字段解读
API 响应是一个 JSON 数组，典型结构如下（以1292052为例）：
[ { "code": 0, "msg": "成功", "data": { "director": "弗兰克·德拉邦特", "douban_id": "1292052", "name": "肖申克的救赎", "score": "9.7", "year": "1994" } } ]字段说明
| 字段 | 类型 | 含义 | 注意事项 |
|---|---|---|---|
code | integer | 业务状态码，0 表示成功 | 非 0 表示错误，需根据msg排查 |
msg | string | 业务描述信息 | 可用于日志输出或用户提示 |
data | object | 电影详情对象 | 包含以下常见子字段（以实际返回为准） |
data.director | string | 导演姓名 | 可能为空字符串 |
data.douban_id | string | 豆瓣电影 ID | 与请求的id一致 |
data.name | string | 电影名称 | 中文名 |
data.score | string | 豆瓣评分（字符串） | 如 "9.7"，需要转换为数字时注意保留精度 |
data.year | string | 上映年份 | 如 "1994" |
除了上述字段，文档说明中还提到data对象可能包含：actors（演员列表）、type（类型）、region（地区）、duration（片长）、episodes（集数，仅剧集）、hot_comments（热门短评）等。如果业务需要这些字段，请以实际返回的 JSON 为准，并做好容错处理（字段缺失时提供默认值）。
重要提示：返回的
score是字符串类型，在比较或计算时注意类型转换。例如 JavaScript 中应使用parseFloat(data.score)。
常见错误与排查
| HTTP 状态码 | 错误原因 | 排查步骤 |
|---|---|---|
| 401 | API Key 缺失或无效 | 检查请求头是否添加X-API-Key，并确认 Key 尚未过期、权限正确。 |
| 400 | id参数缺失或格式错误 | 确认id参数已传递且格式正确（数字或完整 URL）。URL 需包含http://或https://。 |
| 404 | 电影不存在或 ID 无效 | 检查豆瓣 ID 是否正确（可通过豆瓣网站验证）。 |
| 429 | 请求频率超过 QPS 限制（5/s） | 在单次请求后等待至少 200ms 再发下一次，或实现排队机制。 |
| 500 | 服务端内部错误 | 稍后重试，若持续出现请联系 API 提供方。 |
| 无响应 / 超时 | 网络问题或 DNS 解析失败 | 检查网络连通性，确认能访问v1.apizero.cn。 |
另外注意：返回的code字段也可能为非 0 值（如code: -1），此时msg会说明具体业务错误，例如“参数错误”“数据获取失败”等。建议在代码中既判断 HTTP 状态码，也判断code字段。
工程化注意事项
1. API Key 安全管理
- 使用环境变量或密钥管理服务（如 Vault）存储 API Key，禁止写入版本控制系统。
- 在 Node.js 中可通过
process.env.APIZERO_API_KEY读取。
2. 限流控制
QPS 上限为 5，即每秒最多 5 次请求。若需要批量查询（例如同时查 20 部电影），应采用“令牌桶”或“固定间隔”策略：
- 固定间隔：每 200ms 发送一次请求。
- 批量并发：使用信号量限制并发数为 5。
示例（Python 伪代码）：
import time import requests def fetch_movie(movie_id): headers = {"X-API-Key": os.environ["APIZERO_API_KEY"]} resp = requests.get("https://v1.apizero.cn/api/douban-movie", params={"id": movie_id}, headers=headers) return resp.json() # 限流：每次请求后休眠 0.2 秒 for mid in movie_ids: result = fetch_movie(mid) time.sleep(0.2)3. 缓存策略
电影信息（如评分、导演、年份）变化频率极低，建议加入本地缓存（内存或 Redis）以减少重复请求，降低被限流风险。缓存时间可设为 1 天或更长，但需考虑短评等动态数据的时效性。
from functools import lru_cache @lru_cache(maxsize=128) def get_movie_info(movie_id): # 实际请求代码 pass4. 错误重试与熔断
对于 5xx 或网络超时错误，可设计指数退避重试（最多 3 次）。对于 429 错误，应等待「Retry-After」头指定的时间（若无则默认等待 1 秒）。若连续失败次数过多，应暂时熔断，避免浪费资源。
5. 数据类型与空值处理
score是字符串，需要数值比较时先parseFloat。- 部分字段可能为空字符串或
null，建议使用空值合并运算符（如??）提供默认值。 - 数组字段（如
actors）可能缺失或为[]，遍历前先判断长度。
6. 请求日志与监控
记录每次请求的douban_id、状态码、响应时间、code值，便于问题定位和性能分析。
参考文档
- 豆瓣电影信息 API 文档
- 原始 Markdown 文档
以上文档包含更完整的字段列表、错误码列表以及更新日志。建议开发前仔细阅读。