# code-adventure **Repository Path**: Ken2024888/code-adventure ## Basic Information - **Project Name**: code-adventure - **Description**: code-adventure“升级打怪”式的Git项目，核心是设计一套**从简单到复杂的阶段性任务**，每个阶段对应一个“关卡”，完成后解锁新的技术挑战（类似“打怪升级”），同时用Git的分支管理、提交记录、Issues等功能跟踪进度。这类项目非常适合系统化提升编程能力，同时模拟真实项目的开发流程。 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-11 - **Last Updated**: 2025-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ##### “升级打怪”式的Git项目，核心是设计一套**从简单到复杂的阶段性任务**，每个阶段对应一个“关卡”，完成后解锁新的技术挑战（类似“打怪升级”），同时用Git的分支管理、提交记录、Issues等功能跟踪进度。这类项目非常适合系统化提升编程能力，同时模拟真实项目的开发流程。 ##### 项目名称：`code-adventure`（代码冒险） **核心目标**：从0开始，逐步构建一个支持用户闯关、积分排名的“编程练习平台”，每个阶段完善平台的一个核心功能，同时学习对应的技术点。 ##### 阶段设计（关卡+怪物+奖励） 每个阶段对应一个Git分支（如`stage-1`、`stage-2`），完成后合并到`main`分支，用Issues记录当前阶段的任务清单，用Merge Request做“闯关验收”。 ##### 🌱 阶段1：项目初始化（新手村） - **怪物（挑战）**：搭建基础项目结构，掌握Git基础操作。 ##### - **任务清单**： ##### 1. 在GitLab/Gitee创建仓库`code-adventure`，初始化README.md（说明项目目标）。 ##### 2. 用Maven/Gradle创建Java项目，添加基础目录（`src/main/java`、`src/test/java`）。 ##### 3. 编写第一个类`HelloAdventure.java`，实现打印“欢迎来到代码冒险！”。 ###### 4. 提交代码（规范提交信息：`feat: init project and hello world`），创建`stage-1`分支并推送。 ##### - **奖励（技能）**：Git基础（init/commit/push/branch）、项目结构规范。 ##### 🐢 阶段2：基础功能 - 用户注册（小怪物） - **怪物（挑战）**：实现简单的用户注册逻辑，学习面向对象和集合。 ##### - **任务清单**： ##### 1. 创建`User`类（属性：id、username、password、score），实现get/set和构造方法。 ##### 2. 创建`UserService`类，用`HashMap`存储用户数据，实现`register(username, password)`方法（校验用户名唯一）。 ##### 3. 编写测试类`UserServiceTest`，测试注册成功/失败（重复用户名）的场景。 ##### 4. 提交到`stage-2`分支，通过MR合并到`main`，用Issues关闭“实现用户注册”任务。 ##### - **奖励（技能）**：面向对象编程、集合框架（HashMap）、单元测试（JUnit）。 ##### ##### 🐇 阶段3：数据持久化 - 文件存储（中怪物） - **怪物（挑战）**：将用户数据保存到本地文件，避免程序重启后丢失，学习I/O流。 ##### - **任务清单**： ##### 1. 扩展`UserService`，新增`saveToFile()`和`loadFromFile()`方法，用JSON格式（借助`jackson`库）读写用户数据到`users.json`。 ##### 2. 处理文件不存在、JSON解析错误等异常（添加try-catch）。 ##### 3. 测试：注册用户后重启程序，验证数据是否恢复。 ##### 4. 提交时忽略`users.json`（添加到`.gitignore`），避免敏感数据提交。 ##### - **奖励（技能）**：I/O流操作、JSON处理、异常处理、`.gitignore`配置。 ##### 🐻 阶段4：数据库集成 - MySQL（大怪物） - **怪物（挑战）**：用数据库替代文件存储，学习SQL和JDBC/ORM。 ##### - **任务清单**： ##### 1. 设计`users`表（字段：id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) UNIQUE, password VARCHAR(50), score INT）。 ##### 2. 用MyBatis/MyBatis-Plus连接MySQL，实现`UserMapper`接口（CRUD操作）。 ##### 3. 改造`UserService`，用数据库操作替代HashMap和文件操作。 ##### 4. 添加数据库配置文件`application.properties`，通过GitLab/Gitea的“环境变量”存储数据库密码（避免硬编码）。 ##### - **奖励（技能）**：SQL语法、数据库设计、ORM框架、配置安全管理。 ##### 🐍 阶段5：Web接口 - 后端API（精英怪） - **怪物（挑战）**：用Spring Boot/Vert.x实现HTTP接口，让前端能调用。 ##### - **任务清单**： ##### 1. 集成Spring Boot（或Vert.x Web），创建`UserController`。 ##### 2. 实现接口： ##### - POST `/api/register`：用户注册（接收JSON参数）。 ##### - GET `/api/users`：查询所有用户（带分页）。 ##### - GET `/api/users/{id}`：查询单个用户。 ##### 3. 添加接口文档（用Swagger/OpenAPI），方便调试。 ##### 4. 用Postman测试所有接口，编写API测试用例。 ##### - **奖励（技能）**：RESTful API设计、Web框架使用、接口文档、HTTP协议。 ##### 🐉 阶段6：前端页面 - 交互界面（Boss级） - **怪物（挑战）**：开发简单前端页面，实现用户注册/查询的交互，学习前后端联动。 ##### - **任务清单**： ##### 1. 在项目中添加前端模块（用Vue/React/HTML+JS），创建注册页面（表单提交）和用户列表页。 ##### 2. 用Axios调用后端API，实现表单提交、数据展示、错误提示（如“用户名已存在”）。 ##### 3. 简单美化（用Bootstrap/Tailwind），确保移动端适配。 ##### 4. 前后端联调：解决跨域问题（后端配置CORS）。 ##### - **奖励（技能）**：前端基础、AJAX请求、跨域处理、前后端协作。 ##### 🐋 阶段7：性能与安全 - 加固系统（史诗级） - **怪物（挑战）**：优化性能并解决安全漏洞，学习缓存、加密、限流。 ##### - **任务清单**： ##### 1. 密码加密：存储时用BCrypt加密，不再明文保存。 ##### 2. 接口限流：用Redis+Spring Cloud Gateway（或Vert.x的限流组件）限制`/api/register`的请求频率（如1分钟最多10次）。 ##### 3. 缓存优化：用Redis缓存用户列表（10分钟过期），减少数据库压力。 ##### 4. 安全校验：添加请求参数校验（如用户名长度、密码强度）。 ##### - **奖励（技能）**：加密算法、缓存策略、限流机制、安全防护。 ##### 🐌 阶段8：部署与自动化 - 上线运行（最终Boss） - **怪物（挑战）**：实现自动化部署，让项目能在服务器上运行，学习CI/CD和容器化。 ##### - **任务清单**： ##### 1. 编写Dockerfile，将前后端打包成Docker镜像。 ##### 2. 在GitLab/Gitea配置CI/CD流水线（.gitlab-ci.yml或.gitea/workflow）： ##### - 触发条件：合并到`main`分支后自动构建镜像。 ##### - 步骤：编译代码→运行测试→构建镜像→推送到镜像仓库。 ##### 3. 在云服务器（如阿里云ECS）上用Docker Compose部署（包含MySQL、Redis、应用服务）。 ##### 4. 配置Nginx反向代理，实现域名访问和HTTPS。 ##### - **奖励（技能）**：Docker容器化、CI/CD流水线、云服务部署、Nginx配置。 ##### 如何用GitLab/Gitea管理这个项目？ ##### 1. **仓库初始化**：在GitLab/Gitea创建`code-adventure`仓库，添加LICENSE（如MIT）和详细的README（说明每个阶段的目标）。 ##### 2. **分支策略**： ##### - `main`：主分支，保持可运行状态，只有完成阶段任务后才合并。 ##### - `stage-n`：每个阶段一个分支（如`stage-1`到`stage-8`），在分支上开发，完成后通过MR合并到`main`。 ##### 3. **任务跟踪**：用Issues创建每个阶段的任务清单（如“阶段2：实现用户注册”），每个任务包含子任务（如“创建User类”“编写测试”），完成后勾选并关闭。 ##### 4. **代码评审**：自己作为“评审者”，在MR中检查代码是否符合阶段目标（比如测试是否通过、是否有硬编码），模拟团队协作。 ##### 5. **进度记录**：在README中添加“闯关进度”表格，记录每个阶段的完成时间和学到的技能，可视化成长过程。 ##### 为什么这样设计？ ##### - **循序渐进**：从基础语法到分布式部署，难度逐步提升，避免“一口吃成胖子”。 ##### - **实战导向**：每个阶段的功能都服务于“编程练习平台”这个核心目标，避免碎片化学习。 ##### - **Git深度融合**：通过分支、MR、Issues等功能，不仅练技术，还能掌握企业级项目管理流程。 ##### - **可扩展性**：完成8个阶段后，还能继续扩展（如添加“题目闯关”“排行榜”“社交功能”），持续“升级”。 > # Git 代码提交规范是团队协作和项目维护的重要基础，规范的提交信息能清晰传达代码变更的目的，方便后续代码审查、版本回溯和生成 CHANGELOG。目前业界最流行的是 **Conventional Commits（约定式提交）** 规范，下面详细介绍其核心内容、实践方式和工具支持。 ### 一、为什么需要提交规范？ 1. **提高可读性**：混乱的提交信息（如“fix bug”“update”）无法快速理解变更意图，规范的信息能让团队成员一眼知道“改了什么、为什么改”。 2. **便于追溯**：当需要回滚版本或定位问题时，规范的提交记录可快速筛选关键变更。 3. **自动化支持**：基于规范的提交信息，可自动生成版本日志（CHANGELOG）、语义化版本号（SemVer）等。 4. **统一团队协作**：避免因个人习惯导致的提交风格混乱，降低沟通成本。 ### 二、Conventional Commits 核心规范 提交信息的结构如下（`[]` 表示可选，`|` 表示多选）： ``` <类型>[可选 作用域]: <描述> [可选 正文] [可选 脚注] ``` #### 1. 类型（type）：必须，说明变更的性质 核心类型： - `feat`：新功能（feature），如“新增用户登录接口”。 - `fix`：修复 bug，如“修复密码加密逻辑错误”。 - `docs`：仅文档变更（如 README 更新、注释修改）。 - `style`：代码格式调整（不影响代码逻辑），如缩进、空格、分号修改（非 CSS 样式）。 - `refactor`：重构（既不是新功能也不是修复 bug，如代码结构优化、变量重命名）。 - `perf`：性能优化（如减少内存占用、提升接口响应速度）。 - `test`：新增或修改测试代码（如单元测试、集成测试）。 工程化相关类型： - `build`：构建流程/依赖变更（如 Maven/Gradle 配置修改、依赖库版本升级）。 - `ci`：CI 配置变更（如 GitLab CI、GitHub Actions 脚本修改）。 - `chore`：其他不影响源码和测试的变更（如.gitignore 调整、工具脚本修改）。 特殊类型： - `revert`：回滚之前的提交，格式一般为 `revert: <原提交信息>`，并在脚注注明原提交哈希。 #### 2. 作用域（scope）：可选，说明变更影响的范围 用于指定变更涉及的模块、组件或功能点，便于更精准地定位影响范围。 示例： - 前端：`scope` 可设为 `login`（登录模块）、`header`（头部组件）、`router`（路由）等。 - 后端：`scope` 可设为 `user`（用户模块）、`order`（订单接口）、`db`（数据库层）等。 - 工具类：`scope` 可设为 `utils`（工具函数）、`logger`（日志组件）等。 #### 3. 描述（description）：必须，简洁描述变更内容 - 长度建议不超过 50 字符，避免冗长。 - 用**现在时**（如“add”而非“added”，“fix”而非“fixed”）。 - 首字母小写，结尾不加句号。 示例： - `feat(login): add captcha verification`（新增验证码验证） - `fix(order): correct total price calculation`（修复总价计算错误） #### 4. 正文（body）：可选，详细说明变更原因和内容 - 用于补充“描述”中未说明的细节，如“为什么做这个变更”“具体实现了什么”“与之前的区别”等。 - 每行建议不超过 72 字符，换行用空行分隔。 示例： ``` feat(payment): support Alipay payment - Add Alipay SDK dependency - Implement Alipay callback handler - Update payment status synchronization logic This change allows users to pay via Alipay, which is requested in #123. ``` #### 5. 脚注（footer）：可选，用于说明突破性变更或关联 Issues - **突破性变更（Breaking Changes）**：当变更不兼容之前的版本时，必须在脚注中用 `BREAKING CHANGE:` 开头说明，如： ``` feat(api): refactor user info response structure BREAKING CHANGE: The `/api/user` endpoint now returns `userId` instead of `id`, which affects all clients using this API. ``` - **关联 Issues**：用于关闭或关联任务管理系统中的 Issue，格式为 `Closes #123` 或 `Related to #456`（支持多个，用逗号分隔），如： ``` fix(auth): resolve token expiration bug Closes #789, #901 ``` ### 三、完整示例 1. 新功能提交： ``` feat(shop): add product search by category - Add `category_id` parameter to search API - Optimize database index for category query - Update swagger doc for search interface Related to #345 ``` 2. 修复 bug 提交： ``` fix(cart): prevent adding negative quantity When user inputs negative number in quantity field, the system now defaults to 1. Closes #567 ``` 3. 回滚提交： ``` revert: feat(login): add social login This reverts commit 8a3b9c2d. ``` ### 四、最佳实践 1. **一次提交一个逻辑**：避免一次提交包含多个不相关的变更（如同时改 bug 和加功能），拆分提交更易追溯。 2. **语言统一**：团队内约定用中文或英文（建议英文，更通用），避免混合使用。 3. **避免模糊词汇**：不用“修改了一些问题”“优化了代码”等模糊描述，明确说明“改了什么问题”“优化了哪个逻辑”。 ### 五、工具辅助：强制规范并自动化 通过工具可自动校验提交信息是否符合规范，减少人工检查成本。 1. **commitlint**：检查提交信息格式是否符合规范。 - 安装：`npm install --save-dev @commitlint/cli @commitlint/config-conventional` - 配置：创建 `commitlint.config.js`，指定规则： ```js module.exports = { extends: ['@commitlint/config-conventional'] } ``` 2. **husky**：Git 钩子工具，在 `git commit` 前触发 commitlint 检查。 - 安装：`npm install --save-dev husky` - 配置：在 `package.json` 中添加： ```json { "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } } } ``` 3. **commitizen**：交互式生成符合规范的提交信息（避免手动写格式）。 - 安装：`npm install -g commitizen cz-conventional-changelog` - 配置：`echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc` - 使用：用 `git cz` 代替 `git commit`，按提示选择类型、输入描述等。 4. **standard-version**：根据提交信息自动生成 CHANGELOG 和语义化版本号。 - 运行 `npx standard-version` 会自动： - 从 `feat` 提交识别 minor 版本（如 1.0.0 → 1.1.0）。 - 从 `fix` 提交识别 patch 版本（如 1.1.0 → 1.1.1）。 - 从 `BREAKING CHANGE` 识别 major 版本（如 1.1.1 → 2.0.0）。 ### 总结 Conventional Commits 规范通过结构化的提交信息，让代码变更更清晰、可追溯，是团队协作的“基础设施”。结合工具（commitlint、husky 等）可自动化执行规范，减少人为成本。刚开始可能觉得繁琐，但长期来看能显著提升项目维护效率。