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

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

前言

为了确保代码的一致性、可读性和可维护性，并提高团队协作效率，我们有来开源组织制定了一套详细的开发规范。本指南涵盖了Java、CSS、Vue.js等多种编程语言和框架的编码标准，以及Git的使用规范。这些规范基于行业最佳实践和我们在实际项目中的经验总结，旨在为开发人员提供一个清晰、统一的编码标准，帮助每个成员编写高质量的代码。

Java 代码规范

命名规范

包名

• 规则说明：统一使用单数形式，全小写。
• 示例：com.example.service

类名

• 规则说明：可以使用复数形式，首字母大写+驼峰命名。
• 示例：UserServices

实体名

名称	规则
dto	远程调用传参
form	前端表单传参
query	查询传参 (查询参数大于5个建议封装query对象)
vo	返回前端显示 (可使用dto代替)
entity	映射数据库实体，和数据表字段完全一致

规则说明：dto 和 vo 实体类名带后缀且全大写。

• 正例：UserDTO、UserVO
• 反例：UserDto、UserVo

组件包名

• 规则说明：组件包父包，包括listener，handler等。
• 示例：com.example.component

泛型通配符

名称	规则
E	Element (在集合中使用，因为集合中存放的是元素)
T	Type（Java 类）
K	Key（键）
V	Value（值）
N	Number（数值类型）
？	表示不确定的Java类型
S、U、V	2nd、3rd、4th types

参数规范

动态排序字段命名

名称	字段名	值
排序字段名	orderBy	列名
排序规则	sort	升序：asc 降序：desc

分页参数命名

名称	字段名	默认值
页码	pageNum	1
每页数量	pageSize	10

查询参数

• 规则说明：查询参数大于5个建议封装为query对象。

方法规范

方法命名

作用域	示例
列表查询	getUserList / listUsers / getUsers
分页查询	getUserPage / listPagedUsers
单个查询	getUser / getUserDetail / getUserInfo

方法调用

• 规则说明：禁止Service跨实体直接调用Mapper。
• 正例：UserService 直接调用 UserMapper
• 反例：UserService 直接调用 DeptMapper

方法体

• 规则说明：单个方法体不建议超过50行或一屏，超过建议封装。

数据库规范

字段规范

• 是与否概念：is_xxx使用is前缀意义更加明确，考虑兼容性、扩展性和移植性建议类型为tinyint而非bit。
• 必有字段：id，create_time，update_time

索引命名

类型	规则
普通索引	idx_cloumn_name
唯一索引	uk_cloumn_name

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);// Computedconst doubleCount = computed(() => count.value * 2);// Watcherwatch(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 开发手册项目主页