目录
前言
为了确保代码的一致性、可读性和可维护性，并提高团队协作效率，我们有来开源组织制定了一套详细的开发规范。本指南涵盖了Java、CSS、Vue.js等多种编程语言和框架的编码标准，以及Git的使用规范。这些规范基于行业最佳实践和我们在实际项目中的经验总结，旨在为开发人员提供一个清晰、统一的编码标准，帮助每个成员编写高质量的代码。
Java 代码规范
命名规范
包名
- 规则说明：统一使用单数形式，全小写。
- 示例：
com.example.service
类名
- 规则说明：可以使用复数形式，首字母大写+驼峰命名。
- 示例：
UserServices
实体名
规则说明：dto 和 vo 实体类名带后缀且全大写。
- 正例：
UserDTO、UserVO - 反例：
UserDto、UserVo
组件包名
- 规则说明：组件包父包，包括listener，handler等。
- 示例：
com.example.component
泛型通配符
参数规范
动态排序字段命名
分页参数命名
查询参数
- 规则说明：查询参数大于5个建议封装为query对象。
方法规范
方法命名
方法调用
- 规则说明：禁止Service跨实体直接调用Mapper。
- 正例：
UserService直接调用UserMapper - 反例：
UserService直接调用DeptMapper
方法体
- 规则说明：单个方法体不建议超过50行或一屏，超过建议封装。
数据库规范
字段规范
- 是与否概念：
is_xxx使用is前缀意义更加明确，考虑兼容性、扩展性和移植性建议类型为tinyint而非bit。 - 必有字段：
id，create_time，update_time
索引命名
Vue 代码规范
Vue.js 风格指南
- 参考：Vue.js 风格指南
组合式 API 顺序
<script setup>
// import语句
import { ref, computed, watch } from 'vue';
// Props(defineProps)
defineProps(['propA', 'propB']);
// Emits(defineEmits)
const emit = defineEmits(['update', 'delete']);
// 响应式变量定义
const count = ref(0);
// Computed
const doubleCount = computed(() => count.value * 2);
// Watcher
watch(count, (newValue, oldValue) => {
console.log(`Count changed from ${oldValue} to ${newValue}`);
});
// 函数
function increment() {
count.value++;
}
// 生命周期
onMounted(() => {
console.log('Component mounted');
});
//Expose(defineExpose)
defineExpose({ count, increment });
</script>
CSS 规范
CSS 命名(BEM)
- 规则说明：遵循BEM命名法，保证类名的可读性和结构化。
- 示例：
block__element--modifier
Git 规范
提交规范
- 参考：Vue 规范 (Angular)
feat增加新功能fix修复问题/BUGstyle代码风格相关无影响运行结果的perf优化/性能提升refactor重构revert撤销修改test测试相关docs文档/注释chore依赖更新/脚手架配置修改等workflow工作流改进ci持续集成types类型定义文件更改wip开发中，临时提交
分支功能
- master 为主分支
- 原则只接受从develop的合并请求，不接受pr
- develop 为开发分支
- 接受pr和feature的合并
- feature/* 为功能开发分支
- 由开发人员提交代码并合并到develop分支
- 不定期从develop分支合并到master，每次合并到master上为发一次版本，版本号应当调整
版本号命名规则
- 主版本号.子版本号.修正版本号
- 项目初版本时，版本号为
0.1.0 - 局部修改或bug修正时，主版本号和子版本号不变，修正版本号加1
- 增加部分功能时，主版本号不变，子版本号加1，修正版本号复位为0
- 重大修改时，主版本号加1
- 项目初版本时，版本号为