豆瓣电影信息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。
  • 示例值：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" } } ]

字段说明

字段类型含义注意事项
codeinteger业务状态码，0 表示成功非 0 表示错误，需根据msg排查
msgstring业务描述信息可用于日志输出或用户提示
dataobject电影详情对象包含以下常见子字段（以实际返回为准）
data.directorstring导演姓名可能为空字符串
data.douban_idstring豆瓣电影 ID与请求的id一致
data.namestring电影名称中文名
data.scorestring豆瓣评分（字符串）如 "9.7"，需要转换为数字时注意保留精度
data.yearstring上映年份如 "1994"

除了上述字段，文档说明中还提到data对象可能包含：actors（演员列表）、type（类型）、region（地区）、duration（片长）、episodes（集数，仅剧集）、hot_comments（热门短评）等。如果业务需要这些字段，请以实际返回的 JSON 为准，并做好容错处理（字段缺失时提供默认值）。

重要提示：返回的score是字符串类型，在比较或计算时注意类型转换。例如 JavaScript 中应使用parseFloat(data.score)。

常见错误与排查

HTTP 状态码错误原因排查步骤
401API Key 缺失或无效检查请求头是否添加X-API-Key，并确认 Key 尚未过期、权限正确。
400id参数缺失或格式错误确认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): # 实际请求代码 pass

4. 错误重试与熔断

对于 5xx 或网络超时错误，可设计指数退避重试（最多 3 次）。对于 429 错误，应等待「Retry-After」头指定的时间（若无则默认等待 1 秒）。若连续失败次数过多，应暂时熔断，避免浪费资源。

5. 数据类型与空值处理

  • score是字符串，需要数值比较时先parseFloat。
  • 部分字段可能为空字符串或null，建议使用空值合并运算符（如??）提供默认值。
  • 数组字段（如actors）可能缺失或为[]，遍历前先判断长度。

6. 请求日志与监控

记录每次请求的douban_id、状态码、响应时间、code值，便于问题定位和性能分析。

参考文档

  • 豆瓣电影信息 API 文档
  • 原始 Markdown 文档

以上文档包含更完整的字段列表、错误码列表以及更新日志。建议开发前仔细阅读。