最小可运行示例：王者战力查询接口接入

为什么需要最小可运行示例

接入一个 API 时，最耗时的往往不是业务逻辑，而是反复阅读文档、猜测参数、拼接请求、解析响应。如果能在 5 分钟内跑通一个最小可运行示例，后面的开发就会顺畅得多。本文以「王者战力查询」接口为例，从零开始构造两个最精简的请求：一个是获取英雄列表，一个是通过英雄名查询全国战力分布。整个过程中只需要一个终端、一行 curl 和一把 API Key。

最小可运行示例的关键在于：只保留必要参数、使用公开可复制的数据、输出足够清晰的返回结果。这样既方便验证接口连通性，又能为后续的代码封装提供一个确定的基线。

适用场景

这个接口面向的是需要把「王者荣耀全国战力数据」整合进自己应用或脚本的开发者。典型场景包括：

• 游戏数据展示站点：按英雄展示各区服的最低/最高战力上榜线；
• 社区机器人：用户输入英雄名和区服，机器人返回该英雄的省市区战力分布；
• 数据分析脚本：采集不同英雄在不同平台的战力分布，观察地域差异；
• 工具类 App：提供战力查询入口，辅助玩家进行游戏内决策。

需要强调的是，这类数据属于游戏生态的衍生数据，接口返回的是榜单截图级别的汇总信息，而非任何玩家的个人隐私。开发者使用时应当注意数据展示的合规性，避免将数据用于与官方社区规则相冲突的场景。

接口能力边界

在写代码之前，先明确这个接口能做什么、不能做什么。

两个核心动作

区服与查询类型

• 区服代码：aqq（Android QQ）、awx（Android 微信）、iqq（iOS QQ）、iwx（iOS 微信）；
• 查询类型：all（完整列表，默认）、min（各级最低战力 + 相近排名）、max（各级最高战力 + 相近排名）。

请求限制

接口的 QPS 为 5/s，即每秒最多 5 个请求。这个限制对普通开发和轻量脚本足够了，但需要注意不要在循环里无脑并发。如果确实有高频需求，应当先与接口提供方确认是否有更高的配额，而不是在本地无限重试。

鉴权与请求头

接口在匿名状态下也可能可用，但作为正规接入，建议在请求头中携带 API Key。文档中给出的两种鉴权头格式如下：

Authorization: Bearer sk_live_xxxxxxxxxxxxxx

或者使用文档中 curl 示例里的方式：

X-API-Key: sk_live_xxxxxxxxxxxxxx

实际以apizero.cn/aidocs/wzry的文档页为准。在本地测试时，可以把 Key 放进环境变量，避免把凭证硬编码进脚本。

第一步：拉取英雄列表

最小可运行示例的第一步，是确认接口连通性并拿到一份英雄目录。直接请求action=heroes，不需要携带任何业务参数：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/wzry?action=heroes"

如果没有配置环境变量，也可以直接写死 Key 测试，但请注意不要提交到公开仓库。

返回内容是一个 JSON 数组，每个元素代表一个英雄，关键字段包括：

• name：英雄中文名，如「赵云」；
• ename：英雄数字 ID，如赵云是107；
• title：英雄称号，如「苍天翔龙」；
• avatar：头像 URL。

第二步：查询战力分布

假设我们要查询安卓 QQ 区赵云的最低战力分布，请求如下：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/wzry?action=query&hero=赵云&zone=aqq&type=min"

这里使用了三个关键参数：

• action=query：表示进行战力查询；
• hero=赵云：指定英雄，也可以用hero_id=107代替；
• zone=aqq：指定区服为 Android QQ；
• type=min：返回各级最低战力。

如果不传type，默认返回all，即约 90 行的完整列表。

如果希望使用hero_id，可以这样写：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/wzry?action=query&hero_id=107&zone=iwx&type=max"

这里hero_id的优先级高于hero，所以当两者同时出现时，接口以hero_id为准。

返回字段解读

action=query的响应结构如下（为节省篇幅做了简化）：

{ "code": 0, "msg": "成功", "request_id": "abc123def456", "data": { "action": "query", "hero": { "ename": "107", "name": "赵云", "title": "苍天翔龙", "avatar": "https://game.gtimg.cn/images/yxzj/img201606/heroimg/107/107.jpg" }, "zone": { "code": "aqq", "platform": "QQ", "system": "Android" }, "type_code": "min", "type": "最低战力", "rank_data": { "extreme": { "province": { "address": "云南", "level": "province", "rank": 4500 }, "city": { "address": "海南/三亚市", "level": "city", "rank": 1800 }, "district": { "address": "北京/朝阳区", "level": "district", "rank": 800 } }, "similar": { "province": [ { "address": "云南", "rank": 4500 }, { "address": "甘肃", "rank": 4520 } ], "city": [], "district": [] } }, "syn_date": "2026-05-06" } }

顶层字段

• code：业务状态码，0表示成功；
• msg：状态描述；
• request_id：请求唯一标识，排查问题时可以携带；
• data：业务数据主体。

data 内部字段

注意：similar中的rank与extreme中的rank含义相同，都是战力值而非排名序号。这一点很容易被误解，建议在封装代码时明确注释。

常见错误排查

1. 返回 401 或鉴权失败

检查请求头是否携带了正确的 API Key。如果是使用Authorization头，记得带Bearer前缀并保留空格。另外确认 Key 没有包含多余换行符。

2. 返回参数缺失提示

action=query时，hero与hero_id必须二选一，且zone必填。如果只传action=query而没有英雄信息，接口会提示参数错误。例如：

curl -sS "https://v1.apizero.cn/api/wzry?action=query&zone=aqq"

这是一个容易犯的示例错误，因为看起来zone已经给了，但缺少英雄参数仍无法执行。

3. 英雄名不存在

如果传入的英雄名不在英雄列表里，接口可能返回空数据或业务错误码。建议先调用action=heroes拉取最新列表，再根据name或ename构造查询参数。

4. 区服代码拼写错误

区服代码只有四种：aqq、awx、iqq、iwx。注意大小写与全半角，不要把aqq写成aq或AQQ。

5. QPS 超限

工程化注意事项

缓存英雄列表

英雄列表相对固定，不必每次查询都请求一次action=heroes。建议在服务启动时拉取一次，缓存到内存或 Redis，并为缓存设置过期时间（比如每天刷新一次）。这样既能减少接口调用量，也能提高查询参数的构建速度。

统一参数校验

在业务层做一层参数校验，可以避免把无效请求发到上游。例如：

• zone必须限定在四个枚举值内；
• type必须是all、min、max之一；
• hero或hero_id至少存在一个，且 hero_id 的优先级高于 hero；
• 当hero_id存在时，可以忽略hero。

设置超时与重试

网络请求必须设置超时。建议超时时间控制在 5 秒以内，重试次数不超过 2 次。重试时最好使用指数退避，避免在接口短暂不可用时造成请求风暴。

注意hero_id的类型

在响应示例中，hero.ename是字符串"107"，而在请求参数中hero_id的类型是 number。接入时要注意类型转换，避免把数字类型直接拼接成hero_id=107后收到奇怪的结果——本质上 107 是整型，但 JSON 序列化时可能变成字符串，建议在代码中显式转换为int。

处理syn_date

syn_date表示当前榜单快照的同步日期。不同日期的数据可能不同，因此在展示或分析时，建议把syn_date一并保存。如果需要对比历史变化，可以用它作为分区字段。

只在必要时请求max和all

type=all返回约 90 条记录，数据量较大；type=min和type=max则只返回每个级别的一个代表值及相近排名。如果业务只需要一档线的战力值，选择min或max更高效。

从 curl 到最小代码封装

有了上述 curl 示例，封装成代码就很简单了。这里给出一个 Python 的最小示例，展示如何把请求参数组织成requests调用：

import requests API_URL = "https://v1.apizero.cn/api/wzry" API_KEY = "sk_live_xxxxxxxxxxxxxx" # 替换为真实 Key def query_hero(hero: str, zone: str, req_type: str = "min"): params = { "action": "query", "hero": hero, "zone": zone, "type": req_type, } headers = {"X-API-Key": API_KEY} resp = requests.get(API_URL, params=params, headers=headers, timeout=5) resp.raise_for_status() return resp.json() if __name__ == "__main__": result = query_hero("赵云", "aqq", "min") print(result["data"]["rank_data"]["extreme"]["province"])

这个封装保留了最少的参数传递逻辑，适合作为项目脚手架的一部分。生产环境建议再加上日志记录、异常捕获和配置管理。

小结

最小可运行示例的价值在于帮你快速建立“接口能通”的确定感。本文通过heroes和query两个 action，完整演示了王者战力查询接口的调用链路：从鉴权、参数构造、发送请求，到解析rank_data中的省市区战力值。后续扩展方向可以是多英雄并发查询、榜单历史归档、以及基于similar数据的波动分析。

接入过程中，最重要的原则是：以官方文档为准，不要假设接口行为。尤其是鉴权字段、错误码和限流策略，不同版本的接口可能略有差异，务必以你的实际请求返回为准。

参考文档

• 接口文档页：https://apizero.cn/aidocs/wzry
• 原始文档：https://apizero.cn/aidocs/wzry/raw.md