贡献指南

感谢您对 Snapshot 项目的关注！我们欢迎任何形式的贡献。

🤝 如何贡献

报告问题

如果您发现了 bug 或有功能建议：

检查 Issues 确保问题未被报告
创建新 Issue，使用合适的模板
提供详细的信息：
- Bug 报告：复现步骤、预期行为、实际行为、环境信息
- 功能建议：使用场景、预期效果、可能的实现方案

提交代码

开发流程

Fork 仓库

# 在 GitHub 上点击 Fork 按钮
git clone https://github.com/<YOUR_USERNAME>/snapshot.git
cd snapshot

创建特性分支

git checkout -b feature/AmazingFeature
# 或修复 bug: git checkout -b fix/bug-description

进行开发
- 遵循代码规范（见下文）
- 添加必要的测试
- 更新相关文档

提交更改

git add .
git commit -m "feat: 添加文件批量下载功能"

推送到分支
```
git push origin feature/AmazingFeature
```
创建 Pull Request
- 在 GitHub 上创建 PR
- 填写 PR 模板
- 等待代码审查

📝 代码规范

后端 (Java)

遵循阿里巴巴Java开发规范

命名规范
- 类名：PascalCase (例如：UploadRecordService)
- 方法名：camelCase (例如：getUploadRecordById)
- 常量：UPPER_SNAKE_CASE (例如：MAX_FILE_SIZE)
- 包名：全小写 (例如：com.snapshot.service)

注释规范

/**
* 根据ID获取上传记录
*
* @param id 上传记录ID
* @return 上传记录对象，不存在返回null
* @throws IllegalArgumentException 如果ID为空
*/
public UploadRecord getUploadRecordById(String id) {
  // 实现代码
}

异常处理
- 使用 GlobalExceptionHandler 统一处理异常
- 自定义异常继承 RuntimeException
- 避免捕获 Exception 基类
MyBatis 规范
- 使用 @Mapper 注解
- SQL 语句放在 XML 文件中
- 使用参数化查询防止 SQL 注入

前端 (Vue.js)

遵循 Vue 官方风格指南

组件命名

<!-- ✅ 推荐 -->
<script>
export default {
name: 'UploadFileList'  // PascalCase
}
</script>

<!-- ❌ 避免 -->
<script>
export default {
name: 'upload-file-list'  // kebab-case
}
</script>

Props 定义

<script>
export default {
props: {
  fileList: {
    type: Array,
    required: true,
    default: () => []
  },
  maxSize: {
    type: Number,
    default: 50 * 1024 * 1024
  }
}
}
</script>

变量命名

// ✅ 推荐
const uploadRecord = ref(null)
const MAX_FILE_COUNT = 10

// ❌ 避免
const upload_record = ref(null)
const max_file_count = 10

组件结构

<template>
<!-- 模板内容 -->
</template>

<script>
import { ref, computed, onMounted } from 'vue'

export default {
name: 'ComponentName',

props: { /* ... */ },

emits: ['update', 'delete'],

setup(props, { emit }) {
  // 1. 响应式数据
  const count = ref(0)

  // 2. 计算属性
  const doubleCount = computed(() => count.value * 2)

  // 3. 方法
  const increment = () => {
    count.value++
    emit('update', count.value)
  }

  // 4. 生命周期
  onMounted(() => {
    console.log('Component mounted')
  })

  return {
    count,
    doubleCount,
    increment
  }
}
}
</script>

<style scoped>
/* 组件样式 */
</style>

📋 提交信息规范

使用约定式提交格式：

格式

<类型>(<范围>): <简短描述>

<详细描述>

<页脚>

类型

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式调整（不影响功能）
refactor: 重构（既不是新功能也不是修复）
perf: 性能优化
test: 添加或修改测试
chore: 构建/工具相关
ci: CI/CD 配置

示例

# 简单提交
git commit -m "feat: 添加文件批量下载功能"

# 详细提交
git commit -m "fix(upload): 修复大文件上传超时问题

- 增加连接超时配置到30分钟
- 添加上传进度重试机制
- 优化内存使用

Closes #123"

✅ Pull Request 检查清单

提交 PR 前请确认：

代码遵循项目规范
已进行自我审查（self-review）
已添加必要的注释（特别是复杂逻辑）
已更新相关文档
所有测试通过
没有引入新的警告
提交信息符合规范
PR 描述清晰，说明了变更内容和原因

🧪 测试

后端测试

cd backend
mvn test

前端测试

cd frontend
npm run test

E2E 测试

npm run test:e2e

📧 联系方式

如有问题：

GitHub Issues: [../../issues]

📄 许可证

提交代码即表示您同意您的贡献将按照项目的 MIT 许可证进行许可。

CONTRIBUTING.md 5.1 KB Historia Raaka