开发规范

作者：许冠杰

一、开发规范

1、命名规范

💬

杜绝完全不规范的缩写，避免望文不知义

命名避免和关键字的重复

1.1、应用命名

a. 应用名称：1-64位字符组成。

注：若在默认租户中创建应用，建议标明【勿删】。

b. 应用标识：以小写字母或数字组成。

c. 环境配置：按需配置。

1.2、页面命名

页面名称：采用大驼峰命名（UpperCamelCase）：每个单词的第一个字母大写，其他字母小写。

正例：ProductList、ProductDetail

1.3、逻辑变量命名

逻辑名、参数名、变量都统一使用 lowerCamelCase 风格，必须遵从小驼峰形式。

正例：localValue / getHttpMessage()

💬

特此说明，增删查改，详情统一使用如下 5 个单词，不得使用其他（目的是为了统一各个端）

add / update / delete / get / detail

2、注释规约

💬

复杂逻辑需写注释

对于注释的要求：

能够准确反映设计思想和代码逻辑； 
能够描述业务含义，使别的开发者能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。 
好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。 
正例：getCompanyInfoByUserId，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。

3、异常

3.1、防止 NPE（空指针），是开发者的基本修养，注意 NPE 产生的场景，做好非空判断。

3.2、尽量避免出现重复的代码（Don’t Repeat Yourself），即 DRY 原则。

说明：随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。 
必要时抽取共性方法，封装成全局逻辑。

4、日志规约

💬

用于调试逻辑使用的日志与弹出消息调试后需及时删除，尤其是前端的输出日志以及弹出消息

谨慎地记录日志。生产环境禁止输出 debug 日志；有选择地输出 info 日志；如果使用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志。

说明：大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。 
记录日志时请思考：这些日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？

5、安全规约

5.1、隶属于用户个人的页面或者功能必须进行权限控制校验。

说明：防止没有做水平权限校验就可随意访问、修改、删除别人的数据，比如查看他人的私信内容、修改他人的订单。

5.2、用户敏感数据禁止直接展示，必须对展示数据进行脱敏。

说明：中国大陆个人手机号码显示为:137****9054，隐藏中间 4 位，或直接不返回敏感数据字段，防止隐私泄露。

6、数据

6.1、禁用保留字，如 desc、range、match、delayed 等，请参考 MySQL 官方保留字。

6.2、实体：

a. 实体的命名最好是遵循“业务名称_表的作用”/“业务名称+首字母大写表的作用”

b. 字段采用“实体+字段含义”的命名方式。

正例： 
实体：Force_project、ForceProject 
字段：productName、productCode

c. 字段允许适当冗余，以提高查询性能，但必须考虑数据一致。冗余字段应遵循：

不是频繁修改的字段。

不是 String 超长字段，更不能是 text 字段。

不是唯一索引的字段。

正例：商品类目名称使用频率高，字段长度短，名称基本不变，可在相关联的表中冗余存储类目名称，避免关联查询。

6.3、枚举：枚举采用“含义”的命名方式，建议使用对应字段名称，使用大驼峰格式。

正例：CustomerLevel、FollowStatus

6.4、数据结构：数据结构命名采用“含义+Structure”的命名方式。

正例：ContractProductStructure

7、多人协作使用姿势 多人协作使用文档

说明：平台不建议多人同时开发一个副本，请使用多人协同开发功能！！！

7.1、页面逻辑、全局逻辑的资源描述必填并写明创建人，可使用姓名缩写。

正例：getCompanyInfoByUserId：通过userId查询公司信息-dm

7.2、数据建模需提前在主应用中完成。

7.3、基于主应用创建属于自己的协作副本，创建副本的时候默认选择主分支，并在自己的协作副本进行开发。开发完成后统一在主应用进行分支的拉取。

7.4、开发过程中需及时进行备份操作，避免内容丢失。

8、需求实现规范

若需求没有明确说明，请按此规范执行

8.1、表单

1）同一个表单中单行输入、数字输入和选择框宽度需一致；

2）单行输入：开启清除按钮，除非特殊说明否则数据入库前需使用trim()函数去掉前后空格

3）多行输入：需开启显示字数统计，可输入最大字符数（默认200），字数统计位置在输入框内，除非特殊说明否则数据入库前需使用trim()函数去掉前后空格

4）数字输入框：如果是小数，精度默认0.01；，除非特殊说明否则数据入库前需使用trim()函数去掉前后空格

5）选择框：超过10条数据需要开启可筛选，以选择框文本字段做模糊匹配；转换器选择Json；超过50条数据需开启分页；开启清除按钮。

6）多选组：转换器选择Json。

8.2、数据查询

1）查询必须有“重置”功能

2）数据表格序号、关键列、操作列需固定

3）日期、数字、状态字段必须有排序

4）所有显示的的内容，需做空值判断，如果为空则隐藏或替换成--、/等字符，不允许出现null，或空标签等内容

5）从数据库查询数据全部用后端分页，页面临时使用的List<>数据可前端分页

6）除非特殊说明单选，否则所有下拉选择均需支持多选（如PRD有说明，按照PRD来执行）

7）需要搜索的字段，实体属性类型不能设置为List<>或map<>

8）使用SQL查询，注意处理Null值问题，如果范围查询在筛选条件中，且允许无最大值或最小值，使用比较运算符>=，<= 等；最大值最小值必须都有，可使用between...and...

8.3 、流程开发

流程出现变更时：需要将历史流程实例全部结束（OA请假流程为例:所有申请均需流转到结束节点）后再发布，使得新流程生效。

8.4、其他规范

1）涉及到数据库中的数据的删除的时候，所有删除动作必须有二次确认

2）所有显示用户名、昵称的地方不允许左连User表，只能选择用户名和昵称列查询。

3）不允许在ForEach循环中调用create/update/get逻辑

4）对查询后的数据、数组等做处理，均需做非空判断

二、项目应用敏感操作规范

1、数据库

但凡操作客户方的制品应用和数据库，一定要谨慎再谨慎；

测试数据库的增删改，必须得到客户确认之后才可执行！

生产数据库的增删改，必须得到项目经理和客户双重确认下才能执行！

2、制品应用

客户的制品应用，我方教练在协助排查问题时，尽量只提供方案，让客户自己操纵。

若客户表示操作太过复杂，需教练直接操作制品应用进行修改时，必须遵守以下规范：

1、修改前必须备份，备份方式不限于应用备份、复制页面、日志备份（云服务器侧），确保不会因为误操作而导致代码丢失！

2、禁止删除客户任何代码！若确实有场景需要删除部分代码，一定要和客户确认改代码业务影响，同时检查改代码层级关系，确保不会影响到子组件及其下事件逻辑；

删改逻辑代码时一定要确认引用关系，若有引用的，必须二次和客户确认是否可删除。在修改逻辑，可将原有逻辑拖出流水线，尽可能保留原有逻辑恢复方式。

3、发布前必须检查是否有丢失的组件或逻辑，一旦发布就不可以再撤回了。

3、多人协作

严格遵守多人协作操作规范（多人协作操纵规范），引导客户使用多人协作，避免客户多人开发同一个应用副本；

若我方教练支持客户多人协作代码合并等操作，在操作前必须备份，仔细检查冲突项，避免因代码拉取或合并导致代码丢失。

4、平台资产

私有化客户的平台资产（包括应用模板，页面模板，接口，依赖库组件，用户账号）禁止操作，我们仅做指导，由客户自己操作！

5、事故场景补救

场景1：若误删代码，保留现场，教练不要再进行操作，IDE页面不要关闭，尽可能保留事故现场的完整；【页面缓存可将内容恢复】

场景2：若多人协作合并导致代码丢失的，可联系开发调用运维接口进行最近一次合并的代码进行回滚；【注意不要再进行任何拉取合并等操作】。