开发指南
项目结构
后端项目结构
后端/
├── src/
│ ├── main/
│ │ ├── java/com/lumenglover/yuemupicturebackend/
│ │ │ ├── annotation/ # 自定义注解
│ │ │ ├── aop/ # 切面编程实现
│ │ │ ├── config/ # 配置类
│ │ │ ├── constant/ # 常量定义
│ │ │ ├── controller/ # 控制器层
│ │ │ ├── exception/ # 异常处理
│ │ │ ├── interceptor/ # 拦截器
│ │ │ ├── manager/ # 业务逻辑管理器
│ │ │ ├── mapper/ # 数据访问层
│ │ │ ├── model/ # 数据模型
│ │ │ ├── service/ # 业务逻辑层
│ │ │ ├── utils/ # 工具类
│ │ │ └── YuemuPictureBackendApplication.java
│ │ └── resources/
│ │ ├── mapper/ # MyBatis映射文件
│ │ ├── application.yml # 主配置文件
│ │ ├── application-dev.yml # 开发环境配置
│ │ ├── application-test.yml # 测试环境配置
│ │ └── application-prod.yml # 生产环境配置
│ └── test/
│ └── java/ # 测试代码
├── pom.xml # Maven配置文件
└── sql/
└── create_table.sql # 数据库表结构脚本前端项目结构
前端/
├── public/ # 静态资源
├── src/
│ ├── api/ # API接口定义
│ ├── assets/ # 静态资源文件
│ ├── components/ # 公共组件
│ ├── constants/ # 常量定义
│ ├── layouts/ # 页面布局
│ ├── pages/ # 页面组件
│ ├── router/ # 路由配置
│ ├── stores/ # 状态管理(Pinia)
│ ├── styles/ # 全局样式
│ ├── utils/ # 工具函数
│ ├── views/ # 视图组件
│ ├── App.vue # 根组件
│ ├── main.ts # 入口文件
│ └── request.ts # 请求封装
├── .env.* # 环境变量配置
├── index.html # HTML模板
├── package.json # 依赖管理
├── tsconfig.json # TypeScript配置
└── vite.config.ts # Vite配置开发环境搭建
后端开发环境
1. 环境准备
- Java 8 (OpenJDK 1.8)
- Maven 3.6+
- MySQL 5.7+
- Redis
- Elasticsearch 8.0+ (必需，用于搜索功能)
- 腾讯云COS (必需，用于文件存储)
- Node.js 22+ (用于前端开发)
2. 数据库初始化
bash
# 创建数据库
CREATE DATABASE yuemu_picture CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# 执行建表脚本
mysql -u root -p yuemu_picture < sql/create_table.sql3. 配置文件
复制并修改开发环境配置：
bash
# 修改数据库连接信息
vim src/main/resources/application-dev.yml4. 启动后端服务
bash
# 编译项目
mvn clean compile
# 运行项目
mvn spring-boot:run前端开发环境
1. 依赖安装
bash
cd 前端
npm install2. 环境变量配置
创建 .env.development 文件：
VITE_API_BASE_URL=http://localhost:8123/api
VITE_BASE_URL=http://localhost:8123
VITE_APP_TITLE=悦木图库3. 启动开发服务器
bash
npm run dev代码规范
Java代码规范
1. 命名规范
- 类名：使用帕斯卡命名法，如
UserController - 方法名：使用驼峰命名法，如
getUserById - 常量：全部大写，单词间用下划线分隔，如
MAX_RETRY_COUNT - 变量：使用驼峰命名法
2. 注释规范
java
/**
* 用户控制器
* 处理用户相关的HTTP请求
*/
@RestController
@RequestMapping("/api/user")
public class UserController {
/**
* 获取用户信息
*
* @param userId 用户ID
* @return 用户信息
*/
@GetMapping("/{userId}")
public BaseResponse<UserVO> getUser(@PathVariable Long userId) {
// 实现代码
}
}3. 代码风格
- 使用Lombok减少样板代码
- 遵循单一职责原则
- 合理使用设计模式
TypeScript代码规范
1. 命名规范
- 组件文件：使用帕斯卡命名法，如
UserProfile.vue - 函数：使用驼峰命名法
- 常量：使用大写字母和下划线
2. 代码风格
typescript
// 类型定义
interface User {
id: number
name: string
email: string
}
// 组件定义
const UserProfile = defineComponent({
name: 'UserProfile',
props: {
userId: {
type: Number,
required: true
}
},
setup(props) {
// 逻辑代码
}
})数据库设计规范
1. 表命名规范
- 使用小写字母和下划线
- 使用复数形式，如
users,pictures - 避免使用保留字
2. 字段命名规范
- 使用小写字母和下划线
- 使用有意义的名称
- ID字段统一使用
id
3. 索引设计
- 为主键和外键建立索引
- 为经常查询的字段建立索引
- 避免过度索引
API设计规范
1. RESTful API设计
GET /api/users # 获取用户列表
POST /api/users # 创建用户
GET /api/users/{id} # 获取指定用户
PUT /api/users/{id} # 更新用户
DELETE /api/users/{id} # 删除用户2. 响应格式
json
{
"code": 0,
"message": "success",
"data": {},
"timestamp": 1640995200000
}3. 错误码规范
- 0: 成功
- 1-999: 系统错误
- 1000-1999: 用户相关错误
- 2000-2999: 内容相关错误
- 3000-3999: 权限相关错误
安全规范
1. 输入验证
- 所有输入必须进行验证
- 使用白名单验证
- 防止SQL注入、XSS攻击
2. 权限控制
- 实施最小权限原则
- 敏感操作需要二次确认
- 记录操作日志
3. 数据保护
- 敏感信息加密存储
- 实施数据备份策略
- 遵守数据隐私法规
测试规范
1. 单元测试
- 覆盖率达到80%以上
- 测试边界条件
- 使用Mock对象
2. 集成测试
- 测试模块间交互
- 验证数据库操作
- 测试API接口
部署规范
1. 构建流程
- 自动化构建
- 代码质量检查
- 自动化测试
2. 部署流程
- 灰度发布
- 回滚机制
- 监控告警
贡献指南
1. 分支管理
main：生产环境分支develop：开发分支feature/*：功能开发分支hotfix/*：紧急修复分支
2. 提交规范
feat: 新增图片上传功能
fix: 修复用户登录问题
docs: 更新API文档
style: 格式化代码
refactor: 重构用户服务
test: 添加单元测试
chore: 更新依赖3. Pull Request
- 描述清晰的变更内容
- 包含相关测试
- 遵循代码规范
- 通过CI检查
性能优化
1. 前端优化
- 代码分割和懒加载
- 图片优化和压缩
- 缓存策略
2. 后端优化
- 数据库查询优化
- 缓存使用
- 异步处理
监控与运维
1. 日志规范
- 结构化日志
- 合理的日志级别
- 敏感信息脱敏
2. 监控指标
- 应用性能指标
- 业务指标
- 系统资源指标
3. 告警机制
- 设置合理的阈值
- 分级告警
- 自动恢复机制