科隆Major这样的线下大赛结束后，最值得回味的往往不只是冠军归属，还有选手在一场场比赛里的数据曲线。想认真做一次赛后复盘，看到的资料却散落在直播页面、赛事官网和第三方统计平台里：选手基本信息、队伍变阵、历史战绩、单场数据各在一处。我在整理这类资料时，做了一个小系统，把所有选手档案装进一个数据库，再提供查询接口和展示页面。这套系统叫“选手档案馆”，技术上是一个最普通的 Spring Boot Web 应用，但把数据建模、接口设计和页面展示串了起来。如果刚写完新手项目，想找一个能练到真实工程感的题目，这个方向比较适合。本文就以 m0NESY 等选手的档案数据为示例，从零搭建一个可运行的选手档案管理系统。
下面从数据设计开始，到接口实现，再到页面验证、常见排错和生产环境扩展，按一条完整链路走一遍。
1. 先想清楚选手档案馆要管哪些数据
1.1 从一次赛后复盘出发，拆解数据需求
看比赛时，弹幕和评论区里最常出现的个人相关话题，大多围绕某位选手“今天状态如何”“这个赛事打得怎么样”“加入当前队伍后的整体表现如何”。赛后真正想查证时，会面临三个问题：
- 选手基本信息分散在队伍页面、直播介绍、社区百科里。
- 单场战绩散落在赛事页面，缺少统一的“按选手归档”的视角。
- 多个赛事的记录格式不同，有人记录 Rating，有人只记击杀和死亡，口径对不上。
所以选手档案馆的第一个目标是建立统一的“选手档案”，把选手基础信息和比赛表现记录关联起来。第二个目标是可以按赛事、按选手快速筛选。第三个目标是能从一个选手的多条记录里聚合出平均值、胜场数等汇总指标。
1.2 核心数据对象和它们之间的关系
从数据模型上看，这个系统涉及四个核心对象：选手（player）、战队（team）、赛事（tournament）、比赛记录（match_record）。
它们之间的关系比较直观：
- 一个战队有多名选手，所以 team 和 player 是一对多关系，player 表通过 team_id 关联 team 表。
- 一名选手会在多个赛事中有比赛记录，所以 player 和 match_record 是一对多关系。
- 一个赛事包含多场比赛记录，所以 tournament 和 match_record 也是一对多关系。
用表格列出每个对象的重点字段，便于后面建表时对齐：
| 实体 | 建议表名 | 核心字段 | 用途 |
|---|---|---|---|
| 战队 | team | name, region, founded_year | 记录战队基础信息 |
| 选手 | player | nickname, real_name, country, team_id, position, join_date | 记录选手档案 |
| 赛事 | tournament | name, tier, location, start_date, end_date | 记录赛事基础信息 |
| 比赛记录 | match_record | player_id, tournament_id, opponent, map_name, result, kills, deaths, rating, adr, match_date | 记录单场表现 |
在实际项目里，还可以继续增加选手转会记录、地图池、队伍阵容变动等表。对于初版系统，上面四张表已经足够跑通主流程。
1.3 数据粒度：不要直接存一张大宽表
刚开始设计的人容易把选手信息、队伍名、赛事名、每场数据都塞进一张表。这样查询是很方便，但会遇到几个问题：
- 队伍改名字或选手转会后，需要更新大量冗余行的数据。
- 赛事名称重复存储，很难统一维护赛事的级别和时间。
- 新增一个选手的多个赛季数据时，表会越来越宽，筛选和索引也不容易设计。
这里采用“事实表 + 维度表”的思路：比赛记录是事实表，战队、选手、赛事是维度表。记录里只存 ID，查询时通过关联把名称带出来。这样既保持数据一致，也为后续聚合统计留出空间。
比赛记录的粒度建议到“选手单场”级别，即一场比赛里每位选手都有一条记录，包含该选手在该场比赛的击杀、死亡、助攻、Rating、ADR 等指标。如果未来要做更细的分析，可以再增加“回合级”数据表，但初版不需要，避免模型过度设计。
2. 搭建 Spring Boot 项目和基础配置
2.1 技术选型说明
选手档案馆不追求复杂的分布式架构，重点在于快速把数据管理闭环搭建起来。技术选型以“常用、好查错、社区资料多”为首要标准。
| 组件 | 选择 | 理由 |
|---|---|---|
| 开发语言 | Java 17 | Spring Boot 3.x 的基础要求，长期支持版本更稳 |
| Web 框架 | Spring Boot 3.x | 起步依赖完善，适合快速搭建 REST API |
| 持久层 | MyBatis-Plus | 内置单表 CRUD，同时保留自定义 SQL，适合本项目 |
| 数据库 | H2 | 嵌入式数据库，学习环境零安装；生产可替换为 MySQL |
| 前端展示 | 原生 HTML + Fetch | 不引入前后端分离复杂度，适合先验证接口 |
MyBatis-Plus 对 Spring Boot 3.x 需要引入专门的 starter，创建项目时以 Maven 仓库当前稳定版本为准。H2 用于本地快速跑通，生产环境建议换成 MySQL 8.x，并做好备份和连接池配置。
2.2 项目目录结构
按包结构拆分，避免所有代码堆在 controller 或 service 里：
player-archive/ ├── pom.xml ├── src/main/java/com/example/archive/ │ ├── ArchiveApplication.java │ ├── controller/ │ │ └── PlayerArchiveController.java │ ├── entity/ │ │ ├── Team.java │ │ ├── Player.java │ │ ├── Tournament.java │ │ └── MatchRecord.java │ ├── mapper/ │ │ ├── TeamMapper.java │ │ ├── PlayerMapper.java │ │ ├── TournamentMapper.java │ │ └── MatchRecordMapper.java │ └── service/ │ ├── PlayerArchiveService.java │ └── impl/ │ └── PlayerArchiveServiceImpl.java └── src/main/resources/ ├── application.yml └── schema.sql实体、Mapper、Service、Controller 各一层。示例为了精简，没有单独抽 VO 和 DTO，实际项目数据返回结构变多后，建议再增加一层 DTO。
2.3 核心依赖和配置
pom.xml 中关键依赖如下：
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-spring-boot3-starter</artifactId> <version>3.5.7</version> </dependency> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies>这里版本号只是示例，实际创建项目时建议用 Spring Initializr 生成的底座，再手动补充 MyBatis-Plus。H2 的 scope 是 runtime，说明它只在运行时使用，不参与打包。
application.yml 配置如下：
server: port: 8080 servlet: encoding: charset: UTF-8 enabled: true force: true spring: datasource: url: jdbc:h2:file:./data/archive;MODE=MySQL;DATABASE_TO_LOWER=TRUE driver-class-name: org.h2.Driver username: sa password: "" h2: console: enabled: true path: /h2-console sql: init: mode: always schema-locations: classpath:schema.sql mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl配置要点：
- H2 URL 使用
file模式，把数据持久化到本地文件，重启后数据不丢。 MODE=MySQL让 H2 尽量兼容 MySQL 语法，后续切换数据库时改动较小。- MyBatis-Plus 开启下划线转驼峰，数据库字段
team_id可以自动映射到实体属性teamId。 spring.sql.init自动执行schema.sql，方便开发环境初始化表结构。
注意：
spring.sql.init.mode=always每次启动都会执行 schema.sql，如果脚本里有DROP TABLE，会清空已有数据。开发环境合适，生产环境不要这样配置。
2.4 项目初始化后的检查点
项目搭建完成后，可以先启动一次空应用，确认能正常访问，再继续做表结构。访问http://localhost:8080/h2-console能看到 H2 控制台，说明数据库配置生效。如果端口被占用，先确认是否有其他进程占用 8080，再检查server.port配置。
3. 定义表结构和演示数据
3.1 建表 SQL
在src/main/resources/schema.sql中定义四张表。为了让后续版本迭代更简单，每张表都保留独立主键，并通过外键表达实体关系。
DROP TABLE IF EXISTS match_record; DROP TABLE IF EXISTS player; DROP TABLE IF EXISTS team; DROP TABLE IF EXISTS tournament; CREATE TABLE team ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(64) NOT NULL, region VARCHAR(32), founded_year INT ); CREATE TABLE player ( id BIGINT PRIMARY KEY AUTO_INCREMENT, nickname VARCHAR(64) NOT NULL, real_name VARCHAR(64), country VARCHAR(32), team_id BIGINT, position VARCHAR(32), join_date DATE, CONSTRAINT fk_player_team FOREIGN KEY (team_id) REFERENCES team(id) ); CREATE TABLE tournament ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(128) NOT NULL, tier VARCHAR(32), location VARCHAR(64), start_date DATE, end_date DATE ); CREATE TABLE match_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, player_id BIGINT NOT NULL, tournament_id BIGINT, opponent VARCHAR(64), map_name VARCHAR(64), result VARCHAR(8), kills INT, deaths INT, assists INT, rating DECIMAL(4,2), adr DECIMAL(5,1), match_date DATE, CONSTRAINT fk_record_player FOREIGN KEY (player_id) REFERENCES player(id), CONSTRAINT fk_record_tournament FOREIGN KEY (tournament_id) REFERENCES tournament(id) );说明几点：
- 选手表里没有用
role作为字段名，因为ROLE在部分数据库里是保留字，容易踩坑，这里改成position。 - 比赛结果用
result存储W或L，短字符串足够。 rating和adr分别用DECIMAL(4,2)和DECIMAL(5,1)，保证小数位固定，避免浮点误差。match_date使用 DATE 类型，方便按日期排序和筛选。
3.2 初始化示例数据
这里插入一组演示数据，m0NESY 和 NiKo 作为选手档案里的示例。下方战绩数字是占位数据，只用来验证系统功能，不是真实历史战绩。接入真实数据时，要从赛事官方或可信数据源导入并二次校验。
INSERT INTO team (id, name, region, founded_year) VALUES (1, 'G2', 'Europe', 2015), (2, 'NAVI', 'Europe', 2009); INSERT INTO player (id, nickname, real_name, country, team_id, position, join_date) VALUES (1, 'm0NESY', 'Ilya Osipov', 'Russia', 1, 'AWPer', '2022-01-03'), (2, 'NiKo', 'Nikola Kovac', 'Bosnia and Herzegovina', 1, 'Rifler', '2020-10-01'); INSERT INTO tournament (id, name, tier, location, start_date, end_date) VALUES (1, 'IEM Cologne 2024', 'S-Tier', 'Cologne', '2024-08-07', '2024-08-18'), (2, 'BLAST Premier World Final 2023', 'S-Tier', 'Abu Dhabi', '2023-12-13', '2023-12-17'); INSERT INTO match_record (player_id, tournament_id, opponent, map_name, result, kills, deaths, assists, rating, adr, match_date) VALUES (1, 1, 'Vitality', 'Inferno', 'W', 24, 16, 3, 1.32, 86.4, '2024-08-09'), (1, 1, 'FaZe', 'Mirage', 'L', 18, 20, 4, 0.98, 71.2, '2024-08-12'), (1, 2, 'Cloud9', 'Ancient', 'W', 26, 13, 2, 1.45, 92.7, '2023-12-14'), (2, 1, 'Vitality', 'Nuke', 'W', 21, 17, 5, 1.18, 79.5, '2024-08-09');使用示例数据时要注意：字段顺序要和表结构一致，尤其是match_record里把player_id放在最前面，避免插入时列错位。演示环境为了省事可以写裸 SQL，生产环境的数据初始化建议使用带INSERT列名的写法，更安全。
3.3 字段说明速查表
| 表 | 字段 | 含义 | 注意事项 |
|---|---|---|---|
| team | founded_year | 战队成立年份 | 用 INT，不做日期计算时比 DATE 简单 |
| player | position | 比赛位置 | 示例值 AWPer、Rifler，可按需扩展 |
| player | join_date | 加入队伍日期 | 记录档案时用于观察转会状态 |
| tournament | tier | 赛事级别 | 示例值 S-Tier、A-Tier，便于筛选 |
| match_record | result | 比赛结果 | 用 W/L 短码，统计胜场时方便 SUM(CASE) |
| match_record | rating | 综合评分 | DECIMAL，按赛事口径统一后再比较 |
| match_record | adr | 平均每回合伤害 | DECIMAL，空值可以先填 0 或 NULL |
3.4 建表阶段的常见坑
- 字段名不要直接叫
match、record、rank这类有保留字风险的词。表名可以使用match_record，字段名保持简单且避开常见保留字。 - 外键约束在开发环境能帮忙发现脏数据，但导入大量历史数据时要特别注意删除顺序，否则容易触发外键冲突。可以先删除 match_record，再删除 player。
- 日期字段建议统一使用
yyyy-MM-dd格式，避免在应用层解析时出现时区偏差。 - 如果使用
file模式的 H2，第一次启动生成的数据文件在项目根目录的data文件夹下，删除该文件夹可以重置演示数据，但也会清空所有记录。
4. 编写查询和聚合接口
4.1 实体类和 Mapper
实体类用@TableName指定表名，用@TableId指定主键类型。以下以 Player 为例：
package com.example.archive.entity; import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableName; import lombok.Data; import java.time.LocalDate; @Data @TableName("player") public class Player { @TableId(type = IdType.AUTO) private Long id; private String nickname; private String realName; private String country; private Long teamId; private String position; private LocalDate joinDate; }MyBatis-Plus 开启下划线转驼峰后，team_id会自动映射teamId，real_name自动映射realName。其他实体类似，不再重复列出。
Mapper 接口继承BaseMapper<T>，就能使用内置的 selectById、selectList 等方法：
package com.example.archive.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.example.archive.entity.Player; import org.apache.ibatis.annotations.Mapper; @Mapper public interface PlayerMapper extends BaseMapper<Player> { }Team、Tournament、MatchRecord 的 Mapper 同样写法。如果不想在每个 Mapper 上都加@Mapper，也可以在主启动类上使用@MapperScan。
4.2 档案列表接口
Controller 负责对外暴露 REST API，Service 负责组织查询逻辑。先看列表接口：
@RestController @RequestMapping("/api/archive") public class PlayerArchiveController { private final PlayerArchiveService archiveService; public PlayerArchiveController(PlayerArchiveService archiveService) { this.archiveService = archiveService; } @GetMapping("/players") public Result listPlayers(@RequestParam(required = false) Long teamId, @RequestParam(required = false) String position) { return Result.success(archiveService.listPlayers(teamId, position)); } }Service 实现里使用 LambdaQueryWrapper 构造动态条件：
public List<Player> listPlayers(Long teamId, String position) { LambdaQueryWrapper<Player> wrapper = Wrappers.lambdaQuery(); wrapper.eq(teamId != null, Player::getTeamId, teamId) .eq(StringUtils.hasText(position), Player::getPosition, position) .orderByAsc(Player::getId); return playerMapper.selectList(wrapper); }这里eq方法第一个参数是布尔条件，条件成立才拼接 SQL。这样查询参数可有可无，不用写多个 if。使用StringUtils.hasText而不是!= null，可以避免空字符串造成错误筛选。
4.3 选手详情和战绩列表接口
选手详情需要关联战队名称，所以不能只查 player 表。这里返回一个 Map，或者在实体里临时增加teamName字段。初版用 Map 更轻量：
@GetMapping("/player/{id}") public Result playerDetail(@PathVariable Long id) { return Result.success(archiveService.playerDetail(id)); }战绩列表接口支持按赛事筛选：
@GetMapping("/player/{id}/records") public Result playerRecords(@PathVariable Long id, @RequestParam(required = false) Long tournamentId) { return Result.success(archiveService.playerRecords(id, tournamentId)); }查询时把 tournament 名称带出来，前端才能直接展示：
public List<Map<String, Object>> playerRecords(Long playerId, Long tournamentId) { LambdaQueryWrapper<MatchRecord> wrapper = Wrappers.lambdaQuery(); wrapper.eq(MatchRecord::getPlayerId, playerId) .eq(tournamentId != null, MatchRecord::getTournamentId, tournamentId) .orderByDesc(MatchRecord::getMatchDate); List<MatchRecord> records = matchRecordMapper.selectList(wrapper); return records.stream().map(record -> { Map<String, Object> item = new HashMap<>(); item.put("id", record.getId()); item.put("tournamentName", tournamentMapper.selectById(record.getTournamentId()).getName()); item.put("opponent", record.getOpponent()); item.put("mapName", record.getMapName()); item.put("result", record.getResult()); item.put("kills", record.getKills()); item.put("deaths", record.getDeaths()); item.put("rating", record.getRating()); item.put("adr", record.getAdr()); item.put("matchDate", record.getMatchDate()); return item; }).collect(Collectors.toList()); }这段代码有一个效率问题：每条比赛记录都要查询一次 tournament 表。数据量小的时候没问题，数据量大以后需要改成在 SQL 里 JOIN，或者用批量查询一次取出所有赛事名称。实际项目里要注意这个优化点。
4.4 聚合统计接口
聚合统计是“档案馆”最有价值的能力。这里按选手统计比赛场次、胜场、平均 Rating 和平均 ADR。
在 Mapper 里定义自定义统计方法：
package com.example.archive.mapper; import com.example.archive.dto.PlayerSummary; import org.apache.ibatis.annotations.Mapper; import org.apache.ibatis.annotations.Param; import org.apache.ibatis.annotations.Select; @Mapper public interface MatchRecordMapper extends BaseMapper<MatchRecord> { @Select("SELECT " + "COUNT(*) AS matchCount, " + "SUM(CASE WHEN result = 'W' THEN 1 ELSE 0 END) AS winCount, " + "ROUND(AVG(rating), 2) AS avgRating, " + "ROUND(AVG(adr), 1) AS avgAdr, " + "ROUND(AVG(kills), 1) AS avgKills, " + "ROUND(AVG(deaths), 1) AS avgDeaths " + "FROM match_record " + "WHERE player_id = #{playerId}") PlayerSummary selectPlayerSummary(@Param("playerId") Long playerId); }PlayerSummary 是 DTO，字段如下：
package com.example.archive.dto; import lombok.Data; import java.math.BigDecimal; @Data public class PlayerSummary { private Long matchCount; private Long winCount; private BigDecimal avgRating; private BigDecimal avgAdr; private BigDecimal avgKills; private BigDecimal avgDeaths; }注意，如果比赛记录表是空表，AVG会返回 NULL，ROUND也会返回 NULL。前端展示之前要做空值处理，或者在 SQL 里用COALESCE包一层默认值。
Controller 暴露接口：
@GetMapping("/player/{id}/summary") public Result playerSummary(@PathVariable Long id) { return Result.success(archiveService.playerSummary(id)); }Service 调用 mapper 里的自定义方法，并补充选手基本信息：
public Map<String, Object> playerSummary(Long playerId) { Player player = playerMapper.selectById(playerId); if (player == null) { throw new RuntimeException("player not found: " + playerId); } PlayerSummary summary = matchRecordMapper.selectPlayerSummary(playerId); Map<String, Object> result = new HashMap<>(); result.put("player", player); result.put("summary", summary); return result; }4.5 接口参数说明
| 接口 | 参数 | 类型 | 说明 |
|---|---|---|---|
| GET /api/archive/players | teamId | Long | 按战队筛选，可选 |
| GET /api/archive/players | position | String | 按位置筛选，可选 |
| GET /api/archive/player/{id} | id | Long | 选手 ID，必填 |
| GET /api/archive/player/{id}/records | tournamentId | Long | 按赛事筛选，可选 |
| GET /api/archive/player/{id}/summary | id | Long | 选手 ID，必填 |
统一返回结构Result在接口里承担包装角色：
public class Result { private int code; private String message; private Object data; public static Result success(Object data) { Result result = new Result(); result.code = 0; result.message = "ok"; result.data = data; return result; } public static Result error(String message) { Result result = new Result(); result.code = 500; result.message = message; return result; } }实际项目里还需要补充全局异常处理，把RuntimeException转成 JSON 错误响应，而不是直接返回 Spring Boot 默认错误页。
5. 用一个页面展示档案
5.1 页面功能设计
接口完成后，放一个轻量页面来验证数据链路。页面放在src/main/resources/static/archive.html，用原生 HTML 和 Fetch 请求接口，不需要构建工具，适合本地演示。
页面包含三块内容：
- 选手 ID 输入框和查询按钮。
- 选手基本信息展示区。
- 战绩记录表格。
5.2 HTML 和 JavaScript 实现
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>选手档案馆</title> <style> body { font-family: Arial, sans-serif; margin: 40px; } table { border-collapse: collapse; width: 100%; margin-top: 16px; } th, td { border: 1px solid #ccc; padding: 6px 10px; text-align: left; } </style> </head> <body> <h3>选手档案查询</h3> <div> <input id="playerId" type="number" value="1" placeholder="选手ID" /> <button onclick="loadData()">查询</button> </div> <h4>基本信息</h4> <pre id="playerInfo">等待查询...</pre> <h4>战绩记录</h4> <table> <thead> <tr> <th>赛事</th> <th>对手</th> <th>地图</th> <th>结果</th> <th>击杀</th> <th>死亡</th> <th>Rating</th> <th>ADR</th> </tr> </thead> <tbody id="recordsBody"></tbody> </table> <script> async function loadData() { const id = document.getElementById('playerId').value; if (!id) { alert('请输入选手 ID'); return; } await loadPlayerInfo(id); await loadRecords(id); } async function loadPlayerInfo(id) { const resp = await fetch(`/api/archive/player/${id}`); const json = await resp.json(); const info = document.getElementById('playerInfo'); if (json.code === 0) { info.textContent = JSON.stringify(json.data, null, 2); } else { info.textContent = json.message; } } async function loadRecords(id) { const resp = await fetch(`/api/archive/player/${id}/records`); const json = await resp.json(); const tbody = document.getElementById('recordsBody'); tbody.innerHTML = ''; if (json.code !== 0) { return; } json.data.forEach(item => { const tr = document.createElement('tr'); tr.innerHTML = ` <td>${item.tournamentName}</td> <td>${item.opponent}</td> <td>${item.mapName}</td> <td>${item.result}</td> <td>${item.kills}</td> <td>${item.deaths}</td> <td>${item.rating}</td> <td>${item.adr}</td> `; tbody.appendChild(tr); }); } loadData(); </script> </body> </html>这个页面没有引入任何前端框架，职责很清晰：请求接口、展示 JSON、渲染表格。好处是接口如果出错，可以直接打开浏览器开发者工具里的 Network 面板看到响应信息，排查链路更短。
5.3 启动验证步骤
- 启动 Spring Boot 应用，控制台出现 Tomcat started on port 8080 表示启动成功。
- 访问
http://localhost:8080/archive.html。 - 输入选手 ID 为 1，点击查询，页面展示 m0NESY 的档案信息。
- 页面下方按日期倒序展示比赛记录。
- 访问
http://localhost:8080/api/archive/player/1/summary，能看到聚合统计结果。
预期结果大致如下：
{ "code": 0, "message": "ok", "data": { "player": { "id": 1, "nickname": "m0NESY", "realName": "Ilya Osipov", "country": "Russia", "teamId": 1, "position": "AWPer", "joinDate": "2022-01-03" }, "summary": { "matchCount": 3, "winCount": 2, "avgRating": 1.25, "avgAdr": 83.4, "avgKills": 22.7, "avgDeaths": 16.3 } } }注意：上面的数值受演示数据决定，真正跑起来后要按自己导入的记录核对口径。Ratings 的单位、ADP 的算法在接入官方数据源前都要确认清楚。
6. 常见问题和排查链路
6.1 常见问题速查
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 启动时报表不存在 | schema.sql 未执行或执行顺序不对 | 查看 H2 控制台表是否创建成功 | 检查spring.sql.init.schema-locations路径 |
| Mapper 注入失败 | 缺少@Mapper或@MapperScan | 看启动日志中的 NoSuchBeanDefinitionException | 在 Mapper 接口加@Mapper |
| 接口返回 404 | Controller 路径写错或页面路径不对 | 查看请求 URL 是否匹配@RequestMapping | 打开 Network 面板核对请求路径 |
| 中文乱码 | 编码配置未生效 | 检查页面响应头 Content-Type | 在 yml 中配置 force 编码 |
| 日期显示 0 值 | 日期字段类型不匹配或时区不对 | 查看插入 SQL 的日期值 | 统一使用yyyy-MM-dd或 LocalDate |
| 聚合结果返回 NULL | 查询范围内没有记录 | 直接执行 SQL 检查 | 使用 COALESCE 包默认值 |
6.2 数据库连接不上
先确认 H2 文件路径是否可写。使用jdbc:h2:file:./data/archive时，data目录要存在或允许程序创建。如果上次异常退出导致文件锁，可以删除data目录后重启，但生产环境不要采用这种方式。
6.3 接口返回数据为空
分三步排查：
- 先访问
http://localhost:8080/h2-console，用 jdbc 的 url、username、password 连接，执行SELECT * FROM match_record，确认表里有没有数据。 - 再访问接口
GET /api/archive/player/1/records，确认返回值。 - 如果数据库有数据但接口为空，检查
player_id是否匹配查询参数，以及 MyBatis-Plus 下划线转驼峰配置是否生效。
6.4 表结构变更后启动失败
开发过程中经常要加字段，结果表结构变了但旧数据文件还保留旧字段，启动时容易报“列不存在”。建议开发阶段删除 H2 的data目录，让 schema.sql 重新执行。也可以使用;MODE=MySQL;DB_CLOSE_DELAY=-1等参数，但最简单的还是重置本地数据文件。
注意：这里回顾一个容易被忽略的环节：H2 的
file模式虽然方便，但配合schema.sql执行 DROP TABLE，会清空演示数据。数据导入脚本和建表脚本的建议顺序是：先备份，再重置，最后重新导入。
6.5 联调时页面和接口跨域
开发环境如果用前后端分离架构，把 Spring Boot 的接口部署在 8080，前端页面跑在 5173 或 3000，浏览器会拦截跨域请求。最简单的做法是本地把 archive.html 放到 Spring Boot 的 static 目录下，避免跨域；如果前后端彻底分离，需要配置 CORS，让接口返回Access-Control-Allow-Origin。
7. 生产环境还需要补充哪些工程能力
7.1 数据采集和更新策略
演示环境靠手工维护 SQL 没有问题，但真实系统必须把数据来源梳理清楚。选手档案的数据通常来自多个渠道：战队官方公告、赛事官方页面、第三方统计平台。接入时要注意：
- 每个数据源要记录来源和抓取时间，避免后续口径对不上。
- 选手改名、换队都必须保留历史记录，不能直接覆盖。
- 比赛记录建议采用增量同步，以比赛日期为游标，每次只拉取新增部分。
- 严禁手工在数据库里改线上数据，必须通过后台任务或管理接口修改，并保留操作日志。
7.2 性能、缓存和索引
数据量小的时候，列表接口直接查询即可。当比赛记录增长到百万行级别，至少要关注三个方向：
- 给
match_record.player_id、match_record.tournament_id、match_record.match_date建立组合索引，避免每次全表扫描。 - 选手热数据可以缓存到 Redis，缓存的 key 建议设计为
archive:player:{id}，更新选手档案时主动失效缓存。 - 列表接口必须分页，不要一次把全量记录返回给前端。Spring Boot 里可以使用 PageHelper 或 MyBatis-Plus 自带的分页插件。
7.3 权限、日志和审计
选手档案管理系统虽然看起来只是查询工具，但它涉及个人身份信息和比赛数据，生产环境要做基础安全防护：
- 查询接口区分匿名可查和管理端维护，后台修改接口要加认证和鉴权。
- 文件型数据库替换为 MySQL 等独立数据库，连接账号遵循最小权限原则。
- 记录数据导入、修改、删除操作的审计日志，至少包含操作人、时间、变更前后内容。
- 敏感字段如选手真实姓名，在对外展示时要评估是否需要脱敏。
7.4 监控与版本升级
选手数据会随着赛事进行持续更新，接口稳定性很重要。生产环境至少添加健康检查接口和基础监控：
- Spring Boot Actuator 暴露
/actuator/health，用于负载均衡健康检查。 - 对
/api/archive/player/{id}这类核心接口统计响应时间和错误率。 - 数据库连接池参数、慢 SQL 日志要提前配置，方便定位性能瓶颈。
- 架构升级时先做兼容测试，尤其注意 MyBatis-Plus 版本升级和 Spring Boot 版本之间的兼容关系。
8. 从档案管理走向数据分析
选手档案馆做到这一步，已经解决了“数据集中管理”的问题。下一步最有价值的方向，是把静态档案变成动态分析工具。
首先是可视化。当前页面只展示表格，可以引入 ECharts 等图表库，把选手多场比赛的 Rating、ADR 画成折线图，观察状态波动。评委和队伍教练在复盘时，最关心的往往不是单场结果，而是趋势。
其次是对比分析。档案馆里的数据是标准化结构，天然适合做选手对比。可以按位置的均值、胜率、ADR 等维度生成雷达图，也可以利用多赛事数据衡量选手在大赛中的稳定性。
最后是预测模型。在积累足够多比赛记录后，可以尝试用机器学习模型预测“选手在某个地图上的表现区间”。但技术不是重点，数据质量才是重点。如果比分数据、回合数据、队伍阵容这些基础信息没有做准，模型结果很难有参考意义。
回到最初的问题。科隆Major这类大赛结束后，你想查证一位选手的真实表现，最可靠的方式不是依赖评论和片段，而是有一套结构清晰、口径统一的档案数据。从四张表、一个 Spring Boot 项目、一个查询页面开始，这套系统已经能回答“这位选手在这个赛事中表现如何”“赛季平均 Rating 是多少”等问题。继续扩展的方向也很明确：接真实数据源、加图表、加对比、加监控。对初学者来说，把这个项目完整落地一遍，比只停留在看接口文档更有价值。
