GreedyAbyss前几天有个朋友问我，能不能用 Spring Boot 给《逃跑吧！少年》这类游戏做一个介绍系统。不是一张静态页面丢上去的官网，而是运营人员能自己维护角色资料、地图玩法、公告资讯，玩家端实时刷新的那种内容系统。我第一反应是：这个需求太典型了。游戏介绍系统表面看是个展示站，本质上是典型的内容管理加前台展示，只不过业务字段带了很多游戏特有的东西，比如技能描述、地图难度、版本上下线状态。整套东西用 Spring Boot 实现，比想象中简单，但坑也不少。这篇把从零搭建到部署的完整设计思路写出来，给正在做游戏资讯站、介绍页、攻略系统的同学一个参考。
整个项目的落地路径我拆成六块：先讲需求边界，再讲工程搭建，然后是数据模型和核心接口，最后聊联调和部署。每一部分都配合实际踩过的坑，尽量让读者可以直接照着做。
1. 为什么给《逃跑吧！少年》做介绍系统：需求边界与功能拆分
1.1 介绍系统不等于静态官网
很多游戏项目早期只放一个静态介绍页，页面是前端写死的，运营想改一句角色描述都要提工单找开发。项目一多，这种模式就完全扛不住了。介绍系统的核心价值，是让非技术人员也能管理内容。
我当时给这个项目定义的目标有三个：一是玩家能通过系统快速了解《逃跑吧！少年》的角色、地图和玩法；二是运营能在后台维护这些内容，包括新增角色、调整排序、上下架公告；三是系统能记录内容变更和访问情况，方便后续做数据分析。
这三点明确之后，功能范围就清楚了，不需要做社区、评论、充值这些和介绍无关的东西。介绍系统的核心是“内容展示”和“内容管理”，做得再大，也只是一个垂直的内容站点。
1.2 功能模块怎么拆
我按使用角色把系统分成了三个端：
- 前台展示端：首页轮播、角色列表、角色详情、地图介绍、玩法说明、公告列表。这个端面向玩家，要求响应快、接口稳定。
- 后台管理端：登录认证、内容管理、文件上传、排序、上下架操作。这个端面向运营，要求操作顺手、权限清晰。
- 系统支撑端：统一异常处理、接口文档、访问日志、缓存、配置管理。这个端是给开发自己用的，但决定了系统能跑多稳。
前台和后台我建议从接口层面就分开，不要混在同一个 Controller 里。比如 api/v1/roles 是玩家端接口，admin/api/v1/roles 是管理端接口。后面做权限控制的时候，只需要按路径拦截，逻辑非常清晰。
1.3 技术选型思路
项目最终选了 Spring Boot 2.7.18 + MyBatis-Plus + Redis + JWT + Vue。这套组合在现在的游戏内容站里很常见，每个选型都有具体原因：
- Spring Boot 负责整体服务端框架，约定大于配置，适合快速搭建后台接口。
- MyBatis-Plus 负责数据库操作，内置分页和逻辑删除，能省掉不少模板代码。
- Redis 做热点缓存，角色列表、公告这些高频读取的数据直接放缓存。
- JWT 做后台管理端的登录态，无状态，方便前端和后端分离部署。
- Vue 负责前台和管理端页面，前后端完全分离，开发阶段可以并行。
这个选型不是追求最新，而是追求稳妥。游戏介绍系统没有特别复杂的计算，核心是清晰的数据结构和稳定的接口，不是炫技的地方。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 初始工程搭建：Spring Boot版本选型、Banner与配置文件的那些坑
2.1 版本不是越高越好，先看JDK再决定
我第一次搭这个项目时，直接选了当时最新的 Spring Boot 3.x，结果还没写代码就发现问题：Spring Boot 3 要求 JDK 17，而很多公司的服务器和内部依赖还停留在 JDK 1.8。项目组也不可能为了一个新项目立刻升级所有基础组件。
所以最后退回 Spring Boot 2.7.18。这个版本是 2.x 的收尾版本，维护周期长，兼容 JDK 1.8，生态最成熟。选择它还有一个原因：2.x 使用的是 javax.* 包，而 3.x 换成了 jakarta.*，如果项目里依赖了老版本的第三方库，直接用 3.x 会遇到大量的编译报错。
这里要提醒一句：Spring Boot 版本并不是越新越好。选型之前先确认 JDK 版本、中间件版本、团队熟悉度，再决定主版本。版本太高导致依赖冲突，往往是项目刚开始最浪费时间的问题。
2.2 IDEA 初始化工程和自定义 Banner
我用 IDEA 的 Spring Initializr 创建工程，Java 版本选 8，依赖勾选了 Web、MyBatis-Plus、Redis、Lombok、Validation、MySQL。这里有个小细节：IDEA 自带的 Initializr 默认会拉取 Spring 官方模板，网络慢的时候容易卡住，可以直接用阿里云的 Initializr 地址，速度会快很多。
工程创建完之后，可以在 src/main/resources 下放一个 banner.txt，启动时会显示自定义 Banner。网上有在线 Banner 生成器，把“逃跑吧少年”打成 ASCII Art 放进去，团队里看着也直观。Banner 不影响功能，但能让项目有个辨识度，几百行代码之前先确定这个是哪个环境、哪个项目，排查问题能少犯迷糊。
2.3 application.yml 和配置文件的拆分
很多教程只写一个 application.yml，但实际项目一定要拆环境。我习惯拆四个文件：
application.yml：公共配置application-dev.yml：开发环境application-test.yml：测试环境application-prod.yml：生产环境
公共配置里放端口、项目名、Jackson 配置等；环境配置里放数据源、Redis、文件路径。比如开发环境连本地库，生产环境连云数据库。用 spring.profiles.active=dev 切换。
启动时指定环境：
bash复制java -jar game-intro-system.jar --spring.profiles.active=prod
数据库连接配置我建议把敏感信息放到环境变量里，不要直接写死在 yml。比如：
yaml复制spring:
datasource:
url: jdbc:mysql://${DB_HOST}:3306/game_intro?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
username: ${DB_USERNAME}
password: ${DB_PASSWORD}
这种做法在打包部署之后特别重要，尤其是代码要提交到 Git 仓库的时候，避免把账号密码带进历史记录。
2.4 自动装配原理帮我排查启动问题
Spring Boot 最核心的机制是自动装配。@SpringBootApplication 实际上是由 @SpringBootConfiguration、@EnableAutoConfiguration 和 @ComponentScan 组合而成的。@EnableAutoConfiguration 会加载 META-INF/spring.factories 或 AutoConfiguration.imports 里注册的自动配置类，根据条件注解决定是否生效。
这句话听起来抽象，但理解之后排查问题非常有用。比如项目引入 Redis 之后没配置连接地址，启动不会报错，只有调用 Redis 操作时才会报客户端连不上。原因就是 Spring Boot 的自动配置类 RedisAutoConfiguration 在生效，只是等待连接被使用。再比如数据源配置错误，启动会直接失败，因为 DataSourceAutoConfiguration 初始化时就需要建立连接。
碰到 Bean 找不到的问题，先看自动配置类是否被条件注解拦掉了。用 IDEA 的自动配置报告功能，启动时加上 --debug，控制台会打印哪些配置类生效、哪些没生效，排查效率高很多。
3. 游戏内容的数据模型：角色、地图、攻略要怎么落表
3.1 先识别核心实体再建表
《逃跑吧！少年》的介绍内容整理下来，核心实体其实就那么几个：游戏角色、地图、玩法模式、资讯公告、攻略文章。每个实体之间尽量独立，不要为了省事搞成大宽表。
我当时设计了这几张核心表：
game_role：角色表，存储角色名称、头像、描述、技能说明、定位分类等。game_map：地图表，存储地图名称、封面图、地形描述、玩法说明。game_mode：玩法模式表，存储模式名称、规则、参与人数。game_article：资讯/攻略表，存储文章标题、正文、封面、类型、发布时间。admin_user：后台管理员表。
实体之间通过外键或 type 字段关联。比如角色表里的 skill_json 字段可以存技能列表，用 JSON 格式；地图表里的 mode_ids 可以存关联玩法模式的 ID 列表。游戏介绍场景里，关联关系并不复杂，不用过度设计。
3.2 状态、版本和上下架设计
内容类系统一定要有状态字段。我用 status 表示内容状态，0 草稿、1 已发布、2 已下线。运营在后台编辑完先存草稿，审核通过后再发布。
为了提高数据可靠性，我还会加一个 version 字段做乐观锁。编辑内容的时候，前端把当前版本号一起提交，后端通过 UPDATE ... SET version = version + 1 WHERE id = ? AND version = ? 来更新，影响行数为 0 就说明内容被其他人改过，提示用户重新加载。这个做法能避免两个运营同时编辑同一篇公告导致互相覆盖。
内容表还需要一个 publish_time 字段，用来支持定时发布。比如公告想周五上午十点上线，运营设置好发布时间，用 Spring 的定时任务每分钟扫描一次，把到时间的草稿改为发布状态。
3.3 建表 SQL 示例
以角色表为例，建表语句大致如下：
sql复制CREATE TABLE `game_role` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`name` varchar(64) NOT NULL COMMENT '角色名称',
`avatar_url` varchar(255) DEFAULT NULL COMMENT '角色头像',
`title` varchar(128) DEFAULT NULL COMMENT '角色称号',
`description` text COMMENT '角色描述',
`skill_json` text COMMENT '技能描述JSON',
`role_type` tinyint(4) DEFAULT 0 COMMENT '角色类型：0主角 1反派 2中立',
`status` tinyint(4) DEFAULT 0 COMMENT '状态：0草稿 1已发布 2已下线',
`sort_order` int(11) DEFAULT 0 COMMENT '排序值',
`version` int(11) DEFAULT 0 COMMENT '乐观锁版本号',
`create_time` datetime DEFAULT CURRENT_TIMESTAMP,
`update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
KEY `idx_role_type_status` (`role_type`, `status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='游戏角色表';
这里要特别注意 utf8mb4，很多老项目用 utf8，存颜文字和部分生僻字会出问题。游戏介绍内容经常有特殊符号，utf8mb4 是底线。
3.4 MyBatis-Plus 还是 Spring Data JPA
这两个方案我都在项目里用过。JPA 的自动建表和 Repository 很省事，但复杂查询需要写 JPQL 或 Specification，团队不熟的话反而更费劲。MyBatis-Plus 和 MyBatis 一脉相承，SQL 是显式写的，排查问题直接看 XML 或注解就知道查了什么，配合内置的 QueryWrapper 和小分页插件，做内容管理系统非常顺手。
选 MyBatis-Plus 还有一个原因：它提供了逻辑删除、自动填充、乐观锁插件，正好对应内容系统的刚需。比如插入记录时自动填充 create_time、update_time，用 @TableField(fill = FieldFill.INSERT) 加上元对象处理器就能实现，不用每个实体类手动 set。
4. 接口层实现：资源映射、缓存、文件上传与事务的实战细节
4.1 RESTful 接口路径设计与 Controller 实现
接口路径我按资源名来设计，不用动词。前台接口统一走 /api/v1/，管理端接口统一走 /admin/api/v1/。比如：
GET /api/v1/roles：获取角色列表GET /api/v1/roles/{id}：获取角色详情GET /api/v1/maps：获取地图列表GET /api/v1/articles?type=notice：获取公告/攻略列表POST /admin/api/v1/roles：新增角色PUT /admin/api/v1/roles/{id}：更新角色DELETE /admin/api/v1/roles/{id}：删除角色
Controller 尽量只做参数接收和结果封装，业务逻辑放到 Service 层。一个简单的前台角色列表接口大概长这样：
java复制@RestController
@RequestMapping("/api/v1/roles")
public class RoleController {
@Autowired
private RoleService roleService;
@GetMapping
public Result<List<RoleVO>> list(@RequestParam(defaultValue = "1") Integer page,
@RequestParam(defaultValue = "10") Integer size) {
return Result.ok(roleService.listPublishedRoles(page, size));
}
@GetMapping("/{id}")
public Result<RoleVO> detail(@PathVariable Long id) {
return Result.ok(roleService.getPublishedRoleById(id));
}
}
统一返回结构 Result 里的 code、message、data 三个字段，前后端约定好错误码范围，后面接 Vue 的时候能省掉很多沟通成本。
4.2 自定义过滤器实现访问日志和请求追踪
Spring Boot 里实现统一的访问日志，我推荐用 OncePerRequestFilter 写过滤器，而不是拦截器。过滤器比拦截器更早进入 Servlet 链路，可以记录完整的请求与响应时间，也能在入口处生成一个 requestId 放进日志框架的 MDC，方便追踪一次请求经过的所有日志。
过滤器的核心代码：
java复制@Component
public class AccessLogFilter extends OncePerRequestFilter {
private static final Logger log = LoggerFactory.getLogger(AccessLogFilter.class);
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
long start = System.currentTimeMillis();
String requestId = UUID.randomUUID().toString().replace("-", "");
MDC.put("requestId", requestId);
try {
filterChain.doFilter(request, response);
} finally {
long cost = System.currentTimeMillis() - start;
log.info("requestId={}, method={}, uri={}, cost={}ms",
requestId, request.getMethod(), request.getRequestURI(), cost);
MDC.remove("requestId");
}
}
}
注意 MDC.remove 一定要放在 finally 里，否则线程池复用线程时，MDC 里的旧数据会被下一个请求读到，日志就串了。
4.3 用 Redis 缓存热点介绍数据
游戏介绍系统的数据读多写少，角色列表和首页公告适合做缓存。我直接用 Spring Cache 抽象，代码层面最简洁：
java复制@Service
public class RoleService {
@Cacheable(cacheNames = "role:list", key = "#page + ':' + #size")
public List<RoleVO> listPublishedRoles(Integer page, Integer size) {
// 查询数据库并返回
}
@CacheEvict(cacheNames = "role:list", allEntries = true)
public void updateRole(Role role) {
// 更新角色数据
}
}
用 @Cacheable 之后，同一个 key 的请求会直接命中 Redis，不会再压到数据库。后台更新角色时，用 @CacheEvict 清空缓存，保证玩家端能看到最新内容。
这里有个坑：@Cacheable 注解默认基于 Spring AOP，只有通过代理对象调用时才生效。如果在同一个类内部调用 listPublishedRoles，注解会失效。所以缓存逻辑和业务逻辑最好拆到不同方法，或者直接从外部 Controller 调用 Service 方法。
4.4 大文件上传下载与本地资源映射
游戏介绍系统里少不了封面图、视频预告这些大文件。Spring Boot 默认上传大小只有 1MB，直接传大图会报错，需要手动调大：
yaml复制spring:
servlet:
multipart:
max-file-size: 100MB
max-request-size: 200MB
文件上传后不能直接放在项目根目录，因为重新打包会丢，建议放到独立目录，比如 /data/game-intro/upload/。然后通过 WebMvcConfigurer 把 URL 映射到本地目录：
java复制@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/files/**")
.addResourceLocations("file:/data/game-intro/upload/");
}
}
这样玩家端可以通过 https://api.example.com/files/role-001.png 直接访问静态资源。所有图片、视频上传接口返回相对路径 /files/xxx.png，前端拼上域名就能用。
如果文件真的特别大，比如单个视频超过 500MB，就需要考虑分片上传。前端把文件切成多个块，后端用临时目录保存分片，全部传完后合并。这个方案能支持断点续传，但复杂度会高很多，前期不用急着做。
4.5 事务失效的几个经典场景
内容管理系统里，保存一篇文章往往要同时更新文章表和全文搜索索引表，事务是必需的。但事务失效的坑非常多，我在这个项目里就遇到过：
- 同一个类内部调用
@Transactional方法，事务不生效。 - 私有方法加
@Transactional，事务不生效。 - 方法内部 catch 了异常，没有往上抛，事务回滚不了。
- 数据库引擎是 MyISAM，不支持事务，但 MyISAM 很少见，用 InnoDB 即可。
正确做法是把方法设为 public，并且从外部对象调用。如果必须在同类内部调用，可以注入自身代理，也可以用 TransactionTemplate 手动控制事务：
java复制@Service
public class ArticleService {
@Autowired
private TransactionTemplate transactionTemplate;
public void publishArticle(Long id, String content) {
transactionTemplate.execute(status -> {
try {
articleMapper.updateContent(id, content);
articleMapper.updateStatus(id, 1);
return true;
} catch (Exception e) {
status.setRollbackOnly();
throw e;
}
});
}
}
TransactionTemplate 的优点是事务边界完全可控，也不存在代理调用失效的问题，适合内部逻辑复杂的方法。
5. 前后端分离联调：Vue项目、JWT和Swagger如何和平共处
5.1 跨域配置是第一个拦路虎
前端用 Vue 跑在 http://localhost:5173，后端接口在 http://localhost:8080，浏览器直接请求会被跨域拦截。开发环境最简单的办法是用 Vite 的代理，把 /api 转发到后端。如果要后端直接支持跨域，可以写一个 CORS 配置：
java复制@Configuration
public class CorsConfig implements WebMvcConfigurer {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
.allowedOriginPatterns("*")
.allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
.allowedHeaders("*")
.allowCredentials(true)
.maxAge(3600);
}
}
这里有个小坑：allowCredentials(true) 的时候，allowedOrigins 不能写 *，要用 allowedOriginPatterns("*")。否则容器启动时会报 When allowCredentials is true, allowedOrigins cannot contain the special value "*"。
5.2 JWT 认证与 Swagger 放行
后台管理接口不能裸奔，我用了 JWT 做登录认证。登录成功后签发一个 token，前端把 token 放在请求头 Authorization 里。后端在拦截器里校验 token，取到管理员 ID 后放进请求上下文。
但加完拦截器之后，Swagger 页面的访问也被拦截了。联调的时候最烦这个问题。正确做法是配置拦截器时把 Swagger 相关路径全部放行：
java复制@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(jwtInterceptor)
.addPathPatterns("/admin/api/**")
.excludePathPatterns("/admin/api/v1/login")
.excludePathPatterns("/swagger-ui/**", "/v3/api-docs/**", "/doc.html");
}
Swagger 我用的是 Knife4j，界面比原生 Swagger UI 好看，接口调试也方便。加了拦截器之后一定要记得把 /doc.html 放行，很多项目就漏了这一个路径，导致前端同学打不开文档。
5.3 Long 类型精度丢失和字段命名
前后端联调时有个很容易忽略的问题：数据库主键是 Long 类型，如果值超过 JavaScript 的 Number.MAX_SAFE_INTEGER，前端拿到的数值会精度丢失。解决办法是在后端给 Long 字段加序列化注解，转成字符串给前端：
java复制public class RoleVO {
@JsonSerialize(using = ToStringSerializer.class)
private Long id;
private String name;
// ...
}
字段命名方面，后端建议统一用驼峰命名，前端用驼峰解析 JSON，默认就是匹配的，不需要额外改。
5.4 循环依赖的处理
如果项目采用构造器注入，Spring Boot 2.6 之后默认不允许循环依赖，启动直接报错。我之前写代码时不小心让 ArticleService 注入了 RoleService，而 RoleService 又注入了 ArticleService，结果启动失败。
解决循环依赖的思路不是打开开关，而是从设计上拆开。把两个类都依赖的公共逻辑抽到第三个 Service 里，或者用 @Lazy 延迟其中一个注入。推荐第一种，因为循环依赖本身是个设计坏味道，能用重构解决就不要靠框架兜底。
6. 测试、打包与Docker部署：从IDEA到Docker Desktop的经历
6.1 单元测试不要只测个寂寞
Spring Boot 项目里的单元测试，很多人只写一个 contextLoads() 验证上下文能启动，这远远不够。至少要把核心接口的 Controller 层测试补上，用 MockMvc 模拟请求：
java复制@SpringBootTest
@AutoConfigureMockMvc
class RoleControllerTest {
@Autowired
private MockMvc mockMvc;
@Test
void listRoles_shouldReturnOk() throws Exception {
mockMvc.perform(MockMvcRequestBuilders.get("/api/v1/roles")
.param("page", "1")
.param("size", "10"))
.andExpect(MockMvcResultMatchers.status().isOk())
.andExpect(MockMvcResultMatchers.jsonPath("$.code").value(0));
}
}
测试数据库尽量用 H2 或测试库，不要依赖开发库里的脏数据。Service 层测试可以用 Mockito 把 Mapper 打桩，专注测业务逻辑分支，比如角色状态为草稿时，前台接口不应该返回。
6.2 JDK 1.8 项目打包到 Docker Desktop
这个项目最终要跑在 Docker 里。由于项目基于 JDK 1.8，Dockerfile 基础镜像要选择 OpenJDK 8：
dockerfile复制FROM openjdk:8-jre-alpine
COPY target/game-intro-system.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar", "--spring.profiles.active=prod"]
构建镜像：
bash复制mvn clean package -DskipTests
docker build -t game-intro-system:1.0.0 .
docker run -d --name game-intro -p 8080:8080 \
-e DB_HOST=192.168.1.10 \
-e DB_USERNAME=game \
-e DB_PASSWORD=password \
game-intro-system:1.0.0
在 Docker Desktop 上跑有两个常见的坑：一是容器内存默认给得不大，Spring Boot 启动时如果报 OOM，打开 Docker Desktop 的 Settings，把 Memory 调到 4GB 以上；二是容器内访问宿主机数据库时，不能用 localhost，要用 host.docker.internal。这两个问题不解决，项目在本地跑得好好的，一到 Docker 里就各种奇怪。
6.3 上线后的配置外部化和日志
部署之后最担心的是配置改不了。我把数据库密码、Redis 地址、文件路径全部放到环境变量里，Spring Boot 的 yml 用 ${ENV_NAME} 读取，这样运维不需要重新打镜像，只需要在 Docker 启动命令里加 -e 参数。
日志一定要输出到容器外部目录，否则容器一删日志全没了。Docker 启动时加：
bash复制-v /data/logs/game-intro:/logs
然后在 application.yml 里配置：
yaml复制logging:
file:
name: /logs/game-intro.log
最后再把 Spring Boot Actuator 的 /actuator/health 暴露出来，配合 Docker 的健康检查，能及时发现服务宕机。
这套系统做完以后，我最大的体会是：游戏介绍类项目真正花时间的不是 Spring Boot 的代码，而是内容结构和状态流转的设计。把角色、地图、文章这些实体梳理清楚，把状态和缓存边界定好，剩下的 Controller、Service 基本就是重复劳动。另外，开发阶段一定要把测试和 Docker 部署流程提前跑通，越早暴露环境问题，后面联调就越省心。如果后续要把系统扩展成完整的游戏资料站，我建议可以在现有基础上增加标签系统、搜索关键字、操作审计和定时发布任务，这些模块的接口设计思维和这个项目完全一致，直接往里面加表和服务就可以了。