科隆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 也是一对多关系。用表格列出每个对象的重点字段便于后面建表时对齐实体建议表名核心字段用途战队teamname, region, founded_year记录战队基础信息选手playernickname, real_name, country, team_id, position, join_date记录选手档案赛事tournamentname, tier, location, start_date, end_date记录赛事基础信息比赛记录match_recordplayer_id, tournament_id, opponent, map_name, result, kills, deaths, rating, adr, match_date记录单场表现在实际项目里还可以继续增加选手转会记录、地图池、队伍阵容变动等表。对于初版系统上面四张表已经足够跑通主流程。1.3 数据粒度不要直接存一张大宽表刚开始设计的人容易把选手信息、队伍名、赛事名、每场数据都塞进一张表。这样查询是很方便但会遇到几个问题队伍改名字或选手转会后需要更新大量冗余行的数据。赛事名称重复存储很难统一维护赛事的级别和时间。新增一个选手的多个赛季数据时表会越来越宽筛选和索引也不容易设计。这里采用“事实表 维度表”的思路比赛记录是事实表战队、选手、赛事是维度表。记录里只存 ID查询时通过关联把名称带出来。这样既保持数据一致也为后续聚合统计留出空间。比赛记录的粒度建议到“选手单场”级别即一场比赛里每位选手都有一条记录包含该选手在该场比赛的击杀、死亡、助攻、Rating、ADR 等指标。如果未来要做更细的分析可以再增加“回合级”数据表但初版不需要避免模型过度设计。2. 搭建 Spring Boot 项目和基础配置2.1 技术选型说明选手档案馆不追求复杂的分布式架构重点在于快速把数据管理闭环搭建起来。技术选型以“常用、好查错、社区资料多”为首要标准。组件选择理由开发语言Java 17Spring 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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-spring-boot3-starter/artifactId version3.5.7/version /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/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;MODEMySQL;DATABASE_TO_LOWERTRUE 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模式把数据持久化到本地文件重启后数据不丢。MODEMySQL让 H2 尽量兼容 MySQL 语法后续切换数据库时改动较小。MyBatis-Plus 开启下划线转驼峰数据库字段team_id可以自动映射到实体属性teamId。spring.sql.init自动执行schema.sql方便开发环境初始化表结构。注意spring.sql.init.modealways每次启动都会执行 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 字段说明速查表表字段含义注意事项teamfounded_year战队成立年份用 INT不做日期计算时比 DATE 简单playerposition比赛位置示例值 AWPer、Rifler可按需扩展playerjoin_date加入队伍日期记录档案时用于观察转会状态tournamenttier赛事级别示例值 S-Tier、A-Tier便于筛选match_recordresult比赛结果用 W/L 短码统计胜场时方便 SUM(CASE)match_recordrating综合评分DECIMAL按赛事口径统一后再比较match_recordadr平均每回合伤害DECIMAL空值可以先填 0 或 NULL3.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会自动映射teamIdreal_name自动映射realName。其他实体类似不再重复列出。Mapper 接口继承BaseMapperT就能使用内置的 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 BaseMapperPlayer { }Team、Tournament、MatchRecord 的 Mapper 同样写法。如果不想在每个 Mapper 上都加Mapper也可以在主启动类上使用MapperScan。4.2 档案列表接口Controller 负责对外暴露 REST APIService 负责组织查询逻辑。先看列表接口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 ListPlayer listPlayers(Long teamId, String position) { LambdaQueryWrapperPlayer 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 ListMapString, Object playerRecords(Long playerId, Long tournamentId) { LambdaQueryWrapperMatchRecord wrapper Wrappers.lambdaQuery(); wrapper.eq(MatchRecord::getPlayerId, playerId) .eq(tournamentId ! null, MatchRecord::getTournamentId, tournamentId) .orderByDesc(MatchRecord::getMatchDate); ListMatchRecord records matchRecordMapper.selectList(wrapper); return records.stream().map(record - { MapString, 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 BaseMapperMatchRecord { 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会返回 NULLROUND也会返回 NULL。前端展示之前要做空值处理或者在 SQL 里用COALESCE包一层默认值。Controller 暴露接口GetMapping(/player/{id}/summary) public Result playerSummary(PathVariable Long id) { return Result.success(archiveService.playerSummary(id)); }Service 调用 mapper 里的自定义方法并补充选手基本信息public MapString, Object playerSummary(Long playerId) { Player player playerMapper.selectById(playerId); if (player null) { throw new RuntimeException(player not found: playerId); } PlayerSummary summary matchRecordMapper.selectPlayerSummary(playerId); MapString, Object result new HashMap(); result.put(player, player); result.put(summary, summary); return result; }4.5 接口参数说明接口参数类型说明GET /api/archive/playersteamIdLong按战队筛选可选GET /api/archive/playerspositionString按位置筛选可选GET /api/archive/player/{id}idLong选手 ID必填GET /api/archive/player/{id}/recordstournamentIdLong按赛事筛选可选GET /api/archive/player/{id}/summaryidLong选手 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 langzh-CN head meta charsetUTF-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 idplayerId typenumber value1 placeholder选手ID / button onclickloadData()查询/button /div h4基本信息/h4 pre idplayerInfo等待查询.../pre h4战绩记录/h4 table thead tr th赛事/th th对手/th th地图/th th结果/th th击杀/th th死亡/th thRating/th thADR/th /tr /thead tbody idrecordsBody/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接口返回 404Controller 路径写错或页面路径不对查看请求 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 重新执行。也可以使用;MODEMySQL;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 是多少”等问题。继续扩展的方向也很明确接真实数据源、加图表、加对比、加监控。对初学者来说把这个项目完整落地一遍比只停留在看接口文档更有价值。 从零搭建选手档案管理系统：Spring Boot数据建模与接口实战
科隆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 也是一对多关系。用表格列出每个对象的重点字段便于后面建表时对齐实体建议表名核心字段用途战队teamname, region, founded_year记录战队基础信息选手playernickname, real_name, country, team_id, position, join_date记录选手档案赛事tournamentname, tier, location, start_date, end_date记录赛事基础信息比赛记录match_recordplayer_id, tournament_id, opponent, map_name, result, kills, deaths, rating, adr, match_date记录单场表现在实际项目里还可以继续增加选手转会记录、地图池、队伍阵容变动等表。对于初版系统上面四张表已经足够跑通主流程。1.3 数据粒度不要直接存一张大宽表刚开始设计的人容易把选手信息、队伍名、赛事名、每场数据都塞进一张表。这样查询是很方便但会遇到几个问题队伍改名字或选手转会后需要更新大量冗余行的数据。赛事名称重复存储很难统一维护赛事的级别和时间。新增一个选手的多个赛季数据时表会越来越宽筛选和索引也不容易设计。这里采用“事实表 维度表”的思路比赛记录是事实表战队、选手、赛事是维度表。记录里只存 ID查询时通过关联把名称带出来。这样既保持数据一致也为后续聚合统计留出空间。比赛记录的粒度建议到“选手单场”级别即一场比赛里每位选手都有一条记录包含该选手在该场比赛的击杀、死亡、助攻、Rating、ADR 等指标。如果未来要做更细的分析可以再增加“回合级”数据表但初版不需要避免模型过度设计。2. 搭建 Spring Boot 项目和基础配置2.1 技术选型说明选手档案馆不追求复杂的分布式架构重点在于快速把数据管理闭环搭建起来。技术选型以“常用、好查错、社区资料多”为首要标准。组件选择理由开发语言Java 17Spring 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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-spring-boot3-starter/artifactId version3.5.7/version /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/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;MODEMySQL;DATABASE_TO_LOWERTRUE 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模式把数据持久化到本地文件重启后数据不丢。MODEMySQL让 H2 尽量兼容 MySQL 语法后续切换数据库时改动较小。MyBatis-Plus 开启下划线转驼峰数据库字段team_id可以自动映射到实体属性teamId。spring.sql.init自动执行schema.sql方便开发环境初始化表结构。注意spring.sql.init.modealways每次启动都会执行 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 字段说明速查表表字段含义注意事项teamfounded_year战队成立年份用 INT不做日期计算时比 DATE 简单playerposition比赛位置示例值 AWPer、Rifler可按需扩展playerjoin_date加入队伍日期记录档案时用于观察转会状态tournamenttier赛事级别示例值 S-Tier、A-Tier便于筛选match_recordresult比赛结果用 W/L 短码统计胜场时方便 SUM(CASE)match_recordrating综合评分DECIMAL按赛事口径统一后再比较match_recordadr平均每回合伤害DECIMAL空值可以先填 0 或 NULL3.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会自动映射teamIdreal_name自动映射realName。其他实体类似不再重复列出。Mapper 接口继承BaseMapperT就能使用内置的 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 BaseMapperPlayer { }Team、Tournament、MatchRecord 的 Mapper 同样写法。如果不想在每个 Mapper 上都加Mapper也可以在主启动类上使用MapperScan。4.2 档案列表接口Controller 负责对外暴露 REST APIService 负责组织查询逻辑。先看列表接口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 ListPlayer listPlayers(Long teamId, String position) { LambdaQueryWrapperPlayer 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 ListMapString, Object playerRecords(Long playerId, Long tournamentId) { LambdaQueryWrapperMatchRecord wrapper Wrappers.lambdaQuery(); wrapper.eq(MatchRecord::getPlayerId, playerId) .eq(tournamentId ! null, MatchRecord::getTournamentId, tournamentId) .orderByDesc(MatchRecord::getMatchDate); ListMatchRecord records matchRecordMapper.selectList(wrapper); return records.stream().map(record - { MapString, 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 BaseMapperMatchRecord { 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会返回 NULLROUND也会返回 NULL。前端展示之前要做空值处理或者在 SQL 里用COALESCE包一层默认值。Controller 暴露接口GetMapping(/player/{id}/summary) public Result playerSummary(PathVariable Long id) { return Result.success(archiveService.playerSummary(id)); }Service 调用 mapper 里的自定义方法并补充选手基本信息public MapString, Object playerSummary(Long playerId) { Player player playerMapper.selectById(playerId); if (player null) { throw new RuntimeException(player not found: playerId); } PlayerSummary summary matchRecordMapper.selectPlayerSummary(playerId); MapString, Object result new HashMap(); result.put(player, player); result.put(summary, summary); return result; }4.5 接口参数说明接口参数类型说明GET /api/archive/playersteamIdLong按战队筛选可选GET /api/archive/playerspositionString按位置筛选可选GET /api/archive/player/{id}idLong选手 ID必填GET /api/archive/player/{id}/recordstournamentIdLong按赛事筛选可选GET /api/archive/player/{id}/summaryidLong选手 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 langzh-CN head meta charsetUTF-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 idplayerId typenumber value1 placeholder选手ID / button onclickloadData()查询/button /div h4基本信息/h4 pre idplayerInfo等待查询.../pre h4战绩记录/h4 table thead tr th赛事/th th对手/th th地图/th th结果/th th击杀/th th死亡/th thRating/th thADR/th /tr /thead tbody idrecordsBody/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接口返回 404Controller 路径写错或页面路径不对查看请求 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 重新执行。也可以使用;MODEMySQL;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 是多少”等问题。继续扩展的方向也很明确接真实数据源、加图表、加对比、加监控。对初学者来说把这个项目完整落地一遍比只停留在看接口文档更有价值。