开发文档规范

开发文档

开发规范

一、命名

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

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 nameFROM security_userWHERE 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信息等

六、接口文档

• 编写接口文档时，不能直接导出接口文档，避免影响其它人编写的文档信息，需手动编写

• 按模块新建文档信息，每个小模块放在一个包下

• 需删除接口中没有必要的参数，避免参数过多

• 若接口中需传入参数，请标注是否必传

• 文档中的参数和响应信息，需添加注释信息来描述

• 文档中的参数和响应信息，需添加示例信息

若修改原框架中的代码，请提前告知