3天搞定英雄联盟排位等级查询：2026最新实战避坑指南

刚把老项目跑起来，直接报错：401 Unauthorized。心里一沉，又是版本升级后 API 全变了。Riot Games 在 2026 年初彻底重构了开发者接口，旧的 v1 版本直接下架，很多网上的教程瞬间失效，连 CSDN 上不少高赞文章的代码都跑不通。如果你还在用几年前的 Key 和端点，别折腾了，今天这篇文章就是为你准备的。

我们要从零搭建一个轻量级的英雄联盟排位等级查询工具。这不是为了做游戏辅助，而是为了学习如何稳定地对接一个高频变动的第三方 API。通过这个项目，你会掌握 API 鉴权、异步请求处理、数据清洗以及本地缓存策略。哪怕你之前没碰过 Riot 的接口，跟着做，3 天内就能拥有自己的工具。

项目目标与痛点分析

为什么我们要专门做一个查询工具？因为官方客户端里的数据展示太粗糙，而直接调接口又太累。

核心痛点很明确：数据获取的稳定性。Riot 的 API 有严格的速率限制（Rate Limit），而且不同地区的服务器（EU、NA、KR、CN 等）数据隔离。很多开发者踩过的坑是：以为拿到了全球数据，结果发现只有本地服务器的数据。

我们的项目目标很简单：

精准定位：输入玩家昵称和地区，返回当前的排位赛等级（Rank）、分段（Division）和小分（LP）。
数据持久化：将查询结果存入 SQLite，避免重复请求触发限流。
友好展示：终端输出简洁明了的表格，包含最近 5 局的胜负情况。

这里有一个关键概念需要澄清：排位等级（Rank） 并不等于 胜点（LP）。Rank 是青铜、白银、黄金、铂金、翡翠、钻石、大师、宗师、最强王者这九个阶段。LP 是你在该阶段内的积分，决定你往上升还是往下降。我们的代码必须同时提取这两个字段，否则数据是不完整的。

目录结构设计

一个清晰的项目结构能帮你快速定位问题。我们采用 Python 的 requests 库进行 HTTP 请求，sqlite3 进行本地存储，rich 库美化终端输出。

lol-rank-query/
├── main.py          # 程序入口
├── config.py        # 配置文件，存放 API Key
├── api_client.py    # 封装 API 请求逻辑
├── database.py      # 数据库操作模块
├── utils.py         # 工具函数，如数据格式化
├── requirements.txt # 依赖库列表
└── .env             # 环境变量文件（不提交到 Git）

config.py 里我们只放非敏感配置，比如默认的地区映射。API Key 必须放在 .env 文件中，通过 python-dotenv 加载。这是工程化的基本素养，千万不要把 Key 硬编码在代码里，否则一旦推送到 GitHub，你的 Key 就会被爬取滥用。

核心代码实现

1. API 客户端封装

Riot 的新版 API 要求使用 Bearer Token 鉴权。2026 最新的接口端点有所变化，特别是获取排位信息的端点，从原来的 /lol/summoner/v4/summoners/{name}/ranked-stats 变为了更细粒度的 /lol/match/v5/matches 结合 /lol/champion-mastery/v4/champions 等组合查询，或者直接使用新的 /lol/summoner/v5/summoners/{name}/current-acts（注：具体端点随版本微调，此处以通用逻辑为例，实际需查阅官方开发者文档最新状态）。

为了保持代码的可维护性，我们封装一个 RiotClient 类。

import requests
import os
from dotenv import load_dotenvload_dotenv()class RiotClient:def __init__(self):self.api_key = os.getenv("RIOT_API_KEY")if not self.api_key:raise ValueError("未找到 RIOT_API_KEY，请检查 .env 文件")# 2026 最新版本的基础 URL，注意区分地区self.base_url = "https://asia.api.riotgames.com" # 默认亚服，可配置def get_summoner_id(self, name: str, region: str = "KR") -> str:"""第一步：根据玩家昵称获取 Summoner ID注意：昵称是唯一的，但 ID 是全局唯一的"""url = f"{self.base_url}/lol/summoner/v4/summoners/by-name/{name}"headers = {"X-Riot-Token": self.api_key}try:response = requests.get(url, headers=headers, timeout=10)response.raise_for_status() # 如果状态码不是 2xx，抛出异常data = response.json()return data.get("id")except requests.exceptions.HTTPError as http_err:if http_err.response.status_code == 404:raise ValueError(f"玩家 '{name}' 在 {region} 服不存在")raise http_errdef get_ranked_stats(self, summoner_id: str, region: str = "KR") -> dict:"""第二步：根据 Summoner ID 获取排位等级信息返回字典包含: tier, division, points, wins, losses"""url = f"{self.base_url}/lol/summoner/v4/summoners/{summoner_id}/ranked-stats"headers = {"X-Riot-Token": self.api_key}try:response = requests.get(url, headers=headers, timeout=10)response.raise_for_status()data = response.json()# 提取单排/双排 (SOLO) 的数据solo_queue = data.get("soloQueue")if not solo_queue:return {}return {"tier": solo_queue.get("tier"),       # 如 "DIAMOND""division": solo_queue.get("division"),# 如 "II""points": solo_queue.get("points"),    # LP 值"wins": solo_queue.get("wins"),"losses": solo_queue.get("losses")}except requests.exceptions.HTTPError as http_err:if http_err.response.status_code == 429:raise Exception("触发速率限制，请稍后重试")raise http_err

逐行讲解关键点：

response.raise_for_status()：这是很多新手忽略的步骤。如果 API 返回 404 或 401，requests 默认不会报错，必须手动抛出异常，才能捕获到具体的错误原因。
timeout=10：网络请求必须设置超时。否则如果服务器无响应，你的程序会一直挂起，直到用户手动杀掉进程。
地区参数：region 参数至关重要。KR（韩服）、NA（美服）、EU（欧服）的数据是完全独立的。如果你在 KR 服查不到人，去 NA 服肯定也是查不到的，除非你传对了参数。

2. 数据库操作与缓存

为了避免每次查询都请求 API（浪费配额且慢），我们引入 SQLite 缓存。如果 5 分钟内查过同一个玩家，直接返回缓存数据。

import sqlite3
import time
import jsonclass RankCache:def __init__(self, db_path="rank_cache.db"):self.conn = sqlite3.connect(db_path)self.cursor = self.conn.cursor()self._init_db()def _init_db(self):"""初始化表结构"""self.cursor.execute('''CREATE TABLE IF NOT EXISTS rank_data (summoner_id TEXT PRIMARY KEY,name TEXT,region TEXT,data TEXT,       -- 存储 JSON 字符串timestamp REAL   -- 缓存时间戳)''')self.conn.commit()def get_cached(self, summoner_id: str, max_age=300):"""获取缓存数据，max_age 单位为秒，默认 5 分钟"""self.cursor.execute("SELECT data, timestamp FROM rank_data WHERE summoner_id = ?", (summoner_id,))row = self.cursor.fetchone()if not row:return Nonedata_str, timestamp = row# 检查是否过期if time.time() - timestamp > max_age:return Nonereturn json.loads(data_str)def save(self, summoner_id: str, name: str, region: str, data: dict):"""保存数据到缓存"""self.cursor.execute('''INSERT OR REPLACE INTO rank_data (summoner_id, name, region, data, timestamp)VALUES (?, ?, ?, ?, ?)''', (summoner_id, name, region, json.dumps(data), time.time()))self.conn.commit()

为什么用 INSERT OR REPLACE？ 因为 summoner_id 是主键。每次查询同一个玩家，我们直接用新数据覆盖旧数据。这样逻辑简单，不需要先 SELECT 判断是否存在再决定 INSERT 或 UPDATE，减少了两次数据库交互。

运行与测试

将以上代码整合到 main.py 中。

import sys
from api_client import RiotClient
from database import RankCache
from rich.console import Console
from rich.table import Tableconsole = Console()def query_rank(client: RiotClient, cache: RankCache, name: str, region: str):# 1. 尝试从缓存获取try:summoner_id = client.get_summoner_id(name, region)except ValueError as e:console.print(f"[red]{e}[/red]")returncached_data = cache.get_cached(summoner_id)if cached_data:console.print("[yellow]从缓存中加载数据[/yellow]")data = cached_dataelse:console.print("[blue]正在从 API 获取最新数据...[/blue]")data = client.get_ranked_stats(summoner_id, region)if data:cache.save(summoner_id, name, region, data)if not data:console.print("[red]未找到排位数据，可能玩家未参与排位赛[/red]")return# 2. 展示结果table = Table(title=f"玩家: {name} ({region})")table.add_column("项目", style="cyan")table.add_column("值", style="magenta")table.add_row("大段", data["tier"])table.add_row("小段", data["division"])table.add_row("胜点 (LP)", str(data["points"]))table.add_row("总胜场", str(data["wins"]))table.add_row("总败场", str(data["losses"]))console.print(table)if __name__ == "__main__":if len(sys.argv) < 3:console.print("用法: python main.py <玩家昵称> <地区(如 KR, NA, EU)>")sys.exit(1)name = sys.argv[1]region = sys.argv[2].upper()client = RiotClient()cache = RankCache()try:query_rank(client, cache, name, region)except Exception as e:console.print(f"[red]发生错误: {e}[/red]")

测试步骤：

安装依赖：pip install requests python-dotenv rich
创建 .env 文件，填入你的 RIOT_API_KEY=你的密钥。
运行：python main.py Faker KR
观察输出，确认表格正常显示。
再次运行相同命令，观察是否提示“从缓存中加载数据”，且速度明显变快。

常见报错排查：

401 Unauthorized：API Key 错误，或者 .env 文件没被正确加载。检查控制台是否有 ValueError: 未找到 RIOT_API_KEY。
404 Not Found：玩家昵称拼写错误，或者地区选错。英雄联盟昵称区分大小写吗？不区分，但必须完全匹配。
429 Too Many Requests：你请求太快了。Riot 对单个 API Key 的速率限制是每秒 5 次请求，每 10 分钟 300 次。如果你的脚本在循环查询，必须加 time.sleep(0.2)。

优化扩展

基础功能跑通后，我们可以做哪些优化？

并发查询：如果你要查询多个玩家，使用 asyncio 和 aiohttp 可以大幅提升速度。但要注意，并发数不能超过 API 的速率限制。
数据可视化：将历史查询数据绘制成折线图，展示某个玩家 LP 的波动趋势。这需要对数据库做更细致的记录，每次查询都追加一条记录，而不是覆盖。
Web 界面：用 Flask 或 FastAPI 封装一个简单的 Web 页面，让用户在浏览器里输入昵称查询。
错误重试机制：网络波动可能导致请求失败。引入 tenacity 库，实现指数退避重试。

from tenacity import retry, stop_after_attempt, wait_exponential@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
def robust_get(url, headers):response = requests.get(url, headers=headers, timeout=10)response.raise_for_status()return response

这段代码会自动重试 3 次，每次间隔时间指数增长（2秒、4秒、8秒），能有效应对临时的网络抖动或服务端瞬时过载。