159 lines
4.0 KiB
Markdown
159 lines
4.0 KiB
Markdown
|
# NBA Stats API 验证检查清单
|
|||
|
|
|
|||
|
|
## 一、API 接口定义检查
|
|||
|
|
|
|||
|
|
### 1.1 接口路径
|
|||
|
|
- ✅ **路径**: `/Scoreboard`
|
|||
|
|
- ✅ **Base URL**: `https://stats.nba.com/stats/`
|
|||
|
|
- ✅ **完整 URL**: `https://stats.nba.com/stats/Scoreboard`
|
|||
|
|
|
|||
|
|
### 1.2 请求参数
|
|||
|
|
- ✅ **GameDate**: 日期格式 `YYYY-MM-DD`（如 `2024-12-15`）
|
|||
|
|
- ✅ **LeagueID**: 联盟ID，默认 `"00"` (NBA)
|
|||
|
|
- ✅ **DayOffset**: 日期偏移，默认 `0`
|
|||
|
|
|
|||
|
|
**注意**: NBA Stats API 的参数名称是**大小写敏感**的：
|
|||
|
|
- ✅ `GameDate` (正确)
|
|||
|
|
- ❌ `gameDate` (错误)
|
|||
|
|
- ✅ `LeagueID` (正确)
|
|||
|
|
- ❌ `leagueId` (错误)
|
|||
|
|
|
|||
|
|
### 1.3 请求头设置
|
|||
|
|
- ✅ **User-Agent**: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36`
|
|||
|
|
- ✅ **Referer**: `https://www.nba.com/`
|
|||
|
|
- ✅ **Accept**: `application/json`
|
|||
|
|
- ✅ **Accept-Language**: `en-US,en;q=0.9`
|
|||
|
|
- ✅ **Origin**: `https://www.nba.com`
|
|||
|
|
|
|||
|
|
## 二、响应格式检查
|
|||
|
|
|
|||
|
|
### 2.1 响应结构
|
|||
|
|
NBA Stats API 返回的 JSON 结构：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"resultSets": [
|
|||
|
|
{
|
|||
|
|
"name": "GameHeader",
|
|||
|
|
"headers": ["GAME_DATE_EST", "GAME_SEQUENCE", "GAME_ID", ...],
|
|||
|
|
"rowSet": [[...], [...]]
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"name": "LineScore",
|
|||
|
|
"headers": ["GAME_DATE_EST", "GAME_SEQUENCE", "GAME_ID", "TEAM_ID", ...],
|
|||
|
|
"rowSet": [[...], [...]]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.2 ResultSet 名称
|
|||
|
|
- ✅ **GameHeader**: 比赛基本信息
|
|||
|
|
- ✅ **LineScore**: 比分信息（每支球队一行）
|
|||
|
|
|
|||
|
|
### 2.3 GameHeader 字段顺序
|
|||
|
|
根据注释，字段顺序应该是：
|
|||
|
|
```
|
|||
|
|
[0] GAME_DATE_EST
|
|||
|
|
[1] GAME_SEQUENCE
|
|||
|
|
[2] GAME_ID
|
|||
|
|
[3] GAME_STATUS_ID
|
|||
|
|
[4] GAME_STATUS_TEXT
|
|||
|
|
[5] GAMECODE
|
|||
|
|
[6] HOME_TEAM_ID
|
|||
|
|
[7] VISITOR_TEAM_ID
|
|||
|
|
[8] SEASON
|
|||
|
|
[9] LIVE_PERIOD
|
|||
|
|
[10] LIVE_PC_TIME
|
|||
|
|
[11] NATL_TV_BROADCASTER_ABBREV
|
|||
|
|
[12] LIVE_PERIOD_TIME_BCAST
|
|||
|
|
[13] WH_STATUS
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.4 LineScore 字段顺序
|
|||
|
|
根据注释，字段顺序应该是：
|
|||
|
|
```
|
|||
|
|
[0] GAME_DATE_EST
|
|||
|
|
[1] GAME_SEQUENCE
|
|||
|
|
[2] GAME_ID
|
|||
|
|
[3] TEAM_ID
|
|||
|
|
[4] TEAM_ABBREVIATION
|
|||
|
|
[5] TEAM_NAME
|
|||
|
|
[6] PTS_QTR1
|
|||
|
|
[7] PTS_QTR2
|
|||
|
|
[8] PTS_QTR3
|
|||
|
|
[9] PTS_QTR4
|
|||
|
|
[10] PTS_OT1
|
|||
|
|
[11] PTS_OT2
|
|||
|
|
[12] PTS_OT3
|
|||
|
|
[13] PTS_OT4
|
|||
|
|
[14] PTS
|
|||
|
|
[15] FG_PCT
|
|||
|
|
[16] FT_PCT
|
|||
|
|
[17] FG3_PCT
|
|||
|
|
[18] AST
|
|||
|
|
[19] REB
|
|||
|
|
[20] TOV
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 三、代码实现检查
|
|||
|
|
|
|||
|
|
### 3.1 接口定义 ✅
|
|||
|
|
```kotlin
|
|||
|
|
@GET("Scoreboard")
|
|||
|
|
suspend fun getScoreboard(
|
|||
|
|
@Query("GameDate") gameDate: String? = null,
|
|||
|
|
@Query("LeagueID") leagueId: String = "00",
|
|||
|
|
@Query("DayOffset") dayOffset: Int = 0
|
|||
|
|
): Response<ScoreboardResponse>
|
|||
|
|
```
|
|||
|
|
- ✅ 参数名称大小写正确
|
|||
|
|
- ✅ 参数类型正确
|
|||
|
|
|
|||
|
|
### 3.2 请求头设置 ✅
|
|||
|
|
- ✅ 已设置所有必需的请求头
|
|||
|
|
- ✅ User-Agent 格式正确
|
|||
|
|
|
|||
|
|
### 3.3 响应解析 ⚠️
|
|||
|
|
**潜在问题**：
|
|||
|
|
1. **ResultSet 查找方式**: 使用 `firstOrNull { it.name == "GameHeader" }` 可能不够准确
|
|||
|
|
- 建议：使用索引 `resultSets[0]` 或 `resultSets.getOrNull(0)`
|
|||
|
|
- 或者：先检查 `resultSets.size >= 2`
|
|||
|
|
|
|||
|
|
2. **字段索引**: 当前代码假设字段顺序固定
|
|||
|
|
- 建议：根据 `headers` 数组动态查找字段索引，而不是硬编码索引
|
|||
|
|
|
|||
|
|
3. **错误处理**: 当前有基本的错误处理，但可以更详细
|
|||
|
|
|
|||
|
|
## 四、建议的改进
|
|||
|
|
|
|||
|
|
### 4.1 使用 headers 动态查找字段
|
|||
|
|
```kotlin
|
|||
|
|
// 根据 headers 查找字段索引，而不是硬编码
|
|||
|
|
val gameDateIndex = headers.indexOf("GAME_DATE_EST")
|
|||
|
|
val gameIdIndex = headers.indexOf("GAME_ID")
|
|||
|
|
// ...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.2 增强错误处理
|
|||
|
|
- 记录完整的响应内容（用于调试）
|
|||
|
|
- 验证 headers 数量是否匹配
|
|||
|
|
- 验证 rowSet 数据是否完整
|
|||
|
|
|
|||
|
|
### 4.3 添加响应验证
|
|||
|
|
- 验证 resultSets 数量
|
|||
|
|
- 验证每个 resultSet 的 name
|
|||
|
|
- 验证 headers 和 rowSet 的对应关系
|
|||
|
|
|
|||
|
|
## 五、测试建议
|
|||
|
|
|
|||
|
|
1. **单元测试**: 测试 API 调用和响应解析
|
|||
|
|
2. **集成测试**: 测试完整的获取流程
|
|||
|
|
3. **错误场景测试**: 测试 API 失败、数据不完整等情况
|
|||
|
|
|
|||
|
|
## 六、已知问题
|
|||
|
|
|
|||
|
|
1. **API 限制**: NBA Stats API 可能需要特定的请求头，否则可能返回 403 或空数据
|
|||
|
|
2. **数据格式**: 响应格式可能因日期而异（有比赛 vs 无比赛）
|
|||
|
|
3. **时区问题**: `GAME_DATE_EST` 是 EST 时区，需要注意时区转换
|
|||
|
|
|