企业官网建设流程全解析

• 文档
• 教程
• 后端

「钓鱼佬」是仓库 docs/md/project/xfg-fish-pond/xfg-fish-pond.md 中讲解的一个轻量级网页游戏项目：以 SpringBoot + Redis 为技术底座，提供 Java、Python 双版本实现，通过登录、画鱼、鱼塘、钓鱼、投票、签到积分等玩法，把 Redisson 对 Redis 各类数据结构（Map、Set、String）的常用操作串联成一套完整的实战案例。读完本文，你将掌握该项目的整体玩法与启动方式，理解用户会话、积分、鱼类、钓鱼记录、投票统计、健康检查等六大模块的 Redis 存储设计，并结合仓库内大营销、AI MCP Gateway 等项目的源码，看懂 Redisson 客户端配置、IRedisService 封装与分布式场景的进阶用法。

一、项目背景与定位

在互联网应用场景中，京东、淘宝、拼多多等平台时常会看到游戏化玩法，如集卡、浇水、养动物，通过这些场景增强用户粘性、提高转化率。这些游戏化场景背后是一套套营销玩法，最终把券、积分、物品发放给用户。「钓鱼佬」网页游戏正是对这一类轻量游戏化营销场景的复刻：项目以娱乐化的方式，让学习者掌握 Redis 技术，同时可以与社群内的大营销（积分、兑换、返利、抽奖）等业务项目做微服务对接，形成流程闭环。

从仓库 docs/README.md 的项目定位看，本仓库是作者多年一线互联网 Java 开发的学习历程技术汇总，而「钓鱼佬」属于其中的轻量实战项目类型，其特点可以概括为：

• 技术栈轻量：基于 SpringBoot + Redis 实现，后端仅有一层架构，页面和后端代码都比较简单，适合作为 Redis 学习与二次开发的起点。
• 双版本实现：项目提供 Java（SpringBoot 服务端 + 前端代码）与 Python 两个版本，数据统一使用 Redis 存储。
• 可对接可扩展：项目可以与大营销（积分、兑换、返利、抽奖）对接，可以把 AI 场景接入，还可以接入小型支付完成"买卖鱼"的交易，甚至扩展"在线售卖"等玩法。

二、运行效果与核心玩法

项目整体是一个网页游戏应用，围绕"鱼"构建了完整的用户行为链路。

1. 登录

用户登录后，服务端会把用户信息写入 Redis，并维护在线用户列表。登录页是整个玩法的入口，所有后续操作（画鱼、钓鱼、投票、签到）都建立在已登录用户身份之上。

2. 画鱼

登录用户可以在画布上绘制自己的鱼（包含名称、emoji 等属性），绘制完成后将鱼投放进鱼塘。投放后，这条鱼会出现在所有登录用户可见的公共鱼塘中，其他用户可以看到、投票，甚至"钓走"。

3. 鱼塘

鱼塘页面可以看到所有登录用户投放进来的鱼，还可以钓鱼。钓鱼有一定概率把别人的鱼钓到自己的鱼篓里。钓鱼需要消耗积分，积分通过每日签到获取。此外页面中还内置了一些问题话术和"救赎时间"（上班摸鱼等于救赎自己）等趣味设计，增加娱乐性。

4. 居民

在"鱼塘居民"页面下，可以看到各个伙伴画的鱼，并可以对每条鱼点一个"喜欢"或"不喜欢"，形成投票数据。

三、工程结构与项目启动

1. 工程代码

项目代码由以下部分组成：

• 前端代码：负责登录、画鱼、鱼塘、居民等页面展示与交互；
• SpringBoot 服务端代码（xfg-fish-pond-app）：提供全部业务接口；
• Python 版本代码：同一套玩法的另一种实现。

服务端通过redisService统一操作 Redis，从调用形式看，这是对 Redisson 客户端的轻量封装——这与仓库 docs/md/road-map/redis.md 中"使用 Redisson 框架处理 Redis 调用"的思路一致。

2. 环境与启动配置

启动前，需要在xfg-fish-pond-app模块下的resources/application-dev.yml中配置 Redis 连接信息，核心配置项如下：

spring: redis: host: localhost # Redis 地址 port: 6379 # Redis 端口 password: 123456 # Redis 密码，按实际环境填写 # 连接池、超时等参数可按需补充

配置完成后启动项目，点击打开页面即可访问。仓库 docs/md/road-map/redis.md 中给出了一套更完整的 Redisson 自定义连接配置参考，包含pool-size（连接池大小）、min-idle-size（最小空闲连接数）、idle-timeout、connect-timeout（连接超时）、retry-attempts（重试次数）、retry-interval（重试间隔）、ping-interval、keep-alive等参数，可作为本项目连接参数调优的参考。

3. Docker 部署

如果要部署到云服务器，可以通过 Docker 构建镜像完成部署，这与仓库内其他项目的云部署方式一致（可参考 Docker 部署 等相关文档）。

四、Redis 技术实战：六大 Controller 逐一拆解

本套项目的数据存储全部基于 Redis 实现，是学习 Redis 应用技术的最佳素材。以下六大模块的代码全部来自原文档，建议对照源码逐行阅读。

1. 用户会话管理（UserController）

登录时存储用户信息：

RMap<String, String> userMap = redisService.getMap(userKey); userMap.put("userId", userId); userMap.put("username", username); userMap.put("loginTime", LocalDateTime.now().toString()); userMap.expire(86400, TimeUnit.SECONDS); // 24小时过期

这里使用 Redis 的 Hash 结构（Redisson 的RMap）保存单个用户的多字段信息，并通过expire设置 24 小时过期，实现会话的自动失效。相比字符串拼接序列化，Hash 结构便于对单个字段做读写和局部更新。

用户列表管理：

redisService.addSetMember(USER_LIST_KEY, userId); // 添加到在线用户列表 redisService.removeSetMember(USER_LIST_KEY, userId); // 从在线用户列表移除

在线用户列表使用 Redis 的 Set 结构（对应 Redisson 的RSet）：Set 天然去重，addSetMember/removeSetMember对应 SADD/SREM，可以低成本维护一个"当前在线用户"的集合，供鱼塘、居民等页面展示使用。

2. 积分系统（PointsController）

积分存储和操作：

// 获取用户积分 int points = Integer.parseInt(pointsMap.getOrDefault("points", "0")); // 更新积分 pointsMap.put("points", String.valueOf(newPoints)); pointsMap.put("lastUpdated", LocalDateTime.now().toString());

用户积分同样以 Hash 结构存储，points字段记录积分余额，lastUpdated记录最近更新时间。读取时用getOrDefault避免首次访问空指针。

签到记录：

String today = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd")); RMap<String, String> signMap = redisService.getMap(signKey); signMap.put(today, LocalDateTime.now().toString());

签到以"日期"为 key 写入 Hash，天然保证一天只能签一次（重复写同一天的 key 只是覆盖时间戳，可用作签到去重校验的依据），钓鱼所需的积分就来自每日签到。

积分变动记录：

String recordValue = points + "|" + type + "|" + reason + "|" + LocalDateTime.now().toString(); recordsMap.put(recordId, recordValue);

积分流水采用"管道符拼接"的紧凑格式（积分|类型|原因|时间），每条流水以recordId为 key 存入 Hash。这种"以字符串拼接换空间、以 Hash 分片存明细"的做法，是轻量项目记录审计日志的常见手法。

3. 鱼类管理（FishController）

添加鱼到池塘：

RMap<String, String> fishMap = redisService.getMap(fishKey); fishMap.put("name", fishName); fishMap.put("emoji", emoji); fishMap.put("userId", userId); fishMap.put("createTime", LocalDateTime.now().toString()); // 添加到鱼类列表 redisService.addSetMember(FISH_LIST_KEY, fishId);

每条鱼以fishId对应的 Hash 保存属性（名称、emoji、所属用户、创建时间），同时把fishId加入全局 Set（FISH_LIST_KEY），用于鱼塘页面的全量遍历。Hash + Set 的组合解决了"单条鱼的属性读写"与"所有鱼的列表枚举"两个诉求。

4. 钓鱼系统（FishingController）

钓鱼记录：

String recordValue = success + "|" + fishEmoji + "|" + fishName + "|" + fishRarity + "|" + LocalDateTime.now().toString() + "|" + transferred + "|" + originalOwner + "|" + fishId; recordsMap.put(recordId, recordValue);

钓鱼结果被记录为一条完整流水：是否成功（success）、鱼的 emoji 与名称、稀有度（fishRarity）、时间、是否转移（transferred）、原主人（originalOwner）、鱼 ID。transferred与originalOwner字段支撑了"把别人的鱼钓到自己鱼篓"这一核心玩法：鱼的所有权发生了转移，原主人信息被保留在记录中。

鱼篓管理：

String fishValue = emoji + "|" + name + "|" + rarity + "|" + LocalDateTime.now().toString() + "|" + originalFishId + "|" + image; basketMap.put(fishId, fishValue);

钓到的鱼写入个人鱼篓（basketMap），保留鱼的完整展示信息，并记录originalFishId追溯来源。至此，鱼的流转路径完整覆盖：画鱼（FishController 入库）→ 鱼塘展示（FISH_LIST_KEY）→ 钓鱼转移（FishingController 记录 + 鱼篓落库）。

5. 投票系统（VoteController）

用户投票记录：

RMap<String, String> userVotesMap = redisService.getMap(userVotesKey); userVotesMap.put(fishId, voteType); // "like" 或 "dislike"

以用户为维度记录其对各条鱼的投票（key 为 fishId，值为 "like"/"dislike"），后续可通过检查该 Map 判断用户是否已对某条鱼投票，实现一人一票。

投票统计：

fishVotesMap.put("likes", String.valueOf(currentLikes)); fishVotesMap.put("dislikes", String.valueOf(currentDislikes)); fishVotesMap.put("score", String.valueOf(currentLikes - currentDislikes));

以鱼为维度聚合投票统计：likes、dislikes分别累计，score作为净得分（喜欢数 - 不喜欢数），用于居民页面的排序与展示。这里体现了 Redis Hash 做计数器聚合的典型用法——先读旧值、再写新值，轻量且直观。

6. 系统监控（SystemController）

Redis 健康检查：

// 设置测试值 redisService.setValue("health_check", "ok"); // 读取测试值 String value = redisService.getValue("health_check"); // 删除测试值 redisService.remove("health_check"); // 获取用户总数 Map<String, String> userList = redisService.getMapAll("user_list");

健康检查使用 Redis String 结构完成"写入 → 读取 → 删除"的探活闭环，验证 Redis 服务的连通性与读写能力；同时通过getMapAll读取用户列表，获取在线用户总数，把"监控"与"业务数据"结合在了一起。

五、源码级延伸：Redisson 在仓库中的设计范式

「钓鱼佬」项目把 Redis 玩法的覆盖面做得非常全（Map、Set、String 一应俱全），但它只是仓库 Redis 技术体系中的一环。结合仓库内其他项目的源码，可以更完整地理解这套 Redisson 使用范式。

1. Redisson 客户端配置与统一服务封装

在仓库的 Redis 学习路线文档 中，Redisson 客户端通过RedisClientConfigProperties配置类 +RedisClientConfig启动类创建，配置项覆盖 host、port、password、连接池、超时、重试、心跳等；而 AI MCP Gateway 分布式 Redis 设计 一节进一步说明：工程在 app 模块 config 包下新增RedisClientConfig和RedisClientConfigProperties创建 Redisson 客户端 Bean，并在 infrastructure 层提供IRedisService接口与RedissonService实现类，覆盖键值操作、队列、集合、Map、锁、信号量、布隆过滤器、发布订阅等几乎全部 Redis 数据结构操作。「钓鱼佬」代码中的redisService.getMap、addSetMember、setValue等调用，正是这类统一服务封装的使用方式——它让业务代码不直接依赖 Redisson API，便于统一扩展与替换。

2. 从 Map/Set/String 到锁、发布订阅的进阶

• Hash（RMap）：在本项目用于用户信息、积分、鱼属性、投票统计等多字段对象，是"轻量实体"的首选结构；
• Set（RSet）：在本项目用于在线用户列表、鱼类列表，承担去重与全量枚举；
• String：在本项目用于健康检查，在 大营销不超卖库存规则实现 中则用于decr原子扣减库存——文档明确说明"decr 是原子操作，效率非常高"，且"不要用一条 key 加锁和等待释放的方式来处理，要尽可能考虑分摊竞争，达到无锁化"；
• 锁与发布/订阅：仓库 Redis 学习路线文档 展示了独占锁（RLock lock = redissonService.getLock("create_order_lock_" + sku)）、分段锁/无锁化（按sku_decrCount拆分锁 key）以及自定义@RedisTopic注解动态注入RTopicBean 的发布/订阅高级玩法。

3. 与营销系统对接的扩展思路

原文档明确说明，本项目可以与大营销的积分、兑换、返利、抽奖做微服务对接，也可以接入 AI 场景或小型支付实现"买卖鱼"交易。这种对接思路与仓库中 大营销平台系统 的玩法一致：营销平台把券、积分、物品发放给用户，而「钓鱼佬」的签到积分、鱼篓资产可以作为营销活动的用户侧载体——例如用积分兑换抽奖机会、用鱼作为可交易资产等，把娱乐玩法与营销转化串成闭环。

六、扩展玩法与二次开发

原文档提供了清晰的扩展方向：

• 在线售卖：已有伙伴建议让鱼支持在线售卖，可在此基础上扩展交易模块（可结合小型支付组件实现买卖双方的积分/资金流转）；
• AI 辅助开发：页面和后端代码都比较简单、后端仅有一层架构，可以自己实现扩展，也可以使用 trae.ai、Cursor 等 AI 工具辅助开发；
• 玩法叠加：增加鱼的稀有度概率、钓鱼成功率、签到奖励梯度、排行榜等，都能在现有 Hash/Set/String 结构上低成本演进。

总而言之，这套「钓鱼佬」项目以游戏化场景为载体，把 Redisson 操作 Redis 的核心数据结构（Map、Set、String）融入真实的用户行为链路中，配合仓库内 Redis 学习路线文档中的连接池配置、分布式锁、发布/订阅等进阶内容，构成了一个从入门到进阶、从单体玩法到分布式对接的完整 Redis 实战学习路径。

• 文档
• 教程
• 后端