开发规范模板

项目开发规范文档，包含从克隆项目到提交代码的完整流程规范。

包含内容

克隆项目 + 分支管理 + 合并代码 + 提交规范 + 代码注释规范

一、克隆项目

bash

1# 克隆后端
2git clone https://gitee.com/company/laby-server.git
3
4# 克隆前端
5git clone https://gitee.com/company/laby-web.git

二、分支管理

2.1 分支说明

分支	说明	部署环境
main	生产分支，禁止直接提交	生产环境
test	测试分支，禁止直接提交	测试环境
develop	开发主分支	开发环境
feature/xxx	个人功能开发分支	本地
bugfix/xxx	Bug 修复分支	本地
hotfix/xxx	紧急修复分支	本地

2.2 分支命名规范

格式：类型/姓名缩写-功能描述

类型	格式	示例
功能开发	feature/缩写-功能模块	feature/zs-user-module
Bug 修复	bugfix/缩写-问题描述	bugfix/ls-login-error
紧急修复	hotfix/缩写-问题描述	hotfix/ww-security-fix

2.3 创建个人分支

bash

1# 切换到 develop 分支并拉取最新代码
2git checkout develop
3git pull origin develop
4
5# 创建并切换到个人分支
6git checkout -b feature/zs-user-module

三、合并代码

3.1 合并到测试分支

开发完成后，将个人分支合并到 test 分支触发测试环境部署：

bash

1# 先同步最新代码，避免冲突
2git checkout develop
3git pull origin develop
4git checkout feature/zs-user-module
5git rebase develop
6
7# 切换到 test 分支合并
8git checkout test
9git pull origin test
10git merge feature/zs-user-module
11git push origin test

3.2 合并到 develop 分支

功能测试通过后，合并到 develop：

bash

1git checkout develop
2git pull origin develop
3git merge feature/zs-user-module
4git push origin develop

3.3 合并到生产分支（main）

注意

合并到 main 分支需要技术负责人审批，不得自行操作。

bash

1# 由技术负责人执行
2git checkout main
3git pull origin main
4git merge test
5git tag v1.0.1
6git push origin main --tags

3.4 解决冲突

bash

1# 查看冲突文件
2git status
3
4# 编辑冲突文件，解决冲突后
5git add .
6git commit -m "fix: 解决合并冲突"
7git push origin feature/zs-user-module

四、提交规范

4.1 提交格式

1<type>(<scope>): <subject>

type：提交类型
scope：影响范围（可选），如模块名
subject：简短描述，不超过 50 个字符

4.2 提交类型

type	说明	示例
feat	新功能	`feat(user): 新增用户列表查询`
fix	Bug 修复	`fix(login): 修复登录失败问题`
docs	文档更新	`docs(readme): 更新部署文档`
style	代码格式（不影响逻辑）	`style(user): 格式化代码`
refactor	代码重构	`refactor(order): 重构订单模块`
perf	性能优化	`perf(query): 优化用户列表查询`
test	测试相关	`test(user): 新增用户单元测试`
chore	构建 / 依赖变更	`chore(deps): 升级 Spring Boot`
revert	回滚提交	`revert: 回滚用户模块变更`

4.3 提交示例

bash

1git commit -m "feat(user): 新增用户分页查询接口"
2git commit -m "fix(login): 修复 token 过期后未跳转登录页"
3git commit -m "refactor(order): 重构订单状态流转逻辑"
4git commit -m "perf(dict): 字典数据增加 Redis 缓存"
5git commit -m "docs(env): 更新测试环境配置文档"

五、代码注释规范

5.1 后端注释规范（Java）

类注释：

java

1/**
2 * 用户管理 Controller
3 *
4 * @author zs
5 * @date 2026-05-11
6 */
7@RestController
8@RequestMapping("/user")
9public class UserController {
10}

方法注释：

java

1/**
2 * 分页查询用户列表
3 *
4 * @param pageReqVO 分页请求参数
5 * @return 用户分页数据
6 */
7@GetMapping("/page")
8public CommonResult<PageResult<UserRespVO>> getUserPage(@Valid UserPageReqVO pageReqVO) {
9    return success(userService.getUserPage(pageReqVO));
10}

行内注释：

java

1// 校验用户是否存在
2UserDO user = userMapper.selectById(id);
3if (user == null) {
4    throw exception(USER_NOT_EXISTS);
5}
6
7// 更新用户状态
8user.setStatus(status);
9userMapper.updateById(user);

注意事项

类和方法必须写注释，行内注释按需添加
注释要说明"为什么"，而不是重复代码本身
禁止提交无意义注释，如 // test、// 123

5.2 前端注释规范（TypeScript / Vue）

组件注释：

vue

1<!--
2 * 用户列表组件
3 * @description 展示用户分页列表，支持搜索、新增、编辑、删除
4 * @author zs
5 * @date 2026-05-11
6-->
7<template>
8  <div class="user-list">
9  </div>
10</template>

函数注释（JSDoc）：

typescript

1/**
2 * 获取用户分页列表
3 * @param params 查询参数
4 * @returns 用户分页数据
5 */
6export const getUserPage = async (params: UserPageReqVO) => {
7  return await request.get({ url: '/user/page', params })
8}

行内注释：

typescript

1// 过滤掉已禁用的用户
2const activeUsers = users.filter(user => user.status === 1)
3
4// 格式化时间为 YYYY-MM-DD
5const formatDate = (date: Date) => dayjs(date).format('YYYY-MM-DD')

注意事项

组件必须写头部注释
公共函数、工具函数必须写 JSDoc 注释
复杂逻辑必须写行内注释说明意图

六、代码规范

6.1 命名规范

后端（Java）

命名规范

类型	规范	示例
类名	UpperCamelCase	`UserController`
方法名	lowerCamelCase	`getUserById`
变量名	lowerCamelCase	`userId`
常量	UPPER_SNAKE_CASE	`MAX_RETRY_COUNT`
包名	全小写，点分隔	`com.laby.user`
数据库表名	snake_case	`sys_user`
数据库字段	snake_case	`user_id`
枚举类	UpperCamelCase，枚举值全大写	`UserStatusEnum.ENABLE`

类名后缀约定

后缀	说明	示例
`Controller`	控制层	`UserController`
`Service`	服务接口	`UserService`
`ServiceImpl`	服务实现	`UserServiceImpl`
`Mapper`	数据访问层	`UserMapper`
`DO`	数据库实体	`UserDO`
`VO`	视图对象	`UserRespVO`
`ReqVO`	请求参数对象	`UserPageReqVO`
`DTO`	数据传输对象	`UserDTO`
`Convert`	对象转换器	`UserConvert`
`Enum`	枚举类	`UserStatusEnum`
`Utils`	工具类	`DateUtils`
`Config`	配置类	`RedisConfig`

前端（TypeScript）

类型	规范	示例
组件名	UpperCamelCase	`UserList.vue`、`OrderDetail.vue`
变量 / 函数	lowerCamelCase	`userList`、`getUserPage`
常量	UPPER_SNAKE_CASE	`MAX_PAGE_SIZE`、`BASE_URL`
类型 / 接口	UpperCamelCase	`UserVO`、`PageResult`
CSS 类名	kebab-case	`user-list`、`order-detail`
文件名（非组件）	kebab-case	`user-api.ts`、`date-utils.ts`
Props	lowerCamelCase	`userId`、`pageSize`
Emit 事件	kebab-case	`update:modelValue`、`page-change`

6.2 代码风格

后端（Java）

缩进与格式：

使用 4 个空格缩进，不使用 Tab
每行不超过 120 个字符
方法之间空一行，逻辑块之间空一行
左大括号不换行，右大括号单独一行

java

1// 正确
2public UserRespVO getUserById(Long id) {
3    UserDO user = userMapper.selectById(id);
4    if (user == null) {
5        throw exception(USER_NOT_EXISTS);
6    }
7    return UserConvert.INSTANCE.convert(user);
8}
9
10// 错误 - 大括号换行、缩进混乱
11public UserRespVO getUserById(Long id)
12{
13  UserDO user = userMapper.selectById(id);
14  return UserConvert.INSTANCE.convert(user);
15}

其他约定：

方法参数超过 3 个时，换行对齐
链式调用每个方法单独一行
不允许出现魔法值，统一定义为常量
集合初始化指定大小：new ArrayList<>(16)

java

1// 不允许魔法值
2if (user.getStatus() == 1) { }       // 错误
3
4if (user.getStatus() == UserStatusEnum.ENABLE.getStatus()) { }  // 正确
5
6// 链式调用换行
7LambdaQueryWrapper<UserDO> wrapper = new LambdaQueryWrapper<UserDO>()
8        .eq(UserDO::getStatus, status)
9        .like(UserDO::getUsername, keyword)
10        .orderByDesc(UserDO::getCreateTime);

前端（TypeScript / Vue）

缩进与格式：

使用 2 个空格缩进
每行不超过 100 个字符
字符串统一使用单引号
语句末尾不加分号（遵循项目 ESLint 配置）

typescript

1// 正确
2const getUserList = async (params: UserPageReqVO) => {
3  const { list, total } = await getUserPage(params)
4  userList.value = list
5  totalCount.value = total
6}
7
8// 错误
9const getUserList = async(params:UserPageReqVO)=>{
10  const {list,total} = await getUserPage(params);
11  userList.value=list;
12}

Vue 组件结构顺序：

vue

1<template>
2  <!-- 模板内容 -->
3</template>
4
5<script setup lang="ts">
6// 1. import 导入
7// 2. defineProps / defineEmits
8// 3. 响应式数据
9// 4. 计算属性
10// 5. 方法
11// 6. 生命周期
12</script>
13
14<style scoped lang="scss">
15/* 样式 */
16</style>

6.3 其他规范

异常处理规范

不允许吞掉异常（catch 后不处理）
业务异常统一使用项目封装的 ServiceException
不允许直接返回 null，使用 Optional 或抛出异常

java

1// 错误 - 吞掉异常
2try {
3    doSomething();
4} catch (Exception e) {
5    // 什么都不做
6}
7
8// 错误 - 直接打印堆栈
9} catch (Exception e) {
10    e.printStackTrace();
11}
12
13// 正确 - 记录日志 + 抛出业务异常
14} catch (Exception e) {
15    log.error("[getUserById] 查询用户失败，id: {}", id, e);
16    throw exception(USER_QUERY_FAILED);
17}

日志规范

使用 @Slf4j 注解，不允许使用 System.out.println
日志级别：DEBUG（调试）、INFO（关键流程）、WARN（潜在问题）、ERROR（异常）
日志内容要包含关键参数，方便排查问题

java

1// 错误
2System.out.println("用户不存在");
3log.info("查询用户");
4
5// 正确
6log.info("[getUserById] 开始查询用户，id: {}", id);
7log.warn("[getUserById] 用户状态异常，id: {}，status: {}", id, user.getStatus());
8log.error("[getUserById] 查询用户失败，id: {}", id, e);

接口规范

统一使用 RESTful 风格
接口路径使用小写 kebab-case
统一返回 CommonResult<T> 包装类

操作	方法	路径示例
分页查询	GET	`/user/page`
详情查询	GET	`/user/{id}`
新增	POST	`/user/create`
修改	PUT	`/user/update`
删除	DELETE	`/user/delete`
批量删除	DELETE	`/user/delete-batch`

java

1// 统一返回格式
2@GetMapping("/page")
3public CommonResult<PageResult<UserRespVO>> getUserPage(@Valid UserPageReqVO reqVO) {
4    return success(userService.getUserPage(reqVO));
5}
6
7@PostMapping("/create")
8public CommonResult<Long> createUser(@Valid @RequestBody UserSaveReqVO reqVO) {
9    return success(userService.createUser(reqVO));
10}

注意事项

接口入参必须加 @Valid 注解进行参数校验
敏感字段（手机号、身份证等）返回时需要脱敏处理
删除操作统一使用逻辑删除，不允许物理删除

七、写在最后

规范不是束缚，是团队协作的基础。好的代码让人一眼看懂，好的提交让人一目了然。每一次认真对待规范，都是在为团队节省时间、为自己积累口碑。

提示

遇到规范中未覆盖的场景，以可读性优先、团队一致性优先为原则处理，并及时同步给团队。

forum

评论区 / Comments

share分享文章 / Share

一、克隆项目​

二、分支管理​

2.1 分支说明​

2.2 分支命名规范​

2.3 创建个人分支​

三、合并代码​

3.1 合并到测试分支​

3.2 合并到 develop 分支​

3.3 合并到生产分支（main）​

3.4 解决冲突​

四、提交规范​

4.1 提交格式​

4.2 提交类型​

4.3 提交示例​

五、代码注释规范​

5.1 后端注释规范（Java）​

5.2 前端注释规范（TypeScript / Vue）​

六、代码规范​

6.1 命名规范​

后端（Java）​

前端（TypeScript）​

6.2 代码风格​

后端（Java）​

前端（TypeScript / Vue）​

6.3 其他规范​

异常处理规范​

日志规范​

接口规范​

七、写在最后​

评论区 / Comments

一、克隆项目

二、分支管理

2.1 分支说明

2.2 分支命名规范

2.3 创建个人分支

三、合并代码

3.1 合并到测试分支

3.2 合并到 develop 分支

3.3 合并到生产分支（main）

3.4 解决冲突

四、提交规范

4.1 提交格式

4.2 提交类型

4.3 提交示例

五、代码注释规范

5.1 后端注释规范（Java）

5.2 前端注释规范（TypeScript / Vue）

六、代码规范

6.1 命名规范

后端（Java）

前端（TypeScript）

6.2 代码风格

后端（Java）

前端（TypeScript / Vue）

6.3 其他规范

异常处理规范

日志规范

接口规范

七、写在最后