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, lossesurl = f{self.base_url}/lol/summoner/v4/summoners/{summoner_id}/ranked-statsheaders = {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), # 如 DIAMONDdivision: solo_queue.get(division),# 如 IIpoints: 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秒），能有效应对临时的网络抖动或服务端瞬时过载。
小结
这个项目虽然小，但涵盖了实际开发中遇到的典型问题：API 鉴权、错误处理、数据缓存、代码封装。
特别是 2026 年最新的 API 变化，提醒我们：永远不要相信网上的旧教程。在动手写代码前，一定要去官方的开发者文档（developer.riotgames.com）确认最新的端点和参数。CSDN 等社区有很多优质文章，但它们的时效性有限，作为参考可以，作为唯一依据不行。
你在项目里踩过这个坑吗？比如 API 限流导致的数据丢失，或者地区参数传错导致的诡异 Bug？评论区聊聊，看看有没有更好的解决方案。 3天搞定英雄联盟排位等级查询：2026最新实战避坑指南
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, lossesurl = f{self.base_url}/lol/summoner/v4/summoners/{summoner_id}/ranked-statsheaders = {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), # 如 DIAMONDdivision: solo_queue.get(division),# 如 IIpoints: 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秒），能有效应对临时的网络抖动或服务端瞬时过载。
小结
这个项目虽然小，但涵盖了实际开发中遇到的典型问题：API 鉴权、错误处理、数据缓存、代码封装。
特别是 2026 年最新的 API 变化，提醒我们：永远不要相信网上的旧教程。在动手写代码前，一定要去官方的开发者文档（developer.riotgames.com）确认最新的端点和参数。CSDN 等社区有很多优质文章，但它们的时效性有限，作为参考可以，作为唯一依据不行。
你在项目里踩过这个坑吗？比如 API 限流导致的数据丢失，或者地区参数传错导致的诡异 Bug？评论区聊聊，看看有没有更好的解决方案。