开发文档规范

原创已于 2025-10-11 21:41:13 修改 · 345 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#设计规范 #代码规范

于 2025-10-11 21:40:33 首次发布

软件同时被 2 个专栏收录

32 篇文章

订阅专栏

文档

1 篇文章

订阅专栏

开发文档

开发规范

一、命名

所有命名，必须见名知义，命名与代码含义相关，避免与代码无关联的命名

1、类名

所有类名首字母必须大写，单词之间使用驼峰命名

所有类名必须根据业务，添加统一前缀

例如：

安全系统下，用户管理模块

@RequestMapping("/security/user")
public class SecurityUserController {
    
}
public class SecurityUserService {
    
}
public class SecurityUserServiceImpl {
    
}
public class SecurityUserMapper {
    
}
public class SecurityUserBo {
    
}
public class SecurityUserVo {
    
}

2、方法名

所有方法名必须使用驼峰命名，首字母小写

例如：

public String getName() {
    
}

3、字段名

所有字段名必须使用驼峰命名，首字母小写

例如：

private String demoName;

4、表名

所有表名必须使用下划线命名

所有表名必须根据业务，添加统一前缀

例如：

安全系统下，用户管理模块

@TableName("security_user")
public class SecurityUser {
    
}

二、注释

文档注释使用/** */，多行注释使用/* */，单行注释使用//

1、类注释

所有类上需要添加注释，至少包括：描述、作者、日期

例如：

/**
 * 安全-用户管理
 * 
 * @author Seria
 * @date 2024/10/01
 */
@RequestMapping("/security/user")
@RestController
public class SecurityUserController {
    
}

2、方法注释

所有方法上需要添加注释

例如：

/**
 * 通过Id获取名称
 *
 * @param id Id
 * @return 返回名称
 */
public String getNameById(Long id) {
    
}

3、字段注释

所有字段需要添加注释

例如：

public class User {
    /**
     * Id
     */
    private Long id;
    /**
     * 名称
     */
    private String name;
}

4、其它注释说明

每个类、方法、字段上必须添加注释，用来描述清楚该代码的作用

方法中，代码超过一定行数，必须添加注释，来描述每段代码的作用

例如：

/**
 * 通过Id获取名称
 *
 * @param id Id
 * @return 返回名称
 */
public getNameById(Long id) {
    // 判断Id是否为空
    if(null == id) {
        throw new ServiceException("Id不能为空");
    }
    
    // 如果Id不为空，则通过Id进行查询操作
    return userMapper.selectNameById(id);
}

三、接口开发

1、接口注释

所有Controller、Service、ServiceImpl、Mapper、Domain、Bo、Vo类上，必须添加注释描述信息
类名、接口路径、表名，必须根据业务，添加统一前缀，例如：/security/user

2、Controller

所有业务逻辑，写在ServiceImpl中，Controller中不写业务相关代码

3、Mapper

所有的SQL语句，必须写在Mapper.xml中，不能在Mapper中使用注解写SQL语句

例如：

错误示例：

public interface SecurityUserMapper {
    /**
     * 通过Id获取名称
     *
     * @param id Id
     * @return 返回名称
     */
    @Select("SELECT name FROM security_user WHERE id = #{id}")
    String getNameById(Long id);
}

正确示例：

Mapper

public interface SecurityUserMapper {
    /**
     * 通过Id获取名称
     *
     * @param id Id
     * @return 返回名称
     */
    String getNameById(Long id);
}

Mapper.xml

<!-- 通过Id获取名称 -->
<select id="getNameById" resultType="java.lang.String">
    	SELECT name
    	FROM security_user
    	WHERE id = #{id}
</select>

4、表设计

所有的表中，必须包含以下字段：

id：bigint(20)类型
create_by：varchar(64)类型
create_time：datetime(0)类型
update_by：varchar(64)类型
update_time：datetime(0)类型
is_del：int(11)类型（0未删除，1已删除）

在新建业务表时，所有表名必须添加统一业务前缀

表中所有字段，必须将注释内容写全

如果表中字段和其它表字段有关联，必须在注释内容中体现

非必要，减少外键使用，关联操作在代码中进行处理

例如：

用户表：

字段名	类型	注释
id	bigint(20)	Id
name	varchar(255)	名称
dept_id	bigint(20)	部门Id（sys_dept表Id）
create_by	varchar(64)	创建者
create_time	datetime	创建时间
update_by	varchar(64)	更新者
update_time	datetime	更新时间
is_del	int(11)	是否删除（0未删除，1已删除）

5、逻辑删除

所有删除，必须使用逻辑删除，通过修改is_del = 1来进行删除操作

6、警告

删除代码中，多余的import引用
方法、字段之间，避免出现过多的换行，换行最多不能超过两行
尽可能的减少代码中的警告信息
删除代码中，多余的打印信息

四、前端

统一使用模板样式开发
所有功能，不能在views、api、pages目录下直接进行开发，需根据业务模块，放在对应的模块包下开发
关键属性、函数，必须进行注释描述，每个代码片段必须添加注释信息
若页面内容过多，需封装组件处理，封装组件在该功能模块下进行新建，避免在全局新建
包名、文件名、字段名、属性名等，必须添加注释信息，定义名称必须符合字段描述
调用接口发送请求时，非必要字段无法传递，减少字段的传递
调用接口后响应的信息，必须先判断接口返回的状态码，在进行业务处理，避免处理错误
调用接口后响应的信息，必须先判断返回的属性值是否存在，避免处理错误

例如：

view

<template>
  <div class="app-container">
    <!-- 顶部搜索 -->
    <el-form :model="queryParams" ref="queryForm" size="small" :inline="true" v-show="showSearch">
        <!-- 搜索内容... -->
      <!-- 搜索按钮 -->
      <el-form-item>
        <!-- 搜索按钮... -->
      </el-form-item>
    </el-form>

    <!-- 顶部操作按钮 -->
    <el-row :gutter="10" class="mb8">
      <el-col :span="1.5">
          <!-- 顶部操作按钮... -->
    </el-row>

    <!-- 表格数据 -->
    <el-table v-loading="loading" :data="DemoList" @selection-change="handleSelectionChange">
        <!-- 表格数据内容... -->
      <!-- 表格操作按钮 -->
      <el-table-column label="操作" align="center" class-name="small-padding fixed-width">
          <!-- 操作按钮，必须添加权限标识符... -->
      </el-table-column>
    </el-table>

    <!-- 分页 -->
    <pagination v-show="total > 0" :total="total" :page.sync="queryParams.pageNum" :limit.sync="queryParams.pageSize" @pagination="getList"/>

    <!-- 添加或修改弹窗 -->
    <el-dialog :title="title" :visible.sync="open" width="500px" append-to-body>
      <!-- 表单 -->
      <el-form ref="form" :model="form" :rules="rules" label-width="100px">
          <!-- 弹窗表单内容... -->
      </el-form>
      <!-- 弹窗按钮 -->
      <div slot="footer" class="dialog-footer">
          <!-- 弹窗按钮... -->
      </div>
    </el-dialog>

  </div>
</template>

<script>
import {getPage, add} from "@/api/web/demo/demo";

export default {
  name: "Demo",
  data() {
    return {
      // 遮罩层
      loading: true,
      // 表单参数
      form: {},

      // 表单校验
      rules: {},
        
      // 其它属性内容...
    };
  },
  created() {
    this.getList();
  },
  methods: {

    /** 查询列表分页 */
    getList() {
      this.loading = true;
      getPage(this.queryParams).then(response => {
          this.bannerList = response.rows;
          this.total = response.total;
          this.loading = false;
        }
      );
    },
    
    // 其它处理...
  }
};
</script>

<!-- 样式 -->
<style lang="scss" scoped>

</style>

api

import request from '@/utils/request'

// 获取列表分页
export function getPage(query) {
  return request({
    url: '/web/demo/page',
    method: 'get',
    params: query
  })
}

五、代码提交

代码检查后，减少代码中多余的引用、减少代码中的警告信息之后，进行提交代码
提交代码前，保证提交的代码可正常运行
不可直接在master分支进行开发，需切换其它分支进行开发
代码提交的Commit描述，描述清楚本次提交代码的内容
避免一次提交大量文件，每次新增或修改功能，进行提交代码操作
避免重复提交相同功能，将相同功能整体提交，避免重复、多次提交相同代码
代码提交时，不可提交通用配置信息，例如：vue.config.js、.env.development、.env.production中的接口地址不可提交
代码提交时，不可提交和代码不相关的信息，例如：log、node_modules、dist、.idea、.vscode、.hbuilderx、unpackage、package-lock.json信息等