184 lines
5.6 KiB
Markdown
184 lines
5.6 KiB
Markdown
# 英雄联盟API开发工具包
|
||
|
||
`TypeScript` `SDK` `英雄联盟` `Riot API` `npm`
|
||
|
||
<p align="center">
|
||
<img src="https://raw.githubusercontent.com/adrianmg/league-sdk/main/logo.png" alt="League SDK" width="600">
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://www.npmjs.com/package/league-sdk"><img src="https://img.shields.io/npm/v/league-sdk.svg" alt="npm 版本"></a>
|
||
<img src="https://img.shields.io/npm/dw/league-sdk.svg" alt="npm 下载量">
|
||
<img src="https://img.shields.io/badge/coverage-92%25-brightgreen" alt="覆盖率">
|
||
</p>
|
||
|
||
# league-sdk
|
||
|
||
一个完整类型化的 TypeScript SDK，用于访问 Riot 英雄联盟 API。
|
||
|
||
## 为什么选择这个 SDK？
|
||
|
||
直接使用原始 Riot API 需要调用多个端点、处理复杂路由并手动转换数据。本 SDK 将一切化繁为简：
|
||
|
||
**原始 API（多次调用，手动处理）：**
|
||
```typescript
|
||
// 1. 通过 Riot ID 获取账户（区域端点）
|
||
const account = await fetch(`https://asia.api.riotgames.com/riot/account/v1/accounts/by-riot-id/Hide%20on%20bush/KR1?api_key=${key}`);
|
||
const { puuid } = await account.json();
|
||
|
||
// 2. 获取召唤师数据（平台端点）
|
||
const summoner = await fetch(`https://kr.api.riotgames.com/lol/summoner/v4/summoners/by-puuid/${puuid}?api_key=${key}`);
|
||
const { id: summonerId } = await summoner.json();
|
||
|
||
// 3. 获取段位数据（平台端点，不同 ID）
|
||
const leagues = await fetch(`https://kr.api.riotgames.com/lol/league/v4/entries/by-puuid/${puuid}?api_key=${key}`);
|
||
const ranked = await leagues.json();
|
||
const soloQ = ranked.find(q => q.queueType === 'RANKED_SOLO_5x5');
|
||
|
||
// 4. 手动计算胜率
|
||
const winRate = soloQ.wins / (soloQ.wins + soloQ.losses);
|
||
```
|
||
|
||
**使用 league-sdk：**
|
||
```typescript
|
||
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
|
||
const soloQ = await player.getSoloQueueStats();
|
||
console.log(`${soloQ.tier} ${soloQ.division} - ${(soloQ.winRate * 100).toFixed(1)}% 胜率`);
|
||
```
|
||
|
||
## 快速上手
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
npm install league-sdk
|
||
# 或
|
||
bun add league-sdk
|
||
```
|
||
|
||
### API 密钥
|
||
|
||
前往 [developer.riotgames.com](https://developer.riotgames.com/) 获取密钥。开发者密钥有效期 24 小时（每秒 20 次，每 2 分钟 100 次）。如需永久密钥，请注册产品。
|
||
|
||
### 快速示例
|
||
|
||
```typescript
|
||
import { LolClient } from 'league-sdk';
|
||
|
||
const client = new LolClient({
|
||
apiKey: process.env.RIOT_API_KEY!,
|
||
platform: 'kr'
|
||
});
|
||
|
||
// 获取玩家及其段位数据
|
||
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
|
||
const soloQ = await player.getSoloQueueStats();
|
||
|
||
// 获取近期对局
|
||
const matches = await client.matches.getForPlayer(player.puuid, { count: 5 });
|
||
for (const match of matches) {
|
||
const p = match.getParticipant(player.puuid)!;
|
||
console.log(`${p.championName}: ${p.kills}/${p.deaths}/${p.assists}`);
|
||
}
|
||
```
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
bun install && bun test
|
||
```
|
||
|
||
```bash
|
||
# 适用于 AI Agent 的技能
|
||
npx skills add https://github.com/adrianmg/league-sdk --skill league-sdk
|
||
```
|
||
|
||
## 功能特性
|
||
|
||
| 服务 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| **Players（玩家）** | 通过 Riot ID 或 PUUID 查询 | `client.players.getByRiotId('Name', 'Tag')` |
|
||
| **Matches（对局）** | 对局历史与详情 | `client.matches.getForPlayer(puuid)` |
|
||
| **Mastery（熟练度）** | 英雄熟练度数据 | `client.mastery.getForPlayer(puuid)` |
|
||
| **Live Game（实时对局）** | 当前对局观战信息 | `client.liveGame.getForPlayer(puuid)` |
|
||
| **Status（状态）** | 服务器健康状态 | `client.status.get('euw1')` |
|
||
| **Challenges（挑战）** | 挑战任务进度 | `client.challenges.getPlayerProfile(puuid)` |
|
||
| **Clash（冠军杯）** | 赛事信息 | `client.clash.getPlayer(puuid)` |
|
||
| **Data Dragon（静态数据）** | 静态数据（无需密钥） | `client.dataDragon.getChampions()` |
|
||
|
||
## 实体对象
|
||
|
||
```typescript
|
||
// 玩家
|
||
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
|
||
player.puuid; player.riotId; player.level;
|
||
await player.getSoloQueueStats();
|
||
|
||
// 对局
|
||
const match = await client.matches.getById('EUW1_1234567890');
|
||
match.gameMode; match.gameDurationFormatted; match.winner;
|
||
const p = match.getParticipant(puuid)!;
|
||
p.kills; p.deaths; p.assists; p.kda; p.csPerMinute;
|
||
```
|
||
|
||
## 常量与工具函数
|
||
|
||
```typescript
|
||
import { PLATFORMS, QUEUES, isRankedQueue, formatRank, compareRanks } from 'league-sdk';
|
||
|
||
PLATFORMS.EUW1 // 'euw1'
|
||
isRankedQueue(420) // true（单双排）
|
||
formatRank('DIAMOND', 'II') // "钻石 II"
|
||
compareRanks('DIAMOND', 'II', 'PLATINUM', 'I') // 1（钻石 > 铂金）
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
类型化错误：`NotFoundError`、`RateLimitError`（含 `retryAfter`）、`AuthenticationError`。
|
||
|
||
## 资源下载
|
||
|
||
```bash
|
||
npx league-sdk-assets --output ./assets --all
|
||
```
|
||
|
||
也可通过 `league-sdk/scripts` 使用程序化 API。
|
||
|
||
## 请求限速
|
||
|
||
内置限速器（每秒 20 次，每 2 分钟 100 次）。可通过 `rateLimiter` 选项配置，或使用 `client.getRateLimitStatus()` 查看当前状态。
|
||
|
||
## 示例服务器
|
||
|
||
```bash
|
||
RIOT_API_KEY=your-key bun run example/server.ts
|
||
```
|
||
|
||
## 支持的平台
|
||
|
||
| 平台 | 区域 | 位置 |
|
||
|------|------|------|
|
||
| `na1` | americas | 北美 |
|
||
| `br1` | americas | 巴西 |
|
||
| `la1` | americas | 拉丁美洲北部 |
|
||
| `la2` | americas | 拉丁美洲南部 |
|
||
| `euw1` | europe | 欧洲西部 |
|
||
| `eun1` | europe | 欧洲北欧及东部 |
|
||
| `tr1` | europe | 土耳其 |
|
||
| `ru` | europe | 俄罗斯 |
|
||
| `kr` | asia | 韩国 |
|
||
| `jp1` | asia | 日本 |
|
||
| `oc1` | sea | 大洋洲 |
|
||
| `ph2` | sea | 菲律宾 |
|
||
| `sg2` | sea | 新加坡 |
|
||
| `th2` | sea | 泰国 |
|
||
| `tw2` | sea | 台湾 |
|
||
| `vn2` | sea | 越南 |
|
||
|
||
## 许可证
|
||
|
||
MIT
|
||
|
||
## 致谢
|
||
|
||
本项目在 GitHub Copilot 和 Claude 等 AI 编程工具的协助下开发完成。 |