# 🚀 结伴客开发指南 ## 📋 项目概述 结伴客是一个创新的社交旅行平台,融合了结伴旅行和动物认领功能。本开发指南为开发者提供完整的开发环境搭建、代码规范、最佳实践等指导,帮助团队高效协作开发。 ## 🎯 开发目标 ### 代码质量目标 - **可维护性**:代码结构清晰,易于理解和修改 - **可扩展性**:支持功能快速迭代和模块化扩展 - **性能优化**:响应时间 < 200ms,并发支持 1000+ - **安全性**:数据安全,防止常见安全漏洞 ### 团队协作目标 - **统一规范**:代码风格、命名规范、提交规范统一 - **文档完善**:API文档、技术文档实时更新 - **测试覆盖**:单元测试覆盖率 > 80% - **持续集成**:自动化构建、测试、部署 ## 🛠️ 开发环境搭建 ### 系统要求 #### 前端开发环境 - **Node.js**: 16.0+ (推荐使用 18.x LTS) - **包管理器**: npm 8.0+ 或 yarn 1.22+ 或 pnpm 7.0+ - **微信开发者工具**: 最新稳定版 (1.06.x) - **IDE**: VS Code (推荐) / WebStorm - **Git**: 2.30+ - **浏览器**: Chrome 100+ (开发调试) #### 后端开发环境 - **Node.js**: 16.0+ (主要后端) - **JDK**: Java 17 (微服务版本,推荐使用 OpenJDK) - **Maven**: 3.6+ (Java项目构建) - **IDE**: IntelliJ IDEA (推荐) / Eclipse / VS Code - **数据库**: MySQL 8.0+ - **缓存**: Redis 6.0+ - **消息队列**: RabbitMQ 3.8+ (可选) - **容器化**: Docker 20.10+ 和 Docker Compose 1.29+ ### 快速环境安装 #### macOS 环境安装 ```bash # 使用 Homebrew 安装开发工具 # 1. 安装 Homebrew (如果未安装) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 2. 安装 Node.js 和 npm brew install node # 3. 安装 Java 17 brew install openjdk@17 echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc # 4. 安装 Maven brew install maven # 5. 安装 Docker brew install docker docker-compose # 6. 安装数据库 brew install mysql redis # 7. 安装开发工具 brew install git wget curl # 8. 验证安装 node --version # 应显示 v16.x 或更高 java --version # 应显示 Java 17 mvn --version # 应显示 Maven 3.6+ docker --version # 应显示 Docker 20.10+ ``` #### Windows 环境安装 1. **Node.js**: 从 [官网](https://nodejs.org/) 下载安装 2. **JDK 17**: 从 [Adoptium](https://adoptium.net/) 下载安装 3. **Maven**: 从 [官网](https://maven.apache.org/) 下载配置 4. **Docker Desktop**: 从 [官网](https://www.docker.com/products/docker-desktop) 下载安装 5. **微信开发者工具**: 从 [官网](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html) 下载安装 #### Ubuntu/Debian 环境安装 ```bash # 更新包管理器 sudo apt update # 安装 Node.js curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs # 安装 Java 17 sudo apt install openjdk-17-jdk # 安装 Maven sudo apt install maven # 安装 Docker sudo apt install docker.io docker-compose # 安装 MySQL sudo apt install mysql-server # 安装 Redis sudo apt install redis-server ``` ### 环境验证 ```bash # 验证 Node.js 和 npm node --version npm --version # 验证 Java 和 Maven java -version mvn -version # 验证 Docker docker --version docker-compose --version # 验证数据库连接 mysql --version redis-cli --version ``` ## 🏗️ 项目架构 ### 整体架构 ```mermaid graph TB A[微信小程序前端] --> B[API网关] C[管理后台前端] --> B D[官网前端] --> B B --> E[认证服务] B --> F[用户服务] B --> G[旅行服务] B --> H[动物服务] B --> I[订单服务] B --> J[商家服务] E --> K[MySQL数据库] F --> K G --> K H --> K I --> K J --> K E --> L[Redis缓存] F --> L G --> L H --> L subgraph "服务注册与发现" M[Eureka Server] end E --> M F --> M G --> M H --> M I --> M J --> M ``` ### 目录结构 ``` jiebanke/ ├── frontend/ # 前端项目 │ ├── miniprogram/ # 微信小程序 │ ├── admin-web/ # 管理后台 │ └── website/ # 官方网站 ├── backend-java/ # Java后端服务 │ ├── eureka-server/ # 服务注册中心 │ ├── gateway-service/ # API网关 │ ├── auth-service/ # 认证服务 │ ├── user-service/ # 用户服务 │ ├── travel-service/ # 旅行服务 │ ├── animal-service/ # 动物服务 │ ├── order-service/ # 订单服务 │ ├── merchant-service/ # 商家服务 │ └── common/ # 公共模块 ├── docs/ # 项目文档 ├── scripts/ # 部署脚本 └── docker-compose.yml # Docker编排文件 ``` ## 📝 开发规范 ### 1. 代码规范 #### 前端代码规范 ##### JavaScript/TypeScript 规范 ```javascript // ✅ 推荐写法 const getUserInfo = async (userId) => { try { const response = await api.get(`/users/${userId}`); return response.data; } catch (error) { console.error('获取用户信息失败:', error); throw error; } }; // ❌ 不推荐写法 function getUserInfo(userId) { return new Promise((resolve, reject) => { api.get('/users/' + userId).then(res => { resolve(res.data); }).catch(err => { reject(err); }); }); } ``` ##### Vue 组件规范 ```vue ``` #### 后端代码规范 ##### Java 命名规范 ```java // ✅ 推荐写法 public class UserService { private static final int MAX_RETRY_COUNT = 3; private final UserMapper userMapper; /** * 根据用户ID获取用户信息 * * @param userId 用户ID * @return 用户信息 * @throws BusinessException 当用户不存在时抛出 */ public UserDTO getUserById(Long userId) { if (userId == null || userId <= 0) { throw new IllegalArgumentException("用户ID不能为空或小于等于0"); } User user = userMapper.selectById(userId); if (user == null) { throw new BusinessException(ErrorCode.USER_NOT_FOUND, "用户不存在"); } return UserConverter.toDTO(user); } } // ❌ 不推荐写法 public class userservice { public Object getuser(Object id) { return userMapper.selectById((Long)id); } } ``` ##### Spring Boot 控制器规范 ```java @RestController @RequestMapping("/api/v1/users") @Validated @Slf4j public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService = userService; } @GetMapping("/{id}") @Operation(summary = "获取用户信息", description = "根据用户ID获取用户详细信息") public ApiResponse getUserById( @PathVariable @Min(1) Long id) { log.info("获取用户信息, userId: {}", id); try { UserDTO user = userService.getUserById(id); return ApiResponse.success(user); } catch (BusinessException e) { log.warn("获取用户信息失败, userId: {}, error: {}", id, e.getMessage()); return ApiResponse.error(e.getCode(), e.getMessage()); } catch (Exception e) { log.error("获取用户信息系统错误, userId: {}", id, e); return ApiResponse.error(ErrorCode.SYSTEM_ERROR, "系统错误"); } } } ``` ### 2. 数据库规范 #### 表设计规范 ```sql -- ✅ 推荐的表结构设计 CREATE TABLE users ( id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID', openid VARCHAR(100) UNIQUE NOT NULL COMMENT '微信openid', nickname VARCHAR(50) NOT NULL COMMENT '用户昵称', avatar VARCHAR(255) COMMENT '头像URL', gender ENUM('male', 'female', 'unknown') DEFAULT 'unknown' COMMENT '性别', phone VARCHAR(20) UNIQUE COMMENT '手机号码', status ENUM('active', 'inactive', 'banned') DEFAULT 'active' COMMENT '用户状态', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', INDEX idx_openid (openid), INDEX idx_phone (phone), INDEX idx_status (status), INDEX idx_created_at (created_at) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户基础信息表'; ``` #### SQL 查询规范 ```sql -- ✅ 推荐的查询写法 SELECT u.id, u.nickname, u.avatar, u.created_at FROM users u WHERE u.status = 'active' AND u.created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY) ORDER BY u.created_at DESC LIMIT 20; -- ❌ 不推荐的查询写法 select * from users where status='active' order by created_at desc; ``` ### 3. API 接口规范 #### RESTful API 设计 ```javascript // ✅ 推荐的API设计 GET /api/v1/users // 获取用户列表 GET /api/v1/users/{id} // 获取单个用户 POST /api/v1/users // 创建用户 PUT /api/v1/users/{id} // 更新用户 DELETE /api/v1/users/{id} // 删除用户 GET /api/v1/users/{id}/travels // 获取用户的旅行计划 POST /api/v1/travels // 创建旅行计划 // ❌ 不推荐的API设计 GET /api/getUserList POST /api/createUser GET /api/user_travels?userId=123 ``` #### 统一响应格式 ```json { "code": 200, "message": "success", "data": { "id": 1, "nickname": "张三", "avatar": "https://example.com/avatar.jpg" }, "timestamp": "2025-01-15T10:30:00Z" } ``` #### 错误响应格式 ```json { "code": 400, "message": "参数错误", "data": null, "errors": [ { "field": "phone", "message": "手机号格式不正确" } ], "timestamp": "2025-01-15T10:30:00Z" } ``` ### 4. Git 工作流规范 #### 分支管理 ```bash # 主要分支 main # 生产环境分支 develop # 开发环境分支 release/* # 发布分支 hotfix/* # 热修复分支 # 功能分支 feature/user-management # 用户管理功能 feature/travel-booking # 旅行预订功能 feature/animal-adoption # 动物认领功能 # 修复分支 bugfix/login-issue # 登录问题修复 bugfix/payment-error # 支付错误修复 ``` #### 提交信息规范 ```bash # 提交信息格式 ():