【有来开源组织】开发规范手册

🚀 作者主页： 有来技术
🔥 开源项目： youlai-mall 🍃 vue3-element-admin 🍃 youlai-boot
🌺 仓库主页： Gitee 💫 Github 💫 GitCode
💖 欢迎点赞 👍 收藏 ⭐留言 📝 如有错误敬请纠正！

前言

为了确保代码的一致性、可读性和可维护性，并提高团队协作效率，我们有来开源组织制定了一套详细的开发规范。本指南涵盖了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 修复问题/BUG
  • style 代码风格相关无影响运行结果的
  • perf 优化/性能提升
  • refactor 重构
  • revert 撤销修改
  • test 测试相关
  • docs 文档/注释
  • chore 依赖更新/脚手架配置修改等
  • workflow 工作流改进
  • ci 持续集成
  • types 类型定义文件更改
  • wip 开发中，临时提交

分支功能

1. master 为主分支
   • 原则只接受从develop的合并请求，不接受pr
2. develop 为开发分支
   • 接受pr和feature的合并
3. feature/* 为功能开发分支
   • 由开发人员提交代码并合并到develop分支
   • 不定期从develop分支合并到master，每次合并到master上为发一次版本，版本号应当调整

版本号命名规则

• 主版本号.子版本号.修正版本号
  • 项目初版本时，版本号为 0.1.0
  • 局部修改或bug修正时，主版本号和子版本号不变，修正版本号加1
  • 增加部分功能时，主版本号不变，子版本号加1，修正版本号复位为0
  • 重大修改时，主版本号加1

参考

• 阿里开发手册
  • 阿里巴巴 Java 开发手册（黄山版）
  • 阿里巴巴 Java 开发手册项目主页